Remote security model primitives + shared server package

[nedtwigg]

What

Introduces the remote security model — the primitives that let a Client browser prove to a Host that it is an approved device operated by an authenticated user — plus the shared server-lib-common package and a minimal Hono server that will host them.

Design spec: docs/specs/remote-security-model.md.

Packages

• server-lib-common — the server-side counterpart to dor-lib-common. Runtime-agnostic (compiles into both a browser bundle and a Node process), zero runtime dependencies, "types": []. All crypto goes through globalThis.crypto (WebCrypto), so the same code runs on the Client and the Host.
• server — a Hono webserver. The app is built separately from the serve() entrypoint so routes can be tested via app.request() without binding a port; the route path and response shape live in server-lib-common so frontend and backend can't drift.

Security primitives (server-lib-common/src/security/)

Module	Role
deviceKey	Long-lived Client identity — a non-extractable ECDSA P-256 keypair; its raw public key is the Client's id everywhere in the model.
challenge	Freshness — unguessable (256-bit), fast-expiring, single-use Host challenges; consuming one removes it whether or not the rest of the attempt succeeds.
passkey	Fresh user presence — verifies a WebAuthn ES256 assertion; the Host stores only a hash of each paired passkey key, so a compromised Server can't substitute one.
acl	Authorization — each Host's own list of approved Clients; an approved Client is the pair of (passkey credential, device key), and authorize() owns that conjunction rule.
pairing	The only path into the ACL; its approve step models the local user approval on the Host — the Server can relay a request but can't grant access.
connection	authorizeConnection — the Host's final decision. Evaluates every layer (never short-circuits), consumes the challenge up front, and allows only when all pass.
ecdsa / bytes / webcrypto	Leaf helpers: DER↔raw signature conversion, base64url/UTF-8/constant-time byte ops, and minimal structural WebCrypto typings.

Key guarantees (enforced by tests)

• The Host is the final authority: a denied/pending pairing grants nothing; the Server can't pair on the user's behalf.
• A captured request can't be replayed — challenges are single-use and expire.
• Passkey and device key must sit on the same active record; each paired separately is not authorization.
• A compromised Server can't substitute a passkey (hash check) or connect for a different account (the Host re-checks the account binding itself).
• authorizeConnection never throws on attacker-controlled input — a malformed passkey key denies as passkey-key-mismatch rather than crashing.

Testing

node --test across every module, including security-guarantees.test.mjs — end-to-end scenarios covering each guarantee in the spec — driven by a simulated Client / Authenticator / Host harness. 111 tests, all passing, strict TypeScript build green.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	7a304ff
Status:	✅  Deploy successful!
Preview URL:	https://87749d07.mouseterm.pages.dev
Branch Preview URL:	https://security-model.mouseterm.pages.dev

View logs

[dormouse-bot]

Reviewed the remote security model end to end against the spec — the primitives are well-built and the guarantees are backed by genuinely adversarial tests. Replay protection (challenge burned up front, before any other work), the passkey∧device same-record conjunction, the passkey-key→stored-hash→assertion-signature binding chain, device-signature domain separation, and the WebAuthn checks (rpIdHash, origin allowlist, type, UP/UV flags, decoded-value challenge compare, ES256-only) all trace correctly, and verifyPasskeyAssertion / verifyDeviceChallengeSignature are carefully non-throwing.

One robustness observation inline on authorizeConnection, plus a minor packaging note below. Neither blocks; flagging for your judgment.

Minor: lib/package.json now depends on server-lib-common (workspace:*) and builds it in pretest, but nothing under lib/src imports it yet. If that's forward-wiring for the frontend to consume HELLO_ROUTE/the shared primitives, fine to leave; otherwise it's a currently-unused runtime dependency.

[dormouse-bot]

The module hardens malformed field content — a non-base64url passkey.publicKey denies as passkey-key-mismatch rather than crashing (the deliberate .catch(() => null) below), matching the "never throws on attacker-controlled input" guarantee in the PR description. But the structural access here isn't guarded: if request.passkey (or request.passkey.assertion) is missing or non-object, request.passkey.assertion.credentialId throws synchronously, and since authorizeConnection is async that surfaces as a rejected promise rather than an { allowed: false } decision.

There's no caller that hits this today (the server package is still hello-world), so it's forward-looking — but the natural HTTP handler is const request = await c.req.json(); return authorizeConnection(host, request), at which point request is unvalidated attacker JSON and a missing passkey becomes a 500 / unhandled rejection instead of a deny. Worth either a shape guard at the top of authorizeConnection or an explicit note that callers must validate structure before this point. Judgment call on where that boundary lives — flagging, not prescribing.

[nedtwigg]

we'll do validation like this in the handler

[dormouse-bot]

Sounds good — validating request shape in the handler is exactly the caller-side boundary I had in mind as the alternative to a guard inside authorizeConnection. That keeps this function's contract as "well-formed ConnectionRequest in, decision out" and puts untrusted-JSON rejection at the trust boundary where the 400 belongs. Resolved from my side.