@ultimat3/http 16.0.0 → 17.0.0

package/CLAUDE.md

@@ -19,6 +19,41 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 
 ## Rules
 
+- **Every numeric knob `defineHttpConfig` resolves is screened, `As of 2026-08-26`** — `port`,
+  `bodyLimitBytes`, `requestTimeoutMs`, `maxInflight`, `drainTimeoutMs` and `trustedProxyHops`,
+  each a whole number in its own domain or `X_CONFIG_INVALID` (core's code, borrowed as
+  `@ultimat3/auth` borrows it). Measured with `NaN`, which is what `Number(process.env.…)` answers
+  for an unset variable: `total > NaN` is false so the body cap stopped capping and the whole
+  payload was buffered; `NaN <= 0` is false so a deadline armed and `setTimeout(fn, NaN)` is 1ms,
+  which 504s every request; `ceiling > 0` is false so `admit` shed nothing; and
+  `Math.max(0, Math.floor(NaN))` is `NaN`, so `trustProxy: true` silently trusted no hop and every
+  caller's ip became the proxy's. `Math.max(0, …)` was the guard for the last of those — a clamp is
+  not a validator, and this package relied on one. `webhook-verify.ts` screens its own two
+  (`toleranceMs`, `maxBytes`) and `rate-limit.ts` its `maxKeys`; the helper names carry `Finite`
+  (`assertFiniteCount`, `assertFiniteKeyCap`, `assertFiniteBodyLimit`) because
+  `bun run finite-bounds` recognises a repair by the shape of the CALL — spelled `count`, all five
+  config options read as unchecked to the ratchet while every one was screened. `maxBytes` is
+  refused HERE as well as inside `readWithinLimit`: that one is a file away and its `fix:` names
+  core's reader rather than the option the caller wrote.
+
+  **The FLOOR is per option, because only the caller knows what zero means** (`As of 2026-08-26`).
+  `requestTimeoutMs: 0` is "no deadline" and `maxInflight: 0` is "never shed" — decisions the code
+  reads — so those two floor at 0; `trustedProxyHops` floors at **1**, and it shipped for one day
+  screened at 0. `forwardedElement` answers `undefined` for `hops < 1`, so
+  `{ trustProxy: true, trustedProxyHops: 0 }` was byte-for-byte the failure the screen's own comment
+  names: `clientAddress` falls back to the socket, one rate-limit bucket for everything behind the
+  ingress, `x-forwarded-proto` untrusted and HSTS never emitted. `-1` and `NaN` were refused for
+  producing exactly that state and `0` was accepted into it. `resolveTrustedProxyHops` owns both
+  refusals — unset is `X_TRUST_PROXY_UNSET`, out of domain is `X_CONFIG_INVALID` — and there is no
+  `?? 0` behind it, because a default of zero reopens the same hole from the other side.
+
+  **`MAX_PROXY_HOPS` is EXPORTED, `As of 2026-08-26`**, and that is the point of it. It was module
+  private, so `@ultimat3/cli`'s `trustedHopsFromEnv` — which screens the same setting arriving as
+  `TRUSTED_PROXY_HOPS` — restated the literal, and one setting came to have two ceilings: that end
+  said 16 while this one said 64, so a deployment behind 20 hops was accepted by the library and
+  refused at boot. `cli` is tier 5 and this is tier 2, so the import is downward and legal. The
+  number lives here because this is where the setting is.
+
 - Route `meta.auth` is required. Never default a route to public.
 - **An app declares its half of `HttpConfig` through `configureHttp()`, and the boot lays its own
   facts over it** (`As of 2026-08-24`). Until 12.0.0 the entire tuning surface was **unreachable
@@ -542,6 +577,23 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   only. `HTTP_ERROR_TITLES` holds owned codes, and `registerErrorCodes` takes it whole and
   unguarded — declaring a borrowed one throws `X_ERROR_CODE_DUPLICATE` at import, which is the
   point. `factsOf` therefore reads a borrowed code's title off the error itself, never the map.
+- **A `cache-control` age is delta-seconds or it is DROPPED, never emitted** (`As of 2026-08-26`).
+  `finiteDeltaSeconds` in `response.ts` — `Number.isSafeInteger && >= 0`, per field. `max-age=NaN`
+  is not a shorter age, it is an unparseable directive a conforming cache IGNORES, so the response
+  fell back to heuristic caching rather than to the declared age. TOTAL, never a throw: this is the
+  response path, and a bad cache hint must not become a 500. Every fallback is the SHORTER
+  direction — `max-age` to 0, `s-maxage` and `stale-while-revalidate` omitted — so nothing here can
+  lengthen an age the caller did not ask for. `http.cache_hint_not_delta_seconds` names the field.
+  **The boot-time half is `route-cache.ts`, `As of 2026-08-26`** — the layered form: refuse where
+  the value is WRITTEN, be total where it is USED. `createRouter` screens `Route.cache`'s three
+  delta-seconds fields per route and throws `X_CONFIG_INVALID` naming the route and the key, so
+  `cache: { maxAgeSeconds: Number(process.env.CACHE_AGE) }` fails at boot instead of registering
+  cleanly and surfacing as one warn line per request, forever. The two screens must accept exactly
+  the same set: this one decides what may be DECLARED, `finiteDeltaSeconds` what may be WRITTEN,
+  and a value one accepts and the other drops is a silent hole between them. **Zero stays legal at
+  both ends** — `max-age=0` is "revalidate every time" and `PRIVATE_CACHE`, `defaultCache`'s
+  anonymous hint and the CLI's authorized-object hint all declare it. `ctx.cache` is NOT screened
+  and must not be: it is app-set per request at runtime, which is the total side by definition.
 - Tests must not touch the network — the preload seals `fetch`. Socket tests live in
   `e2e/` and run with `bun test packages/http/e2e`, sealed: `start()` calls core's
   `markListening()`, so the seal treats our own port as self, not egress. Never unseal.
@@ -564,6 +616,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `redirect.ts` | the intent slot a handler that cannot return a `Response` fills |
 | `auth-redirect.ts` | where an unauthenticated browser goes, and where it comes back to |
 | `cache-policy.ts` | the default `CacheHint` for a route that declared none — route AND actor |
+| `route-cache.ts` | the screen a `Route.cache` hint gets where it is DECLARED, thrown from `createRouter`; the response path's `finiteDeltaSeconds` is the total half of the same rule |
 | `rate-limit.ts` | the token-bucket maths, the store interface, the memory driver and `toBucket` |
 | `rate-limit-postgres.ts` | the SHARED store: one table, one `insert … on conflict` per take, over a structural `PgExecutor` |
 | `rate-limit-errors.ts` | every refusal a rate limit produces — the 429 and the six declaration faults. Split off `errors.ts` at the ceiling; the codes and titles stay there, one registry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "16.0.0",
+  "version": "17.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/i18n": "16.0.0",
-    "@ultimat3/schema": "16.0.0",
-    "@ultimat3/time": "16.0.0"
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/i18n": "17.0.0",
+    "@ultimat3/schema": "17.0.0",
+    "@ultimat3/time": "17.0.0"
   }
 }

package/src/config.ts

@@ -6,7 +6,7 @@
 import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';
-import { trustProxyUnset } from './errors';
+import { httpCountInvalid, trustProxyUnset } from './errors';
 import {
   DEFAULT_LOCALE_CONFIG,
   DEFAULT_TZ_CONFIG,
@@ -121,6 +121,78 @@ const env = (name: string): string | undefined => {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
 };
 
+/**
+ * A whole, in-range count, or the refusal that names it.
+ *
+ * `Number.isSafeInteger` and not `Number.isFinite`: these are byte counts, millisecond budgets and
+ * request ceilings, and above 2^53 a double cannot name its own successor — the same rule
+ * `@ultimat3/schema` states for an integer at the wire boundary. The `Finite` in the name is
+ * load-bearing: `bun run finite-bounds` recognises a repair by the shape of the CALL, so a screen
+ * named `count` left every option below reading as unchecked.
+ *
+ * `min` is the CALLER's, exactly as it is on `@ultimat3/core`'s `finiteCount`, because only the
+ * caller knows what zero means: `requestTimeoutMs: 0` is "no deadline" and `maxInflight: 0` is
+ * "never shed", both decisions the code reads, while `trustedProxyHops: 0` is a proxy trusted for
+ * nothing — the state the whole declaration exists to refuse. A helper that picked one bound would
+ * be wrong at half the call sites, and a second helper for "positive" would be the copy.
+ */
+const assertFiniteCount = (
+  name: string,
+  value: number,
+  max: number,
+  expected: string,
+  example: string,
+  min: 0 | 1 = 0,
+): number => {
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw httpCountInvalid(name, value, expected, example);
+  }
+  return value;
+};
+
+const MAX_PORT = 65_535;
+
+/**
+ * Nobody has 64 proxies in front of one process; a bigger number is a typo, not a topology.
+ *
+ * EXPORTED, and that is the point of it: `@ultimat3/cli`'s `trustedHopsFromEnv` screens the same
+ * setting from `TRUSTED_PROXY_HOPS` and had to restate the literal, which is how one setting came
+ * to have two ceilings — that end said 16 while this one said 64, so a deployment behind 20 hops
+ * was accepted by the library and refused at boot. `cli` is tier 5 and this is tier 2, so the
+ * import is downward and legal; the number lives here because this is where the setting is.
+ */
+export const MAX_PROXY_HOPS = 64;
+
+/**
+ * Which `x-forwarded-for` entry is the caller, or the refusal that says the declaration is not one.
+ *
+ * Screened, not clamped. `Math.max(0, Math.floor(x))` turned `-1` into `0` and `NaN` into `NaN`,
+ * and BOTH mean "trust nothing" to `forwardedElement` — so the one declaration saying which entry
+ * the caller wrote silently stopped being made, and every request's client ip became the proxy's
+ * own. One rate-limit bucket for everything behind the ingress, no word said.
+ *
+ * **`0` is that same state and is refused with them**, `As of 2026-08-26`. `forwardedElement`
+ * answers `undefined` for `hops < 1`, so `{ trustProxy: true, trustedProxyHops: 0 }` produced
+ * exactly the failure the screen was written for while the screen accepted it. One is the smallest
+ * topology `trustProxy: true` can describe.
+ *
+ * There is no `?? 0` fallback, and that is the point: an undeclared count is `trustProxyUnset()`,
+ * because "trust the header" and "know which entry of it" are one declaration and half of it is a
+ * header the caller writes. A default of zero would reopen the same hole from the other side.
+ */
+const resolveTrustedProxyHops = (trustProxy: boolean, declared: number | undefined): number => {
+  if (!trustProxy) return 0;
+  if (declared === undefined) throw trustProxyUnset();
+  return assertFiniteCount(
+    'trustedProxyHops',
+    declared,
+    MAX_PROXY_HOPS,
+    'the whole number of proxies that append to x-forwarded-for, at least 1',
+    'trustProxy: true, trustedProxyHops: 1',
+    1,
+  );
+};
+
 export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
   // `ULTIMATE_ENV` is the framework's one environment key and `NODE_ENV` is only its fallback, so
   // reading `NODE_ENV` alone made a deployment that declared production the documented way serve
@@ -135,14 +207,22 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
   const trustProxy = input.trustProxy ?? false;
   // Refused here, not on the first request: "trust the header" and "know which entry of it" are
   // one declaration, and half of it is a header the caller writes.
