@fuzdev/fuz_app 0.134.0 → 0.135.0

package/dist/auth/cell_actions.js

@@ -165,7 +165,7 @@ export const create_cell_actions = (deps) => {
         // **in-tx** (only when an authorizer is mounted), reusing the parent row
         // when the parent *is* the root, else one read by `root_id` — so the
         // authorizer stays pure + the read rides the handler's connection (no
-        // separate-handle deadlock on the single-connection PGlite).
+        // separate-handle deadlock on the single-connection in-memory drivers).
         const parent_id = input.parent_id ?? null;
         let root_id = null;
         let root_data = null;

package/dist/auth/role_schema.d.ts

@@ -24,7 +24,17 @@ import { z } from 'zod';
 import { type CredentialTypeSchemaResult } from './credential_type_schema.js';
 import { type GrantPathSchemaResult } from './grant_path_schema.js';
 import type { ScopeKindSchemaResult } from './scope_kind_schema.js';
-/** Valid role name: lowercase letters and underscores, no leading/trailing underscore. */
+/**
+ * The longest role name `RoleName` admits, in characters. A role string is
+ * caller-chosen text until it passes the grammar, and the grant verbs record
+ * the role they refuse in a failure audit row, so the grammar bounds its
+ * length too. Same value as the Rust spine's `ROLE_NAME_LENGTH_MAX`.
+ */
+export declare const ROLE_NAME_LENGTH_MAX = 64;
+/**
+ * Valid role name: lowercase letters and underscores, no leading/trailing
+ * underscore, at most `ROLE_NAME_LENGTH_MAX` characters.
+ */
 export declare const RoleName: z.ZodString;
 export type RoleName = z.infer<typeof RoleName>;
 /** System-level role. Requires daemon token (filesystem proof). Controls the keep. */
@@ -78,7 +88,7 @@ export declare const is_builtin_role: (name: string) => name is BuiltinRole;
  * `builtin_role_specs_by_name`.
  */
 export interface RoleSpec {
-    /** Unique role name. Must match `RoleName` regex; collisions with builtins throw. */
+    /** Unique role name. Must match `RoleName` — its regex and length cap; collisions with builtins throw. */
     name: string;
     /** Admin-UI-facing copy describing the role's intent. */
     description?: string;
@@ -146,7 +156,8 @@ export interface RoleSchemaResult {
  *
  * Construction-time guards (all fire on misconfiguration):
  *
- * 1. Every `consumer_roles[i].name` matches `RoleName` regex.
+ * 1. Every `consumer_roles[i].name` matches `RoleName` — its regex and its
+ *    `ROLE_NAME_LENGTH_MAX` length cap.
  * 2. No two consumer roles share a name.
  * 3. No consumer role collides with a builtin (`keeper` / `admin`).
  * 4. When `options.credential_types` is supplied, every entry in

package/dist/auth/role_schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEN,KAAK,0BAA0B,EAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,aAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,iEAAiE;AACjE,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,WACX,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ;IACxB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAuBnE,CAAC;AAEH,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACvC,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,+FAA+F;IAC/F,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oFAAoF;IACpF,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,0GAA0G;IAC1G,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC1C;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,kBAAkB,GAC9B,gBAAgB,aAAa,CAAC,QAAQ,CAAC,EACvC,UAAS,uBAA4B,KACnC,gBA2CF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,MAAM,MAAM,EACZ,YAAY,MAAM,KAChB,OAGF,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,GACtC,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,YAAY,MAAM,KAChB,KAAK,CAAC,MAAM,CAMd,CAAC"}
+{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEN,KAAK,0BAA0B,EAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,QAAQ,aAMnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,iEAAiE;AACjE,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,WACX,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ;IACxB,0GAA0G;IAC1G,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAuBnE,CAAC;AAEH,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACvC,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,+FAA+F;IAC/F,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oFAAoF;IACpF,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,0GAA0G;IAC1G,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC1C;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,kBAAkB,GAC9B,gBAAgB,aAAa,CAAC,QAAQ,CAAC,EACvC,UAAS,uBAA4B,KACnC,gBA2CF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,MAAM,MAAM,EACZ,YAAY,MAAM,KAChB,OAGF,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,GACtC,YAAY,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,YAAY,MAAM,KAChB,KAAK,CAAC,MAAM,CAMd,CAAC"}

package/dist/auth/role_schema.js

@@ -23,9 +23,20 @@
 import { z } from 'zod';
 import { CREDENTIAL_TYPE_DAEMON_TOKEN } from './credential_type_schema.js';
 import { GRANT_PATH_ADMIN, GRANT_PATH_BOOTSTRAP } from './grant_path_schema.js';
-/** Valid role name: lowercase letters and underscores, no leading/trailing underscore. */
+/**
+ * The longest role name `RoleName` admits, in characters. A role string is
+ * caller-chosen text until it passes the grammar, and the grant verbs record
+ * the role they refuse in a failure audit row, so the grammar bounds its
+ * length too. Same value as the Rust spine's `ROLE_NAME_LENGTH_MAX`.
+ */
+export const ROLE_NAME_LENGTH_MAX = 64;
+/**
+ * Valid role name: lowercase letters and underscores, no leading/trailing
+ * underscore, at most `ROLE_NAME_LENGTH_MAX` characters.
+ */
 export const RoleName = z
     .string()
+    .max(ROLE_NAME_LENGTH_MAX, `Role names must be at most ${ROLE_NAME_LENGTH_MAX} characters`)
     .regex(/^[a-z][a-z_]*[a-z]$|^[a-z]$/, 'Role names must be lowercase letters and underscores (a-z_), no leading/trailing underscore');
 // Builtin roles — provided by fuz_app, always available.
 /** System-level role. Requires daemon token (filesystem proof). Controls the keep. */
@@ -99,7 +110,8 @@ const validate_registry_membership = (role_name, field, values, registry) => {
  *
  * Construction-time guards (all fire on misconfiguration):
  *
- * 1. Every `consumer_roles[i].name` matches `RoleName` regex.
+ * 1. Every `consumer_roles[i].name` matches `RoleName` — its regex and its
+ *    `ROLE_NAME_LENGTH_MAX` length cap.
  * 2. No two consumer roles share a name.
  * 3. No consumer role collides with a builtin (`keeper` / `admin`).
  * 4. When `options.credential_types` is supplied, every entry in

package/dist/db/migrate.d.ts

@@ -50,7 +50,7 @@
  * tx atomicity + the `(namespace, name)` PK on `schema_version`: the
  * loser's INSERT hits a PK violation, the chain-tx rolls back, and the
  * next boot reads the committed state and proceeds cleanly. Environments
- * without `pg_advisory_lock` (some PGlite versions) silently fall through.
+ * without `pg_advisory_lock` (pglet) silently fall through.
  *
  * @module
  */

package/dist/db/migrate.js

@@ -50,7 +50,7 @@
  * tx atomicity + the `(namespace, name)` PK on `schema_version`: the
  * loser's INSERT hits a PK violation, the chain-tx rolls back, and the
  * next boot reads the committed state and proceeds cleanly. Environments
- * without `pg_advisory_lock` (some PGlite versions) silently fall through.
+ * without `pg_advisory_lock` (pglet) silently fall through.
  *
  * @module
  */
@@ -99,7 +99,7 @@ const namespace_lock_key = (namespace) => {
  * Run `fn` with the namespace's advisory lock held.
  *
  * Acquire / release are best-effort and silently fall through in
- * environments without `pg_advisory_lock` (some PGlite versions). The
+ * environments without `pg_advisory_lock` (pglet). The
  * `finally` ensures release on any throw from `fn`.
  */
 const with_namespace_lock = async (db, namespace, fn) => {

package/dist/http/CLAUDE.md

@@ -19,6 +19,7 @@ effects, see ../../../docs/architecture.md.
 - `http/error_schemas.ts` — `ERROR_*` constants, standard error shapes, `derive_error_schemas`.
 - `http/schema_helpers.ts` — shared Zod introspection (null/void/strict/surface/merge/middleware-applies) + `to_void_params` / `to_input_params` / `safe_parse_dropping_unknown_keys`.
 - `http/middleware_spec.ts` — `MiddlewareSpec` interface.
+- `http/body_limit.ts` — `create_body_limit_middleware(max_size)`: the `413` body cap `create_app_server` mounts. Refuses on `Content-Length` without reading `c.req.raw.body` and answers `Connection: close` — `413` past the cap, `400` `ERROR_INVALID_CONTENT_LENGTH` when the value is not a plain run of ASCII digits (a length the cap cannot read, which Hono's `bodyLimit` would pass uncounted) — else falls through to Hono's streaming `bodyLimit` (no `Content-Length`, or one beside `Transfer-Encoding`; that `413` carries no `Connection: close`). Mounted with `app.use`, not as a `MiddlewareSpec`, so neither status appears in a route's merged error schemas. After the header `413` Node closes at once (the header is what makes `@hono/node-server` do so), Deno closes once the declared body has arrived, and Bun keeps the connection and serves the next request (../../../docs/security.md §Body Size Limiting).
 - `http/surface.ts` — `AppSurface`, `AppSurfaceSpec`, `generate_app_surface`, diagnostics.
 - `http/surface_query.ts` — pure filters/groupings over `AppSurface`.
 - `http/proxy.ts` — trusted-proxy middleware, CIDR parsing, rightmost-first XFF resolution. Pulls `hono/utils/ipaddr` for CIDR matching.
@@ -207,7 +208,7 @@ confirmation.
 ### `ERROR_*` constants by category
 
 - **Validation**: `ERROR_INVALID_REQUEST_BODY`, `ERROR_INVALID_JSON_BODY`, `ERROR_INVALID_ROUTE_PARAMS`, `ERROR_INVALID_QUERY_PARAMS`
-- **Auth**: `ERROR_AUTHENTICATION_REQUIRED`, `ERROR_INSUFFICIENT_PERMISSIONS`, `ERROR_CREDENTIAL_TYPE_REQUIRED`, `ERROR_RATE_LIMIT_EXCEEDED`, `ERROR_INVALID_CREDENTIALS`, `ERROR_PAYLOAD_TOO_LARGE`
+- **Auth**: `ERROR_AUTHENTICATION_REQUIRED`, `ERROR_INSUFFICIENT_PERMISSIONS`, `ERROR_CREDENTIAL_TYPE_REQUIRED`, `ERROR_RATE_LIMIT_EXCEEDED`, `ERROR_INVALID_CREDENTIALS`, `ERROR_PAYLOAD_TOO_LARGE`, `ERROR_INVALID_CONTENT_LENGTH`
 - **Origin + bearer**: `ERROR_FORBIDDEN_ORIGIN`, `ERROR_INVALID_TOKEN`, `ERROR_ACCOUNT_NOT_FOUND`
 - **Keeper/daemon**: `ERROR_KEEPER_ACCOUNT_NOT_FOUND`
 - **Bootstrap**: `ERROR_ALREADY_BOOTSTRAPPED`, `ERROR_TOKEN_FILE_MISSING`

package/dist/http/body_limit.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Request body size limit — rejects an oversized body with `413`, and a
+ * `Content-Length` it cannot read with `400`, before auth and validation.
+ *
+ * Wraps Hono's `bodyLimit` with a header-first check:
+ *
+ * - A `Content-Length` that is not a plain run of ASCII digits (`abc`, `-1`,
+ *   `+5`, `1e9`, `0x1F4`, empty, or a combined `5, 500`) is refused with `400`
+ *   `{error: 'invalid_content_length'}`. A cap cannot be applied to a length
+ *   that does not parse, and `bodyLimit` passes such a request on uncounted.
+ *   The runtimes' HTTP parsers answer their own bodiless `400` to most of
+ *   these before the application sees them, so this branch is defense in
+ *   depth where they do and the refusal where they do not: Node's refuses
+ *   them all; Deno hands over a repeated equal header as one combined value
+ *   (`50, 50`); Bun hands over an empty value and a repeated header, equal or
+ *   differing (`5, 50`), framing the body on the first (observed on Node
+ *   24.14.1, Deno 2.8.3, Bun 1.3.11). The Rust spine's parser (hyper) refuses
+ *   a malformed value and differing repeats, and accepts an equal repeat as
+ *   the one value.
+ * - A request whose `Content-Length` exceeds the cap is refused with `413`
+ *   `{error: 'payload_too_large'}`, whatever its method. A digit run of any
+ *   length compares as a number, so one too long to represent exactly is over
+ *   the cap, never unreadable.
+ * - Both refusals answer on the header alone — without touching
+ *   `c.req.raw.body` — and carry `Connection: close`.
+ * - A request with a well-formed `Content-Length` beside `Transfer-Encoding`,
+ *   or with no `Content-Length`, falls through to `bodyLimit`'s streaming
+ *   count: with `Transfer-Encoding` the declared length does not frame the
+ *   body, so the bytes that arrive are what is measured. That `413` is sent
+ *   once more than the cap has been read and carries no `Connection: close`.
+ *   The Node, Deno and Bun parsers refuse a request carrying both headers
+ *   with their own `400`; hyper accepts one and frames its body as chunked.
+ * - A well-formed `Content-Length` within the cap is trusted to frame the
+ *   body, as the runtime's HTTP parser enforces.
+ *
+ * What the connection does after the header `413` is the runtime's
+ * (`docs/security.md` §"Body Size Limiting"):
+ *
+ * - **Node** (`@hono/node-server`) closes at once, the body unread. The
+ *   `Connection: close` header is what does it: without one the adapter
+ *   holds the connection for a drain window and then closes or, the body
+ *   untouched and arriving within the window, reads it off and serves the
+ *   next request.
+ * - **Deno** closes once the whole declared body has arrived and holds the
+ *   connection open while a client withholds it; a request pipelined behind
+ *   the body is not served. Neither the header nor what the handler does with
+ *   the body changes that (observed on Deno 2.8.3).
+ * - **Bun** keeps the connection, skips the declared body, and serves the
+ *   next request on it (observed on Bun 1.3.11).
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Create the body size limit middleware.
+ *
+ * @param max_size - the largest accepted body, in bytes
+ * @returns middleware answering `413` `{error: 'payload_too_large'}` past the cap and `400` `{error: 'invalid_content_length'}` to a `Content-Length` that is not a run of digits
+ */
+export declare const create_body_limit_middleware: (max_size: number) => MiddlewareHandler;
+//# sourceMappingURL=body_limit.d.ts.map

package/dist/http/body_limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body_limit.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/body_limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAQ9C;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,MAAM,KAAG,iBAwB/D,CAAC"}

package/dist/http/body_limit.js

@@ -0,0 +1,87 @@
+/**
+ * Request body size limit — rejects an oversized body with `413`, and a
+ * `Content-Length` it cannot read with `400`, before auth and validation.
+ *
+ * Wraps Hono's `bodyLimit` with a header-first check:
+ *
+ * - A `Content-Length` that is not a plain run of ASCII digits (`abc`, `-1`,
+ *   `+5`, `1e9`, `0x1F4`, empty, or a combined `5, 500`) is refused with `400`
+ *   `{error: 'invalid_content_length'}`. A cap cannot be applied to a length
+ *   that does not parse, and `bodyLimit` passes such a request on uncounted.
+ *   The runtimes' HTTP parsers answer their own bodiless `400` to most of
+ *   these before the application sees them, so this branch is defense in
+ *   depth where they do and the refusal where they do not: Node's refuses
+ *   them all; Deno hands over a repeated equal header as one combined value
+ *   (`50, 50`); Bun hands over an empty value and a repeated header, equal or
+ *   differing (`5, 50`), framing the body on the first (observed on Node
+ *   24.14.1, Deno 2.8.3, Bun 1.3.11). The Rust spine's parser (hyper) refuses
+ *   a malformed value and differing repeats, and accepts an equal repeat as
+ *   the one value.
+ * - A request whose `Content-Length` exceeds the cap is refused with `413`
+ *   `{error: 'payload_too_large'}`, whatever its method. A digit run of any
+ *   length compares as a number, so one too long to represent exactly is over
+ *   the cap, never unreadable.
+ * - Both refusals answer on the header alone — without touching
+ *   `c.req.raw.body` — and carry `Connection: close`.
+ * - A request with a well-formed `Content-Length` beside `Transfer-Encoding`,
+ *   or with no `Content-Length`, falls through to `bodyLimit`'s streaming
+ *   count: with `Transfer-Encoding` the declared length does not frame the
+ *   body, so the bytes that arrive are what is measured. That `413` is sent
+ *   once more than the cap has been read and carries no `Connection: close`.
+ *   The Node, Deno and Bun parsers refuse a request carrying both headers
+ *   with their own `400`; hyper accepts one and frames its body as chunked.
+ * - A well-formed `Content-Length` within the cap is trusted to frame the
+ *   body, as the runtime's HTTP parser enforces.
+ *
+ * What the connection does after the header `413` is the runtime's
+ * (`docs/security.md` §"Body Size Limiting"):
+ *
+ * - **Node** (`@hono/node-server`) closes at once, the body unread. The
+ *   `Connection: close` header is what does it: without one the adapter
+ *   holds the connection for a drain window and then closes or, the body
+ *   untouched and arriving within the window, reads it off and serves the
+ *   next request.
+ * - **Deno** closes once the whole declared body has arrived and holds the
+ *   connection open while a client withholds it; a request pipelined behind
+ *   the body is not served. Neither the header nor what the handler does with
+ *   the body changes that (observed on Deno 2.8.3).
+ * - **Bun** keeps the connection, skips the declared body, and serves the
+ *   next request on it (observed on Bun 1.3.11).
+ *
+ * @module
+ */
+import { bodyLimit } from 'hono/body-limit';
+import { ERROR_INVALID_CONTENT_LENGTH, ERROR_PAYLOAD_TOO_LARGE } from './error_schemas.js';
+/** A well-formed `Content-Length` value: one or more ASCII digits and nothing else. */
+const CONTENT_LENGTH_DIGITS = /^[0-9]+$/;
+/**
+ * Create the body size limit middleware.
+ *
+ * @param max_size - the largest accepted body, in bytes
+ * @returns middleware answering `413` `{error: 'payload_too_large'}` past the cap and `400` `{error: 'invalid_content_length'}` to a `Content-Length` that is not a run of digits
+ */
+export const create_body_limit_middleware = (max_size) => {
+    const streaming_limit = bodyLimit({
+        maxSize: max_size,
+        onError: (c) => c.json({ error: ERROR_PAYLOAD_TOO_LARGE }, 413)
+    });
+    return async (c, next) => {
+        const content_length = c.req.header('content-length');
+        if (content_length !== undefined) {
+            if (!CONTENT_LENGTH_DIGITS.test(content_length)) {
+                // a length that does not parse cannot be capped, and `bodyLimit`
+                // would pass the request on without counting it
+                return c.json({ error: ERROR_INVALID_CONTENT_LENGTH }, 400, { connection: 'close' });
+            }
+            // `Number` of a digit run is never `NaN`; past exact precision it is
+            // still a huge number (or `Infinity`), so it compares as over the cap
+            if (!c.req.header('transfer-encoding') && Number(content_length) > max_size) {
+                // refused on the header alone, the body untouched; `Connection: close`
+                // makes `@hono/node-server` close at once instead of holding the
+                // connection or serving the request behind the body
+                return c.json({ error: ERROR_PAYLOAD_TOO_LARGE }, 413, { connection: 'close' });
+            }
+        }
+        return streaming_limit(c, next);
+    };
+};

package/dist/http/db_routes.js

@@ -425,8 +425,8 @@ export const create_db_route_specs = (deps, options) => {
                     }
                     // 23503 foreign_key_violation / 23001 restrict_violation — the
                     // same referencing-row refusal: PG 18+ raises 23001 for `ON
-                    // DELETE RESTRICT` constraints where PG ≤17 (PGlite today)
-                    // raises 23503 for both.
+                    // DELETE RESTRICT` constraints where PG ≤17 raises 23503 for
+                    // both.
                     if (code === '23503' || code === '23001') {
                         const pg_err = err;
                         log?.warn('Foreign key violation:', pg_err.detail, pg_err.constraint);

package/dist/http/error_schemas.d.ts

@@ -53,6 +53,8 @@ export declare const ERROR_RATE_LIMIT_EXCEEDED: "rate_limit_exceeded";
 export declare const ERROR_INVALID_CREDENTIALS: "invalid_credentials";
 /** Request body exceeds the maximum allowed size. */
 export declare const ERROR_PAYLOAD_TOO_LARGE: "payload_too_large";
+/** Request `Content-Length` header is not a plain run of ASCII digits. */
+export declare const ERROR_INVALID_CONTENT_LENGTH: "invalid_content_length";
 /** Request origin not in allowlist. */
 export declare const ERROR_FORBIDDEN_ORIGIN: "forbidden_origin";
 /**

package/dist/http/error_schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/error_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI9D,0CAA0C;AAC1C,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAG,mBAA4B,CAAC;AAEpE,6CAA6C;AAC7C,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAI1E,wCAAwC;AACxC,eAAO,MAAM,6BAA6B,EAAG,yBAAkC,CAAC;AAEhF,+CAA+C;AAC/C,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,yCAAyC;AACzC,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AAExE,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AAExE,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,EAAG,mBAA4B,CAAC;AAIpE,uCAAuC;AACvC,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAG,eAAwB,CAAC;AAE5D,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,EAAG,mBAA4B,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAG,gBAAyB,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAIlE,uDAAuD;AACvD,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAIlF,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAItE,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAEtE,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAEhE,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE,6DAA6D;AAC7D,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,0DAA0D;AAC1D,eAAO,MAAM,iCAAiC,EAAG,6BAAsC,CAAC;AAIxF,6DAA6D;AAC7D,eAAO,MAAM,4BAA4B,EAAG,wBAAiC,CAAC;AAE9E,gEAAgE;AAChE,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAItE,kDAAkD;AAClD,eAAO,MAAM,2BAA2B,EAAG,uBAAgC,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AAExE,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,EAAG,eAAwB,CAAC;AAE5D,wEAAwE;AACxE,eAAO,MAAM,gCAAgC,EAAG,4BAAqC,CAAC;AAKtF,iFAAiF;AACjF,eAAO,MAAM,QAAQ;;iBAAuC,CAAC;AAC7D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;iBAgB1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,2EAA2E;AAC3E,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,uFAAuF;AACvF,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,0GAA0G;AAC1G,eAAO,MAAM,2BAA2B;;iBAEtC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,qFAAqF;AACrF,eAAO,MAAM,eAAe;;iBAE1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB;;;;;;iBAG7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;;EAAoC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,yBAAyB;IACzC,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,eAAO,MAAM,oBAAoB,GAAI,6EAOlC,yBAAyB,KAAG,iBA8C9B,CAAC"}
+{"version":3,"file":"error_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/error_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI9D,0CAA0C;AAC1C,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAG,mBAA4B,CAAC;AAEpE,6CAA6C;AAC7C,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAI1E,wCAAwC;AACxC,eAAO,MAAM,6BAA6B,EAAG,yBAAkC,CAAC;AAEhF,+CAA+C;AAC/C,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,yCAAyC;AACzC,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AAExE,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AAExE,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,EAAG,mBAA4B,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,EAAG,wBAAiC,CAAC;AAI9E,uCAAuC;AACvC,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAG,eAAwB,CAAC;AAE5D,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,EAAG,mBAA4B,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAG,gBAAyB,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAIlE,uDAAuD;AACvD,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAIlF,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAItE,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAEtE,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAEhE,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE,6DAA6D;AAC7D,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,0DAA0D;AAC1D,eAAO,MAAM,iCAAiC,EAAG,6BAAsC,CAAC;AAIxF,6DAA6D;AAC7D,eAAO,MAAM,4BAA4B,EAAG,wBAAiC,CAAC;AAE9E,gEAAgE;AAChE,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAItE,kDAAkD;AAClD,eAAO,MAAM,2BAA2B,EAAG,uBAAgC,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAG,sBAA+B,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AAExE,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,EAAG,eAAwB,CAAC;AAE5D,wEAAwE;AACxE,eAAO,MAAM,gCAAgC,EAAG,4BAAqC,CAAC;AAKtF,iFAAiF;AACjF,eAAO,MAAM,QAAQ;;iBAAuC,CAAC;AAC7D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;iBAgB1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,2EAA2E;AAC3E,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,uFAAuF;AACvF,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,0GAA0G;AAC1G,eAAO,MAAM,2BAA2B;;iBAEtC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,qFAAqF;AACrF,eAAO,MAAM,eAAe;;iBAE1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB;;;;;;iBAG7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;;EAAoC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,yBAAyB;IACzC,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,eAAO,MAAM,oBAAoB,GAAI,6EAOlC,yBAAyB,KAAG,iBA8C9B,CAAC"}

package/dist/http/error_schemas.js

@@ -55,6 +55,8 @@ export const ERROR_RATE_LIMIT_EXCEEDED = 'rate_limit_exceeded';
 export const ERROR_INVALID_CREDENTIALS = 'invalid_credentials';
 /** Request body exceeds the maximum allowed size. */
 export const ERROR_PAYLOAD_TOO_LARGE = 'payload_too_large';
+/** Request `Content-Length` header is not a plain run of ASCII digits. */
+export const ERROR_INVALID_CONTENT_LENGTH = 'invalid_content_length';
 // --- Origin & bearer token verification ---
 /** Request origin not in allowlist. */
 export const ERROR_FORBIDDEN_ORIGIN = 'forbidden_origin';

package/dist/realtime/outbound_budget.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The byte budget of the frames waiting to be written to one connection — a
+ * WebSocket or an SSE stream.
+ *
+ * A producer never waits on a recipient: a broadcast is synchronous and called
+ * from anywhere, so a client that stopped reading makes the server hold what it
+ * has not taken. `OutboundBudget` is the bound on that, and it is accounting
+ * only — its owner holds the frames and decides what "waiting" means for its
+ * connection (`WsOutboundWriter` for a WebSocket, `create_sse_response` for an
+ * SSE stream).
+ *
+ * - **The charge.** Each waiting frame is charged its payload bytes — the
+ *   UTF-8 length of its text — plus `OUTBOUND_FRAME_OVERHEAD_BYTES`.
+ * - **The rule.** A frame is admitted when the charges already waiting plus
+ *   its own stay within the budget — and, whatever its size, when nothing is
+ *   waiting, so a single message larger than the whole budget is deliverable.
+ *
+ * Nothing counts frames: any number may wait while their charges fit. The twin
+ * of the Rust spine's `fuz_realtime` outbound queue, with the same charge and
+ * the same rule.
+ *
+ * @module
+ */
+/**
+ * What a waiting frame is charged against its budget on top of its payload
+ * bytes.
+ *
+ * It stands for what a queued frame costs beyond its text, so a frame with
+ * little or no payload is not free: a budget of `B` never holds more than `B`
+ * divided by this many frames, whatever their size. A fixed charge, not a
+ * measurement of memory use. Same value as the Rust spine's constant.
+ */
+export declare const OUTBOUND_FRAME_OVERHEAD_BYTES = 64;
+/** What was waiting when a frame did not fit its connection's budget. */
+export interface OutboundOverflow {
+    /** Payload bytes waiting, without the per-frame overhead the budget also charges. */
+    queued_bytes: number;
+    /** Frames waiting. */
+    queued_frames: number;
+    /** Payload bytes of the frame that did not fit, without its overhead. */
+    frame_bytes: number;
+}
+/**
+ * The accounting for one connection's waiting frames (module doc).
+ *
+ * `admit` charges a frame that fits, `release` frees the charge of one that is
+ * no longer waiting, and `clear` frees them all.
+ */
+export declare class OutboundBudget {
+    #private;
+    /** The budget, in bytes. */
+    readonly max_bytes: number;
+    /**
+     * @param max_bytes - the budget, in bytes; `0` admits one frame at a time
+     * @throws Error when `max_bytes` is not a non-negative safe integer
+     */
+    constructor(max_bytes: number);
+    /** Payload bytes waiting, without the per-frame overhead. */
+    get queued_bytes(): number;
+    /** Frames waiting. */
+    get queued_frames(): number;
+    /**
+     * Charge a frame of `frame_bytes` payload bytes if it fits: when nothing is
+     * waiting, or when the charges waiting plus its own stay within the budget.
+     *
+     * @param frame_bytes - the frame's payload length in UTF-8 bytes
+     * @returns whether the frame was admitted and charged
+     * @mutates this - adds the frame's charge when it is admitted
+     */
+    admit(frame_bytes: number): boolean;
+    /**
+     * Free the charge of one admitted frame that is no longer waiting.
+     *
+     * @param frame_bytes - the payload length the frame was admitted with
+     * @mutates this - removes the frame's charge
+     */
+    release(frame_bytes: number): void;
+    /**
+     * Free every charge — the owner discarded what was waiting.
+     *
+     * @mutates this - removes every charge
+     */
+    clear(): void;
+    /**
+     * What is waiting, for the log line of a frame that did not fit.
+     *
+     * @param frame_bytes - the payload length of the frame that did not fit
+     */
+    to_overflow(frame_bytes: number): OutboundOverflow;
+}
+//# sourceMappingURL=outbound_budget.d.ts.map

package/dist/realtime/outbound_budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound_budget.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/outbound_budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAChC,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,cAAc;;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAK3B;;;OAGG;gBACS,SAAS,EAAE,MAAM;IAO7B,6DAA6D;IAC7D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,sBAAsB;IACtB,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAanC;;;;;OAKG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKlC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB;CAGlD"}

package/dist/realtime/outbound_budget.js

@@ -0,0 +1,108 @@
+/**
+ * The byte budget of the frames waiting to be written to one connection — a
+ * WebSocket or an SSE stream.
+ *
+ * A producer never waits on a recipient: a broadcast is synchronous and called
+ * from anywhere, so a client that stopped reading makes the server hold what it
+ * has not taken. `OutboundBudget` is the bound on that, and it is accounting
+ * only — its owner holds the frames and decides what "waiting" means for its
+ * connection (`WsOutboundWriter` for a WebSocket, `create_sse_response` for an
+ * SSE stream).
+ *
+ * - **The charge.** Each waiting frame is charged its payload bytes — the
+ *   UTF-8 length of its text — plus `OUTBOUND_FRAME_OVERHEAD_BYTES`.
+ * - **The rule.** A frame is admitted when the charges already waiting plus
+ *   its own stay within the budget — and, whatever its size, when nothing is
+ *   waiting, so a single message larger than the whole budget is deliverable.
+ *
+ * Nothing counts frames: any number may wait while their charges fit. The twin
+ * of the Rust spine's `fuz_realtime` outbound queue, with the same charge and
+ * the same rule.
+ *
+ * @module
+ */
+/**
+ * What a waiting frame is charged against its budget on top of its payload
+ * bytes.
+ *
+ * It stands for what a queued frame costs beyond its text, so a frame with
+ * little or no payload is not free: a budget of `B` never holds more than `B`
+ * divided by this many frames, whatever their size. A fixed charge, not a
+ * measurement of memory use. Same value as the Rust spine's constant.
+ */
+export const OUTBOUND_FRAME_OVERHEAD_BYTES = 64;
+/**
+ * The accounting for one connection's waiting frames (module doc).
+ *
+ * `admit` charges a frame that fits, `release` frees the charge of one that is
+ * no longer waiting, and `clear` frees them all.
+ */
+export class OutboundBudget {
+    /** The budget, in bytes. */
+    max_bytes;
+    #bytes = 0;
+    #frames = 0;
+    /**
+     * @param max_bytes - the budget, in bytes; `0` admits one frame at a time
+     * @throws Error when `max_bytes` is not a non-negative safe integer
+     */
+    constructor(max_bytes) {
+        if (!Number.isSafeInteger(max_bytes) || max_bytes < 0) {
+            throw new Error(`OutboundBudget: max_bytes must be a non-negative integer, got ${max_bytes}`);
+        }
+        this.max_bytes = max_bytes;
+    }
+    /** Payload bytes waiting, without the per-frame overhead. */
+    get queued_bytes() {
+        return this.#bytes;
+    }
+    /** Frames waiting. */
+    get queued_frames() {
+        return this.#frames;
+    }
+    /**
+     * Charge a frame of `frame_bytes` payload bytes if it fits: when nothing is
+     * waiting, or when the charges waiting plus its own stay within the budget.
+     *
+     * @param frame_bytes - the frame's payload length in UTF-8 bytes
+     * @returns whether the frame was admitted and charged
+     * @mutates this - adds the frame's charge when it is admitted
+     */
+    admit(frame_bytes) {
+        if (this.#frames !== 0 &&
+            this.#bytes + frame_bytes + (this.#frames + 1) * OUTBOUND_FRAME_OVERHEAD_BYTES >
+                this.max_bytes) {
+            return false;
+        }
+        this.#bytes += frame_bytes;
+        this.#frames++;
+        return true;
+    }
+    /**
+     * Free the charge of one admitted frame that is no longer waiting.
+     *
+     * @param frame_bytes - the payload length the frame was admitted with
+     * @mutates this - removes the frame's charge
+     */
+    release(frame_bytes) {
+        this.#bytes -= frame_bytes;
+        this.#frames--;
+    }
+    /**
+     * Free every charge — the owner discarded what was waiting.
+     *
+     * @mutates this - removes every charge
+     */
+    clear() {
+        this.#bytes = 0;
+        this.#frames = 0;
+    }
+    /**
+     * What is waiting, for the log line of a frame that did not fit.
+     *
+     * @param frame_bytes - the payload length of the frame that did not fit
+     */
+    to_overflow(frame_bytes) {
+        return { queued_bytes: this.#bytes, queued_frames: this.#frames, frame_bytes };
+    }
+}

package/dist/realtime/sse.d.ts

@@ -4,6 +4,22 @@
  * Provides generic helpers for creating SSE response streams
  * and a notification type aligned with JSON-RPC 2.0.
  *
+ * ## Outbound bound
+ *
+ * `SseStream.send` never waits on its client: each frame is written to the
+ * response stream, which holds it until the client reads. What a stream holds
+ * unread is kept within `SSE_OUTBOUND_QUEUE_BYTES` — each frame charged its
+ * bytes as written (`data: ` prefix and terminator included) plus
+ * `OUTBOUND_FRAME_OVERHEAD_BYTES`, and a frame always accepted when nothing is
+ * unread, so a single frame larger than the budget is still deliverable. A
+ * frame that does not fit **ends the stream**: it is not written, what was
+ * unread is dropped, the body ends with no final frame, and the stream's
+ * `on_close` listeners run. One `warn` line names the stream's account (when
+ * the caller passed it) and what was unread; no audit row is written, since each would itself be fanned to every
+ * stream. A client that is reading reconnects and misses the frames in
+ * between. The twin of the Rust spine's `fuz_realtime` SSE bound — the same
+ * budget and charge.
+ *
  * @module
  */
 import type { Context } from 'hono';
@@ -15,7 +31,11 @@ import type { Logger } from '@fuzdev/fuz_util/log.ts';
  * Transport-agnostic — works with any serializable type.
  */
 export interface SseStream<T = unknown> {
-    /** Send data to the client as a JSON SSE event. */
+    /**
+     * Send data to the client as a JSON SSE event. Never waits: a frame the
+     * stream's outbound budget does not fit ends the stream instead (module doc,
+     * "Outbound bound").
+     */
     send: (data: T) => void;
     /** Send a comment (for keep-alive pings). */
     comment: (text: string) => void;
@@ -40,6 +60,14 @@ export interface SseNotification {
     /** Method-specific payload. */
     params: unknown;
 }
+/** Options for `create_sse_response`. */
+export interface SseResponseOptions {
+    /**
+     * The account the stream belongs to, named in the warning logged when the
+     * stream ends on its outbound budget.
+     */
+    account_id?: string | null;
+}
 /**
  * Create an SSE response for a Hono context.
  *
@@ -59,10 +87,15 @@ export interface SseNotification {
  * Uses `hono_stream.write()` directly (not `writeSSE`) to avoid
  * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
  *
- * @param log - logger for serialization and `on_close` listener errors
+ * What the stream holds unread is bounded by `SSE_OUTBOUND_QUEUE_BYTES`; a
+ * frame past it ends the stream (module doc, "Outbound bound").
+ *
+ * @param log - logger for serialization and `on_close` listener errors, and
+ *   for the warning when the stream ends on its outbound budget
+ * @param options - what the overflow warning names
  * @returns object with the streaming `Response` and an `SseStream` controller
  */
-export declare const create_sse_response: <T = unknown>(c: Context, log: Logger) => {
+export declare const create_sse_response: <T = unknown>(c: Context, log: Logger, options?: SseResponseOptions) => {
     response: Response;
     stream: SseStream<T>;
 };

package/dist/realtime/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AA8DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,KACT;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CA4D5C,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAE,EAC9D,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,KAAK,MAAM,KACT;IAAE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBjD,CAAC"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAMtD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC;;;;OAIG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,EACX,UAAU,kBAAkB,KAC1B;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CAyF5C,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAE,EAC9D,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,KAAK,MAAM,KACT;IAAE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBjD,CAAC"}