@gotcos/glasses-server 7.0.7 → 7.0.18

package/server/lib/web-key-authority.ts

@@ -0,0 +1,372 @@
+// Server acceptance of a signed Control Web turn (6.99.31, plan §4.5). Behind
+// COS_WEB_KEY_AUTHORITY (default off). Off, nothing here is consulted and a web turn is exactly
+// what 6.99.29 made it: recorded, never vouched (`web_cookie_derivable_from_token`).
+//
+// A web turn is vouched (`authority: 'web-key'`) only when EVERY check below holds. Any failure
+// delivers the turn unvouched with the specific reason, never refuses it outright: the words were
+// typed by someone holding a valid cookie, and the receiving agent still sees them as a request.
+//
+//   - the request already passed the full web cookie path with no token and a non-local socket
+//     (G2TurnProvenance.originOf decides that; only then is an envelope even read)
+//   - the envelope is exactly `cos-web-turn/1`, canonical JCS bytes, closed scope
+//   - an anchor is registered; `aud` is this install; `origin` is the expected https origin and is
+//     the Origin the browser stamped on this very request
+//   - the key is enrolled with a valid anchorSig, is not revoked; `kver` and `epoch` are current
+//   - the P-256 signature verifies over those bytes
+//   - `iat`/`exp` within bounds (exp - iat <= 15 min, iat at most 60 s ahead, now <= exp)
+//   - not a fork, and provider/session (and binding, when signed) equal the route's real target
+//   - the turn id, the exact words (CRLF to LF only) and the ordered attachment manifest match
+//   - an `approve` scope matches an open packet byte for byte, the packet was created by the very
+//     session the envelope names (review B4), and the action is enabled (install or publish)
+//   - the anchor has a valid bootstrap record and is past its 24 h maturity (review B1)
+//   - served-asset integrity is enabled AND its last check passed (review W1)
+//   - a user-verified WebAuthn assertion by the anchored passkey over sha256(envelope JCS) (B2)
+//   - the single-use server nonce is unspent (spent last, so a failing envelope never burns it)
+
+import { createHash } from 'node:crypto'
+import { readSwitch } from './env-switch.js'
+import { b64url, canonicalBytes, fromB64url, parseEnvelopeHeader, sha256Hex, verifyP1363 } from './web-key-envelope.js'
+import type { WebKeyNonces, WebKeyPackets, WebKeyRegistry } from './web-key-registry.js'
+import { webKeyRpId } from './web-key-origin.js'
+import { parsePasskeyHeader, turnPasskeyChallenge, verifyPasskeyAssertion, WEB_PASSKEY_HEADER, type PasskeyAssertion } from './web-key-passkey.js'
+import {
+  signedWordsText, WEB_TURN_IAT_SKEW_S, WEB_TURN_MAX_LIFETIME_S, type WebTurnEnvelope, type WebTurnScope,
+} from '../../shared/web-turn-envelope.js'
+
+export const WEB_ENVELOPE_HEADER = 'x-cos-web-envelope'
+export const WEB_SIGNATURE_HEADER = 'x-cos-web-sig'
+/** Exact scoped install/publish only. Push-main remains refused (`approve_action_not_enabled`). */
+export const WEB_KEY_ENABLED_APPROVE_ACTIONS: ReadonlySet<string> = new Set(['install', 'publish'])
+
+/** The served-asset integrity state the authority reads (review W1). Null: integrity is not running. */
+export interface IntegrityReport { enabled: boolean; lastCheckOk: boolean; checkedAt: number | null; manifestSha256: string | null }
+
+/** The ordered attachment manifest's digest, the same function the queue seal uses (g2-turn-provenance attachmentsDigest). */
+export function manifestDigest(manifest: ReadonlyArray<{ id: string; sha256: string }>): string {
+  if (manifest.length === 0) return ''
+  return createHash('sha256').update(JSON.stringify(manifest.map(e => [e.id, e.sha256])), 'utf8').digest('hex')
+}
+
+export function webKeyAuthorityEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return readSwitch(env.COS_WEB_KEY_AUTHORITY, false)
+}
+
+/**
+ * 7.0.9: COS_WEB_KEY_ANCHOR_BOOTSTRAP (default off, read the same way as COS_WEB_KEY_AUTHORITY).
+ * On with the authority off, ONLY GET /api/web-key/status (token only, its own reply shape) and
+ * POST /api/web-key/anchor answer, so COS Control can register the Mac's anchor and start its 24 h
+ * clock. Nothing else changes: enabled() stays false, so no enrollment, key list or revoke route,
+ * no nonce, packet or handoff, no 3144 signer listener, no extra cookie port, no integrity default
+ * and no vouched turn. With the authority on, this switch is irrelevant.
+ */
+export function webKeyAnchorBootstrapEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return readSwitch(env.COS_WEB_KEY_ANCHOR_BOOTSTRAP, false)
+}
+
+/** Which web-key surface is served: everything (`authority`), anchor status and registration only (`bootstrap`), or none (`off`). */
+export type WebKeyMode = 'authority' | 'bootstrap' | 'off'
+
+/** The raw headers of a web request that carries an envelope; judged only once the route knows its target. */
+export interface WebKeyCandidate { envelope: string; signature: string | null; requestOrigin: string | null; passkey?: string | null }
+
+/** What a vouched web-key turn carries: self-proving (the envelope bytes and the signature). */
+export interface WebKeyProof {
+  kid: string
+  kver: number
+  epoch: number
+  iat: number
+  exp: number
+  authId: string
+  /** base64url of the exact JCS bytes the phone signed. */
+  envelope: string
+  signature: string
+  scope: WebTurnScope
+  wordsSha256: string
+  provider: string
+  sessionId: string
+  /** The user-verified WebAuthn assertion over sha256(envelope JCS) (review B2). */
+  passkey: PasskeyAssertion
+  /** Served-asset integrity when this turn was accepted (review W1). */
+  integrity: IntegrityReport
+}
+
+/** What the route knows when it judges: the real destination, the exact words and the files. */
+export interface WebKeyContext {
+  provider: string
+  /** The actual receiving session. Null: unknown (a new session), never vouched. */
+  sessionId: string | null
+  bindingId?: string | null
+  turnId: string
+  /** The words exactly as received, BEFORE any files block. */
+  words: string
+  /** The ordered manifest (id + content hash). Null: the files could not be read (unvouched). */
+  attachments: ReadonlyArray<{ id: string; sha256: string }> | null
+  fork?: boolean
+}
+
+export type WebKeyVerdict = { ok: true; proof: WebKeyProof } | { ok: false; reason: string }
+
+export function wordsDigest(words: string): { sha256: string; len: number } {
+  const text = Buffer.from(signedWordsText(words), 'utf8')
+  return { sha256: createHash('sha256').update(text).digest('hex'), len: text.length }
+}
+
+function headerValue(headers: Record<string, string | string[] | undefined>, name: string): string | null {
+  const raw = headers[name]
+  const v = Array.isArray(raw) ? raw[0] : raw
+  return typeof v === 'string' && v.length > 0 ? v.trim() : null
+}
+
+/** The envelope headers of a request, or null when it carries none. */
+export function webKeyCandidateOf(headers: Record<string, string | string[] | undefined>): WebKeyCandidate | null {
+  const envelope = headerValue(headers, WEB_ENVELOPE_HEADER)
+  if (envelope === null) return null
+  return { envelope, signature: headerValue(headers, WEB_SIGNATURE_HEADER), requestOrigin: headerValue(headers, 'origin'), passkey: headerValue(headers, WEB_PASSKEY_HEADER) }
+}
+
+export interface WebKeyAuthorityDeps {
+  registry: WebKeyRegistry
+  nonces: WebKeyNonces
+  packets: WebKeyPackets
+  /** This Mac's MagicDNS name (aud is bound to it). Null: aud is unknown and nothing is vouched. */
+  selfDnsName: () => string | null
+  /** The one origin a phone signs from: webKeySignerOrigin() (`https://<selfDnsName>:3144`). Null: none. */
+  expectedOrigin: () => string | null
+  /** Served-asset integrity (review W1). Absent or null: integrity is off, so nothing is vouched. */
+  integrity?: () => IntegrityReport | null
+  enabled?: () => boolean
+  /** 7.0.9: the anchor bootstrap switch. Absent: COS_WEB_KEY_ANCHOR_BOOTSTRAP, read at call time. */
+  bootstrap?: () => boolean
+  now?: () => number
+}
+
+export class WebKeyAuthority {
+  private readonly now: () => number
+
+  constructor(readonly deps: WebKeyAuthorityDeps) {
+    this.now = deps.now ?? Date.now
+  }
+
+  enabled(): boolean {
+    try { return (this.deps.enabled ?? webKeyAuthorityEnabled)() } catch { return false }
+  }
+
+  /**
+   * 7.0.9: the routes' mode. The authority wins; the bootstrap switch matters only with it off.
+   * Never consulted by acceptance, recheck or review: those read enabled() alone.
+   */
+  mode(): WebKeyMode {
+    if (this.enabled()) return 'authority'
+    let bootstrap = false
+    try { bootstrap = (this.deps.bootstrap ?? webKeyAnchorBootstrapEnabled)() === true } catch { bootstrap = false }
+    return bootstrap ? 'bootstrap' : 'off'
+  }
+
+  get registry(): WebKeyRegistry { return this.deps.registry }
+  get nonces(): WebKeyNonces { return this.deps.nonces }
+  get packets(): WebKeyPackets { return this.deps.packets }
+
+  /** The integrity state now, or a refusal reason: off or failing means no vouch (review W1). */
+  integrityNow(): { ok: true; report: IntegrityReport } | { ok: false; reason: 'integrity_off' | 'integrity_failed'; report: IntegrityReport | null } {
+    let report: IntegrityReport | null = null
+    try { report = this.deps.integrity ? this.deps.integrity() : null } catch { report = null }
+    if (!report || report.enabled !== true) return { ok: false, reason: 'integrity_off', report }
+    if (report.lastCheckOk !== true) return { ok: false, reason: 'integrity_failed', report }
+    return { ok: true, report: { enabled: true, lastCheckOk: true, checkedAt: report.checkedAt ?? null, manifestSha256: report.manifestSha256 ?? null } }
+  }
+
+  /** Judge one candidate against the route's real target. Never throws (a throw reads as a refusal). */
+  accept(candidate: WebKeyCandidate, ctx: WebKeyContext): WebKeyVerdict {
+    try { return this.acceptInner(candidate, ctx) } catch (error) {
+      console.error(`[web-key] accept failed: ${error instanceof Error ? error.message : error}`)
+      return { ok: false, reason: 'web_key_check_failed' }
+    }
+  }
+
+  private acceptInner(candidate: WebKeyCandidate, ctx: WebKeyContext): WebKeyVerdict {
+    if (!this.enabled()) return { ok: false, reason: 'web_key_authority_off' }
+    if (!candidate.signature) return { ok: false, reason: 'signature_missing' }
+    const parsed = parseEnvelopeHeader(candidate.envelope)
+    if (!parsed.ok) return { ok: false, reason: parsed.reason }
+    const env: WebTurnEnvelope = parsed.envelope
+    const registry = this.deps.registry
+    const anchorRefusal = registry.anchorRefusal()
+    if (anchorRefusal) return { ok: false, reason: anchorRefusal }
+    if (!registry.anchorMature()) return { ok: false, reason: 'anchor_too_new' }
+    const integrity = this.integrityNow()
+    if (!integrity.ok) return { ok: false, reason: integrity.reason }
+    const selfDns = this.deps.selfDnsName()
+    const aud = registry.aud(selfDns)
+    if (!aud) return { ok: false, reason: 'aud_unavailable' }
+    if (env.aud !== aud) return { ok: false, reason: 'aud_mismatch' }
+    const origin = this.deps.expectedOrigin()
+    if (!origin) return { ok: false, reason: 'origin_unavailable' }
+    if (env.origin !== origin || candidate.requestOrigin !== origin) return { ok: false, reason: 'origin_mismatch' }
+    const state = registry.entryState(env.kid, selfDns)
+    if (!state.ok) return { ok: false, reason: state.reason }
+    if (env.kver !== state.entry.kver) return { ok: false, reason: 'key_version_stale' }
+    if (env.epoch !== registry.epoch()) return { ok: false, reason: 'epoch_stale' }
+    if (!verifyP1363(state.key, parsed.bytes, candidate.signature)) return { ok: false, reason: 'signature_invalid' }
+    // Review B2: the phone key alone vouches nothing. A user-verified passkey assertion by the
+    // anchored passkey, over sha256(these exact envelope bytes), from this exact origin.
+    if (!candidate.passkey) return { ok: false, reason: 'passkey_missing' }
+    const assertion = parsePasskeyHeader(candidate.passkey)
+    if (!assertion) return { ok: false, reason: 'passkey_malformed' }
+    const rpId = webKeyRpId(selfDns)
+    if (!rpId) return { ok: false, reason: 'aud_unavailable' }
+    const pk = verifyPasskeyAssertion(assertion, {
+      challenge: turnPasskeyChallenge(parsed.bytes), origin, rpId,
+      credentialId: state.entry.approval.passkey_credential_id, publicKey: state.passkeyKey,
+    })
+    if (!pk.ok) return { ok: false, reason: pk.reason }
+    const nowS = Math.floor(this.now() / 1000)
+    if (env.exp <= env.iat || env.exp - env.iat > WEB_TURN_MAX_LIFETIME_S) return { ok: false, reason: 'lifetime_invalid' }
+    if (env.iat > nowS + WEB_TURN_IAT_SKEW_S) return { ok: false, reason: 'iat_in_future' }
+    if (nowS > env.exp) return { ok: false, reason: 'signature_expired' }
+    // Forks and unknown destinations are delivered unvouched (the receiving child has no id yet).
+    if (env.fork || ctx.fork === true) return { ok: false, reason: 'fork_destination_unbound' }
+    if (ctx.sessionId === null) return { ok: false, reason: 'destination_unbound' }
+    if (env.provider !== ctx.provider || env.sessionId !== ctx.sessionId) return { ok: false, reason: 'destination_mismatch' }
+    if (env.bindingId !== null && env.bindingId !== (ctx.bindingId ?? null)) return { ok: false, reason: 'destination_mismatch' }
+    if (env.turnId !== ctx.turnId) return { ok: false, reason: 'turn_id_mismatch' }
+    const words = wordsDigest(ctx.words)
+    if (env.wordsSha256 !== words.sha256 || env.wordsLen !== words.len) return { ok: false, reason: 'words_changed' }
+    // The footer step trims trailing whitespace before it appends (footed()), so words ending in
+    // whitespace could never verify downstream. Refuse them here: the signer trims before hashing.
+    if (/[\t\n\v\f\r ]$/.test(signedWordsText(ctx.words))) return { ok: false, reason: 'words_trailing_whitespace' }
+    if (ctx.attachments === null) return { ok: false, reason: 'attachments_unsealable' }
+    if (env.attachments.length !== ctx.attachments.length
+      || env.attachments.some((a, i) => a.id !== ctx.attachments![i].id || a.sha256 !== ctx.attachments![i].sha256)) {
+      return { ok: false, reason: 'attachments_changed' }
+    }
+    let packetSha: string | null = null
+    if (env.scope.kind === 'approve') {
+      const scope = env.scope
+      const packet = this.deps.packets.get(scope.packetSha256)
+      if (!packet) return { ok: false, reason: 'packet_unknown' }
+      const bytes = canonicalBytes(packet)
+      if (!bytes || sha256Hex(bytes) !== scope.packetSha256) return { ok: false, reason: 'packet_mismatch' }
+      if (packet.action !== scope.action || packet.artifact !== scope.artifact || packet.version !== scope.version
+        || packet.digest !== scope.digest || packet.channel !== scope.channel) {
+        return { ok: false, reason: 'packet_mismatch' }
+      }
+      // Review B4: only the session that created the packet (request context, never body) may be
+      // the one this approval is delivered to.
+      if (packet.provider !== env.provider || packet.sessionId !== env.sessionId) return { ok: false, reason: 'packet_session_mismatch' }
+      if (!WEB_KEY_ENABLED_APPROVE_ACTIONS.has(scope.action)) return { ok: false, reason: 'approve_action_not_enabled' }
+      packetSha = scope.packetSha256
+    }
+    // authId = sha256(signature bytes) (plan §4.4): the one consume key for this authorization.
+    const authId = sha256Hex(fromB64url(candidate.signature) as Buffer)
+    // LAST: a failing envelope never burns its nonce, and a replay of a good one finds it spent.
+    const spent = this.deps.nonces.consume(env.nonce, authId)
+    if (spent !== 'ok') return { ok: false, reason: spent }
+    if (packetSha !== null) this.deps.packets.close(packetSha)
+    registry.noteUsed(env.kid)
+    return {
+      ok: true,
+      proof: {
+        kid: env.kid, kver: env.kver, epoch: env.epoch, iat: env.iat, exp: env.exp, authId,
+        envelope: b64url(parsed.bytes), signature: candidate.signature, scope: env.scope, wordsSha256: env.wordsSha256,
+        provider: env.provider, sessionId: env.sessionId, passkey: assertion, integrity: integrity.report,
+      },
+    }
+  }
+
+  /**
+   * At a queue drain or a Cursor Stop hand-off (plan §4.5): the parked approval still holds only
+   * while the flag is on, the signature has not expired (never re-dated), the key is not revoked,
+   * the epoch has not moved, integrity still passes, the words are still the signed words, and the
+   * parked files (the seal's manifest digest) are still the signed manifest. Null when it holds.
+   */
+  recheck(proof: WebKeyProof, words: string, attachmentsDigest: string): string | null {
+    try {
+      if (!this.enabled()) return 'web_key_authority_off'
+      if (Math.floor(this.now() / 1000) > proof.exp) return 'signature_expired'
+      const state = this.deps.registry.entryState(proof.kid, this.deps.selfDnsName())
+      if (!state.ok) return state.reason
+      if (proof.epoch !== this.deps.registry.epoch()) return 'epoch_stale'
+      const integrity = this.integrityNow()
+      if (!integrity.ok) return integrity.reason
+      if (wordsDigest(words).sha256 !== proof.wordsSha256) return 'words_changed'
+      const parsed = parseEnvelopeHeader(proof.envelope)
+      if (!parsed.ok) return parsed.reason
+      if (parsed.envelope.scope.kind === 'approve' && !WEB_KEY_ENABLED_APPROVE_ACTIONS.has(parsed.envelope.scope.action)) return 'approve_action_not_enabled'
+      // Review note "drain checks words, not files": the signed manifest must equal the parked one.
+      if (manifestDigest(parsed.envelope.attachments) !== attachmentsDigest) return 'attachments_changed'
+      return null
+    } catch {
+      return 'web_key_check_failed'
+    }
+  }
+
+  /**
+   * For GET /api/g2-turns/:id: re-verify a stored proof (it is self-proving, so a record read back
+   * from disk can still vouch), and say whether the key is revoked now. Null reason: it verifies.
+   * `record` is the ledger row's own fields: every one must equal the signed envelope (review B3),
+   * so a ledger edit cannot pair a genuine envelope with another session, turn or text.
+   */
+  review(proof: WebKeyProof, record: { turnId: string; target: { provider: string; sessionId: string } }): { reason: string | null; entry: Record<string, unknown> | null; facts: Record<string, unknown> | null } {
+    try {
+      if (!this.enabled()) return { reason: 'web_key_authority_off', entry: null, facts: null }
+      const parsed = parseEnvelopeHeader(proof.envelope)
+      if (!parsed.ok) return { reason: parsed.reason, entry: null, facts: null }
+      const env = parsed.envelope
+      const registry = this.deps.registry
+      const stored = registry.entry(env.kid)
+      const entry = stored ? {
+        kid: stored.kid, spki: stored.spki, passkeySpki: stored.passkeySpki, kver: stored.kver, label: stored.label,
+        approval: stored.approval, anchorSig: stored.anchorSig, ...(typeof stored.revokedAt === 'number' ? { revokedAt: stored.revokedAt } : {}),
+      } : null
+      const anchor = registry.anchor()
+      const integrity = this.integrityNow()
+      const at = this.now()
+      const facts: Record<string, unknown> = {
+        aud: env.aud,
+        wordsSha256: env.wordsSha256,
+        anchor: anchor ? { spkiSha256: anchor.spkiSha256, fingerprint: anchor.fingerprint, setAt: anchor.setAt, ageMs: Math.max(0, at - anchor.setAt), mature: registry.anchorMature() } : null,
+        epoch: registry.epoch(),
+        revoked: registry.revocations(),
+        revocationDigest: registry.revocationDigest(),
+        integrity: integrity.report ?? { enabled: false, lastCheckOk: false, checkedAt: null, manifestSha256: null },
+        integrityAtAccept: proof.integrity ?? null,
+        consumeKeys: [`turn:${env.turnId}`, `web:${env.aud}:${proof.authId}`],
+      }
+      const sigBytes = fromB64url(proof.signature)
+      const same = (a: unknown, b: unknown): boolean => canonicalBytes(a)?.equals(canonicalBytes(b) ?? Buffer.alloc(0)) === true
+      if (record.turnId !== env.turnId || record.target?.provider !== env.provider || record.target?.sessionId !== env.sessionId
+        || proof.kid !== env.kid || proof.kver !== env.kver || proof.epoch !== env.epoch || proof.iat !== env.iat || proof.exp !== env.exp
+        || proof.provider !== env.provider || proof.sessionId !== env.sessionId || proof.wordsSha256 !== env.wordsSha256
+        || !same(proof.scope, env.scope) || !sigBytes || proof.authId !== sha256Hex(sigBytes)) {
+        return { reason: 'record_envelope_mismatch', entry, facts }
+      }
+      const nowS = Math.floor(at / 1000)
+      if (env.exp <= env.iat || env.exp - env.iat > WEB_TURN_MAX_LIFETIME_S) return { reason: 'lifetime_invalid', entry, facts }
+      if (env.iat > nowS + WEB_TURN_IAT_SKEW_S) return { reason: 'iat_in_future', entry, facts }
+      if (nowS > env.exp) return { reason: 'signature_expired', entry, facts }
+      if (env.fork) return { reason: 'fork_destination_unbound', entry, facts }
+      if (env.scope.kind === 'approve' && !WEB_KEY_ENABLED_APPROVE_ACTIONS.has(env.scope.action)) return { reason: 'approve_action_not_enabled', entry, facts }
+      const refusal = registry.anchorRefusal()
+      if (refusal) return { reason: refusal, entry, facts }
+      if (!registry.anchorMature()) return { reason: 'anchor_too_new', entry, facts }
+      if (env.aud !== registry.aud(this.deps.selfDnsName())) return { reason: 'aud_mismatch', entry, facts }
+      if (env.origin !== this.deps.expectedOrigin()) return { reason: 'origin_mismatch', entry, facts }
+      const state = registry.entryState(env.kid, this.deps.selfDnsName())
+      if (!state.ok) return { reason: state.reason, entry, facts }
+      if (!verifyP1363(state.key, parsed.bytes, proof.signature)) return { reason: 'signature_invalid', entry, facts }
+      if (env.epoch !== registry.epoch()) return { reason: 'epoch_stale', entry, facts }
+      const rpId = webKeyRpId(this.deps.selfDnsName())
+      if (!proof.passkey || !rpId) return { reason: 'passkey_missing', entry, facts }
+      const pk = verifyPasskeyAssertion(proof.passkey, {
+        challenge: turnPasskeyChallenge(parsed.bytes), origin: env.origin, rpId,
+        credentialId: state.entry.approval.passkey_credential_id, publicKey: state.passkeyKey,
+      })
+      if (!pk.ok) return { reason: pk.reason, entry, facts }
+      if (!proof.integrity || proof.integrity.enabled !== true || proof.integrity.lastCheckOk !== true) return { reason: 'integrity_off', entry, facts }
+      if (!integrity.ok) return { reason: integrity.reason, entry, facts }
+      return { reason: null, entry, facts }
+    } catch {
+      return { reason: 'web_key_check_failed', entry: null, facts: null }
+    }
+  }
+}

