Skip to content

DEV-448: add /device page to approve device code sign-in - #23

Merged
xkickflip merged 1 commit into
mainfrom
chris-dev-448-add-device-code-login-rfc-8628-for-terminal
Nov 21, 2026
Merged

xkickflip merged 1 commit into
mainfrom
chris-dev-448-add-device-code-login-rfc-8628-for-terminal

Conversation

@xkickflip

Copy link
Copy Markdown
Member

Summary

Terminal and headless sign-in currently depends on the localhost callback, which needs a browser on the same machine as the agent and, in the Safari fallback, puts tokens in browser history and access logs. This adds the web half of the OAuth 2.0 Device Authorization Grant (RFC 8628): the verification page where you approve a device code. Tokens then go straight to the polling client, so nothing has to pass from the browser to the local API.

  1. New /device page (the verification_uri). /device?code=BCDF-GHJK (verification_uri_complete) arrives with the code filled in. Bare /device asks you to type the code, accepting any case, with or without the dash.
  2. Signed-out visitors go to /login?redirect=/device?code=… and come back with the same code.
  3. Looks up the code with GET /v1/auth/device?code= and names the requesting app before anything is approved, so you approve only when it shows the same code.
  4. Approve or Deny posts { user_code, approve } to /v1/auth/device/approve. Deny gives the client access_denied.
  5. API failures become messages on the page: 404 means the code is invalid or expired, 403 means the email is unverified, and 429 means too many attempts.

Test plan

  • Start a device-code sign-in from docent and open the verification_uri_complete link while signed out. Sign in and confirm you land back on /device with the code filled in.
  • Open bare /device, type the code in lowercase without the dash, and confirm it is accepted and the app name is shown.
  • Approve and confirm the client's poll returns tokens and the page says the app is signed in.
  • Repeat and Deny, and confirm the client gets access_denied and the page says nothing was signed in.
  • Enter an expired or made-up code and confirm the "not valid or has expired" message and the entry form.

- /device?code=BCDF-GHJK signs you in first if needed, then names the
  app asking (GET /v1/auth/device) and shows the code to compare
- Approve or Deny posts to /v1/auth/device/approve; the device's agent
  gets its tokens on its next poll
- Bare /device asks for the code; any case, with or without the dash
- Expired, used, unverified-account and rate-limited codes get their own
  messages
@xkickflip
xkickflip merged commit af1106c into main Nov 21, 2026
1 check passed
@xkickflip
xkickflip deleted the chris-dev-448-add-device-code-login-rfc-8628-for-terminal branch November 21, 2026 01:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant