Skip to content

Phase 1: Backend device authorization flow #1281

Closed

Description

@neuromechanist

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; answers authorization_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 tokens for 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

  1. neuromechanist commented on Sep 7, 2026

    @neuromechanist
    ContributorAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    backendBackend/API relatedfeatureNew feature or enhancement

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions