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

package/server/sse-server.ts

@@ -52,6 +52,24 @@ import { errMsg, randomId } from './util.ts'
 // path so the same `location` block routes both.
 export const SSE_OPEN_PATH = '/api/sync/sse'
 
+// Cadence of the server-driven keepalive sweep: every tick we write a `:`
+// comment to each open session's downstream so intermediary proxies don't
+// idle-close it (nginx et al. default to a ~60s read timeout). This is the
+// server's own liveness upkeep — the client no longer POSTs a periodic ping
+// (which forced a stream takeover every tick).
+//
+// Reaping model (replaces the old POST-driven idle timer): a session is
+// dropped on its downstream response `close` — clean disconnect, or a
+// half-open socket the per-session TCP keepalive forces closed (see
+// SseSession.SOCKET_KEEPALIVE_MS) — NOT by this sweep. We intentionally
+// trust connection-level liveness. The one topology this can't see is a
+// buffering / TLS-terminating proxy that holds the upstream open after the
+// real client vanished (keepalive then probes the proxy hop, not the
+// client); such a session lingers until `maxSessions`, the hard backstop.
+// This is the same exposure the WS heartbeat already has (its ping only
+// proves the proxy↔server hop too), not a new class of leak.
+const KEEPALIVE_SWEEP_MS = 30_000
+
 export type SseServerDeps = {
   // The WS dispatch is the cohesive unit; SSE just provides another
   // transport into it. Closure over the same handler / hub / objstore
@@ -70,12 +88,6 @@ export type SseServerDeps = {
   // the per-frame budget is the same as the WS plane after the
   // dispatcher splits them.
   maxBodyBytes: number
-  // Idle timeout for a session with no inbound POSTs. Detects the
-  // wandered-off browser tab the WS heartbeat sweep handles via
-  // ping/pong on real sockets. The client's JSON ping/pong heartbeat
-  // (every 15s) is the steady-state liveness signal; this is the
-  // hard ceiling.
-  sessionIdleMs: number
   debug: boolean
 }
 
@@ -86,6 +98,9 @@ export type SseServer = {
   // Iterates active sessions. Lifecycle's graceful-shutdown loop
   // reads this to close SSE sessions alongside WS clients.
   sessions: () => Iterable<SseSession>
+  // The keepalive-sweep timer. Lifecycle clears it on shutdown (parity
+  // with the WS heartbeat timer) so a tick can't fire mid-teardown.
+  keepaliveTimer: ReturnType<typeof setInterval>
 }
 
 // Inbound POST body. Every field optional — an empty-body POST is a
@@ -98,7 +113,7 @@ type SseBody = {
 }
 
 export function installSseServer(deps: SseServerDeps): SseServer {
-  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, sessionIdleMs, debug } = deps
+  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, debug } = deps
 
   // Active SSE sessions, keyed by the random session id `createSession`
   // mints on the first POST that lacks a `?id=` (or whose id this
