@preventive/triage 1.0.0-alpha.0

package/server/objstore/tokens.ts

@@ -0,0 +1,168 @@
+// Single-use bearer tokens for the v1.objstore REST plane.
+//
+// Issued from the WS plane (after the `objstore-put-begin` /
+// `objstore-fetch` Ed25519 signature verifies) and presented in the
+// `Authorization: Bearer …` header of the corresponding HTTP PUT /
+// GET. The token IS the auth on the REST path — the workspace seed
+// never reaches the HTTP request, only the (HMAC-bound) capability
+// the WS handshake just minted.
+//
+// Format: `${b64url(payloadJson)}.${b64url(hmac)}`
+//   payload:
+//     PUT  → { op: 'put', tag, res, sid, len, exp }
+//     GET  → { op: 'get', tag, res, ver, inc, exp }
+// HMAC: HMAC-SHA-256 over the base64url-encoded payload, with a
+// 32-byte secret minted at server start. Restart invalidates every
+// outstanding token (fine — TTL is short, clients re-handshake).
+//
+// PUT single-use is implicit: the staging row referenced by `sid` is
+// dropped on `commitPut`, so a replayed PUT fails the row lookup.
+// GET is multi-use within the TTL — the bytes are AEAD'd ciphertext
+// the relay can't read, so the leak window for a captured token +
+// captured ciphertext is bounded by `exp` and gives no plaintext.
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+
+export const DEFAULT_TOKEN_TTL_MS = 5 * 60 * 1000
+
+export type PutTokenPayload = {
+  op: 'put'
+  tag: string
+  res: string
+  sid: string
+  len: number
+  exp: number
+}
+
+export type GetTokenPayload = {
+  op: 'get'
+  tag: string
+  res: string
+  ver: number
+  // Incarnation the live row carried when the token was minted. The
+  // REST GET re-checks it so a token issued for one incarnation can't
+  // serve a recreated incarnation that happens to share the version
+  // number.
+  inc: string
+  exp: number
+}
+
+export type TokenPayload = PutTokenPayload | GetTokenPayload
+
+export type TokenSecret = Uint8Array<ArrayBuffer>
+
+export function newTokenSecret(): TokenSecret {
+  // 32 bytes for HMAC-SHA-256 — matches the block / output size and
+  // keeps brute-force forgery ~2^256 work.
+  return randomBytes(32) as Uint8Array<ArrayBuffer>
+}
+
+function b64u(bytes: Buffer | Uint8Array): string {
+  return Buffer.from(bytes).toString('base64url')
+}
+
+function fromB64u(str: string): Buffer {
+  return Buffer.from(str, 'base64url')
+}
+
+function hmac(secret: TokenSecret, data: string): Buffer {
+  // `Uint8Array` IS `BinaryLike` per node:crypto's types — no cast
+  // needed. `createHmac` accepts the secret directly.
+  return createHmac('sha256', secret).update(data).digest()
+}
+
+export function signToken(secret: TokenSecret, payload: TokenPayload): string {
+  const body = b64u(Buffer.from(JSON.stringify(payload), 'utf8'))
+  const sig = b64u(hmac(secret, body))
+  return `${body}.${sig}`
+}
+
+// Returns the parsed payload on success, or null on any failure
+// (malformed shape, bad HMAC, expired). Single error-reason channel
+// keeps the REST handler from leaking distinguishing info to the
+// client — every reject is an opaque 401.
+export function verifyToken(secret: TokenSecret, token: unknown, now: number = Date.now()): TokenPayload | null {
+  if (typeof token !== 'string') return null
+  const dot = token.indexOf('.')
+  if (dot <= 0 || dot === token.length - 1) return null
+  const body = token.slice(0, dot)
+  const sig = token.slice(dot + 1)
+  let expected: Buffer
+  try { expected = hmac(secret, body) } catch { return null }
+  let provided: Buffer
+  try { provided = fromB64u(sig) } catch { return null }
+  // The HMAC output is always 32 bytes; reject any other-length
+  // signature outright (timingSafeEqual itself throws on
+  // length-mismatch). The early return on length is fine
+  // operationally — an attacker controls the sig length they
+  // submit, so leaking that bit isn't a side channel they don't
+  // already know.
+  if (provided.byteLength !== expected.byteLength) return null
+  if (!timingSafeEqual(provided, expected)) return null
+  let parsed: unknown
+  try { parsed = JSON.parse(fromB64u(body).toString('utf8')) } catch { return null }
+  if (!isValidPayload(parsed)) return null
+  if (parsed.exp < now) return null
+  return parsed
+}
+
+function isValidPayload(v: unknown): v is TokenPayload {
+  if (!v || typeof v !== 'object') return false
+  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).
+  if (!Number.isSafeInteger(o['exp']) || (o['exp'] as number) < 0) return false
+  if (o['op'] === 'put') {
+    return typeof o['sid'] === 'string'
+      && typeof o['len'] === 'number'
+      && Number.isSafeInteger(o['len'])
+      && o['len'] >= 0
+  }
+  if (o['op'] === 'get') {
+    return typeof o['ver'] === 'number'
+      && Number.isSafeInteger(o['ver'])
+      && o['ver'] >= 0
+      && typeof o['inc'] === 'string'
+  }
+  return false
+}
+
+// Convenience constructors so the WS handler doesn't have to assemble
+// the payload shape inline.
+export function mintPutToken(
+  secret: TokenSecret,
+  tag: string, res: string, sid: string, len: number,
+  ttlMs: number = DEFAULT_TOKEN_TTL_MS,
+): { token: string; exp: number } {
+  const exp = Date.now() + ttlMs
+  return { token: signToken(secret, { op: 'put', tag, res, sid, len, exp }), exp }
+}
+
+export function mintGetToken(
+  secret: TokenSecret,
+  tag: string, res: string, ver: number, inc: string,
+  ttlMs: number = DEFAULT_TOKEN_TTL_MS,
+): { token: string; exp: number } {
+  const exp = Date.now() + ttlMs
+  return { token: signToken(secret, { op: 'get', tag, res, ver, inc, exp }), exp }
+}
+
+// `Authorization: Bearer <token>` extractor. Returns the token
+// string on match, null otherwise — case-insensitive on the scheme
+// but strict on whitespace shape.
+export function extractBearer(header: unknown): string | null {
+  if (typeof header !== 'string') return null
+  const m = /^Bearer\s+(\S+)\s*$/iu.exec(header)
+  return m ? m[1]! : null
+}

