@preventive/triage 1.0.0-alpha.0

package/server/sync-handlers.ts

@@ -0,0 +1,311 @@
+// Triage-sync protocol handlers: `workspace-save` and
+// `workspace-subscribe`. Built once at boot with the DB handle plus
+// the transport / auth / registry primitives it needs; the WS message
+// dispatcher in index.ts calls the returned handlers. Kept out of the
+// entrypoint so the protocol logic (the save pipeline, the
+// subscribe/catch-up path) is one cohesive, testable unit.
+
+import type { WebSocket } from 'ws'
+import { SAVE_ERROR_REASONS, type SaveErrorReason } from '../common/save-error-reason.ts'
+import { type Handle, type RevisionRow, chainFrom, commitRevision, revisionExists } from './db.ts'
+import { type SaveMsg, type SubscribeMsg, canonicalSave, computeRevisionIdFromCanonical, verifyEd25519, verifySubscribeSig } from './sign.ts'
+import { MAX_CIPHERTEXT_LEN, MAX_FIELD_LEN, validCiphertextShape, validNonce, validTagSigBase } from './validation.ts'
+import { debugTag } from './util.ts'
+import type { UnauthorizedContext } from './auth.ts'
+
+// `chainForWire` accepts the row shape from `chainFrom` (where
+// `keyframe` is the SQLite INTEGER 0 / 1) and returns the same fields
+// with `keyframe` normalised to a strict boolean for the wire.
+type WireRevision = {
+  base: string | null
+  id: string
+  keyframe: boolean
+  nonce: string
+  ciphertext: string
+  signature: string
+}
+
+export type SyncHandlersDeps = {
+  handle: Handle
+  send: (socket: WebSocket, msg: object) => void
+  broadcast: (tag: string, msg: object, except: WebSocket | null) => void
+  subscribe: (socket: WebSocket, tag: string) => void
+  getNonce: (socket: WebSocket) => string | undefined
+  requiresAuth: (socket: WebSocket) => boolean
+  sendUnauthorized: (socket: WebSocket, ctx: UnauthorizedContext) => void
+  workspaceExists: (tag: string) => Promise<boolean>
+  // Objstore inventory snapshot for a workspace tag, as wire rows. The
+  // `workspace-subscribed` ack carries it. Injected — the objstore store
+  // has its own richer `Handle`, so index.ts wires `listLive(
+  // objstoreHandle, tag).then(rows => rows.map(objectMetaWire))` rather
+  // than coupling this module to that store type. Returns [] for a
+  // triage-only tag.
+  objstoreResources: (tag: string) => Promise<object[]>
+  debug: boolean
+}
+
+export type SyncHandlers = {
+  handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
+  handleSubscribe: (socket: WebSocket, msg: SubscribeMsg) => Promise<void>
+  // Exported because the dispatcher's inflight-cap `busy` NACK path
+  // emits a save-error too (the only emit site outside this module).
+  sendSaveError: (socket: WebSocket, workspaceTag: string, base: string | null, reason: SaveErrorReason) => void
+}
+
+export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
+  const { handle, send, broadcast, subscribe, getNonce, requiresAuth, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
+
+  // Typed wrapper for the three `workspace-save-error` emit sites
+  // (too-large at handleSave, stale-base after the catch-up, busy at
+  // the inflight-cap drop). Forces `reason` to be a member of
+  // `SaveErrorReason` so a typo or a server-side addition that didn't
+  // update `common/save-error-reason.ts` fails at compile time rather
+  // than turning into a wire-level surprise. The shared taxonomy is
+  // pinned by `tests/save-error-reason-taxonomy.test.js`.
+  function sendSaveError(
+    socket: WebSocket,
+    workspaceTag: string,
+    base: string | null,
+    reason: SaveErrorReason,
+  ): void {
+    // Runtime guard alongside the compile-time `SaveErrorReason` union —
+    // covers the case where the `reason` argument is a variable (not a
+    // string literal) and TS's narrowing can't enforce taxonomy
+    // membership at the call site. Throws because a server emitting a
+    // typo'd reason would be a wire-protocol break the client can't
+    // recover from; better to fail fast in the test suite than to
+    // silently land bytes the client coerces to `'rejected'`.
+    if (!SAVE_ERROR_REASONS.has(reason)) {
+      throw new Error(`sendSaveError: reason '${reason}' is not in SAVE_ERROR_REASONS — update common/save-error-reason.ts`)
+    }
+    send(socket, { type: 'workspace-save-error', workspaceTag, base, reason })
+  }
+
+  // Normalise `keyframe` on outbound chain entries to a strict boolean.
+  // SQLite stores the column as INTEGER (0/1) and `chainFrom` returns
+  // raw rows; the wire contract (and the canonical signing payload)
+  // uses strict `=== true` to mark keyframes. Forwarding the integer
+  // shape works only because every shipping client coerces via
+  // `Boolean(rev.keyframe)` before reconstructing the canonical bytes —
+  // fragile if a future client (or test harness) ever strict-compares.
+  // Convert once on the send side.
+  function chainForWire(revisions: RevisionRow[]): WireRevision[] {
+    return revisions.map((r) => ({ ...r, keyframe: r.keyframe === 1 }))
+  }
+
+  async function handleSave(socket: WebSocket, msg: SaveMsg): Promise<void> {
+    // `base` is `string | null`; null is the keyframe-root marker.
+    if (!validTagSigBase(msg.workspaceTag, MAX_FIELD_LEN) || !validNonce(msg.nonce, MAX_FIELD_LEN) || !validCiphertextShape(msg.ciphertext) || !validTagSigBase(msg.signature, MAX_FIELD_LEN) || (msg.base != null && !validTagSigBase(msg.base, MAX_FIELD_LEN))) return
+    // Compute canonical bytes + content-addressed id ONCE, then thread
+    // both through the precheck → sig verify → commit pipeline:
+    //   1. canonicalSave (sync, throws on lone-surrogate input)
+    //   2. SHA-256 → id
+    //   3. precheck: revisionExists → short-circuit ack on replay
+    //      (skips Ed25519 verify; closes the round-9 H1 CPU-DoS vector
+    //      where a passive observer floods captured saves)
+    //   4. verifyEd25519 against the SAME canonical bytes the id was
+    //      hashed from — provably tied
+    //   5. ciphertext size policy (post-sig so the explicit error only
+    //      reaches a legit signer)
+    //   6. commitRevision — re-checks dup + base + inserts via a single
+    //      gated INSERT (dup gate + head-equals-base gate + the
+    //      server-assigned seq folded into one statement) — NO write
+    //      lock. The dup recheck, headFor, base-match and insert all
+    //      collapse into that one statement, whose head-check and
+    //      MAX(seq) read one snapshot; the `UNIQUE(workspace_tag, seq)`
+    //      PK rejects any racer that computed the same seq. So two
+    //      concurrent saves with the same `base` and different ids
+    //      can't both insert (the loser's `head IS base` gate fails →
+    //      `stale-base`, no chain fork even though UNIQUE is on id, not
+    //      base), and two concurrent same-id retransmits resolve to one
+    //      `inserted` + one `duplicate` with no UNIQUE throw escaping.
+    //      See `commitRevisionSqlite` / `tryCommitNeon` in db*.ts.
+    let canonical: Uint8Array<ArrayBuffer>
+    try { canonical = canonicalSave(msg) } catch { return }
+    const id = await computeRevisionIdFromCanonical(canonical)
+    const tag = msg.workspaceTag
+    if (await revisionExists(handle, tag, id)) {
+      if (debug) console.log(`save (precheck dup ${id.slice(0, 8)}…) → ack-only`)
+      send(socket, { type: 'workspace-save-ack', workspaceTag: tag, base: msg.base ?? null, id })
+      return
+    }
+    if (!await verifyEd25519(tag, canonical, msg.signature)) {
+      if (debug) console.warn('reject save: bad signature', debugTag(tag))
+      return
+    }
+    // Size policy — emit an explicit error so the client can surface
+    // the failure to the user. Without this, an oversized save hangs
+    // forever in the client's `pending` slot (no ack, no rebase).
+    if (msg.ciphertext.length > MAX_CIPHERTEXT_LEN) {
+      if (debug) console.warn(`reject save: ciphertext too large (${msg.ciphertext.length} > ${MAX_CIPHERTEXT_LEN})`)
+      sendSaveError(socket, tag, msg.base == null || typeof msg.base !== 'string' ? null : msg.base, 'too-large')
+      return
+    }
+    // Auth gate for the FIRST action against a workspace tag that
+    // doesn't yet exist on the server (no rows in workspace_revision
+    // AND none in workspace_object). Once any row lands, the workspace
+    // is established and every signed action flows freely — access
+    // control falls back to the Ed25519 signature for the rest of the
+    // workspace's lifetime. Checked AFTER sig verify so the
+    // `unauthorized` frame only reaches a legitimate signer; shape /
+    // sig attacks still drop silently.
+    //
+    // RACE: `workspaceExists` reads at a different moment than the
+    // commit's gated INSERT (a plain TOCTOU — there is no lock spanning
+    // the two). Under concurrent saves on a fresh tag, an
+    // unauthenticated socket whose `workspaceExists` observes "true"
+    // (because an authenticated peer's commit landed between this
+    // socket's check and its commit) skips the gate and commits as the
+    // second writer. Accepted: the unauthenticated peer still had to
+    // produce a valid Ed25519 signature (= holds the workspace seed),
+    // and "two concurrent writes both authorising" is the worst case.
+    // Tightening would require folding the gate into the commit
+    // statement itself and is not worth the layer crossing for the
+    // soft-policy guarantee.
+    if (requiresAuth(socket) && !await workspaceExists(tag)) {
+      if (debug) console.warn(`reject save: unauthorized (new workspace ${debugTag(tag)})`)
+      sendUnauthorized(socket, { kind: 'gated', workspaceTag: tag, base: msg.base ?? null })
+      return
+    }
+    // NOTE: Earlier revisions auto-subscribed the sending socket here.
+    // That created a replay vector — a passive observer who captured
+    // any single valid `workspace-save` frame could replay it from any
+    // TCP connection forever to attach as a subscriber and silently
+    // mirror every future encrypted broadcast for the workspace,
+    // without ever holding the seed (the duplicate-id path returns
+    // ack-only and doesn't reject the socket). Audit round-9 H1.
+    //
+    // The legitimate client always sends an explicit
+    // `workspace-subscribe` (see `trySendSubscribe` in
+    // `client/triage-sync.js` — fires on key derivation, on socket
+    // open, on continuity-break recovery, on dismissError). The
+    // subscribe path remains the only way to attach as a subscriber.
+    const baseNorm = msg.base ?? null
+    // `keyframe === true` is what canonicalSave bound the signature to
+    // (strict equality); the signer's intent is unambiguous here.
+    const keyframe = msg.keyframe === true
+    const commit = await commitRevision(handle, {
+      tag, id, base: baseNorm, keyframe,
+      nonce: msg.nonce, ciphertext: msg.ciphertext, signature: msg.signature,
+    })
+    if (commit.kind === 'duplicate') {
+      if (debug) console.log(`save (duplicate id ${id.slice(0, 8)}…) → ack-only`)
+      send(socket, { type: 'workspace-save-ack', workspaceTag: tag, base: baseNorm, id })
+      return
+    }
+    if (commit.kind === 'stale-base') {
+      // Client claimed a base that's no longer head. Catch-up chain is
+      // computed OUTSIDE the lock — a concurrent commit landing between
+      // lock-release and `chainFrom` only means the catch-up is fresher
+      // than the recheck saw, which is benign (clients tolerate extra
+      // revisions in the chain).
+      //
+      // Wire order: send `workspace-state` (catch-up) FIRST, then the
+      // typed `workspace-save-error { reason: 'stale-base' }`. The
+      // catch-up's handler clears `session.pending`; the subsequent
+      // error frame's `handleSaveError` then early-returns on the
+      // missing pending and does NOT mark the session errored — exactly
+      // what we want, since stale-base is a recoverable race (client
+      // rebases + re-saves). The typed frame is for protocol clarity
+      // (debug surfaces / explicit rejection signal), not for triggering
+      // an error transition. Audit follow-up to round-15 —
+      // `sync-server-races.test.js:1105`.
+      const revisions = chainForWire(await chainFrom(handle, tag, baseNorm))
+      if (debug) console.log(`save (stale base ${baseNorm} vs head ${commit.head}) → chain ${revisions.length}`)
+      send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
+      sendSaveError(socket, tag, baseNorm, 'stale-base')
+      return
+    }
+    if (debug) console.log(`save${keyframe ? ' [keyframe]' : ''} → revision ${id.slice(0, 8)}… for ${debugTag(tag)}`)
+    send(socket, {
+      type: 'workspace-save-ack',
+      workspaceTag: tag,
+      base: baseNorm,
+      id,
+    })
+    // Carry `keyframe` as a strict boolean on the broadcast wire —
+    // peers strict-compare `=== true` (matching the canonical-payload
+    // contract). The previous shape emitted `keyframe ? 1 : 0` which a
+    // strict check would treat as non-keyframe, making a replayed
+    // keyframe look like a regular delta on broadcast paths even though
+    // the chain-fetch path (chainFrom → SQLite integer) DID round-trip
+    // correctly.
+    broadcast(tag, {
+      type: 'workspace-state',
+      workspaceTag: tag,
+      revisions: [{
+        base: baseNorm,
+        id,
+        keyframe,
+        nonce: msg.nonce,
+        ciphertext: msg.ciphertext,
+        signature: msg.signature,
+      }],
+    }, socket)
+  }
+
+  async function handleSubscribe(socket: WebSocket, msg: SubscribeMsg): Promise<void> {
+    if (typeof msg.workspaceTag !== 'string') return
+    // Same `string | null` contract as `base` in handleSave. The signed
+    // canonical uses `String(from)`, but the chain-lookup path
+    // (`typeof msg.from === 'string' ? msg.from : null`) treats every
+    // non-string as null — so a legit signer sending `from: { … }`
+    // would silently take the keyframe-fallback path even though the
+    // signature was over a different canonical shape. Reject at the
+    // wire gate.
+    if (msg.from != null && typeof msg.from !== 'string') return
+    // The challenge nonce we issued on this socket is bound into the
+    // signed canonical, blocking cross-connection replay of a captured
+    // subscribe frame. A subscribe arriving before we sent the
+    // challenge (impossible from the legitimate client) has no nonce to
+    // verify against — drop. Audit round-9 H2.
+    const nonce = getNonce(socket)
+    if (typeof nonce !== 'string') return
+    const ok = await verifySubscribeSig(msg, nonce)
+    if (!ok) {
+      if (debug) console.warn('reject subscribe: bad signature', debugTag(msg.workspaceTag))
+      return
+    }
+    // Bail if the socket closed during the verify await. The close
+    // handler's `unsubscribeAll(socket)` already ran (when there was
+    // nothing to remove yet), and `subscribe()` below would add the
+    // dead socket to `subscribers[tag]` — a permanent leak: broadcasts
+    // no-op via `send`'s readyState gate, but the Set entry pins the
+    // socket reference past close, blocking GC. Audit round-12.
+    if (socket.readyState !== socket.OPEN) {
+      if (debug) console.warn('reject subscribe: socket closed mid-verify', debugTag(msg.workspaceTag))
+      return
+    }
+    const tag = msg.workspaceTag
+    subscribe(socket, tag)
+    // Explicit ack — distinguishes "the server processed my subscribe
+    // and registered me as a peer" from "the WebSocket is open". A
+    // client that sent a malformed / bad-sig subscribe never gets this;
+    // a client that did gets one before the chain arrives. Lets the UI
+    // surface a `connecting → online` transition based on real handshake
+    // completion, not just socket state.
+    //
+    // The ack also carries the objstore inventory snapshot: the same
+    // subscribe that registers this socket for objstore-put / -deleted
+    // broadcasts seeds the client's initial inventory in one handshake.
+    // The client keeps it live thereafter from those broadcasts.
+    // Returns [] for a triage-only workspace. A failing inventory
+    // lookup must NOT sink the subscribe — degrade to an empty snapshot
+    // (broadcasts will fill it in) so the ack + chain still go out.
+    let resources: object[] = []
+    try { resources = await objstoreResources(tag) }
+    catch (err) { if (debug) console.warn('subscribe: objstore inventory lookup failed', debugTag(tag), err) }
+    send(socket, { type: 'workspace-subscribed', workspaceTag: tag, resources })
+    // `from` is the last revision id the client claims to have applied —
+    // now a base64url string, not an integer. We send only revisions
+    // after that. Client lying about `from` just means they get a
+    // smaller catch-up — their subsequent saves will reveal stale state
+    // on the usual base-mismatch path. Null / missing → full chain.
+    const fromId = typeof msg.from === 'string' ? msg.from : null
+    const revisions = chainForWire(await chainFrom(handle, tag, fromId))
+    if (debug) console.log(`subscribe ${debugTag(tag)} from=${fromId?.slice(0, 8) ?? 'null'} → chain ${revisions.length}`)
+    send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
+  }
+
+  return { handleSave, handleSubscribe, sendSaveError }
+}

package/server/util.ts

@@ -0,0 +1,27 @@
+// Small cross-cutting helpers shared across the relay (both the
+// triage-sync root plane and the objstore plane). Kept in one module
+// so the one-liners don't scatter / drift across call sites.
+
+import { randomBytes } from 'node:crypto'
+
+// Truncate a base64url tag for `DEBUG=1` logging. A full workspaceTag
+// is an Ed25519 public key; operator logs shouldn't carry it verbatim.
+export function debugTag(s: string): string { return `${s.slice(0, 12)}…` }
+
+// 16 random bytes → 22 base64url chars (no padding). The shared shape
+// for per-socket challenge nonces and staging ids — collision is
+// 1/2^128. `isValidStagingId` in objstore/store.ts validates exactly
+// this shape.
+export function randomId(): string { return randomBytes(16).toString('base64url') }
+
+// Log-friendly view of an unknown throw, for use as a `console.*`
+// ARGUMENT (not interpolated into a template literal — see below).
+// `errMsg` for the common one-line warning, `errStack` where a
+// post-mortem wants the throw site. An Error's `.message` / `.stack`
+// is a string; a non-Error throw is returned unchanged so console
+// renders it structurally (util.inspect) instead of coercing it to
+// the useless `[object Object]`. A template-literal caller would
+// coerce the return via `String()` and lose that, so pass these as a
+// separate console argument.
+export function errMsg(err: unknown): unknown { return (err as Error)?.message ?? err }
+export function errStack(err: unknown): unknown { return (err as Error)?.stack ?? err }

