@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.5

package/server/sync-handlers.ts

@@ -5,6 +5,8 @@
 // entrypoint so the protocol logic (the save pipeline, the
 // subscribe/catch-up path) is one cohesive, testable unit.
 
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { Buffer } from 'node:buffer'
 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'
@@ -24,6 +26,47 @@ type WireRevision = {
   signature: string
 }
 
+// Structured result of the shared save pipeline (`commitSave`), rendered
+// per transport: WS → protocol frames; REST → JSON + HTTP status.
+type SaveOutcome =
+  | { kind: 'rejected' }                                   // malformed / bad sig → WS drop / REST 400
+  | { kind: 'ack'; id: string; base: string | null }       // committed → save-ack / 200
+  | { kind: 'duplicate'; id: string; base: string | null } // replay → ack-only / 200
+  | { kind: 'too-large'; base: string | null }             // ciphertext over cap → save-error / 413
+  | { kind: 'unauthorized'; base: string | null }          // new-workspace gate → unauthorized / 401
+  | { kind: 'stale-base'; base: string | null; revisions: WireRevision[] } // conflict → state+error / 409
+
+// Hard cap on a `POST /api/sync/save` JSON body. The save frame is the small
+// fields + a base64 ciphertext capped at MAX_CIPHERTEXT_LEN (2 MiB); 4 MiB
+// (the WS plane's maxPayload / the SSE plane's maxBodyBytes) leaves headroom
+// for the envelope so the in-pipeline size policy — not the reader — decides
+// `too-large`. Bounds the read so a hostile client can't stream an unbounded
+// body into memory before the parse.
+const SAVE_BODY_MAX = 4 * 1024 * 1024
+
+// Read a JSON request body up to `SAVE_BODY_MAX`, returning the parsed value
+// or null on overflow / parse failure / read error (mirrors the objstore
+// mint reader). The REST save body is the only body this module reads.
+async function readSaveBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let total = 0
+  try {
+    for await (const chunk of req) {
+      const buf = chunk as Buffer
+      total += buf.length
+      if (total > SAVE_BODY_MAX) return null
+      chunks.push(buf)
+    }
+  } catch { return null }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) }
+  catch { return null }
+}
+
+function respondJson(res: ServerResponse, status: number, obj: object): void {
+  res.writeHead(status, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(obj))
+}
+
 export type SyncHandlersDeps = {
   handle: Handle
   send: (socket: WebSocket, msg: object) => void
@@ -38,6 +81,11 @@ export type SyncHandlersDeps = {
   subscribe: (socket: WebSocket, tag: string) => void
   getNonce: (socket: WebSocket) => string | undefined
   requiresAuth: (socket: WebSocket) => boolean
+  // Whether an operator password is configured. The REST save plane's
+  // new-workspace gate (it has no socket to read operator-auth state from)
+  // collapses to `passwordConfigured && workspace-new` — the socket-less
+  // analog of `requiresAuth`, matching the objstore `restPutGate`.
+  passwordConfigured: boolean
   sendUnauthorized: (socket: WebSocket, ctx: UnauthorizedContext) => void
   workspaceExists: (tag: string) => Promise<boolean>
   // Objstore inventory snapshot for a workspace tag, as wire rows. The
@@ -52,6 +100,10 @@ export type SyncHandlersDeps = {
 
 export type SyncHandlers = {
   handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
+  // Session-independent REST save plane (`POST /api/sync/save`), wired into
+  // the HTTP dispatcher in server/http.ts. Runs the same pipeline as
+  // `handleSave` and renders the outcome as a JSON response.
+  handleSaveRest: (req: IncomingMessage, res: ServerResponse) => 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).
@@ -59,7 +111,7 @@ export type SyncHandlers = {
 }
 
 export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
-  const { handle, send, broadcast, publishRevision, subscribe, getNonce, requiresAuth, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
+  const { handle, send, broadcast, publishRevision, subscribe, getNonce, requiresAuth, passwordConfigured, 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
@@ -97,9 +149,24 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     return revisions.map((r) => ({ ...r, keyframe: r.keyframe === 1 }))
   }
 
-  async function handleSave(socket: WebSocket, msg: SaveMsg): Promise<void> {
+  // Transport-agnostic save pipeline, shared by the WS `handleSave` renderer
+  // and the REST `handleSaveRest` renderer. Runs the full validate → precheck
+  // → sig-verify → size/auth gates → commit → broadcast pipeline and returns a
+  // structured `SaveOutcome` the caller renders for its transport. Two params
+  // abstract the transport:
+  //   - `authRequired`: the new-workspace gate decision (WS: requiresAuth(
+  //     socket); REST: passwordConfigured — a REST request can't be operator-
+  //     authorised, so the gate collapses to "password set AND workspace new").
+  //   - `except`: the broadcast exclusion — the originating socket on the WS
+  //     path (so it isn't echoed its own save), or null on the REST path (the
+  //     request isn't a subscriber socket; the originator's own echo lands on
+  //     its subscription stream and is an idempotent no-op — applyChainToBase
+  //     skips a revision whose id already equals the client's baseRevision,
+  //     and a same-content re-apply converges. Matches objstore-deleted's
+  //     `except: null`).
+  async function commitSave(msg: SaveMsg, authRequired: boolean, except: WebSocket | null): Promise<SaveOutcome> {
     // `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
+    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 { kind: 'rejected' }
     // 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)
@@ -114,72 +181,43 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     //   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.
+    //      lock. See `commitRevisionSqlite` / `tryCommitNeon` in db*.ts.
     let canonical: Uint8Array<ArrayBuffer>
-    try { canonical = canonicalSave(msg) } catch { return }
+    try { canonical = canonicalSave(msg) } catch { return { kind: 'rejected' } }
     const id = await computeRevisionIdFromCanonical(canonical)
     const tag = msg.workspaceTag
+    const baseNorm = msg.base ?? null
     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
+      return { kind: 'duplicate', id, base: baseNorm }
     }
     if (!await verifyEd25519(tag, canonical, msg.signature)) {
       if (debug) console.warn('reject save: bad signature', debugTag(tag))
-      return
+      return { kind: 'rejected' }
     }
     // 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
+      return { kind: 'too-large', base: baseNorm }
     }
     // 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)) {
+    // doesn't yet exist on the server. Checked AFTER sig verify so the
+    // `unauthorized` outcome only reaches a legitimate signer; shape /
+    // sig attacks still drop silently. The TOCTOU between `workspaceExists`
+    // and the commit's gated INSERT is an accepted soft-policy race — a
+    // racer still had to produce a valid Ed25519 signature (= holds the
+    // seed). Same gate the objstore put-begin applies.
+    if (authRequired && !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
+      return { kind: 'unauthorized', base: baseNorm }
     }
-    // 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
+    // Save does NOT subscribe the sender — that would be a replay vector
+    // (a captured frame replayed from any connection would attach as a
+    // subscriber without holding the seed). Explicit `workspace-subscribe`
+    // (signs the per-connection nonce) is the ONLY attach path. Round-9 H1.
+    //
     // `keyframe === true` is what canonicalSave bound the signature to
     // (strict equality); the signer's intent is unambiguous here.
     const keyframe = msg.keyframe === true
@@ -189,43 +227,24 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     })
     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
+      return { kind: 'duplicate', id, base: baseNorm }
     }
     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`.
+      // Client claimed a base that's no longer head. The catch-up chain is
+      // computed OUTSIDE any lock — a concurrent commit landing here only
+      // means the catch-up is fresher (benign; clients tolerate extra
+      // revisions). The WS renderer sends `workspace-state` (catch-up) FIRST
+      // then the typed `stale-base` error; the REST renderer returns the
+      // chain in the 409 body. Either way the catch-up clears the client's
+      // pending and the error is a no-op on the now-missing pending (a
+      // recoverable race — client rebases + re-saves).
       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
+      return { kind: 'stale-base', base: baseNorm, revisions }
     }
     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). An integer 0/1 here would make a keyframe look like a
-    // regular delta on broadcast paths.
+    // strict-compare `=== true` (matching the canonical-payload contract).
     broadcast(tag, {
       type: 'workspace-state',
       workspaceTag: tag,
@@ -237,16 +256,51 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
         ciphertext: msg.ciphertext,
         signature: msg.signature,
       }],
-    }, socket)
-    // Cross-instance fan-out. The bus payload carries only the revision
-    // id — peers on OTHER instances re-fetch the row from
-    // workspace_revision to compose their local `workspace-state`. Sized
-    // for the bus's 8 KB payload budget, which can't carry a 2 MiB
-    // ciphertext. SQLite mode passes a no-op; Neon mode publishes via
-    // pg_notify. Best-effort: a dropped publish only means peers on
-    // other instances miss the live push, but they still catch up via
-    // the shared DB on their next subscribe / reconnect.
+    }, except)
+    // Cross-instance fan-out. The bus payload carries only the revision id —
+    // peers on OTHER instances re-fetch the row. SQLite mode passes a no-op;
+    // Neon mode publishes via pg_notify. Best-effort.
     publishRevision(tag, id)
+    return { kind: 'ack', id, base: baseNorm }
+  }
+
+  // WS renderer: run the shared pipeline against this socket and render the
+  // outcome as the protocol frames the client expects on its stream. A
+  // `rejected` outcome drops silently (matches the prior malformed/bad-sig
+  // behaviour). For every non-rejected outcome the tag was validated inside
+  // `commitSave`, so the cast to string is sound.
+  async function handleSave(socket: WebSocket, msg: SaveMsg): Promise<void> {
+    const outcome = await commitSave(msg, requiresAuth(socket), socket)
+    if (outcome.kind === 'rejected') return
+    const tag = msg.workspaceTag as string
+    if (outcome.kind === 'unauthorized') { sendUnauthorized(socket, { kind: 'gated', workspaceTag: tag, base: outcome.base }); return }
+    if (outcome.kind === 'too-large') { sendSaveError(socket, tag, outcome.base, 'too-large'); return }
+    if (outcome.kind === 'stale-base') {
+      // State FIRST (its handler clears pending), then the typed error.
+      send(socket, { type: 'workspace-state', workspaceTag: tag, revisions: outcome.revisions })
+      sendSaveError(socket, tag, outcome.base, 'stale-base')
+      return
+    }
+    // ack | duplicate
+    send(socket, { type: 'workspace-save-ack', workspaceTag: tag, base: outcome.base, id: outcome.id })
+  }
+
+  // REST renderer: the session-independent `POST /api/sync/save` plane. Reads
+  // the save frame from the JSON body, runs the SAME pipeline (no socket;
+  // new-workspace gate = passwordConfigured; broadcast except = null), and
+  // maps the outcome to a JSON + HTTP status the client switches on. SSE-mode
+  // clients POST here so a save doesn't take over their event-stream; a 401
+  // routes them to the in-band frame (which runs the operator auth flow).
+  // Mounted + gated (same-origin, shutdown, idle-timeout) in server/http.ts.
+  async function handleSaveRest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const body = await readSaveBody(req)
+    if (!body || typeof body !== 'object') { respondJson(res, 400, { reason: 'bad-request' }); return }
+    const outcome = await commitSave(body as SaveMsg, passwordConfigured, null)
+    if (outcome.kind === 'ack' || outcome.kind === 'duplicate') { respondJson(res, 200, { ok: true, id: outcome.id }); return }
+    if (outcome.kind === 'stale-base') { respondJson(res, 409, { reason: 'stale-base', revisions: outcome.revisions }); return }
+    if (outcome.kind === 'too-large') { respondJson(res, 413, { reason: 'too-large' }); return }
+    if (outcome.kind === 'unauthorized') { respondJson(res, 401, { reason: 'unauthorized' }); return }
+    respondJson(res, 400, { reason: 'bad-request' })
   }
 
   async function handleSubscribe(socket: WebSocket, msg: SubscribeMsg): Promise<void> {
@@ -316,5 +370,5 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
     send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
   }
 
-  return { handleSave, handleSubscribe, sendSaveError }
+  return { handleSave, handleSaveRest, handleSubscribe, sendSaveError }
 }

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