Repository navigation
feat: drive sessions from the bridge's web page, every command signed by the browser's own key - #198
Merged
Merged
Conversation
The bridge's web page is going to drive sessions, which means running commands on the machine, so a browser's commands must carry more than a bearer cookie. protocol::web is the spec for its stream: JSON arrays over one WebSocket (CHALLENGE, HELLO, READY/CLOSED, CMD/OK, MSG, PAGE/REPLY), every browser frame signed by a WebCrypto ECDSA P-256 key of the browser's own over the machine, the browser id, the connection's challenge, the seq and the body exactly as sent. BrowserKey reads the raw uncompressed point the page exports (refusing one off the curve), derives the browser's public id from its SHA-256, and verifies WebCrypto's r||s signatures with RustCrypto's p256 (pure Rust). A test vector made by WebCrypto proves the bridge reads what a browser writes. The decoder is total: the corpus gains webFrames, and the totality properties run the new decoder and key parser. Co-Authored-By: Claude Code <[email protected]>
A browser that a paired phone let in is now a principal of the engine: a client of the identity that approved it, addressed as Addressee::browser(identity, id), whose copies the runtime writes to the browser's stream instead of encrypting them. Copies to an identity reach its browsers with a stream open, live text only those watching that session (presence works as for a phone's client, with the same catch-up), never a terminal's output; a reply goes to the asking browser alone. browser_may_send names every command: a browser drives sessions and reads, and never sends what belongs to an identity (session-key, pair-request, web-sign-in: no browser lets in another), what moves a secret or a sign-in, a terminal command (the allowlist names devices), an upload or an agent-configuration write. The engine ignores the rest, and a command from a browser whose identity is no longer paired. Unpairing an identity ends the browsers it let in (Effect::WebEndBrowsers, which the runtime's page carries out). dispatch now takes the terminal's TerminalVia rather than the relay Via, the only thing it used it for. Co-Authored-By: Claude Code <[email protected]>
deymosh
force-pushed
the
docs/web-client-design
branch
from
November 17, 2026 22:55
e831800 to
8791311
Compare
A browser now signs in with a key: POST /api/sign-in carries the public half of a WebCrypto P-256 key, bound to the pending sign-in before any phone sees its code. Its id is the key's (protocol::web), and the key is kept in web-sessions.json beside the cookie's hash. GET /api/stream (a WebSocket on the page's path; every other upgrade is still a phone's direct link) is let through only for an allowed Host, the page's own Origin and a signed-in cookie. The browser then signs the connection's challenge and every frame after it, each with a growing seq; a frame that does not verify, or replays a seq, closes the stream. A verified command is checked against bridge_core::browser_may_send and handed to the engine as Input::WebCommand; the first and last stream of a browser make it a present client of its identity or not. What the engine sends a browser goes down its stream through the direct link's lane: never waited on, and a browser that stops reading is closed as busy. The cookie alone now reaches only /api/me (which also tells the page its machine and id), the QR and its own sign-out. The status, browsers, devices and config routes are gone: the heartbeat arrives on the stream, the browser list through the phone's own web-browsers commands, and devices/config as signed page requests. A browser signed in for 30 days also lapses after 7 days without signing anything. Only a signature moves lastSeenMs, so a copied cookie cannot keep it alive; web-browsers' expiresMs is when it actually lapses. A lapse, sign-out, revocation or unpairing closes its streams with the reason. Data: a web-sessions.json record from before browser keys has none, and is skipped on load; those browsers sign in again. Co-Authored-By: Claude Code <[email protected]>
The page becomes a client. At sign-in it makes a WebCrypto ECDSA P-256 key whose private half cannot be exported, keeps it in IndexedDB and sends the public half with the start; once the phone has let it in (and the key it holds is the one /api/me names), it opens the signed stream and signs every frame with it. A Sessions tab, first: the sessions beside the one open, its transcript (text, light markdown built as elements, thinking, tool calls with their input, result and diff, plans, to-dos, background tasks, notices), live text for the session on screen only, permission, question and plan cards answered in place, input (Enter sends), Stop, End, the mode picker and a new session on any agent and folder. A transcript is synced like the phone's (sync-request with the ranges held, acks batched) and survives a reload. Presence says which session is on screen and renews every five minutes, which also keeps an open tab's sign-in from idling out. Every string from the bridge is set as text: a transcript holds whatever a tool read. The Browsers, Devices and Settings tabs read through the stream. tests/web_page.rs drives the real runtime and agent host with a paired phone core and a browser played over pinned TLS: the key at sign-in, the phone's approval, a session created and answered over the stream, the phone seeing it, and the phone's sign-out closing the stream. It runs with the other end-to-end tests (codedeck e2e, CI). Its second test is a tool that holds such a bridge for a real browser; the page was driven through it in headless Chrome (sign-in, a session, input, a permission card, a reload, every tab, phone width) with no script or CSP error. Co-Authored-By: Claude Code <[email protected]>
A browser opening the bridge's web page meets a certificate warning, since the certificate is the bridge's own; whoever sits between the browser and the bridge can only be caught there. The phone already pins that certificate from the bridge's signed heartbeat, so the Browsers page now shows it before a code goes out: a scanned or typed code lands on "Check the page", with the SHA-256 written as browsers' certificate viewers write it (uppercase pairs, colon-separated, eight to a line) and the code, and only "They match: sign in" sends it. The machine summary carries the pin itself (directCertSha256) besides directPinned. The lifetime the page states follows the bridge's: signed in while used, ended by 7 idle days or 30 in all. Co-Authored-By: Claude Code <[email protected]>
docs/WEB-CLIENT.md is the design of the web page as a client: why the browser speaks the protocol's own JSON over TLS rather than Nostr, the threat model, the sign-in with a key of the browser's own bound before the phone approves, the stream and its signed input, what a browser may send, the lifetimes (7 idle days, 30 in all), why the page renders the wire itself rather than client-core in wasm, the cost, and the tests (with the tool that holds a bridge for a real browser). BRIDGE.md's web page section describes the page as it is now (sessions driven from the browser, the HTTPS routes a cookie still reaches, the stream caps); PROTOCOL.md gains the browser's stream and the new meaning of a browser's id and expiresMs; CLIENT.md the phone's certificate check; the README its line. CLAUDE.md: the signing rule names the browser as the one other signer, and the e2e runs include the web page's. Co-Authored-By: Claude Code <[email protected]>
deymosh
force-pushed
the
docs/web-client-design
branch
from
November 17, 2026 23:08
8791311 to
ed5538d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The bridge's web page becomes a client: a browser drives the bridge's sessions as the phone does. Its commands are signed by a key of its own that its page cannot hand out. This PR started as the design (docs only). At the maintainer's request it now carries the whole feature, one commit per layer:
protocol::web: the browser's stream (CHALLENGE / HELLO / READY / CLOSED / CMD / OK / MSG / PAGE / REPLY). The signed input binds the machine, the browser, the connection's challenge, a growingseqand the exact body text.BrowserKeyreads WebCrypto's raw P-256 point and verifies itsr‖ssignatures with RustCryptop256(pure Rust, new dependency). A WebCrypto-made test vector proves the bridge reads what a browser writes. The corpus gainswebFrames, and the totality properties run the new decoder.Addressee::browser). It gets copies like a phone's client: live text only for the session on screen, replies to itself alone.browser_may_sendnames every command. A browser drives sessions and reads; keys, other browsers' sign-ins, secrets, terminals, uploads and agent-configuration writes stay with the phone. Unpairing an identity ends its browsers.POST /api/sign-in, bound before the phone sees the code./api/streamis gated by Host, Origin and cookie, then every frame must verify with a growing seq. A cookie alone reaches only/api/me, the QR and its own sign-out. The status, browsers, devices and config routes are gone: those now come through the stream. 7 idle days (only a signature moveslastSeenMs) or 30 days in all end a browser. A browser that stops reading is closed, never waited on.tests/web_page.rs, an end-to-end test with a real runtime, agent host and paired phone core, run with the other e2e runs (codedeck e2e, CI).directCertSha256.docs/WEB-CLIENT.md: the design, the threat model, the stream, the allowlist, the lifetimes, rendering, cost and tests. BRIDGE, PROTOCOL, CLIENT and the README are brought in line. CLAUDE.md changes too: the signing rule now names the browser as the one other signer, and the e2e runs include the web page's.Decisions made beyond the agreed outline:
web-sign-inis unchanged on the wire.OKwas lost.nostrfeature-gated out ofprotocol, a wasm build in every release, and'wasm-unsafe-eval'in the CSP.WEB-CLIENT.mdgives the reasoning.Data change (no migration):
web-sessions.jsonrecords from before browser keys have no key and are skipped on load, so already signed-in browsers sign in again.web-browsers'idnow comes from the key, andexpiresMsis when the browser actually lapses.What review changed (folded into the commits)
session-failed, so the test now waits for the catalog and fails at once on a refusal.seqorder. The bridge closes that asbad-signatureand the browser would have been signed out. Frames are now signed and sent one at a time.#sessions/…hash breaking every render.Traffic cost
No new relay traffic and nothing for phones. A browser's copies are neither encrypted nor signed, live text goes only to its session on screen, and an open tab renews its presence every 5 minutes. The phones' links never wait on a browser.
Verification
./codedeck checkgreen (host typecheck/test/build; clippy, test, doc with-D warnings),./codedeck e2egreen (now includingweb_page), and./codedeck android test verifyPaparazziDebug lintDebug: 204 tests, lint "No issues found". I looked at each changed golden.crypto.subtlewith a non-extractable key works over a LAN address in Chrome (the warning bypassed by flag), and the key survives a reload through IndexedDB./favicon.ico.🤖 Generated with Claude Code