@@ -108,26 +123,9 @@ export function installSseServer(deps: SseServerDeps): SseServer {
   // mint a fresh session instead, so a multi-replica deployment doesn't
   // require sticky LB routing to recover.
   const sessions = new Map<string, SseSession>()
-  // Per-session idle timer handle. Reset on every inbound POST; fires
-  // after `sessionIdleMs` of silence to close a stranded session.
-  const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
-
-  function armIdleTimer(sid: string, session: SseSession): void {
-    clearTimeout(idleTimers.get(sid))
-    if (sessionIdleMs <= 0) return
-    const t = setTimeout(() => {
-      if (debug) console.warn(`sse: session ${sid.slice(0, 8)}… idle ${sessionIdleMs}ms → close`)
-      try { session.terminate() } catch {}
-    }, sessionIdleMs)
-    t.unref?.()
-    idleTimers.set(sid, t)
-  }
 
   function dropSession(sid: string): void {
     sessions.delete(sid)
-    const t = idleTimers.get(sid)
-    if (t) clearTimeout(t)
-    idleTimers.delete(sid)
   }
 
   function writeSseHeaders(res: ServerResponse): void {
@@ -149,7 +147,7 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     res.write('retry: 1000\n\n')
   }
 
-  function createSession(res: ServerResponse, req: HttpRequest): { sid: string; session: SseSession } | null {
+  function createSession(res: ServerResponse, req: HttpRequest): SseSession | null {
     if (sessions.size >= maxSessions) {
       if (debug) console.warn(`sse: refused open — sessions ${sessions.size} >= ${maxSessions}`)
       return null
@@ -158,7 +156,6 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     const sid = randomId()
     const session = new SseSession(res)
     sessions.set(sid, session)
-    armIdleTimer(sid, session)
     session.on('close', () => { dropSession(sid) })
     // Announce the continuation token BEFORE the dispatcher emits its
     // `challenge` frame so the client latches the id first and the
@@ -171,7 +168,7 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     // `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 }
+    return session
   }
 
   // Drives a POST body's `password` and `frames` through the shared
@@ -268,19 +265,16 @@ export function installSseServer(deps: SseServerDeps): SseServer {
       // through to createSession with `res` still header-virgin, so
       // the new session can writeSseHeaders without ERR_HTTP_HEADERS_SENT.
       let session: SseSession | null = null
-      let sid: string | null = null
       if (sidFromUrl) {
         const existing = sessions.get(sidFromUrl)
         if (existing && existing.readyState === existing.OPEN && existing.attachResponse(res)) {
           writeSseHeaders(res)
           session = existing
-          sid = sidFromUrl
-          armIdleTimer(sid, session)
         }
       }
       if (!session) {
-        const created = createSession(res, req)
-        if (!created) {
+        session = createSession(res, req)
+        if (!session) {
           // Cap exceeded; createSession already logged. Response
           // headers not yet written by writeSseHeaders, so send a
           // 503 JSON instead.
@@ -288,8 +282,6 @@ export function installSseServer(deps: SseServerDeps): SseServer {
           res.end(JSON.stringify({ error: 'too-many-sessions' }))
           return
         }
-        session = created.session
-        sid = created.sid
       }
       dispatchBody(session, body)
       // Do NOT res.end() — the response stays open as the session's
@@ -323,7 +315,22 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     return true
   }
 
-  return { handle, sessions: () => sessions.values() }
+  // Server-driven keepalive sweep. Writes a `:` comment to every open
+  // session's downstream so proxies don't idle-close it. `unref` so it can't
+  // by itself hold the event loop open (parity with the WS heartbeat timer);
+  // skipped during shutdown so a tick can't write to a session the close
+  // loop is tearing down. Dead-session reaping is the response `close` event
+  // (see SseSession.wireResponse + the per-session TCP keepalive), NOT this
+  // sweep — so a half-open client is dropped without ever POSTing.
+  const keepaliveTimer = setInterval(() => {
+    if (isShuttingDown()) return
+    for (const session of sessions.values()) {
+      try { session.ping() } catch {}
+    }
+  }, KEEPALIVE_SWEEP_MS)
+  keepaliveTimer.unref?.()
+
+  return { handle, sessions: () => sessions.values(), keepaliveTimer }
 }
 
 // Bare-bones query parse for `id=<base64url>`. Avoids URLSearchParams

package/server/sse-session.ts

@@ -28,6 +28,20 @@ import { EventEmitter } from 'node:events'
 import type { Buffer } from 'node:buffer'
 import type { ServerResponse } from 'node:http'
 
+// TCP keepalive idle delay for the downstream socket. With the client no
+// longer POSTing a periodic ping (see client/sync/socket-transport.ts), a
+// QUIET session whose client vanished without a FIN (crash, NAT/idle drop)
+// has no application-level liveness signal — so we lean on the kernel:
+// after this much idle the kernel starts probing, and a dead half-open
+// socket surfaces as a `close`/`error` here. Node's `setKeepAlive` sets
+// only TCP_KEEPIDLE (the delay to the FIRST probe), not the probe
+// interval/count — so full teardown is this delay PLUS the OS's
+// TCP_KEEPINTVL × TCP_KEEPCNT (~minutes on Linux defaults), still bounded
+// and far below the kernel's hours-long default-off behaviour. `maxSessions`
+// is the hard backstop. Behind a TLS-terminating / buffering proxy this
+// probes the proxy hop, not the client — see the reaping note in sse-server.ts.
+const SOCKET_KEEPALIVE_MS = 30_000
+
 export class SseSession extends EventEmitter {
   static readonly CONNECTING = 0
   static readonly OPEN = 1
@@ -62,6 +76,10 @@ export class SseSession extends EventEmitter {
   // spurious session 'error' that operators read as a real transport
   // failure on a healthy session.
   private wireResponse(res: ServerResponse): void {
+    // Probe half-open downstreams at the kernel level (see SOCKET_KEEPALIVE_MS).
+    // A failed probe trips the `close`/`error` handlers below, which is how a
+    // dead-but-quiet SSE client is reaped now that there's no client ping.
+    try { res.socket?.setKeepAlive(true, SOCKET_KEEPALIVE_MS) } catch {}
     res.on('close', () => {
       if (res !== this.currentRes) return  // current-response guard (see above)
       if (this.readyState === SseSession.CLOSED) return
@@ -142,9 +160,8 @@ export class SseSession extends EventEmitter {
   // double-emit), which means without the explicit emit here neither
   // sse-server's dropSession cleanup nor setupPeerConnection's
   // unsubscribeAll/peers.delete would run on any server-initiated
-  // teardown — sessions / hub.subscribers / idleTimers would leak per
-  // close. The wireResponse guard then ensures the later async fire
-  // is a no-op.
+  // teardown — the sessions map / hub.subscribers would leak per close.
+  // The wireResponse guard then ensures the later async fire is a no-op.
   close(code?: number, reason?: string): void {
     if (this.readyState === SseSession.CLOSED) return
     const res = this.currentRes
@@ -173,11 +190,14 @@ export class SseSession extends EventEmitter {
     this.emit('close')
   }
 
-  // The heartbeat sweep ping()s every WS client to detect dead sockets
-  // via the unanswered-pong path. SSE has no `pong` equivalent, so we
-  // write a comment line that keeps the channel alive across proxies
-  // without expecting a reply. The per-session idle timeout in
-  // sse-server.ts owns the dead-client detection.
+  // Server-driven keepalive, called on the SSE keepalive sweep in
+  // sse-server.ts. SSE has no `pong` equivalent, so we write a `:` comment
+  // line — ignored by the client parser — that keeps the downstream from
+  // being idle-closed by intermediary proxies (nginx et al. default to a
+  // ~60s read timeout). Dead-client detection is the response `close` event
+  // (clean disconnect, or a half-open socket the TCP keepalive in
+  // `wireResponse` forces closed), NOT this write: a `:`-comment write to a
+  // half-open socket just buffers, it doesn't synchronously throw.
   ping(): void {
     if (this.readyState !== SseSession.OPEN) return
     const res = this.currentRes

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 }
 }