package/server/lib/web-key-envelope.ts

@@ -0,0 +1,98 @@
+// Crypto for the enrolled phone key (6.99.31, plan §4.2-4.4). node:crypto only.
+//
+// Keys are ECDSA P-256 public keys as SubjectPublicKeyInfo DER, carried base64url. Signatures
+// are IEEE P1363 (r||s, 64 bytes): what WebCrypto emits on the phone and what CryptoKit's
+// `rawRepresentation` gives for the Secure Enclave anchor on the Mac. Every message signed in
+// this protocol is the JCS (RFC 8785) encoding of one closed-shape object (shared/web-turn-envelope.ts).
+
+import { createHash, createPublicKey, verify, type KeyObject } from 'node:crypto'
+import { canonicalJson, parseWebTurnEnvelope, type WebTurnEnvelope } from '../../shared/web-turn-envelope.js'
+
+const B64URL_RE = /^[A-Za-z0-9_-]*$/
+
+export function b64url(buf: Buffer | Uint8Array): string {
+  return Buffer.from(buf).toString('base64url')
+}
+
+/** Strict base64url (no padding, no other alphabet). Null on anything else. */
+export function fromB64url(s: unknown): Buffer | null {
+  if (typeof s !== 'string' || !B64URL_RE.test(s) || s.length % 4 === 1) return null
+  return Buffer.from(s, 'base64url')
+}
+
+export function sha256Hex(data: Buffer | string): string {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+/** A P-256 public key from base64url SPKI DER, or null (wrong curve, not EC, garbage). */
+export function parseP256Spki(spkiB64url: unknown): { key: KeyObject; der: Buffer } | null {
+  const der = fromB64url(spkiB64url)
+  if (!der || der.length < 60 || der.length > 200) return null
+  try {
+    const key = createPublicKey({ key: der, format: 'der', type: 'spki' })
+    if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') return null
+    // Re-export so a key with trailing bytes or a non-canonical encoding is refused.
+    const canonical = key.export({ format: 'der', type: 'spki' }) as Buffer
+    if (!canonical.equals(der)) return null
+    return { key, der }
+  } catch {
+    return null
+  }
+}
+
+/** `kid = base64url(sha256(SPKI))[0..22]` (plan §4.2). */
+export function kidOfSpki(der: Buffer): string {
+  return b64url(createHash('sha256').update(der).digest()).slice(0, 22)
+}
+
+/** The fingerprint people compare: the first 16 hex of sha256(SPKI), upper case, 4 groups of 4. */
+export function fingerprintOfSpki(der: Buffer): string {
+  const hex = sha256Hex(der).slice(0, 16).toUpperCase()
+  return `${hex.slice(0, 4)}-${hex.slice(4, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}`
+}
+
+/** The 6-digit SAS both screens show: sha256(challenge || spki), first 4 bytes mod 10^6. */
+export function sasOf(challenge: Buffer, spkiDer: Buffer): string {
+  const digest = createHash('sha256').update(challenge).update(spkiDer).digest()
+  return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, '0')
+}
+
+/** ECDSA P-256 / SHA-256 over `message`, signature P1363 r||s. Never throws. */
+export function verifyP1363(key: KeyObject, message: Buffer | string, sigB64url: unknown): boolean {
+  const sig = fromB64url(sigB64url)
+  if (!sig || sig.length !== 64) return false
+  try {
+    return verify('sha256', typeof message === 'string' ? Buffer.from(message, 'utf8') : message, { key, dsaEncoding: 'ieee-p1363' }, sig)
+  } catch {
+    return false
+  }
+}
+
+/** The JCS bytes of a closed-shape object, or null when it is not signable. */
+export function canonicalBytes(value: unknown): Buffer | null {
+  try { return Buffer.from(canonicalJson(value), 'utf8') } catch { return null }
+}
+
+/** The largest envelope header accepted (base64url of the JCS bytes). */
+export const WEB_ENVELOPE_HEADER_MAX = 12 * 1024
+
+export type EnvelopeParse =
+  | { ok: true; envelope: WebTurnEnvelope; bytes: Buffer }
+  | { ok: false; reason: 'envelope_malformed' | 'envelope_version_unknown' | 'scope_not_allowed' | 'envelope_not_canonical' }
+
+/**
+ * The `x-cos-web-envelope` header: base64url of the envelope's JCS bytes. Its bytes must already
+ * be canonical (one message, one signable form), and its shape exactly `cos-web-turn/1`.
+ */
+export function parseEnvelopeHeader(header: unknown): EnvelopeParse {
+  if (typeof header !== 'string' || header.length === 0 || header.length > WEB_ENVELOPE_HEADER_MAX) return { ok: false, reason: 'envelope_malformed' }
+  const bytes = fromB64url(header)
+  if (!bytes) return { ok: false, reason: 'envelope_malformed' }
+  let parsed: unknown
+  try { parsed = JSON.parse(bytes.toString('utf8')) } catch { return { ok: false, reason: 'envelope_malformed' } }
+  const shape = parseWebTurnEnvelope(parsed)
+  if (!shape.ok) return shape
+  const canonical = canonicalBytes(shape.envelope)
+  if (!canonical || !canonical.equals(bytes)) return { ok: false, reason: 'envelope_not_canonical' }
+  return { ok: true, envelope: shape.envelope, bytes }
+}

