Device sign-in: approve an app's code on the web, the app gets a scoped token (closes #67) df71c7892d27

-- Device sign-in (oxygenhub#67, RFC 8628 in shape): an app holds the

-- device code (stored as its hash) and polls; the user approves the user

-- code on the web, choosing the scopes; the token is made when the app

-- next polls, so no token is stored in the clear.

CREATE TABLE device_codes (

    id              INTEGER PRIMARY KEY,

    device_hash     TEXT NOT NULL UNIQUE,

    user_code       TEXT NOT NULL UNIQUE,

    client          TEXT NOT NULL,

    scopes          TEXT NOT NULL,

    created_ms      INTEGER NOT NULL,

    expires_ms      INTEGER NOT NULL,

    last_poll_ms    INTEGER NOT NULL DEFAULT 0,

    account_id      INTEGER REFERENCES accounts(id) ON DELETE CASCADE,

    approved_scopes TEXT NOT NULL DEFAULT '',

    denied          INTEGER NOT NULL DEFAULT 0

);

//! Device sign-in (oxygenhub#67), in the shape of RFC 8628: an app that

//! cannot take a password asks for a code, the user approves it on the web

//! (signed in, with their second factor), and the app's next poll gets a

//! token with the scopes the user allowed.

use crate::db::{self, accounts};

use crate::Shared;

use axum::extract::State;

use axum::http::StatusCode;

use axum::response::{IntoResponse, Response};

use axum::Json;

use serde::Deserialize;

use serde_json::json;

/// How long a code lasts, and how often an app may poll.

const LIFETIME_MS: i64 = 15 * 60 * 1000;

const INTERVAL_S: i64 = 5;

/// User codes: consonants only, so no word is spelt and none is mistaken

/// for another letter or a digit.

const USER_ALPHABET: &[u8] = b"BCDFGHJKLMNPQRSTVWXZ";

#[derive(Deserialize)]

pub struct CodeRequest {

    /// What the app calls itself, shown when the user approves it.

    #[serde(default)]

    client: String,

    #[serde(default)]

    scopes: Vec<String>,

}

/// A user code, `XXXX-XXXX`.

fn user_code() -> String {

    use rand::RngCore;

    let mut b = [0u8; 8];

    rand::rngs::OsRng.fill_bytes(&mut b);

    let c: String = b.iter().map(|x| USER_ALPHABET[*x as usize % USER_ALPHABET.len()] as char).collect();

    format!("{}-{}", &c[..4], &c[4..])

}

/// A user code as typed: upper case, spaces and dashes ignored.

pub fn normalize_user_code(s: &str) -> String {

    let c: String = s.chars().filter(|c| c.is_ascii_alphanumeric()).map(|c| c.to_ascii_uppercase()).collect();

    if c.len() == 8 {

        format!("{}-{}", &c[..4], &c[4..])

    } else {

        c

    }

}

fn oauth_error(status: StatusCode, error: &str, detail: &str) -> Response {

    (status, Json(json!({ "error": error, "error_description": detail }))).into_response()

}

/// `POST /api/v1/device/code`: a device code to poll with and a user code

/// to show. No token needed.

pub async fn code(State(app): State<Shared>, Json(req): Json<CodeRequest>) -> Response {

    let known = |s: &str| crate::web::settings::SCOPES.iter().any(|(k, _)| *k == s);

    let mut scopes: Vec<&str> = req.scopes.iter().map(String::as_str).filter(|s| known(s)).collect();

    if scopes.len() != req.scopes.len() {

        return oauth_error(StatusCode::BAD_REQUEST, "invalid_scope", "unknown scope");

    }

    if scopes.is_empty() {

        scopes = vec!["repo:read", "user:read"];

    }

    let client: String = req.client.trim().chars().filter(|c| !c.is_control()).take(80).collect();

    let client = if client.is_empty() { "an app".to_string() } else { client };

    let device = format!("oxydev_{}", crate::auth::random_hex(32));

    let hash = crate::auth::token_hash(&device);

    let expires = db::now_ms() + LIFETIME_MS;

    // A clash of user codes is unlikely; try a few.

    for _ in 0..4 {

        let user = user_code();

        match accounts::create_device_code(&app.db, &hash, &user, &client, &scopes.join(","), expires).await {

            Ok(_) => {

                let base = app.config.base_url().trim_end_matches('/').to_string();

                return Json(json!({

                    "device_code": device,

                    "user_code": user,

                    "verification_uri": format!("{base}/device"),

                    "verification_uri_complete": format!("{base}/device?code={user}"),

                    "expires_in": LIFETIME_MS / 1000,

                    "interval": INTERVAL_S,

                }))

                .into_response();

            }

            Err(sqlx::Error::Database(e)) if e.is_unique_violation() => continue,

            Err(e) => return oauth_error(StatusCode::INTERNAL_SERVER_ERROR, "server_error", &e.to_string()),

        }

    }

    oauth_error(StatusCode::SERVICE_UNAVAILABLE, "server_error", "no free user code; try again")

}

#[derive(Deserialize)]

pub struct TokenRequest {

    device_code: String,

}

/// `POST /api/v1/device/token`: the token once the user approved, or why

/// not yet (`authorization_pending`, `slow_down`, `access_denied`,

/// `expired_token`), as RFC 8628 has it.

pub async fn token(State(app): State<Shared>, Json(req): Json<TokenRequest>) -> Response {

    let hash = crate::auth::token_hash(req.device_code.trim());

    let d = match accounts::device_by_hash(&app.db, &hash).await {

        Ok(Some(d)) => d,

        Ok(None) => return oauth_error(StatusCode::BAD_REQUEST, "expired_token", "no such device code, or it was used"),

        Err(e) => return oauth_error(StatusCode::INTERNAL_SERVER_ERROR, "server_error", &e.to_string()),

    };

    let now = db::now_ms();

    if d.expires_ms < now {

        let _ = accounts::delete_device(&app.db, d.id).await;

        return oauth_error(StatusCode::BAD_REQUEST, "expired_token", "the code expired; ask for a new one");

    }

    if d.denied {

        let _ = accounts::delete_device(&app.db, d.id).await;

        return oauth_error(StatusCode::BAD_REQUEST, "access_denied", "the user denied the request");

    }

    let Some(account_id) = d.account_id else {

        let _ = accounts::device_polled(&app.db, d.id).await;

        if now - d.last_poll_ms < INTERVAL_S * 1000 {

            return oauth_error(StatusCode::BAD_REQUEST, "slow_down", "poll no more often than the interval");

        }

        return oauth_error(StatusCode::BAD_REQUEST, "authorization_pending", "not yet approved");

    };

    // One poll takes the approval: the token is made only by the poll

    // that removed the code.

    match accounts::delete_device(&app.db, d.id).await {

        Ok(true) => {}

        Ok(false) => return oauth_error(StatusCode::BAD_REQUEST, "expired_token", "the code was used"),

        Err(e) => return oauth_error(StatusCode::INTERNAL_SERVER_ERROR, "server_error", &e.to_string()),

    }

    let account = match accounts::account_by_id(&app.db, account_id).await {

        Ok(Some(a)) => a,

        _ => return oauth_error(StatusCode::BAD_REQUEST, "access_denied", "the approving account is gone"),

    };

    let (secret, token_hash) = crate::auth::new_token();

    let name = format!("device: {}", d.client);

    if let Err(e) = accounts::create_token(&app.db, account_id, &name, &token_hash, &d.approved_scopes, "", None).await {

        return oauth_error(StatusCode::INTERNAL_SERVER_ERROR, "server_error", &e.to_string());

    }

    accounts::audit(&app.db, Some(&account), "token.device", &name, &d.approved_scopes).await.ok();

    Json(json!({

        "access_token": secret,

        "token_type": "bearer",

        "scope": d.approved_scopes.replace(',', " "),

        "username": account.username,

    }))

    .into_response()

}

//! `/device`: approving an app's sign-in code (oxygenhub#67). The app shows

//! a code; the user, signed in here, enters it, sees what the app asked

//! for, and approves it with the scopes they choose, or denies it.

use super::settings::{csrf, require, SCOPES};

use super::{Error, Page, Shell};

use crate::api::device::normalize_user_code;

use crate::auth::Viewer;

use crate::db::{self, accounts};

use crate::Shared;

use askama::Template;

use axum::extract::{Query, State};

use serde::Deserialize;

#[derive(Template)]

#[template(path = "device.html")]

pub struct DevicePage {

    shell: Shell,

    code: String,

    /// The pending request the code names, with each scope it asked for.

    pending: Option<(accounts::DeviceCode, Vec<(&'static str, &'static str)>)>,

    done: Option<String>,

    error: Option<String>,

}

/// A code still waiting for an answer.

async fn pending(app: &Shared, code: &str) -> Result<Option<accounts::DeviceCode>, sqlx::Error> {

    Ok(accounts::device_by_user_code(&app.db, code).await?.filter(|d| d.account_id.is_none() && !d.denied && d.expires_ms >= db::now_ms()))

}

fn page(shell: Shell, code: String, d: Option<accounts::DeviceCode>, done: Option<String>, error: Option<String>) -> Page<DevicePage> {

    let pending = d.map(|d| {

        let asked: Vec<(&'static str, &'static str)> = SCOPES.iter().filter(|(k, _)| d.scope_list().contains(k)).copied().collect();

        (d, asked)

    });

    Page(DevicePage { shell, code, pending, done, error })

}

#[derive(Deserialize)]

pub struct CodeQuery {

    #[serde(default)]

    code: String,

}

pub async fn form(State(app): State<Shared>, viewer: Viewer, Query(q): Query<CodeQuery>) -> Result<Page<DevicePage>, Error> {

    let shell = Shell::new(&app, "/device", &viewer);

    require(&viewer, &shell)?;

    let code = normalize_user_code(&q.code);

    if code.is_empty() {

        return Ok(page(shell, code, None, None, None));

    }

    let d = pending(&app, &code).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    let error = d.is_none().then(|| "No app is waiting for that code: it may have expired. Ask the app for a new one.".to_string());

    Ok(page(shell, code, d, None, error))

}

#[derive(Deserialize)]

pub struct DeviceForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    code: String,

    #[serde(default)]

    action: String,

    #[serde(default)]

    scopes: Vec<String>,

}

