Repository navigation
Description
Part of epic #1272.
Add the device authorization grant (RFC 8628) to the backend so the CLI can obtain an API key through ORCID sign-in in a browser on any machine. Nothing here talks to ORCID directly; the authorize step sits behind the existing web session and ORCID routes.
Scope
- Migration 0081: a device-code table with the user code, the device code, the machine name, state (pending, confirmed, denied, expired, consumed), the confirming user, timestamps, and a 10-minute lifetime. Follow the signed-intent pattern from ADR 0044 for single use and nonce handling.
POST /auth/device/start: mints a device code and a short user code, returns the verification URL on nemar.org with the code pre-filled, the polling interval, and the expiry. Rate limited per IP.POST /auth/device/token: the CLI polls with the device code; answersauthorization_pending,slow_down,expired_token,access_denied, or the key exactly once. Rate limited; a device code is single use and refused after expiry or consumption.- Web-session endpoints for the authorize page: look up a user code (returns the machine name and the signed-in account, never the key), confirm, and deny. Confirm and deny are same-origin gated like
POST /auth/orcid/start(ADR 0022). - Confirm issues a NEW named row in
tokensfor that machine; existing keys stay valid. Refusals at confirm time carry a typed reason:pending,revoked,identity_conflict. The service-account refusal lands in phase 4. - Key management for the paste path and for phase 3 logout: list the account's keys (prefix, name, created, last used), mint a named key (shown once), revoke one key by id. Bearer token or web session, through
resolveActingAccount. - Audit rows for start, confirm, deny, expiry, and key mint or revoke. Typed reasons and copy in
shared/contract.
Tests
Route tests at the HTTP entry points with no mocks, in the pattern of backend/test/identity-refusals-route.test.ts and cli-self-service-routes.test.ts: seed a web session with POST /admin/test-fixtures/seed-web-user and the dev_code sign-in, then cover start, poll while pending, slow_down, confirm, deny, expiry, reuse after expiry and after consumption, wrong account, a pending or revoked or identity-conflict account at confirm time, a second start while one is pending, key listing and single-key revocation leaving other keys valid, and the rate limits. A local Bun.serve() ORCID stand-in via ORCID_API_BASE covers the one path that reaches ORCID: a new iD creating the pending account.
Definition of done
- All route tests green locally and in CI; migration checked with
wrangler d1 --local. - One staging walk-through with a real ORCID account recorded here.
Activity
neuromechanist commentedon Sep 7, 2026
Merged into the epic branch by #1287 (squash 5a348bf). Review fixes landed in the same PR. The one remaining item, the staging walk-through with a real ORCID account, needs the routes on api-test.nemar.org, which deploys only from dev; it will be recorded on epic #1272 once the epic branch lands there (or earlier if the branch is deployed by hand). Follow-up filed as #1286 for the pre-existing ISO-versus-SQL timestamp comparisons planning uncovered.