package/server/origin.ts

@@ -0,0 +1,68 @@
+// Same-origin gate for the WS upgrade and REST data plane. We don't
+// support cross-origin browser clients, so any Origin header present
+// on an incoming request MUST match the server's own host (derived
+// from `req.headers.host`, or from `X-Forwarded-Host` /
+// `X-Forwarded-Proto` when a trusted reverse proxy is in front).
+//
+// Why "present-must-match" rather than "always required":
+// - Browser WebSocket handshakes always carry Origin (RFC 6455), so a
+//   foreign-page session attempt always surfaces here.
+// - Browser same-origin XHR/fetch may OMIT Origin; requiring it would
+//   break legitimate same-origin REST calls.
+// - Non-browser clients (the test suite's `ws`, an admin CLI, …) may
+//   also omit Origin. There the trust boundary is the network / token.
+//
+// Reverse-proxy support is OPT-IN via `trustProxy`. When off, we ignore
+// `X-Forwarded-*` and derive the expected origin from `req.headers.host`
+// + `http://`. When on, the proxy headers take precedence. This guards
+// a public-bind deployment (`HOST=0.0.0.0`, no proxy) from a trivial
+// bypass: an attacker page would otherwise send its own
+// `X-Forwarded-Host` + matching `Origin` and walk through. Default: ON
+// for loopback binds (relay behind nginx on same host), OFF otherwise
+// (operator must opt in when fronting a public bind with a proxy).
+
+import type { IncomingMessage as HttpRequest } from 'node:http'
+
+export const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost'])
+
+type HasHeaders = { headers: HttpRequest['headers'] }
+
+export type OriginGate = {
+  // Resolved trust-proxy decision — also read by the boot-time
+  // misconfiguration fail-fast in index.ts.
+  trustProxy: boolean
+  isOriginAllowed(req: HasHeaders): boolean
+}
+
+function firstHeaderValue(v: string | string[] | undefined): string | null {
+  if (typeof v === 'string') return v.split(',')[0]!.trim() || null
+  if (Array.isArray(v) && v.length > 0) return String(v[0]).trim() || null
+  return null
+}
+
+export function createOriginGate(host: string, trustProxyEnv: string | undefined): OriginGate {
+  const trustProxy = trustProxyEnv == null
+    ? LOOPBACK_HOSTS.has(host)
+    : trustProxyEnv === '1' || trustProxyEnv.toLowerCase() === 'true'
+
+  function expectedOrigin(req: HasHeaders): string | null {
+    const xfHost = trustProxy ? firstHeaderValue(req.headers['x-forwarded-host']) : null
+    const xfProto = trustProxy ? firstHeaderValue(req.headers['x-forwarded-proto']) : null
+    const hostHeader = xfHost ?? firstHeaderValue(req.headers['host'])
+    if (!hostHeader) return null
+    const proto = xfProto ?? 'http'
+    return `${proto}://${hostHeader}`
+  }
+
+  function isOriginAllowed(req: HasHeaders): boolean {
+    const origin = firstHeaderValue(req.headers['origin'])
+    // Missing Origin → same-origin browser fetch OR non-browser client.
+    // Both allowed; non-browser callers' trust boundary is the network.
+    if (origin == null) return true
+    const expected = expectedOrigin(req)
+    if (expected == null) return false // Origin present but no Host to compare → deny
+    return origin === expected
+  }
+
+  return { trustProxy, isOriginAllowed }
+}