-  if (trustProxy && input.trustedProxyHops === undefined) throw trustProxyUnset();
+  const trustedProxyHops = resolveTrustedProxyHops(trustProxy, input.trustedProxyHops);
   const csp = { ...DEFAULT_SECURITY.csp, reportOnly: dev, ...input.security?.csp };
   // Beside `assertCorsConfig`, and for its reason: a merged value is the only one that can be
   // judged, and a directive name that is not a token would otherwise be a bare `TypeError` out of
   // the first response's header build — or worse, a second directive nobody declared.
   assertCspExtend(csp.extend);
   return {
-    port: input.port ?? Number.parseInt(env('PORT') ?? '3000', 10),
+    // `Number.parseInt(env('PORT'), 10)` is `NaN` for `PORT=web`, and a config that carries NaN
+    // into `Bun.serve` binds a port nobody asked for.
+    port: assertFiniteCount(
+      'port',
+      input.port ?? Number.parseInt(env('PORT') ?? '3000', 10),
+      MAX_PORT,
+      'a whole port number from 0 to 65535, where 0 asks the OS for a free one',
+      'port: 3000',
+    ),
     hostname: input.hostname ?? env('HOSTNAME') ?? '0.0.0.0',
     basePath: input.basePath ?? '/',
     buildId: input.buildId ?? env('BUILD_ID') ?? null,
@@ -150,13 +230,40 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     dev,
     signInPath: input.signInPath ?? null,
     trustProxy,
-    trustedProxyHops: trustProxy ? Math.max(0, Math.floor(input.trustedProxyHops ?? 0)) : 0,
-    bodyLimitBytes: input.bodyLimitBytes ?? 1_048_576,
+    trustedProxyHops,
+    bodyLimitBytes: assertFiniteCount(
+      'bodyLimitBytes',
+      input.bodyLimitBytes ?? 1_048_576,
+      Number.MAX_SAFE_INTEGER,
+      'a whole number of bytes',
+      'bodyLimitBytes: 1_048_576',
+    ),
     // 30s: longer than any request a browser waits out, shorter than the 15s drain budget times
     // two, so a rolling restart cannot be held open by work started just before SIGTERM.
-    requestTimeoutMs: input.requestTimeoutMs ?? 30_000,
-    maxInflight: input.maxInflight ?? 1_000,
-    drainTimeoutMs: input.drainTimeoutMs ?? null,
+    requestTimeoutMs: assertFiniteCount(
+      'requestTimeoutMs',
+      input.requestTimeoutMs ?? 30_000,
+      Number.MAX_SAFE_INTEGER,
+      'a whole number of milliseconds, where 0 means no deadline',
+      'requestTimeoutMs: 30_000',
+    ),
+    maxInflight: assertFiniteCount(
+      'maxInflight',
+      input.maxInflight ?? 1_000,
+      Number.MAX_SAFE_INTEGER,
+      'a whole number of requests, where 0 means never shed',
+      'maxInflight: 1_000',
+    ),
+    drainTimeoutMs:
+      input.drainTimeoutMs === undefined || input.drainTimeoutMs === null
+        ? null
+        : assertFiniteCount(
+            'drainTimeoutMs',
+            input.drainTimeoutMs,
+            Number.MAX_SAFE_INTEGER,
+            'a whole number of milliseconds, or null for the lifecycle default',
+            'drainTimeoutMs: 15_000',
+          ),
     locale: { ...DEFAULT_LOCALE_CONFIG, ...input.locale },
     tz: { ...DEFAULT_TZ_CONFIG, ...input.tz },
     cors,

package/src/error-map.ts

@@ -38,6 +38,10 @@ export const ERROR_STATUS = {
   // Thrown while `app.config.ts` resolves, so no request is ever answered with it — the row exists
   // because a code with no status is a 500 anyway and this table is the closed one.
   X_CORS_CONFIG_INVALID: 500,
+  // Core's code, borrowed by `defineHttpConfig` for a numeric knob that is not a count. Same
+  // construction-time shelf as the row above, and it needs a row for the same reason: this table
+  // is closed over every code the package can throw, borrowed ones included.
+  X_CONFIG_INVALID: 500,
   X_CSP_DIRECTIVE_INVALID: 500,
   // Thrown while the server is being constructed, so no request is ever answered with it either.
   // The row exists because this table is the closed one: a code missing from it is a 500 anyway,
@@ -271,6 +275,13 @@ export const ERROR_STATUS = {
   // negotiates `Accept-Language` and never throws, so the tag that reaches here came from a path,
   // query or body the caller wrote — the same place `X_IMAGE_QUERY_INVALID` comes from.
   X_LOCALE_UNSUPPORTED: 400,
+  // @ultimat3/core (declared beside `assertLocale`; `@ultimat3/time` owned it until 16.x) — the
+  // sibling of the row above, and strictly more the caller's fault: not a tag at all. It was
+  // pinned as unable to reach a request because the `locale` stage negotiates and never throws,
+  // which is true of that stage and irrelevant to `?locale=`, a path segment or an action input
+  // reaching `formatDate` / `formatMoney` / `describeCron`. Those raised it and answered 500,
+  // paging the on-call for a string the caller typed.
+  X_LOCALE_INVALID: 400,
   // @ultimat3/money — a well-formed code this process carries no row for. The currency table is
   // OPEN (`registerCurrency`), and every surface between the wire and the throw accepts any
   // `^[A-Z]{3}$`: `@ultimat3/schema`'s `CURRENCY_CODE_PATTERN`, the OpenAPI `pattern` emitted from

package/src/errors.ts

@@ -56,6 +56,12 @@ export const HTTP_BORROWED_ERROR_CODES = [
   // the lifecycle that answers `isDraining()` is core's. The `admit` stage is its first thrower:
   // this package documented answering 503 while draining and had no reader of the flag at all.
   'X_DRAINING',
+  // Core's, and the code `app.config.ts is invalid` already means — borrowed for the numeric knobs
+  // `defineHttpConfig` screens, the same way `@ultimat3/auth` borrows it for a `defineAuth`
+  // declaration it cannot honour. A per-knob code of our own would be a second answer to a
+  // question core has already answered, and the throw happens while config resolves, so no request
+  // is ever answered with it.
+  'X_CONFIG_INVALID',
 ] as const;
 
 /** Every code http can throw: the ones it owns plus the two it borrows. */
@@ -334,6 +340,52 @@ export const trustProxyUnset = (): HttpError =>
     fix: 'set TRUSTED_PROXY_HOPS in the deployment environment to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process that is reached directly; an embedder calling defineHttpConfig itself passes { trustProxy: true, trustedProxyHops: 1 }',
   });
 
+/**
+ * A numeric knob that is not a count, refused where `app.config.ts` still names it.
+ *
+ * Every one of these arrives as `Number(process.env.X)` as often as a literal, and `NaN` is not
+ * nullish — so `??` passes it through, `Math.max`/`Math.floor` propagate it, and every comparison
+ * downstream then answers FALSE. What that produces is never a wrong number, it is the guard
+ * switching itself off: `bodyLimitBytes` stops capping the body, `maxInflight` stops shedding,
+ * `trustedProxyHops` stops trusting the proxy it was set for, and `requestTimeoutMs` arms a
+ * `setTimeout(fn, NaN)` — which is 1ms — so every request 504s. `Math.max(1, x)` is not a
+ * validator, which is exactly what `trustedProxyHops` was using.
+ */
+export const httpCountInvalid = (
+  name: string,
+  value: number,
+  expected: string,
+  example: string,
+): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `http.${name} is ${String(value)}; it must be ${expected}, and NaN is what Number(process.env.…) answers for an unset variable — every comparison against it is false, so the limit it names stops being enforced rather than being enforced wrongly`,
+    fix: `set ${name} to ${expected} in configureHttp({ ${example} }), and parse an environment value before you pass it: Number.parseInt(process.env.${name.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()} ?? '', 10) is NaN when the variable is unset`,
+    meta: { option: name, value: String(value) },
+  });
+
+/**
+ * A route DECLARING a cache age that a cache cannot read. `X_CONFIG_INVALID` and not a code of its
+ * own, for the reason the borrowed list gives: this is a declaration the framework cannot honour,
+ * and it is thrown while the route table is built, so no request is ever answered with it.
+ *
+ * Thrown here because `cacheControl` cannot throw: the response path is total by design — it drops
+ * the field and logs — so without this the mistake is a log line once per request, forever, while
+ * the response falls back to HEURISTIC caching, the one behaviour no `CacheHint` ever asked for.
+ */
+export const routeCacheInvalid = (
+  route: string,
+  path: string,
+  field: string,
+  value: number,
+): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `route ${route} (${path}) declares cache.${field} = ${String(value)}, and cache-control delta-seconds is 1*DIGIT — a fraction, a negative and NaN are directives a conforming cache IGNORES, so the response would fall back to heuristic caching instead of the age declared here`,
+    fix: `in the route file declaring ${route}, set meta.cache.${field} to a whole number of seconds, 0 or more — 0 is legal and means "revalidate every time". If it comes from the environment, give it a default before it reaches the route: Number(process.env.X) is NaN when the variable is unset and ?? does not catch that, because NaN is not nullish`,
+    meta: { route, path, option: `cache.${field}`, value: String(value) },
+  });
+
 /**
  * SIGTERM has run the `accept` phase: `readyz` is already 503 and the socket is closing, but a
  * connection the load balancer had not yet stopped using still arrives. Answering it with a

package/src/index.ts

@@ -16,7 +16,7 @@ export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
 export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
 export type { HttpConfig, HttpConfigInput } from './config';
-export { defineHttpConfig, stripBasePath } from './config';
+export { defineHttpConfig, MAX_PROXY_HOPS, stripBasePath } from './config';
 export type { ActorView, RequestContext, RequestContextInit } from './context';
 export {
   actorView,
@@ -82,6 +82,7 @@ export {
   pathInvalid,
   pipelineNoResponse,
   requestTimedOut,
+  routeCacheInvalid,
   routeConflict,
   routeNotFound,
   serverNotStarted,

package/src/rate-limit.ts

@@ -3,6 +3,7 @@
 // `createServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
 // declaration; the bucket maths lives here so every driver agrees on the numbers.
 import { type Clock, systemClock } from '@ultimat3/core';
+import { httpCountInvalid } from './errors';
 import {
   rateLimited,
   rateLimitInvalid,
@@ -232,6 +233,17 @@ export interface MemoryRateLimitStore extends RateLimitStore {
   readonly size: number;
 }
 
+/** A whole positive count, or the config refusal that names it. */
+const assertFiniteKeyCap = (option: string, value: number): number => {
+  if (Number.isSafeInteger(value) && value >= 1) return value;
+  throw httpCountInvalid(
+    `rate limit store ${option}`,
+    value,
+    'a whole number of at least 1',
+    `maxKeys: ${DEFAULT_MAX_RATE_LIMIT_KEYS}`,
+  );
+};
+
 /**
  * Default driver: correct for one process, which is exactly dev and tests.
  *
@@ -246,7 +258,12 @@ export interface MemoryRateLimitStore extends RateLimitStore {
 export const memoryRateLimitStore = (
   options: { readonly maxKeys?: number | undefined } = {},
 ): MemoryRateLimitStore => {
-  const maxKeys = Math.max(1, Math.floor(options.maxKeys ?? DEFAULT_MAX_RATE_LIMIT_KEYS));
+  // Screened, not clamped. `Math.max(1, Math.floor(x))` was the guard, and `Math.floor(NaN)` is
+  // `NaN`: `buckets.size > maxKeys` in `take` is then false so the sweep never runs, and
+  // `buckets.size <= maxKeys` in the sweep is false so it would evict nothing if it did. The cap
+  // is the only thing between a rotating-address scan and this process's memory, and the keys are
+  // addresses the caller chooses — a clamp that quietly answers `NaN` removes it.
+  const maxKeys = assertFiniteKeyCap('maxKeys', options.maxKeys ?? DEFAULT_MAX_RATE_LIMIT_KEYS);
   const evictTo = Math.max(1, Math.floor(maxKeys * 0.9));
   const buckets = new Map<string, BucketState>();
   let lastSweepMs = Number.NEGATIVE_INFINITY;

package/src/response.ts

@@ -1,5 +1,6 @@
 // Response constructors. Every response in the framework is built here so that
 // content types, charsets and cache semantics are decided once instead of per route.
+import { logger } from '@ultimat3/core';
 import { TIMEZONE_HEADER } from '@ultimat3/time';
 import { toProblem } from './error-facts';
 
@@ -116,17 +117,65 @@ export interface CacheHint {
 
 export const NO_STORE: CacheHint = { mode: 'no-store' };
 
+/** A year, the only age at which `immutable` says anything a shorter one does not. */
+const IMMUTABLE_MAX_AGE_SECONDS = 31_536_000;
+
+/**
+ * RFC-9111 delta-seconds is `1*DIGIT`, so `max-age=NaN` is not a shorter age or a longer one — it
+ * is an unparseable directive, and a conforming cache IGNORES a directive it cannot parse. The
+ * response then falls back to HEURISTIC caching (a fraction of `Last-Modified`'s age), which is
+ * the one behaviour no `CacheHint` ever asked for and the one nothing downstream can detect.
+ * `??` guards nullish and `NaN` is not nullish, so an age computed from a timestamp difference or
+ * read out of an env value arrives here intact; a fraction (`ms / 1000`) and a negative (a clock
+ * that went backwards) are the same unparseable token.
+ *
+ * The name carries `finite` deliberately: `bun run finite-bounds` recognises a repair by the shape
+ * of the CALL, so this screen spelled `deltaSeconds` read as no screen at all.
+ *
+ * `isDeltaSeconds` is EXPORTED and has exactly two readers, which is the point of it: this one
+ * decides what may be WRITTEN, and `route-cache.ts` decides what may be DECLARED. A byte-identical
+ * predicate in both files is how the two drift, and a value one accepts and the other drops is a
+ * silent hole in the middle — a route that registers cleanly and then emits no age.
+ *
+ * TOTAL, never a throw: this is the response path, where refusing turns a bad cache hint into a
+ * 500. A dropped age is always the SAFER direction — no `s-maxage` means a shared cache falls back
+ * to `max-age`, and a `max-age` of 0 means revalidate — so nothing here can lengthen an age the
+ * caller did not ask for. The warning is what keeps it from being silent; the fix belongs at the
+ * declaration, and `field` names which one.
+ */
+export const isDeltaSeconds = (value: number): boolean => Number.isSafeInteger(value) && value >= 0;
+
+const finiteDeltaSeconds = (field: string, value: number): number | undefined => {
+  if (isDeltaSeconds(value)) return value;
+  logger.warn('http.cache_hint_not_delta_seconds', { field, value: String(value) });
+  return undefined;
+};
+
 export const cacheControl = (hint: CacheHint): string => {
   if (hint.mode === 'no-store') return 'no-store';
   if (hint.mode === 'immutable') {
-    return `public, max-age=${hint.maxAgeSeconds ?? 31_536_000}, immutable`;
+    const age = finiteDeltaSeconds(
+      'maxAgeSeconds',
+      hint.maxAgeSeconds ?? IMMUTABLE_MAX_AGE_SECONDS,
+    );
+    // 0 rather than the year: a declared age that is not a number is not evidence for the longest
+    // age in the file, and an over-long `immutable` is the one cache mistake a purge cannot undo.
+    return `public, max-age=${String(age ?? 0)}, immutable`;
   }
-  const parts = [hint.mode, `max-age=${hint.maxAgeSeconds ?? 0}`];
+  const parts = [
+    hint.mode,
+    `max-age=${String(finiteDeltaSeconds('maxAgeSeconds', hint.maxAgeSeconds ?? 0) ?? 0)}`,
+  ];
   if (hint.mode === 'public' && hint.sMaxAgeSeconds !== undefined) {
-    parts.push(`s-maxage=${hint.sMaxAgeSeconds}`);
+    const shared = finiteDeltaSeconds('sMaxAgeSeconds', hint.sMaxAgeSeconds);
+    if (shared !== undefined) parts.push(`s-maxage=${String(shared)}`);
   }
   if (hint.staleWhileRevalidateSeconds !== undefined) {
-    parts.push(`stale-while-revalidate=${hint.staleWhileRevalidateSeconds}`);
+    const stale = finiteDeltaSeconds(
+      'staleWhileRevalidateSeconds',
+      hint.staleWhileRevalidateSeconds,
+    );
+    if (stale !== undefined) parts.push(`stale-while-revalidate=${String(stale)}`);
   }
   return parts.join(', ');
 };

package/src/route-cache.ts

@@ -0,0 +1,49 @@
+// Single responsibility: the screen a route's `cache` hint gets where it is DECLARED.
+//
+// The layered form the rest of the framework uses: refuse where a value is WRITTEN, be total where
+// it is USED. `cacheControl` is the total half — it drops a field it cannot emit and warns — and
+// this is the half that throws, because at registration the author is standing right there.
+
+import { routeCacheInvalid } from './errors';
+import type { CacheHint } from './response';
+import { isDeltaSeconds } from './response';
+
+/**
+ * The three `CacheHint` fields that reach a `cache-control` directive as a NUMBER. `tags` and
+ * `vary` are string lists and `mode` is a closed union the compiler already decides.
+ *
+ * A tuple of literals rather than `Object.keys(hint)`: the set is the emitter's, not the caller's,
+ * so a field added to `CacheHint` and forgotten here is a compile error at the emitter's next edit
+ * rather than a silently unscreened age.
+ */
+const DELTA_SECONDS_FIELDS = [
+  'maxAgeSeconds',
+  'sMaxAgeSeconds',
+  'staleWhileRevalidateSeconds',
+] as const;
+
+/**
+ * `isDeltaSeconds` is IMPORTED from `response.ts`, never restated: that file owns what may be
+ * emitted, this one what may be declared, and a byte-identical predicate in both is how a screen
+ * and its emitter come to accept different sets — a route that registers cleanly and then emits no
+ * age at all. **Zero stays legal at both ends**: `max-age=0` means "revalidate every time" and the
+ * framework's own defaults declare it — `PRIVATE_CACHE`, `defaultCache`'s anonymous hint and the
+ * CLI's authorized-object hint all carry `maxAgeSeconds: 0`, so a floor of 1 would refuse the
+ * framework at its own boot.
+ *
+ * Called once per route by `createRouter`, which is the one way a `Route` becomes matchable — so
+ * every hint an app can serve has been through here, including the ones `@ultimat3/cli` mints for
+ * favicons, dev assets and storage objects.
+ */
+export const assertRouteCache = (
+  hint: CacheHint | undefined,
+  route: string,
+  path: string,
+): void => {
+  if (hint === undefined) return;
+  for (const field of DELTA_SECONDS_FIELDS) {
+    const value = hint[field];
+    if (value === undefined || isDeltaSeconds(value)) continue;
+    throw routeCacheInvalid(route, path, field, value);
+  }
+};

package/src/router.ts

@@ -16,6 +16,7 @@ import { routeConflict } from './errors';
 import type { Bucket } from './rate-limit';
 import type { UltimateRequest } from './request';
 import type { CacheHint } from './response';
+import { assertRouteCache } from './route-cache';
 import type { Schema } from './validate';
 
 export type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
@@ -129,6 +130,10 @@ const segmentsOf = (path: string): readonly string[] =>
 export const createRouter = (routes: readonly Route[]): RouteTable => {
   const root = node();
   for (const route of routes) {
+    // Before the trie is touched: a hint that cannot be emitted is refused where it was WRITTEN,
+    // not on the response path — `cacheControl` is total there by design, so the alternative is a
+    // log line once per request and a response that quietly falls back to heuristic caching.
+    assertRouteCache(route.meta.cache, route.meta.name, route.path);
     let current = root;
     const segments = segmentsOf(route.path);
     for (const [index, segment] of segments.entries()) {

package/src/webhook-verify.ts

@@ -22,7 +22,12 @@ import {
   WEBHOOK_TOPIC_HEADER,
   webhookMac,
 } from '@ultimat3/core';
-import { bodyInvalid, webhookSignatureInvalid, webhookSignatureStale } from './errors';
+import {
+  bodyInvalid,
+  httpCountInvalid,
+  webhookSignatureInvalid,
+  webhookSignatureStale,
+} from './errors';
 
 /**
  * How far a delivery's timestamp may sit from this clock, either way. Five minutes is the window
@@ -32,6 +37,23 @@ import { bodyInvalid, webhookSignatureInvalid, webhookSignatureStale } from './e
  */
 export const DEFAULT_WEBHOOK_TOLERANCE_MS = 300_000;
 
+/**
+ * The screen above `toleranceMs`, kept beside the constant it defaults to.
+ *
+ * The `Finite` in the name is load-bearing: `bun run finite-bounds` recognises a repair by the
+ * shape of the CALL, so a screen named for what it guards is invisible to the ratchet that would
+ * otherwise catch the next one of these.
+ */
+const assertFiniteToleranceMs = (toleranceMs: number): number => {
+  if (Number.isSafeInteger(toleranceMs) && toleranceMs >= 0) return toleranceMs;
+  throw httpCountInvalid(
+    'webhook toleranceMs',
+    toleranceMs,
+    'a whole number of milliseconds, zero or more',
+    'toleranceMs: 300_000',
+  );
+};
+
 /**
  * Restated rather than read from `HttpConfig.bodyLimitBytes` (same number, `config.ts`): this
  * function runs inside a route handler with a raw `Request` and no pipeline config in scope, and a
@@ -39,6 +61,23 @@ export const DEFAULT_WEBHOOK_TOLERANCE_MS = 300_000;
  */
 export const DEFAULT_WEBHOOK_BODY_LIMIT = 1_048_576;
 
+/**
+ * The same screen above `maxBytes`, refused HERE and not only where it lands.
+ *
+ * `readWithinLimit` refuses a non-finite limit as well, and that is one file away: its `fix:` names
+ * core's reader, while the edit the caller has to make is the `maxBytes` written on this call. Zero
+ * is excluded on purpose — a cap of nothing refuses every delivery a sender can make.
+ */
+const assertFiniteBodyLimit = (maxBytes: number): number => {
+  if (Number.isSafeInteger(maxBytes) && maxBytes >= 1) return maxBytes;
+  throw httpCountInvalid(
+    'webhook maxBytes',
+    maxBytes,
+    'a whole number of bytes, at least 1',
+    `maxBytes: ${DEFAULT_WEBHOOK_BODY_LIMIT}`,
+  );
+};
+
 export interface WebhookVerifyOptions {
   /** The shared secret for THIS sender. Never logged, never rendered into a refusal. */
   readonly secret: string;
@@ -97,7 +136,7 @@ export async function verifyWebhookSignature(
     );
   }
 
-  const maxBytes = options.maxBytes ?? DEFAULT_WEBHOOK_BODY_LIMIT;
+  const maxBytes = assertFiniteBodyLimit(options.maxBytes ?? DEFAULT_WEBHOOK_BODY_LIMIT);
   // Through core's counting reader, the same one `UltimateRequest.#read` uses: a sender that
   // announces no length must not be able to make this handler hold an unbounded payload before the
   // signature it was never going to pass is even computed.
@@ -123,7 +162,11 @@ export async function verifyWebhookSignature(
   }
 
   const signedAtMs = signature.timestampSeconds * 1_000;
-  const toleranceMs = options.toleranceMs ?? DEFAULT_WEBHOOK_TOLERANCE_MS;
+  // The tolerance IS the replay window, so it is screened before it is compared against: `skewMs >
+  // NaN` is false, which does not widen the window — it removes it, and a webhook captured a year
+  // ago verifies forever with every other check passing. Refused as the config it is, and not by
+  // the sender's error: nothing the caller sends can fix it.
+  const toleranceMs = assertFiniteToleranceMs(options.toleranceMs ?? DEFAULT_WEBHOOK_TOLERANCE_MS);
   const skewMs = Math.abs((options.clock ?? systemClock).now().getTime() - signedAtMs);
   // Both directions: a sender whose clock runs ahead is the same replay window pointed the other
   // way, and accepting the future half doubles it.