package/server/lib/web-key-handoff.ts

@@ -0,0 +1,135 @@
+// The handoff from Control Web (3143) to the phone key signer (3144) (6.99.31, review W2). Behind
+// COS_WEB_KEY_AUTHORITY (default off; the routes in routes/web-key.ts fall through when it is off).
+//
+// HOW IT WORKS. The composer on 3143 posts the turn it wants approved (words, binding, its turn id).
+// The server resolves the real destination from the binding and keeps it here under a random id for
+// two minutes. The composer then NAVIGATES (top level, never a frame or a message) to
+// `https://<host>:3144/#h=<id>`. The signer page claims the id once, from its own origin, and shows
+// exactly what it will sign. The words never travel in a URL; the id is in the fragment, which is
+// not sent to any server and not in a Referer.
+//
+// WHAT IT DOES NOT DO. A handoff is not authority: a cookie holder (so any token holder) can create
+// one. Authority comes only from the phone's tap, its key and Face ID over the envelope the signer
+// builds and shows from these exact bytes.
+
+import { randomBytes } from 'node:crypto'
+import { parseWebApprovalPacket, parseWebTurnScope, type WebApprovalPacket, type WebTurnScope } from '../../shared/web-turn-envelope.js'
+import { canonicalBytes, sha256Hex } from './web-key-envelope.js'
+
+export const WEB_KEY_HANDOFF_TTL_MS = 120_000
+export const WEB_KEY_HANDOFF_MAX_OPEN = 8
+/** The longest words a phone approval carries (the turn route takes more; a phone screen should not). */
+export const WEB_KEY_HANDOFF_MAX_WORDS = 8_000
+
+const TURN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/
+const BINDING_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/
+const OPAQUE = /^[A-Za-z0-9_.:-]{1,256}$/
+
+/** The turn request the signer will post, minus the words (they travel beside it). */
+export interface SignHandoffTurn {
+  bindingId: string
+  epoch: number
+  targetKey: string
+  clientTurnId: string
+  acknowledgedRevision?: string
+  boundTo?: string
+}
+
+export interface SignHandoffRequest {
+  words: string
+  turn: SignHandoffTurn
+  packetSha256: string | null
+}
+
+/** What the signer is told, exactly once. */
+export interface SignHandoffView {
+  handoffId: string
+  exp: number
+  words: string
+  provider: string
+  sessionId: string
+  bindingId: string
+  turn: SignHandoffTurn
+  scope: WebTurnScope
+  /** Full canonical preimage of an approval packet, so the phone can verify and display it. */
+  packet: WebApprovalPacket | null
+  attachments: []
+}
+
+export type HandoffParse = { ok: true; request: SignHandoffRequest } | { ok: false; reason: 'invalid_request' | 'attachments_not_signable' | 'words_too_long' }
+
+/** The composer's body: { bindingId, epoch, targetKey, clientTurnId, prompt, acknowledgedRevision?, boundTo?, packetSha256? }. */
+export function parseHandoffRequest(body: unknown): HandoffParse {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) return { ok: false, reason: 'invalid_request' }
+  const b = body as Record<string, unknown>
+  // Files cannot be signed until the shared files block exists (contract section 6): refuse, never drop.
+  if (b.attachmentIds !== undefined && !(Array.isArray(b.attachmentIds) && b.attachmentIds.length === 0)) return { ok: false, reason: 'attachments_not_signable' }
+  if (typeof b.prompt !== 'string' || b.prompt.trim().length === 0) return { ok: false, reason: 'invalid_request' }
+  if (b.prompt.length > WEB_KEY_HANDOFF_MAX_WORDS) return { ok: false, reason: 'words_too_long' }
+  if (typeof b.bindingId !== 'string' || !BINDING_ID.test(b.bindingId)) return { ok: false, reason: 'invalid_request' }
+  if (!Number.isSafeInteger(b.epoch) || (b.epoch as number) < 1) return { ok: false, reason: 'invalid_request' }
+  if (typeof b.targetKey !== 'string' || b.targetKey.length === 0 || b.targetKey.length > 512) return { ok: false, reason: 'invalid_request' }
+  if (typeof b.clientTurnId !== 'string' || !TURN_ID.test(b.clientTurnId)) return { ok: false, reason: 'invalid_request' }
+  for (const k of ['acknowledgedRevision', 'boundTo'] as const) {
+    if (b[k] !== undefined && b[k] !== null && (typeof b[k] !== 'string' || !OPAQUE.test(b[k] as string))) return { ok: false, reason: 'invalid_request' }
+  }
+  if (b.packetSha256 !== undefined && b.packetSha256 !== null && (typeof b.packetSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(b.packetSha256))) return { ok: false, reason: 'invalid_request' }
+  const turn: SignHandoffTurn = { bindingId: b.bindingId, epoch: b.epoch as number, targetKey: b.targetKey, clientTurnId: b.clientTurnId }
+  if (typeof b.acknowledgedRevision === 'string') turn.acknowledgedRevision = b.acknowledgedRevision
+  if (typeof b.boundTo === 'string') turn.boundTo = b.boundTo
+  return { ok: true, request: { words: b.prompt, turn, packetSha256: typeof b.packetSha256 === 'string' ? b.packetSha256 : null } }
+}
+
+interface OpenHandoff { view: SignHandoffView; claimed: boolean }
+
+export type HandoffClaim = { ok: true; handoff: SignHandoffView } | { ok: false; reason: 'handoff_unknown' | 'handoff_expired' | 'handoff_claimed' }
+
+export class WebKeySignHandoffs {
+  private readonly open = new Map<string, OpenHandoff>()
+
+  constructor(private readonly now: () => number = Date.now, private readonly random: (n: number) => Buffer = randomBytes) {}
+
+  private prune(at: number): void {
+    // Expired ones stay a little past their life so a late claim reads `handoff_expired`, not unknown.
+    for (const [id, h] of this.open) if (at > h.view.exp + WEB_KEY_HANDOFF_TTL_MS) this.open.delete(id)
+  }
+
+  /** Keep one handoff for the resolved destination. The scope is checked here as the envelope parser checks it. */
+  create(request: SignHandoffRequest, target: { provider: string; sessionId: string }, scope: WebTurnScope = { kind: 'message' }, packet: WebApprovalPacket | null = null): { ok: true; handoffId: string; exp: number } | { ok: false; reason: 'handoff_cap_reached' | 'scope_not_allowed' | 'packet_mismatch' } {
+    const at = this.now()
+    this.prune(at)
+    if (parseWebTurnScope(scope) === null) return { ok: false, reason: 'scope_not_allowed' }
+    if (scope.kind === 'approve') {
+      const parsed = parseWebApprovalPacket(packet), encoded = parsed && canonicalBytes(parsed)
+      if (!parsed || !encoded || sha256Hex(encoded) !== scope.packetSha256 || at > parsed.exp || at < parsed.createdAt
+        || parsed.provider !== target.provider || parsed.sessionId !== target.sessionId
+        || ['action', 'artifact', 'version', 'digest', 'channel'].some(k => parsed[k as keyof WebApprovalPacket] !== scope[k as keyof typeof scope])) return { ok: false, reason: 'packet_mismatch' }
+      packet = { ...parsed }
+    } else if (packet !== null) return { ok: false, reason: 'packet_mismatch' }
+    let live = 0
+    for (const h of this.open.values()) if (!h.claimed && at <= h.view.exp) live += 1
+    if (live >= WEB_KEY_HANDOFF_MAX_OPEN) return { ok: false, reason: 'handoff_cap_reached' }
+    const handoffId = this.random(18).toString('base64url')
+    const exp = at + WEB_KEY_HANDOFF_TTL_MS
+    this.open.set(handoffId, {
+      claimed: false,
+      view: {
+        handoffId, exp, words: request.words, provider: target.provider, sessionId: target.sessionId,
+        bindingId: request.turn.bindingId, turn: { ...request.turn }, scope: { ...scope }, packet, attachments: [],
+      },
+    })
+    return { ok: true, handoffId, exp }
+  }
+
+  /** Once only, and only before it expires. */
+  claim(id: unknown): HandoffClaim {
+    const at = this.now()
+    this.prune(at)
+    const h = typeof id === 'string' ? this.open.get(id) : undefined
+    if (!h) return { ok: false, reason: 'handoff_unknown' }
+    if (at > h.view.exp) return { ok: false, reason: 'handoff_expired' }
+    if (h.claimed) return { ok: false, reason: 'handoff_claimed' }
+    h.claimed = true
+    return { ok: true, handoff: { ...h.view, turn: { ...h.view.turn }, scope: { ...h.view.scope }, packet: h.view.packet ? { ...h.view.packet } : null } }
+  }
+}