package/server/validation.ts

@@ -0,0 +1,36 @@
+// Wire-field shape gates for `workspace-save`: base64-or-base64url
+// alphabet, length-bounded. The critical guarantee is "no newlines" —
+// without it, `nonce = "AAA\nBBB"` + `ciphertext = "CCC"` produces the
+// same canonical bytes as `nonce = "AAA"` + `ciphertext = "BBB\nCCC"`
+// (canonicalSave newline-joins), causing same-id collisions across
+// distinct stored fields. Two alphabets:
+//
+//   - workspaceTag / signature / base — base64url-no-padding only.
+//     Clients always emit these via `toBase64({ alphabet: 'base64url',
+//     omitPadding: true })` (client/sync-crypto.ts), and the same
+//     workspaceTag must round-trip through objstore's TAG_RE (also
+//     base64url-no-padding) for cross-protocol consistency. Accepting
+//     `+/=` here would let a buggy or hostile client split its data
+//     across two encodings of the same workspace.
+//   - nonce / ciphertext — base64 OR base64url (union alphabet).
+//     Clients emit these via `toBase64()` with no alphabet hint
+//     (standard base64 with `+/=` padding), and the bytes are opaque
+//     to the server — no cross-protocol identity is bound to the
+//     encoding. The newline-collision guard is the only invariant
+//     here; the wider alphabet is acceptable.
+//
+// Short-field length caps bound the canonical and `MAX_CIPHERTEXT_LEN`
+// bounds chain-bloat; the ciphertext size check runs post-sig (in
+// handleSave) so the error response only reaches a legit signer.
+const TAG_SIG_BASE_RE = /^[\w-]+$/u
+const NONCE_CIPHER_RE = /^[\w+/=-]+$/u
+export const MAX_FIELD_LEN = 128
+export const MAX_CIPHERTEXT_LEN = 2 * 1024 * 1024
+
+export const validTagSigBase = (s: unknown, max: number): s is string => typeof s === 'string' && s.length > 0 && s.length <= max && TAG_SIG_BASE_RE.test(s)
+export const validNonce = (s: unknown, max: number): s is string => typeof s === 'string' && s.length > 0 && s.length <= max && NONCE_CIPHER_RE.test(s)
+// Ciphertext: same alphabet as nonce but the size cap is checked
+// POST-sig (to avoid leaking the cap to unauthenticated probes).
+// Pre-sig only the shape gate applies; `maxPayload` (4 MiB) already
+// bounds the total frame, so the worst-case bytes are still bounded.
+export const validCiphertextShape = (s: unknown): s is string => typeof s === 'string' && s.length > 0 && NONCE_CIPHER_RE.test(s)