pub async fn answer(

    State(app): State<Shared>,

    viewer: Viewer,

    axum_extra::extract::Form(f): axum_extra::extract::Form<DeviceForm>,

) -> Result<Page<DevicePage>, Error> {

    let shell = Shell::new(&app, "/device", &viewer);

    let me = require(&viewer, &shell)?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    let code = normalize_user_code(&f.code);

    let d = pending(&app, &code).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    let Some(d) = d else {

        let e = "No app is waiting for that code: it may have expired. Ask the app for a new one.";

        return Ok(page(shell, code, None, None, Some(e.into())));

    };

    match f.action.as_str() {

        "approve" => {

            // Only scopes the app asked for, and at least one.

            let asked = d.scope_list();

            let chosen: Vec<&str> = f.scopes.iter().map(String::as_str).filter(|s| asked.contains(s)).collect();

            if chosen.is_empty() {

                return Ok(page(shell, code, Some(d), None, Some("Allow at least one of what it asks for, or deny it.".into())));

            }

            let ok = accounts::approve_device(&app.db, d.id, me.account.id, &chosen.join(","))

                .await

                .map_err(|e| Error::from_db(shell.clone(), e))?;

            if !ok {

                return Ok(page(shell, code, None, None, Some("That code was answered or expired meanwhile.".into())));

            }

            accounts::audit(&app.db, Some(&me.account), "device.approved", &d.client, &chosen.join(",")).await.ok();

            let done = format!(

                "Approved: {} is signed in as {} and will get its token in a moment. It is listed under Settings → Tokens, where you can revoke it.",

                d.client, me.account.username

            );

            Ok(page(shell, String::new(), None, Some(done), None))

        }

        "deny" => {

            accounts::deny_device(&app.db, d.id).await.map_err(|e| Error::from_db(shell.clone(), e))?;

            accounts::audit(&app.db, Some(&me.account), "device.denied", &d.client, "").await.ok();

            Ok(page(shell, String::new(), None, Some(format!("Denied: {} was not signed in.", d.client)), None))

        }

        // Looking a typed code up.

        _ => Ok(page(shell, code, Some(d), None, None)),

    }

}

