Skip to content

feat(account): sign in the device with the device flow, or as the app of /dev/null - #24

Merged
jubianchi merged 8 commits into
mainfrom
feat/device-sign-in
Oct 23, 2026
Merged

jubianchi merged 8 commits into
mainfrom
feat/device-sign-in

Conversation

@jubianchi

@jubianchi jubianchi commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

Third of the stack moving the log from the session cookie to the signed API of /dev/null (#22 and #23 are merged): the plugin signs in as a device of its own, with a key it creates.

Two ways to approve the device, the same key and device in the end

  1. Device authorization grant (RFC 8628), proposed upstream in feat: sign in to the API from a terminal with a device code dev-null-sh/dev-null.sh#585. The plugin starts it with POST /api/v1/device-authorizations, shows the code to type on dev-null.sh, and polls POST /api/v1/devices as often as /dev/null says.
  2. Until #585 is merged, /dev/null answers 404, and the plugin falls back on the approval used by the app of /dev/null (#130, in production). This is a stopgap, and the Account tab says so:
    • The plugin links to /mobile/authorize with the fingerprint of its key, the name "Claude Code", a PKCE S256 challenge (RFC 7636), a state, and redirect_uri=devnull://authorize.
    • After Approve, dev-null.sh redirects (303) to devnull://authorize?code=…&state=…, which no terminal receives. The person copies that link, from the Location of the answer in the network tab of the browser's developer tools if it shows nowhere else, and pastes it into the tab within 5 minutes (the code is single-use).
    • The plugin checks the state, then redeems the code with POST /api/v1/devices {code, code_verifier}, signed by the key.

Both ways approve the same key as a device, so nothing needs migrating once #585 is merged: the fallback simply stops being used.

Changes

  • hooks/infrastructure/api.ts: post sends signed JSON to the two sign-in routes only. Commits, deletions and follows are refused before they are signed. Readers take get only.
  • hooks/infrastructure/api-device.ts: device flow start and poll. For the fallback, the approval URL, the code read from the pasted link (for that state only), and the redemption.
  • hooks/pkce.ts: verifier, S256 challenge and state.
  • hooks/application/device-sign-in.ts: starts one sign-in or the other, polls, and approves with the pasted link.
  • hooks/state/device.ts:
    • the key of the device, created once (deviceKey, v1);
    • the sign-in under way, polled by a timer of its own that a /clear leaves;
    • the approval under way, with the link pasted kept in the state only, never in the store; the component never sees the verifier;
    • who approved the device (deviceUser, v1, kept apart from the cookie's username).
  • hooks/components/device-sign-in.tsx: in the Account tab, under the cookie.
  • Principles (CLAUDE.md): the two POST of the sign-in, and the handling of the pasted link (pasted by the person, state only, redeemed with dev-null.sh only, never asked for in the conversation, read, printed or logged).

Before marking ready

Only fakes have exercised this so far. A real round trip on dev-null.sh is needed, through claude --plugin-dir . on this branch: Sign in, Approve, copy the link, paste. It checks that the fingerprint passes /mobile/authorize, that the signature of the redemption verifies, and that the username comes back.

Not yet (next pull request)

  • Following, Latest and Trending read from the API instead of the web app. That also makes Trending stable across pages, and stops the reads from changing the default log on the site.
  • The README principles, the cookie warning (which still cites #130), and the Account layout.

Tests

  • tests/api.test.ts, tests/api-device.test.ts, tests/pkce.test.ts (RFC 7636 vector), tests/device-sign-in.test.ts.
  • tests/log-device.test.tsx, through the pane:
    • the key is created once and reused;
    • code, link and polling, slower on slow_down; approval kept; denial; Cancel;
    • a double press starts once, and a poll in flight leaves a newer sign-in alone;
    • the fallback: the approval link and its parameters, a pasted link redeemed with the verifier of the challenge and then forgotten, a link of another sign-in refused without a request, a double paste redeemed once, an approval cancelled during the redemption left alone;
    • the private key is never shown nor passed as an argument; no cookie is sent to the API.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF

A terminal signs in to the API as RFC 8628 says (dev-null-sh/dev-null.sh#585):
it starts with POST /api/v1/device-authorizations and polls
POST /api/v1/devices, both signed with the key to approve, the JSON body
included. api.ts sends them, and refuses to send anything else: the API
also takes commits, deletions and follows, which the plugin never sends.

The readers of the log take the API's get only.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
hooks/infrastructure/api-device.ts starts a sign-in with POST
/api/v1/device-authorizations, under the name of the device, and reads
the code to type, the page to type it on, how long it lasts and how
often to poll. It shows no page but those of dev-null.sh.

It then polls POST /api/v1/devices with the device code: the username of
whoever approved the device, or what /dev/null still waits for
(authorization_pending, slow_down), or why the sign-in ended
(access_denied, invalid_grant), as RFC 8628 names them; any other
refusal goes through.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
hooks/application/device-sign-in.ts starts the sign-in of the device,
under the name Claude Code, and keeps when it expires and how often to
ask, in milliseconds. Asked whether the device was approved, it gives
who approved it, or the sign-in still waiting, 5 seconds slower when
/dev/null asks to slow down, or why it ended: denied, expired, or
refused. Past its expiry, it asks /dev/null nothing.

Until dev-null-sh/dev-null.sh#585 is merged, /dev/null answers 404: it
says that /dev/null does not offer this sign-in yet.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
The Account tab offers, under the cookie, to approve the plugin once on
dev-null.sh: Sign in with dev-null.sh creates the key of the device the
first time, kept in the store (deviceKey, version 1), starts the sign-in
and shows the code to type and the page to type it on. A timer of its
own then asks /dev/null whether the device was approved, as often as it
says, until someone approves it, kept in the store too (deviceUser,
version 1), or the sign-in ends; Cancel stops it, and a /clear leaves
it.

Whoever approved the device is kept apart from the cookie's username:
Following still reads with the cookie until the log reads the API.

The private key goes to device-key.sh only, in its environment; the
requests to the API carry no cookie.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
@jubianchi
jubianchi changed the base branch from feat/api-log to main October 20, 2026 10:26
Until /dev/null offers the sign-in of a terminal (#585), the device can
be approved the way its app is (#130): dev-null.sh asks the person to
approve the key of the device, under its name, at /mobile/authorize,
with a PKCE challenge (RFC 7636), then sends them back to the app with a
one-time code, in a devnull://authorize link no terminal receives.

hooks/pkce.ts draws the verifier, its S256 challenge and the state of a
sign-in. hooks/infrastructure/api-device.ts builds the page to approve
on, reads the code of the link the person pastes, for that sign-in only,
and redeems it with POST /api/v1/devices and the verifier, which answers
who approved the device.

The principles say how that link is handled: pasted by the person, kept
in the state only, its code redeemed with /dev/null only.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
…ffers no other way

Until /dev/null offers the sign-in of a terminal (#585), it answers 404
to its start: the Account tab now falls back on the approval of the app
of /dev/null, instead of saying it cannot. It links to the page that
approves the key of the device as the app's, with a PKCE challenge drawn
for this sign-in, says how to get the devnull://authorize?code=… link
dev-null.sh sends back, which no terminal receives, and takes it pasted:
its code is redeemed with the verifier, and the device is approved as
with a code typed on dev-null.sh, for the same key.

hooks/application/device-sign-in.ts starts one sign-in or the other, and
approves the device with the link pasted, for that sign-in only. The
link and the verifier stay in the state, never in the store; the
component never sees the verifier.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
@jubianchi jubianchi changed the title feat(account): sign in the device with the device flow feat(account): sign in the device with the device flow, or as the app of /dev/null Oct 23, 2026
…es no POST to start

Production answers 405 to POST /api/v1/device-authorizations, not 404:
an address of the API takes other methods there. The Account tab said
it could not start signing in, instead of asking for the approval of
the device as the app of /dev/null. It now falls back on either answer.

🤖 Généré avec Claude Code
Claude-Session: https://claude.ai/code/session_01Fh4vxQUEH5yYphfgVatQKF
@jubianchi
jubianchi marked this pull request as ready for review October 23, 2026 19:07
@jubianchi
jubianchi merged commit 89d4607 into main Oct 23, 2026
8 checks passed
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