@preventive/triage 1.0.0-alpha.2 → 1.0.0-alpha.4

package/server/objstore/tokens.ts

@@ -112,16 +112,14 @@ function isValidPayload(v: unknown): v is TokenPayload {
   const o = v as Record<string, unknown>
   if (typeof o['tag'] !== 'string' || typeof o['res'] !== 'string') return false
   // `Number.isSafeInteger` over `Number.isInteger`: `exp` is compared
-  // to `Date.now()` (which is itself a safe int), `len` is compared
-  // against the Content-Length the REST layer parsed (which already
-  // gates on `isSafeInteger`), and `ver` is compared against SQLite's
-  // INTEGER (capacity 2^63). An unsafe-but-integer value in the token
-  // round-trips through IEEE-754 and could spoof equality with a
-  // different actual value, or — for `exp` — let an adversarial
-  // token claim a `Number.MAX_SAFE_INTEGER + 1` expiry that compares
-  // ambiguously near the IEEE-754 boundary. Matches the rest of the
-  // codebase's safe-int gates (server/objstore/sign.ts,
-  // server/objstore/rest.ts, server/objstore/handlers.ts).
+  // to `Date.now()` (a safe int), `len` against the Content-Length the
+  // REST layer parsed (itself `isSafeInteger`-gated), and `ver` against
+  // SQLite's INTEGER (capacity 2^63). An unsafe-but-integer value in the
+  // token round-trips through IEEE-754 and could spoof equality with a
+  // different actual value, or — for `exp` — claim a
+  // `Number.MAX_SAFE_INTEGER + 1` expiry that compares ambiguously near
+  // the IEEE-754 boundary. Matches the codebase's other safe-int gates
+  // (server/objstore/sign.ts, rest.ts, handlers.ts).
   if (!Number.isSafeInteger(o['exp']) || (o['exp'] as number) < 0) return false
   if (o['op'] === 'put') {
     return typeof o['sid'] === 'string'
@@ -138,8 +136,7 @@ function isValidPayload(v: unknown): v is TokenPayload {
   return false
 }
 
-// Convenience constructors so the WS handler doesn't have to assemble
-// the payload shape inline.
+// Constructors so the WS handler doesn't assemble the payload inline.
 export function mintPutToken(
   secret: TokenSecret,
   tag: string, res: string, sid: string, len: number,

package/server/peer.ts

@@ -1,9 +1,8 @@
-// Per-connection server state. One `Peer` per accepted WebSocket,
-// replacing the former parallel per-socket WeakMaps (challenge /
-// authorized / alive / inflight / tags). The connection handler
-// constructs one on accept and holds it in a closure, so the hot
-// paths (message dispatch, pong, close) touch fields directly; the
-// few cross-function call sites look it up via `peers.get(socket)`.
+// Per-connection server state. One `Peer` per accepted WebSocket. The
+// connection handler constructs one on accept and holds it in a
+// closure, so the hot paths (message dispatch, pong, close) touch
+// fields directly; the few cross-function call sites look it up via
+// `peers.get(socket)`.
 //
 // Held in a `WeakMap<WebSocket, Peer>` so a closed socket's state GCs
 // with the socket; the close handler also `delete`s it explicitly
@@ -17,9 +16,8 @@ export class Peer {
   // `workspace-subscribe` signature — blocks cross-connection replay
   // of a captured subscribe frame.
   readonly challenge: string
-  // Password-gate authorization flag. Once the `authenticate`
-  // handshake succeeds, every subsequent first-action on this socket
-  // bypasses the new-workspace gate. `false` until then.
+  // Password-gate flag. Once the `authenticate` handshake succeeds,
+  // first-actions on this socket bypass the new-workspace gate.
   authorized = false
   // Heartbeat liveness. The sweep flips it `false` after each `ping()`;
   // the `pong` listener flips it back. A socket still `false` on the

package/server/pubsub.ts

@@ -169,9 +169,8 @@ type NeonState = {
   pendingHandlers: Set<Promise<void>>
 }
 
-// Notification dispatch — closes over `state.senderId` and
-// `state.handler`. Filters foreign channels (defensive) and our own
-// publish round-trip (Postgres NOTIFY delivers to publishers too).
+// Notification dispatch. Filters foreign channels (defensive) and our
+// own publish round-trip (Postgres NOTIFY delivers to publishers too).
 function dispatchNotification(state: NeonState, n: { channel: string; payload?: string }): void {
   if (n.channel !== CHANNEL) return
   if (typeof n.payload !== 'string') return
@@ -187,24 +186,19 @@ function dispatchNotification(state: NeonState, n: { channel: string; payload?:
   // notification dispatch (which would queue further notifications
   // behind it). Errors are logged but don't kill the loop — a missed
   // broadcast surfaces to clients on reconnect via the chain re-pull.
-  //
-  // The promise is also tracked in `state.pendingHandlers` so `stop()`
-  // can drain in-flight handlers BEFORE the lifecycle teardown closes
-  // the DB handle. Without the tracking, `onBusMessage`'s DB queries
-  // (`handle.revisionById.get` / `getLive`) could race
-  // `handle.close()` and throw inside a half-settled handler.
+  // Tracked in `state.pendingHandlers` so `stop()` drains in-flight
+  // handlers before the lifecycle closes the DB handle (see that
+  // field's doc).
   const promise: Promise<void> = fn(msg).catch((err) => {
     console.warn('pubsub: handler error:', errStack(err))
   }).finally(() => { state.pendingHandlers.delete(promise) })
   state.pendingHandlers.add(promise)
 }
 
-// Single connect attempt. Resolves once LISTEN is registered, or
-// rejects on transport / LISTEN failure. Assigns `state.client = c`
-// EAGERLY (before `c.connect()` is awaited) for the two invariants
-// documented on `NeonState.client`: the error handler's equality gate
-// must work mid-handshake, and `stop()` must be able to abort a hung
-// connect by reading `state.client?.end()`.
+// Single connect attempt. Resolves once LISTEN is registered, rejects
+// on transport / LISTEN failure. Assigns `state.client = c` EAGERLY
+// (before awaiting `c.connect()`) for the invariants on
+// `NeonState.client`.
 async function tryConnect(state: NeonState): Promise<void> {
   const c = state.newClient()
   state.client = c
@@ -221,13 +215,11 @@ async function tryConnect(state: NeonState): Promise<void> {
     })
     await c.query(`LISTEN ${CHANNEL}`)
   } catch (err) {
-    // Clear `state.client` only if it still points at OUR client (a
+    // Clear `state.client` only if it still points at OUR client — a
     // racing `stop()` may have already null'd it and ended the
-    // half-connected socket — don't clobber that). The `c.end()`
-    // below may be a redundant second call in that race (stop already
-    // ended it); pg-style Client.end() is idempotent so the second
-    // call is a harmless no-op. The try/catch additionally absorbs
-    // any rejection from end() itself.
+    // half-connected socket; don't clobber that. The `c.end()` below
+    // may then be a redundant second call, but pg-style Client.end()
+    // is idempotent (and the try/catch absorbs any rejection).
     if (state.client === c) state.client = null
     try { await c.end() } catch {}
     throw err
@@ -236,8 +228,7 @@ async function tryConnect(state: NeonState): Promise<void> {
 
 // Outer (re)connect loop. Exits silently on `state.stopped`; otherwise
 // retries with exponential backoff after a connect / LISTEN failure.
-// `tryConnect` assigns `state.client` itself (see the eager-assign
-// rationale on `NeonState.client`), so this loop only counts attempts
+// `tryConnect` owns `state.client`, so this loop only counts attempts
 // and runs the backoff sleep.
 async function connectAndListen(state: NeonState): Promise<void> {
   // oxlint-disable-next-line no-unmodified-loop-condition
@@ -262,10 +253,9 @@ async function connectAndListen(state: NeonState): Promise<void> {
 // default) waiting on the timer. We stash the cancel callback on the
 // shared state object so `stop()` can fire it; the loop's
 // `if (state.stopped) return` then exits on the next turn. The
-// `settled` flag guards against a race between the timer firing and
-// `stop()` racing the same wake-up (Promise resolves are idempotent
-// at the runtime layer, but oxlint's `no-multiple-resolved` rule is
-// stricter and the guard documents the mutual exclusion explicitly).
+// `settled` flag guards the timer-vs-`stop()` wake-up race: resolves
+// are idempotent at runtime, but it also satisfies oxlint's stricter
+// `no-multiple-resolved` and documents the mutual exclusion.
 function cancellableSleep(state: NeonState, ms: number): Promise<void> {
   return new Promise((resolve) => {
     let settled = false

package/server/sign.ts

@@ -55,15 +55,6 @@ export type SubscribeMsg = {
 // `Uint8Array<ArrayBuffer>` (not `<ArrayBufferLike>`) so the bytes
 // thread directly into `crypto.subtle.digest` — `BufferSource`
 // rejects SharedArrayBuffer-backed views.
-//
-// NOTE: `verifySaveSigAndCanonical` is a test-friendly composition
-// helper. Production `handleSave` in `server/index.ts` does NOT
-// call it — it composes `canonicalSave` +
-// `computeRevisionIdFromCanonical` + `verifyEd25519` separately so
-// the dup-precheck (`revisionExists`) can fire BEFORE the Ed25519
-// verify, closing the round-9 H1 CPU-DoS vector where a passive
-// observer floods captured saves. The wrapper exists for unit
-// tests that don't need the precheck ordering.
 export type VerifyResult =
   | { ok: true; canonical: Uint8Array<ArrayBuffer> }
   | { ok: false; canonical: null }
@@ -120,7 +111,14 @@ function canonicalSubscribe(
   { workspaceTag, from }: SubscribeMsg,
   connectionNonce: string,
 ): Uint8Array<ArrayBuffer> {
-  const fromStr = from == null ? '' : String(from)
+  // Strict `from` typing, mirroring canonicalSave's `base` check: `from`
+  // is `string | null`. A non-string non-null value would otherwise
+  // coerce via `String(...)` to canonical bytes the client could never
+  // reproduce (123 → "123", {} → "[object Object]"), so a signature
+  // computed over that coercion would verify against a malformed wire
+  // shape. verifySubscribeSig wraps this call in try/catch → clean drop.
+  if (from != null && typeof from !== 'string') throw new TypeError('canonicalSubscribe: from must be string or null')
+  const fromStr = from == null ? '' : from
   return encodeUtf8([SUBSCRIBE_DOMAIN, workspaceTag as string, fromStr, connectionNonce].join('\n'))
 }
 

package/server/sse-server.ts

@@ -168,9 +168,8 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     session.writeEvent('session', sid)
     // Hand the session to the shared WS connection setup so it joins
     // the same Peer / dispatcher / hub lifecycle as a real WebSocket.
-    // `setupPeerConnection` sends the protocol `challenge` frame as
-    // its first action; that re-uses the normal default-named SSE
-    // message channel.
+    // `setupPeerConnection`'s first action is the protocol `challenge`
+    // frame, on the default-named SSE channel.
     setupPeerConnection(session as unknown as WebSocket, req, peerDeps)
     return { sid, session }
   }
@@ -329,15 +328,14 @@ export function installSseServer(deps: SseServerDeps): SseServer {
 
 // Bare-bones query parse for `id=<base64url>`. Avoids URLSearchParams
 // (which decodes percent-escapes) — `randomId()` mints a 22-char
-// base64url string, and the client echoes it back unchanged, so no
-// escapes are possible on the legitimate path. The {1,64} bound is a
-// deliberately lenient sanity gate: anything outside the base64url
-// alphabet is rejected (and a missing id is treated as "no id"); a
-// client that sent a sid this regex doesn't recognise just gets a
-// fresh session minted by createSession, no failure mode. The wide
-// length window means a future randomId-length change here doesn't
-// silently break old clients that round-trip a longer or shorter
-// token. Returns null on missing / malformed.
+// base64url string echoed back unchanged, so no escapes are possible
+// on the legitimate path. The {1,64} bound is a deliberately lenient
+// sanity gate: anything outside the base64url alphabet is rejected; an
+// unrecognised sid just gets a fresh session from createSession (no
+// failure mode), and the wide length window keeps a future
+// randomId-length change from silently breaking old clients that
+// round-trip a longer/shorter token. Returns null on missing /
+// malformed.
 function parseSidQuery(query: string | undefined): string | null {
   if (typeof query !== 'string') return null
   for (const part of query.split('&')) {

package/server/sse-session.ts

@@ -63,20 +63,14 @@ export class SseSession extends EventEmitter {
   // failure on a healthy session.
   private wireResponse(res: ServerResponse): void {
     res.on('close', () => {
-      // Only the *current* response's close terminates the session. A
-      // swapped-out previous response closes naturally during takeover
-      // and must not knock the session offline.
-      if (res !== this.currentRes) return
+      if (res !== this.currentRes) return  // current-response guard (see above)
       if (this.readyState === SseSession.CLOSED) return
       this.readyState = SseSession.CLOSED
       this.currentRes = null
       this.emit('close')
     })
     res.on('error', (err: Error) => {
-      // Same identity guard as close: drained-out previous responses
-      // may emit RST/EPIPE during flush and we don't want those to
-      // pseudo-fail the healthy session that's now on a new response.
-      if (res !== this.currentRes) return
+      if (res !== this.currentRes) return  // current-response guard (see above)
       this.emit('error', err)
     })
   }

package/server/static.ts

@@ -169,11 +169,9 @@ function buildEntry(staticDir: string, name: string): StaticEntry {
   const ext = extname(name)
   const raw = readFileSync(join(staticDir, name))
   const type = CONTENT_TYPE[ext] ?? 'application/octet-stream'
-  // HTML: lift `<link rel="(module)preload" …>` into a Link header
-  // and drop the tags from the served body so the bytes ship without
-  // the now-redundant in-body hint. ETag + compression run against
-  // the stripped body — the on-disk file and the served body diverge
-  // by exactly the lifted tags.
+  // HTML: lift `<link rel="(module)preload" …>` into a Link header and
+  // drop the tags from the served body. ETag + compression run against
+  // the stripped body (see the header note on the divergence).
   let identity = raw
   let link: string | null = null
   if (ext === '.html') {
@@ -273,13 +271,11 @@ function isUnsafeAttr(s: string): boolean {
   return /[\r\n",;<>]/u.test(s)
 }
 
-// Find character ranges in `html` whose contents are NOT real HTML
-// content: comment bodies and script / noscript raw-text bodies. A
-// `<link>` whose match offset falls inside any range is preserved
-// verbatim (no header lift). Heuristic: a real HTML parser is
-// overkill here — the build emits clean, well-formed markup; this is
-// defence against the build (or a hand edit) accidentally mentioning
-// `<link rel="preload">` somewhere it isn't meant to fire.
+// Char ranges in `html` whose contents are NOT real HTML content:
+// comment bodies and script / noscript raw-text bodies. A `<link>`
+// whose match offset falls in any range is preserved verbatim (no
+// header lift — see the call site for why). Heuristic, not a real
+// parser: the build emits clean, well-formed markup.
 function findSkipRanges(html: string): Array<[number, number]> {
   const ranges: Array<[number, number]> = []
   const patterns = [

package/server/sync-handlers.ts

@@ -13,9 +13,8 @@ import { MAX_CIPHERTEXT_LEN, MAX_FIELD_LEN, validCiphertextShape, validNonce, va
 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.
+// Wire shape `chainForWire` produces from a `chainFrom` row, with
+// `keyframe` normalised from the SQLite INTEGER 0/1 to a strict boolean.
 type WireRevision = {
   base: string | null
   id: string
@@ -88,14 +87,12 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     send(socket, { type: 'workspace-save-error', workspaceTag, base, reason })
   }
 
-  // Normalise `keyframe` on outbound chain entries to a strict boolean.
+  // Normalise `keyframe` to a strict boolean on outbound chain entries.
   // 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.
+  // raw rows; the wire contract (and canonical signing payload) uses
+  // strict `=== true`. Convert once on the send side — forwarding the
+  // integer relies on clients coercing via `Boolean()` before rebuilding
+  // canonical bytes, fragile against any client that strict-compares.
   function chainForWire(revisions: RevisionRow[]): WireRevision[] {
     return revisions.map((r) => ({ ...r, keyframe: r.keyframe === 1 }))
   }
@@ -174,19 +171,14 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
       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.
+    // Save does NOT subscribe the sending socket — that would be a
+    // replay vector: a passive observer who captured one valid
+    // `workspace-save` frame could replay it from any TCP connection to
+    // attach as a subscriber and mirror every future encrypted
+    // broadcast, without holding the seed (the duplicate-id path returns
+    // ack-only, doesn't reject the socket). Explicit `workspace-subscribe`
+    // (signs the per-connection challenge nonce) is the ONLY attach path.
+    // Audit round-9 H1.
     const baseNorm = msg.base ?? null
     // `keyframe === true` is what canonicalSave bound the signature to
     // (strict equality); the signer's intent is unambiguous here.
@@ -230,13 +222,10 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
       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.
+    // Carry `keyframe` as a strict boolean on the broadcast wire — peers
+    // strict-compare `=== true` (matching the canonical-payload
+    // contract). An integer 0/1 here would make a keyframe look like a
+    // regular delta on broadcast paths.
     broadcast(tag, {
       type: 'workspace-state',
       workspaceTag: tag,
@@ -261,15 +250,19 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
   }
 
   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
+    // Mirror handleSave's wire gate: length-cap + base64url-alphabet on
+    // workspaceTag / signature / from BEFORE canonicalSubscribe UTF-8-
+    // encodes them and verifyEd25519 base64-decodes the signature.
+    // Without it a peer can submit up-to-maxPayload strings and force
+    // O(n) encode + decode per subscribe before the 32/64-byte length
+    // gates reject — a CPU-DoS surface handleSave is already hardened
+    // against. `from` keeps the `string | null` contract (null = full-
+    // chain catch-up); a legit signer's `from` is a base64url revision
+    // id, so any non-string / over-long / wrong-alphabet value can't be
+    // one the signature was computed over, and the chain-lookup path
+    // (`typeof msg.from === 'string' ? msg.from : null`) still treats a
+    // null / absent `from` as the keyframe-fallback.
+    if (!validTagSigBase(msg.workspaceTag, MAX_FIELD_LEN) || !validTagSigBase(msg.signature, MAX_FIELD_LEN) || (msg.from != null && !validTagSigBase(msg.from, MAX_FIELD_LEN))) 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

package/server/util.ts

@@ -8,6 +8,15 @@ import { randomBytes } from 'node:crypto'
 // is an Ed25519 public key; operator logs shouldn't carry it verbatim.
 export function debugTag(s: string): string { return `${s.slice(0, 12)}…` }
 
+// Truncated view of a content hash / staging id for logs (objstore GC +
+// 503 diagnostics). Same 12-char prefix convention as `debugTag`; named
+// separately so call sites read as "this is a blob id, not a workspace
+// tag". Tolerates a non-string (logs a placeholder) so a diagnostic
+// path can't itself throw on bad input.
+export function debugId(s: unknown): string {
+  return typeof s === 'string' ? `${s.slice(0, 12)}…` : '<no-id>'
+}
+
 // 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

package/server/ws-server.ts

@@ -55,23 +55,19 @@ export type WsServerDeps = PeerConnectionDeps & {
 }
 
 // Per-connection setup: create Peer, send challenge, wire message /
-// close / error / pong listeners. Shared between the WS connection
-// handler below and the SSE+POST adapter in ./sse-server.ts. The
-// `socket` parameter is the WebSocket-shaped surface (a real `ws`
-// `WebSocket`, or an `SseSession` cast through `as unknown as
-// WebSocket`); the function only uses the subset both expose.
+// close / error / pong listeners. `socket` is the WebSocket-shaped
+// surface — a real `ws` `WebSocket`, or an `SseSession` cast through
+// `as unknown as WebSocket`; only the subset both expose is used.
 export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: PeerConnectionDeps): void {
   const {
     peers, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
     sendSaveError, objstore, track, isShuttingDown, maxInflightPerSocket, debug,
   } = deps
   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.
+  // One Peer holds this connection's state, created before any client
+  // frame can arrive (`socket.on('message')` is wired below). The
+  // heartbeat sweep's two-tick liveness check (see below) is the only
+  // thing closing FDs for an otherwise-idle peer.
   const peer = new Peer(randomId())
   peers.set(socket, peer)
   socket.on('pong', () => { peer.alive = true })
@@ -228,9 +224,8 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
   // 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.
+  // violations). `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)) })
 }