{% extends "base.html" %}

{% block title %}Sign in a device{% endblock %}

{% block content %}

<div class="head"><h1>Sign in a device <small>an app asked to use your account</small></h1></div>

{% if let Some(d) = done %}<p class="note">{{ d }}</p>{% endif %}

{% if let Some(e) = error %}<p class="error">{{ e }}</p>{% endif %}

{% if let Some((d, asked)) = pending %}

<form class="card wide" method="post" action="/device">

  <input type="hidden" name="_csrf" value="{{ shell.csrf }}">

  <input type="hidden" name="code" value="{{ d.user_code }}">

  <h2><strong>{{ d.client }}</strong> wants to sign in as you</h2>

  <p class="small">Code <code>{{ d.user_code }}</code>. Approve only if this is the code your app shows. It gets a token with what you allow here; you can revoke it under Settings → Tokens.</p>

  <label>Allow it to</label>

  <div class="scopes">

    {% for (name, what) in asked %}<label><input type="checkbox" name="scopes" value="{{ name }}" checked> <code>{{ name }}</code> <span class="small mute">{{ what }}</span></label>{% endfor %}

  </div>

  <button type="submit" name="action" value="approve">APPROVE</button>

  <button type="submit" name="action" value="deny" class="secondary">DENY</button>

</form>