package/server/ws-server.ts

@@ -0,0 +1,245 @@
+// WebSocket runtime: the per-connection handler (Peer setup, message
+// dispatch, close/error) and the server-driven heartbeat sweep. Wired
+// once at boot onto the shared `wss` with the protocol handlers +
+// lifecycle hooks it dispatches to. Kept out of index.ts so the WS
+// message loop — the most concurrency-sensitive surface — is one unit.
+
+import type { WebSocket, WebSocketServer } from 'ws'
+import { Buffer } from 'node:buffer'
+import { decodeUtf8 } from '../common/utf8.js'
+import type { SaveErrorReason } from '../common/save-error-reason.ts'
+import { Peer, type PeerRegistry } from './peer.ts'
+import { errMsg, errStack, randomId } from './util.ts'
+import type { SaveMsg, SubscribeMsg } from './sign.ts'
+import type { AuthenticateMsg } from './auth.ts'
+import type { ObjstoreHandlers } from './objstore/handlers.ts'
+import type { ObjstoreDeleteMsg, ObjstoreFetchMsg, ObjstorePutBeginMsg } from './objstore/sign.ts'
+
+// Wire-message envelope as it lands post-`JSON.parse`. Every field is
+// `unknown` until a handler narrows it; the type just documents the
+// dispatch surface so call sites can pattern-match on `msg.type`.
+type IncomingMessage = {
+  type?: unknown
+  [k: string]: unknown
+}
+
+export type WsServerDeps = {
+  wss: WebSocketServer
+  peers: PeerRegistry
+  send: (socket: WebSocket, msg: object) => void
+  unsubscribeAll: (socket: WebSocket) => void
+  handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
+  handleSubscribe: (socket: WebSocket, msg: SubscribeMsg) => Promise<void>
+  handleAuthenticate: (socket: WebSocket, msg: AuthenticateMsg) => void
+  sendSaveError: (socket: WebSocket, workspaceTag: string, base: string | null, reason: SaveErrorReason) => void
+  objstore: ObjstoreHandlers
+  track: (promise: Promise<unknown>) => void
+  isShuttingDown: () => boolean
+  maxInflightPerSocket: number
+  heartbeatIntervalMs: number
+  debug: boolean
+}
+
+// Wires `wss.on('connection')` + starts the heartbeat. Returns the
+// timer so shutdown can clear it.
+export function installWsServer(deps: WsServerDeps): { heartbeatTimer: ReturnType<typeof setInterval> } {
+  const {
+    wss, peers, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
+    sendSaveError, objstore, track, isShuttingDown, maxInflightPerSocket, heartbeatIntervalMs, debug,
+  } = deps
+
+  wss.on('connection', (socket: WebSocket, req) => {
+    if (debug) console.log(`connect from ${req.socket.remoteAddress}`)
+    // One Peer holds this connection's state (challenge / authorized /
+    // alive / inflight / tags). Created before any client frame can
+    // arrive (`socket.on('message')` is wired below). The heartbeat
+    // sweep flips `alive` false after each `ping()`; the `pong` listener
+    // flips it back, and a socket still false on the next sweep is
+    // terminated — the only thing closing FDs for an idle peer.
+    const peer = new Peer(randomId())
+    peers.set(socket, peer)
+    socket.on('pong', () => { peer.alive = true })
+    // Issue the per-connection challenge nonce BEFORE the client can
+    // send anything that needs it. The client signs it into every
+    // `workspace-subscribe` (see canonicalSubscribe in server/sign.ts);
+    // a captured subscribe frame can't be replayed from a different
+    // connection because that connection's nonce differs and the
+    // signature won't verify against the new canonical bytes. Round-9 H2.
+    send(socket, { type: 'challenge', nonce: peer.challenge })
+    // Per-socket handlers are DELIBERATELY NOT serialized (vs the
+    // client-side `messageQueue = messageQueue.then(...)` Promise
+    // chain inside `client/triage-sync.ts:onTransportMessage`).
+    // Each inbound frame spawns its own tracked async IIFE; two
+    // frames from the same socket can interleave across `await`
+    // boundaries inside the handlers. Per-resource correctness needs
+    // no in-process lock: `commitRevision` resolves concurrent saves
+    // via its single gated INSERT (one snapshot + the
+    // `UNIQUE(workspace_tag, seq)` PK — see `server/db.ts`), and the
+    // objstore handlers (`commitPut` / `beginPut` / `deleteObject`)
+    // via the version compare-and-set + content-addressing (see
+    // `server/objstore/store.ts`), backed by post-await
+    // `readyState === OPEN` rechecks in every objstore handler. The
+    // unbounded fan-out is capped by `maxInflightPerSocket` (see
+    // also the `'busy'` NACK at the cap below). Concurrent dispatch
+    // is intentional: it lets multi-workspace clients multiplex
+    // saves + subscribes over one socket without HOL blocking.
+    // Audit follow-up to round-15 concurrency review.
+    socket.on('message', (data: Buffer, isBinary: boolean) => {
+      // Drop new work once shutdown started — `wss.close()` stops new
+      // CONNECTIONS but already-open sockets can still send messages.
+      // Without this gate a message arriving between `wss.close()`
+      // resolving and the `inFlight` snapshot would spawn a handler
+      // that's NOT in the snapshot, then resume against the just-
+      // closed DB and throw inside the commit's gated INSERT. Audit
+      // round-9.
+      if (isShuttingDown()) return
+      // Wire protocol is JSON over text frames. A binary frame is
+      // either a buggy client or someone probing — drop without
+      // attempting to interpret it as text.
+      if (isBinary) return
+      let msg: IncomingMessage | null = null
+      try {
+        // `decodeUtf8` is fatal on invalid UTF-8 (vs `Buffer.toString`
+        // which silently substitutes U+FFFD). The substitution path
+        // would let mangled bytes pass JSON.parse only to fail
+        // signature verification deeper in the handler — wasted work
+        // and noisier logs. Fail at the gate.
+        msg = JSON.parse(decodeUtf8(data)) as IncomingMessage
+      } catch { return }
+      if (!msg || typeof msg !== 'object') return
+      const parsed: IncomingMessage = msg
+      // Per-socket inflight cap. Each tracked handler keeps the socket
+      // alive in `inFlight`, and a peer who keeps firing valid frames
+      // can spawn unbounded handlers — growing SIGTERM drain time and
+      // memory. Drop new work above the cap. Heartbeat ping is the
+      // exception: it's stateless, synchronous, and we want to KEEP
+      // responding so the peer doesn't drop the socket while we're
+      // shedding load. Pings go through a fast inline `send(pong)`
+      // path BELOW that doesn't bump the per-socket inflight counter,
+      // so a ping-spam at the cap can't outrun the gate. Transport
+      // audit `server/index.ts:590` + post-#58 audit follow-up.
+      if (parsed.type === 'ping') {
+        send(socket, { type: 'pong' })
+        return
+      }
+      // `authenticate` runs synchronously (constant-time bytes compare
+      // — no DB, no I/O), so it shares the same fast-inline path as
+      // `ping` and bypasses the per-socket inflight counter. Keeping
+      // it out of the IIFE pool means an unauthenticated client can
+      // still complete the handshake when the socket is otherwise
+      // saturated (matching the philosophy of the `busy` NACK path
+      // for `workspace-save`: don't strand a recoverable handshake
+      // behind the cap).
+      if (parsed.type === 'authenticate') {
+        handleAuthenticate(socket, parsed as AuthenticateMsg)
+        return
+      }
+      if (peer.inflight >= maxInflightPerSocket) {
+        if (debug) console.warn(`drop message: socket inflight ${peer.inflight} >= ${maxInflightPerSocket}`)
+        // For workspace-save specifically, send a typed NACK so the
+        // client's `pending` slot clears IMMEDIATELY instead of
+        // hanging until the next heartbeat (~15–30s). Reason `busy`
+        // is server-side overload; safe to retry. Same wire envelope
+        // as the existing `too-large` save-error path.
+        //
+        // Wire-order interaction with `'stale-base'`: the cap-path
+        // send is SYNCHRONOUS in this message callback and lands on
+        // the wire BEFORE any handler IIFE's `await`-completed reply.
+        // If an earlier in-flight `workspace-save` (frame F1) ends up
+        // emitting a catch-up `workspace-state` + `'stale-base'` while
+        // a later frame F2 hits the cap, the order is `'busy'`(F2) →
+        // `workspace-state`(F1) → `'stale-base'`(F1). The client's
+        // `handleSaveError` correlates on `base`, and the wire-order
+        // trick documented in `common/save-error-reason.ts` (catch-up
+        // clears `pending` before the stale-base frame's
+        // `handleSaveError` runs) still holds.
+        const rawBase = (parsed as SaveMsg).base
+        const baseField: string | null = typeof rawBase === 'string' ? rawBase : null
+        const rawTag = (parsed as SaveMsg).workspaceTag
+        const tagField = typeof rawTag === 'string' ? rawTag : null
+        if (parsed.type === 'workspace-save' && tagField != null) {
+          // `sendSaveError` runs its taxonomy-guard before the wire
+          // send and throws on an unknown reason. Every OTHER emit
+          // site lives inside the `handler` IIFE's try/catch — this
+          // cap path is the only one outside it. Mirror the same
+          // forensic envelope so a future bad reason here surfaces
+          // as `Handler error (type=workspace-save): …` rather than
+          // escaping to ws's emitter as an uncaught.
+          try {
+            sendSaveError(socket, tagField, baseField, 'busy')
+          } catch (err) {
+            console.warn('Handler error (type=workspace-save):', errStack(err))
+          }
+        }
+        return
+      }
+      peer.inflight += 1
+      const handler = (async () => {
+        try {
+          if (parsed.type === 'workspace-save') await handleSave(socket, parsed as SaveMsg)
+          else if (parsed.type === 'workspace-subscribe') await handleSubscribe(socket, parsed as SubscribeMsg)
+          // Objstore control plane — bytes ride the REST plane via
+          // tokens these handlers mint. The Objstore*Msg types are
+          // weak shapes (every field `unknown`); the handlers narrow
+          // each field through their own validators on entry.
+          else if (parsed.type === 'objstore-put-begin') await objstore.handlePutBegin(socket, parsed as ObjstorePutBeginMsg)
+          else if (parsed.type === 'objstore-delete') await objstore.handleDelete(socket, parsed as ObjstoreDeleteMsg)
+          else if (parsed.type === 'objstore-fetch') await objstore.handleFetch(socket, parsed as ObjstoreFetchMsg)
+        } catch (err) {
+          // Forensic logging for unexpected throws — the handlers all
+          // have internal narrow catches (e.g. signature reject paths);
+          // anything reaching here is unexpected. Include the wire
+          // `type` so an operator can correlate to a specific code
+          // path, and prefer `.stack` over `.message` so the post-
+          // mortem has the throw site.
+          const typeStr = typeof parsed.type === 'string' ? parsed.type : '<unknown>'
+          console.warn(`Handler error (type=${typeStr}):`, errStack(err))
+        } finally {
+          peer.inflight -= 1
+        }
+      })()
+      track(handler)
+    })
+    socket.on('close', () => {
+      // `unsubscribeAll` reads `peer.tags` (peer still registered), then
+      // we drop the Peer. The Peer's state would GC once the socket is
+      // unreachable, but `wss.clients` / `ws` internals hold the socket
+      // strongly well past `close`, so the explicit delete frees it
+      // immediately. Audit round-10 + round-13.
+      unsubscribeAll(socket)
+      peers.delete(socket)
+    })
+    // Surface socket-level errors instead of swallowing — these are
+    // the signals operators want under abuse / network flakiness
+    // (TLS handshake failures, frame-decode errors, ws-protocol
+    // violations). The previous `() => {}` left every per-connection
+    // failure invisible. `close` fires after `error` and runs the
+    // unsubscribe cleanup, so logging here doesn't risk leaking.
+    socket.on('error', (err: Error) => { console.warn('Socket error:', errMsg(err)) })
+  })
+
+  // Periodic heartbeat sweep. Two-tick liveness window: a socket that
+  // doesn't `pong` within `heartbeatIntervalMs` of our `ping` sees its
+  // tracker flip to `false`; on the NEXT tick we terminate. `try/catch`
+  // shrugs at any peer that races us into CLOSING / CLOSED (`ws.ping` /
+  // `ws.terminate` throw in that state) — the close event handles
+  // cleanup either way.
+  //
+  // `unref` so the timer alone doesn't keep the event loop alive
+  // (parity with `terminateTimer` in shutdown). Cleared in shutdown so
+  // a graceful SIGTERM doesn't fire one last ping race after wss.close.
+  const heartbeatTimer = setInterval(() => {
+    for (const ws of wss.clients) {
+      const peer = peers.get(ws)
+      if (peer?.alive === false) {
+        try { ws.terminate() } catch {}
+        continue
+      }
+      if (peer) peer.alive = false
+      try { ws.ping() } catch {}
+    }
+  }, heartbeatIntervalMs)
+  heartbeatTimer.unref?.()
+
+  return { heartbeatTimer }
+}