[argszero]

Summary

Sign in with GitHub, for both kinds of client the platform has. Browserless clients (desktop app, CLI, agent) use the device-code flow; the web login page gets a "Sign in with GitHub" button on the ordinary authorisation-code flow. Both meet at one function, land_identity, so whichever entrance a GitHub account uses it lands on the same user row and receives the same existing API key.

Addresses the work order filed as rant 2026-11-09T14:43:55 ("support GitHub sign-in and registration, and let the desktop client obtain an API key in one step").

The contract browserless clients already implement

Endpoint	Request	Success	Intermediate
POST /api/auth/github/device/code	none	200 {device_code, user_code, verification_uri, expires_in, interval}	—
POST /api/auth/github/device/token	{device_code}	200 {api_key, user_id, login}	202 authorization_pending / 429 slow_down / 410 expired_token / 403 access_denied

Field names and status codes are as given in the order; the success body is the same shape as email login (api_key + user_id), plus login. No intermediate state issues a key — those four branches return before the database is touched.

The web half

Endpoint	Request	Success
GET /api/auth/github/authorize	none	200 {authorize_url} + Set-Cookie: atp_gh_state=…
POST /api/auth/github/exchange	{code, state}	200 {api_key, user_id, login}

state must match the HttpOnly cookie authorize set; a mismatch answers 400 github_state_mismatch before any upstream call or database write. Without that binding, a code minted by an attacker could sign a victim's browser into the attacker's account. The cookie is cleared (Max-Age=0) on success, so a used state has no second chance. The front end strips code/state from the address bar immediately on return, then enters the app through the same restoreSession path email login uses.

redirect_uri is derived from server.public_url (trailing slash trimmed) rather than added as a third configuration key, and the same value is sent when exchanging the code, as GitHub requires both to match.

The acceptance items

1. Device-code login — the two endpoints above; the web half added here.
2. Identity is the account — keyed on GitHub's stable numeric id, never on login (which can be renamed and would otherwise create a second account). An existing key is reused through dao::get_or_create_api_key, the same issuance path email login uses; the success body is api_key + user_id as in email login.
3. Registration is already verified — no email code, no email dependency; verified is set on creation and scope stays empty, so a GitHub account with no public email still registers.
4. New accounts get the same treatment — a quotas row is created with the account and the daily gift is grantable on day one; asserted in the gate.
5. Web login page entry — the button plus the authorisation-code flow above, sharing land_identity with the device flow.
6. Exactly two config keys — [github] client_id / client_secret, empty meaning disabled, where the endpoints answer 503 github_login_not_enabled (naming what to set) and never 500. config/config.example.toml carries both, and states the two switches an OAuth App needs: device flow enabled, and the callback URL set to public_url.

Schema

SCHEMA_VERSION 17 → 18. users gains github_id TEXT NOT NULL DEFAULT '' (via ensure_column, so an existing database upgrades in place), a github_login column, and a partial unique index on github_id that excludes '', so email-only accounts are unaffected and no second row can claim an identity. email and password_hash stay NOT NULL (GitHub accounts store an empty string plus an unusable hash), which is why no table rebuild is needed. The migration is described in CHANGELOG.md.

Tests

cargo test 605 passed, 0 failed (590 at the base commit 405f078); cargo fmt --check clean; cargo clippy --all-targets -- -D warnings clean.

The new src/github_oauth_gate.rs is test-only (registered as #[cfg(test)] mod in main.rs) and adds 15 assertions, of which four are the web half: the authorise URL is derived from public_url and the state cookie is HttpOnly + SameSite=Lax; a mismatched state buys no credentials and does not reach upstream; the web flow and the device flow land on the same user row and the same key; the login page carries the button with its key in both language packs.

Tests never call github.com: the upstream base is injectable (AppState::github_api), pointed at a local mock. Every assertion carries a non-empty positive control, so a broken extractor turns red instead of passing on an empty set.

Not in this pull request

Nothing from the order — all six items are here. The OAuth App itself is the host's to create; the code answers 503 with an actionable message until then, which is why an unconfigured deployment is not a merge blocker.