{% else %}

<form class="card" method="post" action="/device">

  <input type="hidden" name="_csrf" value="{{ shell.csrf }}">

  <label for="code">The code your app shows</label>

  <input type="text" id="code" name="code" value="{{ code }}" required autofocus autocomplete="off" placeholder="BCDF-GHJK" style="text-transform:uppercase">

  <button type="submit" name="action" value="lookup">CONTINUE</button>

</form>

{% endif %}

{% endblock %}

pub mod device;

        .route("/device/code", post(device::code))

        .route("/device/token", post(device::token))

// ------------------------------------------------------- device sign-in

/// A device code an app asked for (oxygenhub#67): pending until the user

/// approves or denies it on the web.

#[derive(Clone, Debug, FromRow)]

pub struct DeviceCode {

    pub id: i64,

    pub device_hash: String,

    pub user_code: String,

    pub client: String,

    pub scopes: String,

    pub created_ms: i64,

    pub expires_ms: i64,

    pub last_poll_ms: i64,

    pub account_id: Option<i64>,

    pub approved_scopes: String,

    pub denied: bool,

}

impl DeviceCode {

    pub fn scope_list(&self) -> Vec<&str> {

        self.scopes.split(',').filter(|s| !s.is_empty()).collect()

    }

}

pub async fn create_device_code(

    pool: &Pool,

    device_hash: &str,

    user_code: &str,

    client: &str,

    scopes: &str,

    expires_ms: i64,

) -> sqlx::Result<DeviceCode> {

    // Expired codes go whenever a new one is made.

    sqlx::query("DELETE FROM device_codes WHERE expires_ms < ?").bind(now_ms()).execute(pool).await?;

    sqlx::query_as(

        "INSERT INTO device_codes (device_hash, user_code, client, scopes, created_ms, expires_ms) VALUES (?, ?, ?, ?, ?, ?) RETURNING *",

    )

    .bind(device_hash)

    .bind(user_code)

    .bind(client)

    .bind(scopes)

    .bind(now_ms())

    .bind(expires_ms)

    .fetch_one(pool)

    .await

}