package/server/peer.ts

@@ -0,0 +1,38 @@
+// 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)`.
+//
+// Held in a `WeakMap<WebSocket, Peer>` so a closed socket's state GCs
+// with the socket; the close handler also `delete`s it explicitly
+// because `ws` keeps the socket strongly referenced well past close.
+
+import type { WebSocket } from 'ws'
+
+export class Peer {
+  // Per-connection challenge nonce (round-9 H2), issued in a
+  // `challenge` frame before any client frame and bound into every
+  // `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.
+  authorized = false
+  // Heartbeat liveness. The sweep flips it `false` after each `ping()`;
+  // the `pong` listener flips it back. A socket still `false` on the
+  // next sweep is terminated.
+  alive = true
+  // In-flight async message handlers spawned for this socket, capped by
+  // MAX_INFLIGHT_PER_SOCKET. Incremented at dispatch, decremented in
+  // the handler's `finally`.
+  inflight = 0
+  // Workspace tags this socket is subscribed to — the per-socket
+  // reverse index used to detach from `subscribers` on close.
+  readonly tags = new Set<string>()
+  constructor(challenge: string) { this.challenge = challenge }
+}
+
+export type PeerRegistry = WeakMap<WebSocket, Peer>

package/server/sign.ts

@@ -0,0 +1,231 @@
+// Ed25519 signature verification for incoming wire messages. The
+// canonical signing payload format is identical to the client's
+// (see client/sync-crypto.js's `canonicalSavePayload`) so a
+// signature produced by a holder of the workspace seed verifies
+// here without re-derivation.
+//
+// Two payload types:
+//   save:      `<domain>\n<pubkey>\n<base>\n<keyframe>\n<nonce>\n<ciphertext>`
+//   subscribe: `<domain>\n<pubkey>\n<from>\n<connectionNonce>`
+//
+// `keyframe` is `1` / `0` (string), bound into the signed bytes so
+// the server can't promote/demote a revision after the fact.
+// `from` is the client's last-applied revision id (or empty for a
+// fresh subscribe), so a captured subscribe sig can't be replayed
+// to fast-forward another peer to a different cursor.
+// `connectionNonce` is a per-socket challenge the server emits in
+// a `challenge` frame the moment the socket opens (round-9 H2). A
+// captured subscribe frame can't be replayed from a different
+// connection because the canonical bytes the captured signature
+// covered include the OLD nonce; the attacker's new connection
+// has a DIFFERENT nonce; signature verify fails.
+//
+// Domains are different so a save signature can't be replayed as
+// a subscribe and vice versa.
+
+import { Buffer } from 'node:buffer'
+import { encodeUtf8 } from '../common/utf8.js'
+
+const SAVE_DOMAIN = 'deepview-triage-sync.v1.save'
+const SUBSCRIBE_DOMAIN = 'deepview-triage-sync.v1.subscribe'
+
+// Wire-message shapes the verifiers accept. Fields land here
+// post-`JSON.parse`, so every value starts life as `unknown` —
+// strict type checks (`typeof x === 'string'`) inside the
+// verifiers are the trust boundary, and call sites can pass any
+// `Record<string, unknown>` shape without casts.
+export type SaveMsg = {
+  workspaceTag?: unknown
+  base?: unknown
+  keyframe?: unknown
+  nonce?: unknown
+  ciphertext?: unknown
+  signature?: unknown
+}
+
+export type SubscribeMsg = {
+  workspaceTag?: unknown
+  from?: unknown
+  signature?: unknown
+}
+
+// `verifySaveSigAndCanonical` returns either the validated canonical
+// bytes (for the follow-up content-id hash) or a flat reject. Modeled
+// as a discriminated union so a caller pattern-matches on `ok`.
+// `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 }
+
+function fromB64Url(str: string): Uint8Array<ArrayBuffer> {
+  // `Buffer.from(..., 'base64url')` returns `Buffer<ArrayBufferLike>`;
+  // WebCrypto's `BufferSource` (per @types/node:
+  // `NonSharedArrayBufferView | ArrayBuffer`) rejects
+  // SharedArrayBuffer-backed views. Node's Buffer pool is always
+  // regular ArrayBuffer at runtime, so narrowing the return type
+  // is safe — the cast is the only way to thread the value through
+  // `crypto.subtle.importKey` / `verify` without a redundant copy.
+  return Buffer.from(str, 'base64url') as Uint8Array<ArrayBuffer>
+}
+
+// Mirrors client/sync-crypto.js's `canonicalSavePayload`. `keyframe`
+// is `'1'` for a keyframe revision (`=== true` exactly), `''`
+// otherwise. STRICT equality, not truthy: a non-boolean truthy
+// value like `keyframe: 1` (which JSON.parse couldn't have
+// produced unless the sender went out of its way) hashes as `''`
+// here, matching `handleSave`'s `msg.keyframe === true` storage
+// rule. Without strict matching the canonical and the storage
+// disagree on which inputs are keyframes, and a malformed save
+// can land in the chain unreadable to peers.
+export function canonicalSave(
+  { workspaceTag, base, keyframe, nonce, ciphertext }: SaveMsg,
+): Uint8Array<ArrayBuffer> {
+  // Strict input gates — defense-in-depth against a future caller
+  // that invokes canonicalSave without going through handleSave's
+  // upstream `validTagSigBase` / `validNonce` / `validCiphertextShape`
+  // gates. `base` is `string | null` (previous revision's id); any
+  // non-string non-null value (object, array, number, ...) would
+  // otherwise coerce via `String(...)` to canonical bytes the client
+  // could never reproduce, producing a verify failure with a
+  // confusing diff in the canonical bytes rather than a clean drop.
+  // Mirrors the `isSafeNonNegativeInt` rigor that the objstore
+  // canonical builders apply. Input-validation audit
+  // `server/sign.ts:88`.
+  if (typeof workspaceTag !== 'string') throw new TypeError('canonicalSave: workspaceTag must be string')
+  if (typeof nonce !== 'string') throw new TypeError('canonicalSave: nonce must be string')
+  if (typeof ciphertext !== 'string') throw new TypeError('canonicalSave: ciphertext must be string')
+  if (base != null && typeof base !== 'string') throw new TypeError('canonicalSave: base must be string or null')
+  return encodeUtf8([
+    SAVE_DOMAIN,
+    workspaceTag,
+    base ?? '',
+    keyframe === true ? '1' : '',
+    nonce,
+    ciphertext,
+  ].join('\n'))
+}
+
+function canonicalSubscribe(
+  { workspaceTag, from }: SubscribeMsg,
+  connectionNonce: string,
+): Uint8Array<ArrayBuffer> {
+  const fromStr = from == null ? '' : String(from)
+  return encodeUtf8([SUBSCRIBE_DOMAIN, workspaceTag as string, fromStr, connectionNonce].join('\n'))
+}
+
+// Exported because the v1.objstore signing module (server/objstore/sign.ts)
+// reuses it for its four verifiers — same workspaceTag-as-pubkey contract,
+// same domain-separated canonical bytes. Keeping the WebCrypto plumbing
+// in one place avoids drift between the triage-sync and objstore verify
+// implementations.
+export async function verifyEd25519(
+  pubkeyB64Url: string,
+  message: Uint8Array<ArrayBuffer>,
+  sigB64Url: string,
+): Promise<boolean> {
+  const pubkeyBytes = fromB64Url(pubkeyB64Url)
+  const sigBytes = fromB64Url(sigB64Url)
+  if (pubkeyBytes.length !== 32) return false
+  if (sigBytes.length !== 64) return false
+  try {
+    const key = await crypto.subtle.importKey(
+      'raw',
+      pubkeyBytes,
+      { name: 'Ed25519' },
+      false,
+      ['verify'],
+    )
+    return await crypto.subtle.verify('Ed25519', key, sigBytes, message)
+  } catch {
+    return false
+  }
+}
+
+// Test-friendly composition: verify the save signature AND return
+// the canonical bytes the signature was checked against, so a
+// follow-up step (computing the content-addressed revision id)
+// hashes the EXACT bytes the signature covered. Returns
+// `{ ok: false, canonical: null }` on bad shape / bad sig;
+// `{ ok: true, canonical: <bytes> }` on success.
+//
+// NOT used by `server/index.ts handleSave`. Production composes
+// the smaller helpers (`canonicalSave`, `computeRevisionIdFromCanonical`,
+// `verifyEd25519`) separately so the dup-precheck via
+// `revisionExists` can fire BEFORE Ed25519-verify and skip the
+// expensive crypto work on a replayed save (round-9 H1 CPU-DoS
+// defense). The helper survives because unit tests in
+// `tests/server-sign.test.js` benefit from a clean single-call
+// surface; the round-9 H1 ordering is exercised end-to-end in
+// `tests/sync-server.test.js`.
+//
+// `encodeUtf8` throws on non-string or lone-surrogate input (any of
+// which on the wire is already a hostile / malformed message), so
+// any error in the canonical-payload path is a verification failure.
+export async function verifySaveSigAndCanonical(msg: SaveMsg): Promise<VerifyResult> {
+  // Type-check `workspaceTag` here (alongside `signature`) so a
+  // non-string slips reach `fromB64Url(msg.workspaceTag)` inside
+  // `verifyEd25519` — `fromB64Url` is `Buffer.from(s, 'base64url')`,
+  // which throws TypeError on non-string non-array-like input.
+  // Without this gate, the throw escapes verifyEd25519 (it lives
+  // BEFORE the try/catch around the WebCrypto calls) and the function
+  // rejects with TypeError instead of honouring its `{ ok: false,
+  // canonical: null }` contract — a malformed wire message would
+  // bubble out as a connection-handler exception rather than a clean
+  // drop. Audit round-11.
+  if (typeof msg.workspaceTag !== 'string') return { ok: false, canonical: null }
+  if (typeof msg.signature !== 'string') return { ok: false, canonical: null }
+  let payload: Uint8Array<ArrayBuffer>
+  try { payload = canonicalSave(msg) } catch { return { ok: false, canonical: null } }
+  const ok = await verifyEd25519(msg.workspaceTag, payload, msg.signature)
+  return ok ? { ok: true, canonical: payload } : { ok: false, canonical: null }
+}
+
+// Content-addressed revision id — SHA-256 of the canonical save
+// bytes (same input the signature covers), base64url no padding.
+// Server doesn't get to assign ids: it derives the id from received
+// content and stores under that. Mirrors the client's
+// `computeRevisionId` so two ends always land on the same string.
+// Takes the canonical bytes produced by `canonicalSave` (or, in
+// tests, returned by `verifySaveSigAndCanonical`) so the hash is
+// over EXACTLY the bytes the signature covered.
+export async function computeRevisionIdFromCanonical(canonical: Uint8Array<ArrayBuffer>): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', canonical)
+  return Buffer.from(new Uint8Array(digest)).toString('base64url')
+}
+
+// `connectionNonce` is the per-socket challenge the server issued
+// to the originating connection (see `Peer.challenge` in
+// server/peer.ts). The client signs a canonical that includes the
+// nonce; verifying against the SAME nonce here is what blocks
+// cross-connection replay of a captured subscribe frame. Audit
+// round-9 H2.
+export async function verifySubscribeSig(msg: SubscribeMsg, connectionNonce: unknown): Promise<boolean> {
+  // `async` + `await` the verifyEd25519 result. Without `async` the
+  // function's verify path returned a `Promise<boolean>` while its
+  // type-check / canonical-throw paths returned the literal `false`
+  // — a caller using it as a synchronous predicate (`if
+  // (verifySubscribeSig(...))`) would treat the truthy Promise as
+  // "valid" and accept arbitrary forged signatures. Production's
+  // only call site already `await`s, but the inconsistency was a
+  // footgun for any future caller. Audit round-11.
+  // Same workspaceTag type-check as `verifySaveSigAndCanonical` —
+  // see that function for the rationale (fromB64Url throws TypeError
+  // on non-string and the throw escapes verifyEd25519's try/catch).
+  if (typeof msg.workspaceTag !== 'string') return false
+  if (typeof msg.signature !== 'string') return false
+  if (typeof connectionNonce !== 'string') return false
+  let payload: Uint8Array<ArrayBuffer>
+  try { payload = canonicalSubscribe(msg, connectionNonce) } catch { return false }
+  return await verifyEd25519(msg.workspaceTag, payload, msg.signature)
+}