package/server/lib/web-key-origin.ts

@@ -0,0 +1,21 @@
+// The ONE signing origin for the enrolled phone key and its passkey (6.99.31, review B2/W2).
+// `expectedOrigin` (the envelope's `origin` and the request Origin header), the passkey's
+// `clientDataJSON.origin` check, and the cookie gate's extra port all come from here, so they can
+// never name different origins. The plan puts the signer on its own https origin, port 3144, apart
+// from the big app on 3143 (transcripts, previews): the key never lives on the 3143 origin.
+
+/** The signer's https port (plan §4.8). */
+export const WEB_KEY_SIGNER_PORT = 3144
+
+/** The normalized MagicDNS host (lower case, no trailing dot), or null. */
+export function webKeyRpId(selfDnsName: string | null | undefined): string | null {
+  if (typeof selfDnsName !== 'string') return null
+  const host = selfDnsName.trim().toLowerCase().replace(/\.$/, '')
+  return host && /^[a-z0-9.-]+$/.test(host) ? host : null
+}
+
+/** `https://<host>:3144`, or null when this Mac's MagicDNS name is unknown. */
+export function webKeySignerOrigin(selfDnsName: string | null | undefined): string | null {
+  const host = webKeyRpId(selfDnsName)
+  return host ? `https://${host}:${WEB_KEY_SIGNER_PORT}` : null
+}