pub async fn device_by_user_code(pool: &Pool, user_code: &str) -> sqlx::Result<Option<DeviceCode>> {

    sqlx::query_as("SELECT * FROM device_codes WHERE user_code = ?").bind(user_code).fetch_optional(pool).await

}

pub async fn device_by_hash(pool: &Pool, device_hash: &str) -> sqlx::Result<Option<DeviceCode>> {

    sqlx::query_as("SELECT * FROM device_codes WHERE device_hash = ?").bind(device_hash).fetch_optional(pool).await

}

/// Approve a pending code for an account with these scopes; false when it

/// was no longer pending.

pub async fn approve_device(pool: &Pool, id: i64, account_id: i64, scopes: &str) -> sqlx::Result<bool> {

    let r = sqlx::query(

        "UPDATE device_codes SET account_id = ?, approved_scopes = ? WHERE id = ? AND account_id IS NULL AND denied = 0 AND expires_ms >= ?",

    )

    .bind(account_id)

    .bind(scopes)

    .bind(id)

    .bind(now_ms())

    .execute(pool)

    .await?;

    Ok(r.rows_affected() == 1)

}

pub async fn deny_device(pool: &Pool, id: i64) -> sqlx::Result<()> {

    sqlx::query("UPDATE device_codes SET denied = 1 WHERE id = ? AND account_id IS NULL").bind(id).execute(pool).await?;

    Ok(())

}

pub async fn device_polled(pool: &Pool, id: i64) -> sqlx::Result<()> {

    sqlx::query("UPDATE device_codes SET last_poll_ms = ? WHERE id = ?").bind(now_ms()).bind(id).execute(pool).await?;

    Ok(())

}

/// Remove a code; true when this call removed it (so one poll gets the

/// token, however many race).

pub async fn delete_device(pool: &Pool, id: i64) -> sqlx::Result<bool> {

    let r = sqlx::query("DELETE FROM device_codes WHERE id = ?").bind(id).execute(pool).await?;

    Ok(r.rows_affected() == 1)

}

mod device;

pub(crate) mod settings;

        .route("/device", get(device::form).post(device::answer))

#[tokio::test(flavor = "multi_thread")]

async fn device_sign_in() {

    let h = hub().await;

    let app = &h.app;

    let r =

        call(app, "POST", "/register", None, None, None, Some("username=andy&email=a%40example.com&password=correct-horse-battery")).await;

    let andy = r.cookie.unwrap();

    // An unknown scope is refused.

    let (st, v) = api(app, "POST", "/api/v1/device/code", None, Some(r#"{"client":"x","scopes":["root"]}"#)).await;

    assert_eq!((st, v["error"].as_str()), (StatusCode::BAD_REQUEST, Some("invalid_scope")));

    // The app asks for a code and polls; nobody has approved it yet.

    let (st, v) = api(app, "POST", "/api/v1/device/code", None, Some(r#"{"client":"Phone app","scopes":["repo:read","user:read"]}"#)).await;

    assert_eq!(st, StatusCode::OK, "{v}");

    let device = v["device_code"].as_str().unwrap().to_string();

    let user = v["user_code"].as_str().unwrap().to_string();

    assert_eq!(v["verification_uri_complete"], format!("{}/device?code={user}", h.base));

    let poll = format!(r#"{{"device_code":"{device}"}}"#);

    let (st, v) = api(app, "POST", "/api/v1/device/token", None, Some(&poll)).await;

    assert_eq!((st, v["error"].as_str()), (StatusCode::BAD_REQUEST, Some("authorization_pending")));

    let (_, v) = api(app, "POST", "/api/v1/device/token", None, Some(&poll)).await;

    assert_eq!(v["error"], "slow_down", "polled too soon");

    // The user approves it on the web, allowing less than it asked for.

    let page = call(app, "GET", &format!("/device?code={}", user.to_lowercase().replace('-', "")), None, Some(&andy), None, None).await;

    assert!(page.body.contains("Phone app") && page.body.contains("repo:read"), "{}", page.body);

    let csrf = csrf_of(&page.body);

    let r =

        call(app, "POST", "/device", None, Some(&andy), None, Some(&format!("_csrf={csrf}&code={user}&action=approve&scopes=user%3Aread")))

            .await;

    assert!(r.body.contains("Approved"), "{}", r.body);

    // The next poll gets a token with what was allowed, once.

    let (st, v) = api(app, "POST", "/api/v1/device/token", None, Some(&poll)).await;

    assert_eq!(st, StatusCode::OK, "{v}");

    assert_eq!((v["scope"].as_str(), v["username"].as_str()), (Some("user:read"), Some("andy")));

    let token = v["access_token"].as_str().unwrap().to_string();

    let (st, v) = api(app, "GET", "/api/v1/user", Some(&token), None).await;

    assert_eq!((st, v["username"].as_str()), (StatusCode::OK, Some("andy")));

    let (_, v) = api(app, "POST", "/api/v1/device/token", None, Some(&poll)).await;

    assert_eq!(v["error"], "expired_token", "a code gives one token");

    let tokens = call(app, "GET", "/settings/tokens", None, Some(&andy), None, None).await;

    assert!(tokens.body.contains("device: Phone app"));

    // A denied code says so.

    let (_, v) = api(app, "POST", "/api/v1/device/code", None, Some(r#"{"client":"Other"}"#)).await;

    let (device, user) = (v["device_code"].as_str().unwrap().to_string(), v["user_code"].as_str().unwrap().to_string());

    let page = call(app, "GET", &format!("/device?code={user}"), None, Some(&andy), None, None).await;

    let csrf = csrf_of(&page.body);

    call(app, "POST", "/device", None, Some(&andy), None, Some(&format!("_csrf={csrf}&code={user}&action=deny"))).await;

    let (_, v) = api(app, "POST", "/api/v1/device/token", None, Some(&format!(r#"{{"device_code":"{device}"}}"#))).await;

    assert_eq!(v["error"], "access_denied");

    // Signed out, the page asks for a sign-in first.

    let r = call(app, "GET", "/device", None, None, None, None).await;

    assert!(r.status.is_redirection(), "{}", r.status);

}

    /// POST JSON, returning the status and body whatever the status (the

    /// device sign-in's answers while it waits are errors by design).

    pub fn post_raw(&self, path: &str, body: &impl Serialize) -> Result<(u16, String)> {

        let json = serde_json::to_string(body)?;

        match self.req("POST", path).set("Content-Type", "application/json").send_string(&json) {

            Ok(r) => Ok((r.status(), r.into_string()?)),

            Err(ureq::Error::Status(code, r)) => Ok((code, r.into_string().unwrap_or_default())),

            Err(e) => Err(e).context(format!("POST {path}")),

        }

    }

    /// Sign in to a hub and make it the default: approve a code on the web

    /// (device sign-in), or give a token

        /// The hub, e.g. https://oxygenhub.io

        /// An API token from the hub's Settings → Tokens, instead of

        /// approving a code ("-" reads it from stdin)

    let token = match token.as_deref() {

        Some("-") => {

        Some(t) => t.to_string(),

        None => device_sign_in(&hub, ca.clone())?,

/// Device sign-in (oxygenhub#67): the hub gives a code, the user approves

/// it on the web, and the token arrives here.

fn device_sign_in(hub: &str, ca: Option<std::path::PathBuf>) -> Result<String> {

    let t = Target { hub: hub.to_string(), token: None, ca, owner: String::new(), name: String::new() };

    let c = Client::new(&t)?;

    let host = std::fs::read_to_string("/etc/hostname")

        .ok()

        .or_else(|| std::env::var("COMPUTERNAME").ok())

        .map(|h| h.trim().to_string())

        .filter(|h| !h.is_empty());

    let client = match host {

        Some(h) => format!("oh on {h}"),

        None => "oh".to_string(),

    };

    let scopes = ["repo:read", "repo:write", "proposals:write", "issues:write", "user:read"];

    let (code, body) = c.post_raw("/device/code", &serde_json::json!({ "client": client, "scopes": scopes }))?;

    let v: serde_json::Value = serde_json::from_str(&body).context("the hub's answer to a device code request")?;

    if code != 200 {

        bail!("{hub} cannot sign in a device: {}", v["error_description"].as_str().or(v["detail"].as_str()).unwrap_or(&body));

    }

    let device = v["device_code"].as_str().context("no device code")?.to_string();

    let user = v["user_code"].as_str().unwrap_or("?");

    let url = v["verification_uri_complete"].as_str().or(v["verification_uri"].as_str()).unwrap_or(hub);

    let mut interval = v["interval"].as_u64().unwrap_or(5).max(1);

    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(v["expires_in"].as_u64().unwrap_or(900));

    eprintln!("Open {} and approve the code {}", ui::strong(url), ui::strong(user));

    eprintln!("{}", ui::dim("Waiting for approval (Ctrl-C to give up)…"));

    loop {

        std::thread::sleep(std::time::Duration::from_secs(interval));

        if std::time::Instant::now() > deadline {

            bail!("the code expired before it was approved; run oh auth login again");

        }

        let (code, body) = c.post_raw("/device/token", &serde_json::json!({ "device_code": device }))?;

        let v: serde_json::Value = serde_json::from_str(&body).unwrap_or_default();

        if code == 200 {

            return v["access_token"].as_str().map(String::from).context("no token in the hub's answer");

        }

        match v["error"].as_str() {

            Some("authorization_pending") => {}

            Some("slow_down") => interval += 5,

            Some("access_denied") => bail!("the sign-in was denied on the web"),

            Some("expired_token") => bail!("the code expired before it was approved; run oh auth login again"),

            _ => bail!("signing in: HTTP {code}: {body}"),

        }

    }

}

`oh auth login` shows a code and a link: open it, signed in to the hub, and

approve the code, choosing what `oh` may do (device sign-in). The token

arrives by itself; `oh` checks it, saves it with the CA in

`~/.config/oh/config.toml` (owner-only), and makes that hub the default.

`--token TOKEN` uses a token from Settings → Tokens instead, and

`--token -` reads one from stdin. `OH_TOKEN` (or `OXY_TOKEN`), `OH_HUB` and

`OXY_CA` override the saved values.

| `oh auth login`, `oh auth status` | Sign in (approve a code on the web, or give a token); show who you are |

**Device sign-in** (in the shape of RFC 8628) gives a token to an app that cannot take a password, such as `oh` or a phone client. The app posts `{client, scopes}` to `/api/v1/device/code` without a token and gets a device code (kept, hashed, by the hub), a user code `XXXX-XXXX` (consonants), `verification_uri` (`/device`), `verification_uri_complete`, `expires_in` (15 minutes) and `interval` (5 seconds). It shows the user code and link, and polls `/api/v1/device/token` with `{device_code}`, getting `authorization_pending`, `slow_down` (polled within the interval), `access_denied` or `expired_token` as `{error, error_description}` with 400. The user opens `/device`, signed in (with their second factor), sees the app's name and the scopes it asked for, and approves with any non-empty subset of them, or denies. The next poll makes a token named `device: CLIENT` with the approved scopes and returns `{access_token, token_type: "bearer", scope, username}`, once: the code is then gone. No token exists until that poll, so none is stored in the clear. Approvals, denials and device tokens are in the audit log.