cursedbelt-server 4.1.0 → 4.3.0

package/src/server/middleware/bodyLimit.ts

@@ -0,0 +1,210 @@
+/**
+ * Reading a request body without first agreeing how big it may be.
+ *
+ * ── Why this is one function rather than one per app (2026-07-27) ────────────
+ * The two apps behind the shared owner-auth were inconsistently hardened, in a
+ * way an adversarial review found and neither test suite could:
+ *
+ * - the companion app (since folded into `apps/orch`) read `c.req.text()`,
+ *   checked the length, and returned 413 BEFORE parsing — correct.
+ * - `apps/roms` called `await c.req.json()` first and checked the size deep
+ *   inside the save-state store — i.e. it buffered and parsed an arbitrary body
+ *   into a process whose unit caps at 300 MB of memory before forming an
+ *   opinion about its size.
+ *
+ * Both went through {@link readBoundedJson} after that. The guard is one
+ * function so the posture cannot diverge again, and it is deliberately the
+ * *last* line of defense: a proxy's `client_max_body_size` refuses an oversized
+ * body at the edge, and this refuses it if the proxy is absent, misconfigured,
+ * or bypassed — which is exactly the case in dev, in `preview:prod`, and for any
+ * request that reaches the loopback port directly.
+ *
+ * ── Where it came from (2026-09-17) ──────────────────────────────────────────
+ * Five apps — `roms`, `family`, `music`, `vault`, `collections` — carried this
+ * file byte-for-byte identical (`b36d0eedee7a`), which is the posture diverging
+ * again, only more slowly and with nothing watching: a repo's gate proves that
+ * repo, so five green gates is what five copies of a security guard look like
+ * from the outside. Confirmed identical with `shasum -a256` before the move, so
+ * there was no fork to reconcile and nothing was dropped.
+ *
+ * 🔴 It is published as the LEAF subpath `cursedbelt-server/body-limit`, never
+ * through the `./middleware` barrel — that barrel drags `hono` and the error
+ * envelope, and this module's whole promise is that it imports NOTHING. The
+ * source is a `{ req: { text() } }` / `{ req: { arrayBuffer() } }` /
+ * `{ req: { header() } }` structural type rather than a Hono context, so a
+ * caller needs no framework to use it and a test needs none to exercise it.
+ * `src/leafSubpathsImportNothing.spec.ts` is what holds that promise.
+ */
+
+/** What {@link readBoundedBytes} gives back. */
+export type BoundedBytes =
+  | { ok: true; value: Uint8Array }
+  | { ok: false; status: 413 | 400; error: string };
+
+/** The minimum a route needs to hand over a raw body. */
+export interface BodyBytesSource {
+  req: { arrayBuffer(): Promise<ArrayBuffer> };
+}
+
+/** What {@link readBoundedJson} gives back — a discriminated result, never a throw. */
+export type BoundedJson<T> =
+  | { ok: true; value: T }
+  | { ok: false; status: 413; error: string }
+  | { ok: false; status: 400; error: string };
+
+export interface BoundedJsonOptions {
+  /** Hard ceiling on the raw body, in bytes. */
+  maxBytes: number;
+  /** What to call the payload in the error message (e.g. "save state"). */
+  label?: string;
+}
+
+/** The minimum a route needs from Hono's context — kept structural so tests need no Hono. */
+export interface BodyTextSource {
+  req: { text(): Promise<string> };
+}
+
+/** What {@link readBoundedText} gives back. Same shape, minus the parse failure. */
+export type BoundedText =
+  | { ok: true; value: string }
+  | { ok: false; status: 413 | 400; error: string };
+
+/**
+ * Read a body as TEXT, refusing anything over `maxBytes`.
+ *
+ * The sibling of {@link readBoundedJson}, for a payload that IS the text rather
+ * than a document containing it — `apps/patterns`' chunked sends put their
+ * metadata in the query string and the chunk in the raw body, which spares a
+ * megabyte-scale caller from JSON-escaping every piece and spares this process
+ * from parsing what it is only going to concatenate.
+ *
+ * Same byte-not-character measurement, and for the same reason: it is the number
+ * the proxy in front of this is enforcing.
+ */
+export async function readBoundedText(
+  c: BodyTextSource,
+  options: BoundedJsonOptions,
+): Promise<BoundedText> {
+  const { maxBytes, label = 'body' } = options;
+  let raw: string;
+  try {
+    raw = await c.req.text();
+  } catch {
+    return { ok: false, status: 400, error: `${label} could not be read` };
+  }
+  const bytes = new TextEncoder().encode(raw).length;
+  if (bytes > maxBytes) {
+    return {
+      ok: false,
+      status: 413,
+      error: `${label} too large (${bytes} bytes; the limit is ${maxBytes})`,
+    };
+  }
+  return { ok: true, value: raw };
+}
+
+/**
+ * Read a body as RAW BYTES, refusing anything over `maxBytes`.
+ *
+ * The third member of the family, for a payload that is neither JSON nor text:
+ * roms' ROM-upload chunks are cartridge bytes, and routing them through
+ * {@link readBoundedText} would decode arbitrary binary as UTF-8 — which is
+ * lossy (every invalid sequence becomes U+FFFD) and measures a size that is not
+ * the size the proxy in front is enforcing.
+ *
+ * A `Content-Length` claim is deliberately NOT trusted here: it is a header, and
+ * the guard has to hold against a body that disagrees with it. The measurement is
+ * the buffer that actually arrived.
+ */
+export async function readBoundedBytes(
+  c: BodyBytesSource,
+  options: BoundedJsonOptions,
+): Promise<BoundedBytes> {
+  const { maxBytes, label = 'body' } = options;
+  let buffer: ArrayBuffer;
+  try {
+    buffer = await c.req.arrayBuffer();
+  } catch {
+    return { ok: false, status: 400, error: `${label} could not be read` };
+  }
+  if (buffer.byteLength > maxBytes) {
+    return {
+      ok: false,
+      status: 413,
+      error: `${label} too large (${buffer.byteLength} bytes; the limit is ${maxBytes})`,
+    };
+  }
+  return { ok: true, value: new Uint8Array(buffer) };
+}
+
+/** The minimum {@link refuseOversizedBody} needs — a header lookup, nothing else. */
+export interface BodyHeaderSource {
+  req: { header(name: string): string | undefined };
+}
+
+/**
+ * Refuse a body by its DECLARED `Content-Length`, without reading it.
+ *
+ * The fourth member of the family, and the only one for a body that cannot be
+ * buffered first: a `multipart/form-data` upload. The other three measure the
+ * bytes that actually arrived, which is strictly better — but they get to,
+ * because they buffer. `c.req.formData()` gives no such opportunity: by the time
+ * it resolves, the whole upload is already in a process whose unit caps at
+ * 300 MB of memory, which is the thing the limit exists to prevent.
+ *
+ * So this trusts the header, and the docblock says so plainly. A liar gets
+ * through to the buffering call — but a liar was always going to, and this still
+ * turns the honest 3 GB folder-drop (the actual failure shape) into a refusal
+ * the app can explain instead of an OOM or an nginx HTML 413 the app never sees.
+ * It is a companion to the proxy's `client_max_body_size`, never a replacement.
+ *
+ * A missing or unparseable header is NOT a refusal: chunked requests omit it
+ * legitimately, and refusing them would break a correct client to catch a
+ * dishonest one.
+ */
+export function refuseOversizedBody(
+  c: BodyHeaderSource,
+  options: BoundedJsonOptions,
+): { status: 413; error: string } | null {
+  const { maxBytes, label = 'body' } = options;
+  const declared = Number(c.req.header('content-length'));
+  if (!Number.isFinite(declared) || declared <= maxBytes) return null;
+  return {
+    status: 413,
+    error: `${label} too large (${declared} bytes; the limit is ${maxBytes})`,
+  };
+}
+
+/**
+ * Read a JSON body, refusing anything over `maxBytes` before parsing it.
+ *
+ * The size is measured in BYTES, not characters. `String.length` counts UTF-16
+ * code units, so a body of 4-byte emoji measures half its true size that way —
+ * which would let a caller past a byte limit the proxy is enforcing in real
+ * bytes, and produce the mismatch this module exists to close.
+ */
+export async function readBoundedJson<T = unknown>(
+  c: BodyTextSource,
+  options: BoundedJsonOptions,
+): Promise<BoundedJson<T>> {
+  const { maxBytes, label = 'body' } = options;
+  let raw: string;
+  try {
+    raw = await c.req.text();
+  } catch {
+    return { ok: false, status: 400, error: `${label} could not be read` };
+  }
+  const bytes = new TextEncoder().encode(raw).length;
+  if (bytes > maxBytes) {
+    return {
+      ok: false,
+      status: 413,
+      error: `${label} too large (${bytes} bytes; the limit is ${maxBytes})`,
+    };
+  }
+  try {
+    return { ok: true, value: JSON.parse(raw) as T };
+  } catch {
+    return { ok: false, status: 400, error: `${label} must be JSON` };
+  }
+}