docs(adr): ADR-0012 wire-input hardening

Records decisions from plan-005: shape-guard drop policy (drop+log, no
reply — mirrors undecodable bytes), the three limits and their
defaults/override pattern, execute-error sanitization with authorize
exempt (mut path), and the explicit deferral of dedup identity binding.

Also applies one finding from the codex adversarial review (gpt-5.5):

  Finding 3 — APPLIED: JSON.stringify(decoded) in the wellFormed drop
  path could throw on bigint values (MessagePack useBigInt64 may decode
  bigints). Fixed by using a replacer that stringifies bigints as strings,
  with a fallback to String(decoded) on any other error. The drop+log
  behaviour is now crash-safe for all decoded values.

Rebuttals for findings NOT applied:

  Finding 1 — NOT a gap: replay stores the SANITIZED message ("mutation
  failed") because rejectTx writes the generic string to recordTx before
  the dedup record is written. Old records (pre-upgrade) with SQLite detail
  would only replay if they exist at deploy time; that is a deploy-time
  concern, not a code gap.

  Finding 2 — BY DESIGN: "no mutation handler for '...:...'" is the
  authorize-path catch, kept user-facing per the plan (README: "throw to
  deny"). Exposing the collection:type name is consistent with the library's
  author-configuring-the-DO model; the attacker is already authed. Noted
  in ADR for future review.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: grrowl

docs/adr/0012-wire-input-hardening.md

@@ -0,0 +1,102 @@
+# ADR-0012: Wire-input hardening — frame-shape guards, inbound limits, sanitized execute errors
+
+**Status**: Accepted
+**Date**: 2026-06-11
+**Plan**: [005-wire-input-hardening.md](../../plans/005-wire-input-hardening.md)
+
+## Context
+
+The DO trusted every *decoded* frame's shape. MessagePack decoding was already
+guarded (`webSocketMessage` ignored undecodable bytes), but a frame that decoded
+to the wrong *shape* was dispatched as-is: a `mut` whose `txId` was an object
+could reach `lookupTx` and `sql.exec` bindings with an arbitrary value.
+
+Additionally, nothing capped `ops` length, per-socket subscriptions, or inbound
+frame size, so one authenticated client could force unbounded allocation. And a
+thrown `execute` error's raw message (SQLite constraint text, column names, etc.)
+was forwarded verbatim to the client — leaking internal schema detail.
+
+None of these are unauthenticated holes — the attacker is already an authed socket
+on the same DO — but the library's ethos is reject-don't-degrade, and these are
+the cheap mechanical layers of that.
+
+## Decisions
+
+### D1: Shape guard — drop and log, no reply
+
+A `wellFormed(v: unknown): v is ClientFrame` check runs after decode, before any
+SQL binding. A frame that fails the check is dropped with a server-side
+`console.error` (fail loud in logs) and **no client reply** — mirroring the
+existing "ignore undecodable frames" stance and extending its comment.
+
+The guard validates per variant of `ClientFrame` (enumerated from
+`src/wire/frames.ts`): required fields are checked for correct type and
+non-emptiness; optional fields treat `null` as absent (the client transport
+serialises absent fields as `null` in MessagePack rather than omitting them).
+`where`/`orderBy` fields are left `unknown` — the sql-compiler is their
+validator (it already `fail-loud`s via `UnsupportedPredicateError`).
+
+### D2: Three overrideable limits as `protected readonly` tunables
+
+Following the `tickMs`/`compactionEvery` field pattern (doc comment, `protected
+readonly`, override-able by subclasses at construction time):
+
+- **`maxOpsPerMutation = 128`**: checked at the top of `handleMut`. **Reject,
+  don't truncate** — a partial apply would silently drop client writes. Sends
+  `rejected` with `code: "LIMIT_EXCEEDED"`.
+- **`maxSubsPerSocket = 256`**: checked in `handleSub` before `subs.add`. A
+  re-sub on an existing `subId` replaces the old entry
+  (`SubscriptionRegistry.add` semantics) and does NOT count against the cap —
+  only genuinely new sub IDs are counted. Over-limit → `reset` for the refused
+  `subId` + `console.error`. (Reset is the existing "sub refused" signal.)
+- **`maxFrameBytes = 1_048_576`**: checked in `webSocketMessage` before decode
+  (`typeof message === "string" ? message.length : message.byteLength`).
+  Oversize → drop + `console.error`. Cloudflare caps WS messages at ~1 MiB
+  anyway; this makes the bound explicit, testable, and overrideable.
+
+`SubscriptionRegistry.countFor(ws)` was added to expose the per-socket count
+without exposing the internal Map.
+
+### D3: Execute-error sanitization; authorize errors stay user-facing
+
+In `handleMut`, there are two catch sites:
+
+- **Authorize catch**: unchanged. Authorize errors are user-facing API
+  (`README: "throw to deny"`). The error message passes through verbatim.
+- **Execute catch (transaction)**: the full error is logged server-side
+  (`console.error`) and a **generic** `"mutation failed"` message with code
+  `"EXECUTE_FAILED"` is sent to the client. SQLite constraint strings, column
+  names, and programming-error text are internal detail — not client API surface.
+
+In `handleCall`, authorize and execute share one try/catch. Command authorize
+errors are not currently user-facing API in the same way mutation authorize is, so
+the entire catch is sanitized: log full detail server-side, send `"command failed"`
+with `"EXECUTE_FAILED"` to the client.
+
+**Compatibility note**: the client-visible error text for execute failures changed.
+Callers who matched on specific SQLite error strings or programming-error messages
+must update to the generic messages/codes. Authorize-path messages are unchanged.
+
+### D4: Dedup identity binding deferred
+
+`_sync_seen_tx` is keyed by `txId` alone; any authed socket presenting a
+guessed/leaked txId receives the stored receipt. Risk is low (txIds are
+client-random UUIDs) but the fix needs an identity-keying decision (`TUser` is
+author-defined and unserializable in general — likely a `protected
+dedupScope(user: TUser): string` hook). This is **explicitly deferred** pending
+a maintainer design decision.
+
+## Consequences
+
+- **Security**: arbitrary decoded values no longer reach SQL bindings; inbound
+  resource exhaustion is bounded; internal schema detail does not leak to clients.
+- **Behavior change** (observable by consumers): execute-path `rejected` frames
+  now carry `"mutation failed"`/`"command failed"` + `"EXECUTE_FAILED"` instead of
+  the raw error message. Authorize-path messages are unchanged.
+- **Hibernation**: no idle timers were introduced. All new checks are synchronous
+  and run on the existing `webSocketMessage` path.
+- **Extensibility**: all three limits are `protected readonly` — subclasses can
+  override at construction time. `LimitsTestDO` in the test worker exercises this.
+- **Test coverage**: `tests/wire-hardening.test.ts` (5 tests) pins all four
+  invariants; `tests/error-paths.test.ts` was updated to assert the new generic
+  error text for execute failures.

docs/adr/README.md

@@ -18,3 +18,4 @@ explains the displacement.
 | [0008](./0008-orphaned-cdc-triggers.md) | Orphaned CDC triggers when a collection is removed | Accepted |
 | [0009](./0009-changelog-time-retention.md) | Changelog time-based retention; reset stale reconnects | Accepted |
 | [0010](./0010-typed-mutations-collection-manifest.md) | Typed mutations via a collection-row manifest on `SyncRegistry` | Accepted |
+| [0012](./0012-wire-input-hardening.md) | Wire-input hardening: frame-shape guards, inbound limits, sanitized execute errors | Accepted |

src/server/sync-do.ts

@@ -166,7 +166,16 @@ export abstract class SyncDurableObject<Env = unknown, TUser = unknown> extends
     // wrong structure is dropped + logged. The guard runs BEFORE any SQL
     // binding so no arbitrary decoded value reaches lookupTx or sql.exec.
     if (!this.wellFormed(decoded)) {
-      console.error("malformed frame dropped", JSON.stringify(decoded))
+      // Safe stringify: decoded may contain bigints (MessagePack useBigInt64);
+      // JSON.stringify throws on bigint — use a replacer to avoid crashing the
+      // logging itself.
+      let summary: string
+      try {
+        summary = JSON.stringify(decoded, (_k, v) => (typeof v === "bigint" ? String(v) : v))
+      } catch {
+        summary = String(decoded)
+      }
+      console.error("malformed frame dropped", summary)
       return
     }