@ultimat3/http 1.2.0 → 2.0.0

package/src/rate-limit.ts

@@ -1,7 +1,14 @@
-// Token-bucket rate limiting. The store is an interface so the same limiter runs
-// in-memory in dev/tests and against Redis/Postgres in a multi-replica deployment;
-// the bucket maths lives here so every driver agrees on the numbers.
-import { rateLimited } from './errors';
+// Token-bucket rate limiting. The store is an interface so the same limiter runs in-memory in
+// dev/tests and against a shared tier in a multi-replica deployment — installed through
+// `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 { rateLimited, rateLimitInvalid, rateLimitNotShared, rateLimitScopeUnset } from './errors';
+
+/**
+ * Where a limiter's counters live. A store says which it provides; `RateLimitConfig` says which
+ * the deployment requires, and the two are checked against each other once, at boot.
+ */
+export type RateLimitScope = 'process' | 'shared';
 
 export interface Bucket {
   /** Burst size. */
@@ -18,6 +25,8 @@ export interface RateLimitDecision {
 }
 
 export interface RateLimitStore {
+  /** Declared, never inferred: a driver knows where its counters live; nothing else does. */
+  readonly scope: RateLimitScope;
   take(key: string, bucket: Bucket, cost: number, nowMs: number): Promise<RateLimitDecision>;
   reset(key: string): Promise<void>;
 }
@@ -27,9 +36,23 @@ export interface RateLimitConfig {
   /** Named buckets; a route selects one via `meta.rateLimit`. `default` is required. */
   readonly buckets: Readonly<Record<string, Bucket>>;
   readonly defaultBucket: string;
+  /**
+   * What this deployment requires of the store. `'shared'` says these numbers are the whole
+   * fleet's allowance, and a per-process store then refuses to boot — because N replicas each
+   * holding their own counters enforce N × every number here, silently and only in production.
+   */
+  readonly scope: RateLimitScope;
 }
 
-export const DEFAULT_RATE_LIMIT: RateLimitConfig = {
+/**
+ * Everything the framework can decide on its own. `scope` is NOT here: one process is the only
+ * thing a framework can promise without being told, and defaulting to it made "we did not ask"
+ * indistinguishable from "the app said one replica" — so the chart's `replicas: 3` enforced every
+ * number three times over, silently, and the boot check that exists for this
+ * (`assertRateLimitScope`) never fired because it only reads a `'shared'` declaration. The
+ * comment that used to sit here was right about the fact and wrong about the conclusion: ask.
+ */
+export const DEFAULT_RATE_LIMIT: Omit<RateLimitConfig, 'scope'> = {
   enabled: true,
   defaultBucket: 'default',
   buckets: {
@@ -40,11 +63,90 @@ export const DEFAULT_RATE_LIMIT: RateLimitConfig = {
   },
 };
 
+/**
+ * `defineHttpConfig`'s one resolver for this slice, so the refusal happens where an author can
+ * act on it rather than at the first request. A limiter that is switched off has nothing to be
+ * wrong about, so `enabled: false` needs no declaration — and reads as `'process'`.
+ */
+export const resolveRateLimitConfig = (
+  input: Partial<RateLimitConfig> | undefined,
+): RateLimitConfig => {
+  const merged = { ...DEFAULT_RATE_LIMIT, ...input };
+  if (input?.scope !== undefined) return { ...merged, scope: input.scope };
+  if (!merged.enabled) return { ...merged, scope: 'process' };
+  throw rateLimitScopeUnset();
+};
+
+/** How a route, an action or a query spells a limit before it becomes a `Bucket`. */
+export interface RateLimitDeclaration {
+  /** The burst a caller may spend at once. */
+  readonly limit: number;
+  /** The window that refills it. */
+  readonly windowMs: number;
+}
+
+/**
+ * `{ limit, windowMs }` as the limiter's own vocabulary: `5 / 600_000ms` is five held, one back
+ * every two minutes. The only conversion between a declaration and the enforcement, so the
+ * numbers an OpenAPI operation publishes and the numbers `withRouteBuckets` registers cannot
+ * drift. It lives HERE, beside `Bucket` and the maths, because `@ultimat3/action` and
+ * `@ultimat3/query` are the same tier and can never import each other — a copy in one of them is
+ * a second answer to "what does this limit mean" for the other.
+ *
+ * **The COMPUTED rate is validated, not just the two declared halves.** The division is where a
+ * pair that reads fine becomes one the limiter cannot run on, in both directions:
+ * `{ limit: Number.MAX_VALUE, windowMs: 1 }` computes to `Infinity` — a bucket that never empties,
+ * which is the same "declared a limit, enforced nothing" as `windowMs: 0` — and a tiny limit over
+ * a huge window underflows to `0`, a bucket that never refills, so the endpoint is closed after
+ * its first burst rather than limited.
+ */
+export const toBucket = (owner: string, declared: RateLimitDeclaration): Bucket => {
+  const refuse = (reason: string): never => {
+    throw rateLimitInvalid({
+      owner,
+      limit: declared.limit,
+      windowMs: declared.windowMs,
+      reason,
+    });
+  };
+  // A capacity under one token cannot admit a single request, so the endpoint is closed, not
+  // limited — a policy's job, never a rate limit's.
+  if (!Number.isFinite(declared.limit) || declared.limit < 1) {
+    refuse('limit must be a finite number of at least 1 request');
+  }
+  if (!Number.isFinite(declared.windowMs) || declared.windowMs <= 0) {
+    refuse('windowMs must be finite and greater than zero');
+  }
+  const refillPerSecond = declared.limit / (declared.windowMs / 1000);
+  // Kept though the two checks above make it unreachable today: with `limit >= 1` and a finite
+  // window the smallest rate is ~5.6e-306, which is normal, not zero. It is the guard that has to
+  // move first if `limit >= 1` is ever relaxed.
+  if (!Number.isFinite(refillPerSecond) || refillPerSecond <= 0) {
+    refuse(
+      `the refill rate it computes to is ${refillPerSecond} per second, which is a bucket that never empties — nothing would be enforced`,
+    );
+  }
+  return { capacity: declared.limit, refillPerSecond };
+};
+
 interface BucketState {
   tokens: number;
   lastMs: number;
+  /**
+   * The instant this entry becomes indistinguishable from a missing one: a bucket back at
+   * capacity answers exactly as a first-ever request does. `Infinity` for a bucket that never
+   * refills — only the cap can forget that one.
+   */
+  forgetAtMs: number;
 }
 
+const forgetAt = (state: BucketState, bucket: Bucket, nowMs: number): number => {
+  const toFull = bucket.capacity - state.tokens;
+  if (toFull <= 0) return nowMs;
+  if (bucket.refillPerSecond <= 0) return Number.POSITIVE_INFINITY;
+  return nowMs + Math.ceil((toFull / bucket.refillPerSecond) * 1000);
+};
+
 const decide = (
   state: BucketState,
   bucket: Bucket,
@@ -56,6 +158,7 @@ const decide = (
   state.lastMs = nowMs;
   const allowed = tokens >= cost;
   state.tokens = allowed ? tokens - cost : tokens;
+  state.forgetAtMs = forgetAt(state, bucket, nowMs);
   const deficit = allowed ? bucket.capacity - state.tokens : cost - state.tokens;
   // A bucket that never refills would give an infinite reset; clamp to a day so the
   // Retry-After header stays a number a client can act on.
@@ -70,14 +173,69 @@ const decide = (
   };
 };
 
-/** Default driver: correct for one process, which is exactly dev and tests. */
-export const memoryRateLimitStore = (): RateLimitStore => {
+/**
+ * Hard bound on tracked keys. A key is `route|subject`, so one subject throttled on N routes is
+ * N entries — a higher natural cardinality than an identity table, which is why this cap is
+ * larger than `@ultimat3/auth`'s. At ~200 bytes an entry that is a few megabytes, held.
+ */
+export const DEFAULT_MAX_RATE_LIMIT_KEYS = 20_000;
+
+/** An idle store still sweeps this often, so a burst's state does not sit until the next one. */
+const SWEEP_EVERY_MS = 60_000;
+
+export interface MemoryRateLimitStore extends RateLimitStore {
+  /** Entries tracked right now — the bound, observable. */
+  readonly size: number;
+}
+
+/**
+ * Default driver: correct for one process, which is exactly dev and tests.
+ *
+ * Bounded, because the key falls back to the connection address: a scan rotating through an
+ * IPv6 /64 mints a fresh key per request, and an unbounded map turns that into an OOM. Two
+ * rules keep it flat. A refilled bucket is *forgotten*, not evicted — it answers exactly as a
+ * missing one, so dropping it costs nothing and a scanner's one-request buckets qualify within
+ * a second. Only if that is not enough does the cap evict live state, and then the entries
+ * closest to full go first: throwing away a spent bucket is what would hand the scanner a free
+ * reset, so the most-throttled key is the last one to go.
+ */
+export const memoryRateLimitStore = (
+  options: { readonly maxKeys?: number | undefined } = {},
+): MemoryRateLimitStore => {
+  const maxKeys = Math.max(1, Math.floor(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;
+
+  const sweep = (nowMs: number): void => {
+    lastSweepMs = nowMs;
+    for (const [key, state] of buckets) {
+      if (state.forgetAtMs <= nowMs) buckets.delete(key);
+    }
+    if (buckets.size <= maxKeys) return;
+    // Batched down to `evictTo` so this sort is paid once per 10% of the cap, not per request.
+    const nearestFull = [...buckets.entries()].sort((a, b) => a[1].forgetAtMs - b[1].forgetAtMs);
+    for (const [key] of nearestFull) {
+      if (buckets.size <= evictTo) break;
+      buckets.delete(key);
+    }
+  };
+
   return {
+    scope: 'process',
+    get size() {
+      return buckets.size;
+    },
     take(key, bucket, cost, nowMs) {
-      const state = buckets.get(key) ?? { tokens: bucket.capacity, lastMs: nowMs };
+      const state = buckets.get(key) ?? {
+        tokens: bucket.capacity,
+        lastMs: nowMs,
+        forgetAtMs: nowMs,
+      };
       buckets.set(key, state);
-      return Promise.resolve(decide(state, bucket, cost, nowMs));
+      const decision = decide(state, bucket, cost, nowMs);
+      if (buckets.size > maxKeys || nowMs - lastSweepMs >= SWEEP_EVERY_MS) sweep(nowMs);
+      return Promise.resolve(decision);
     },
     reset(key) {
       buckets.delete(key);
@@ -109,6 +267,19 @@ export const rateLimitKey = (parts: RateLimitKeyParts): string => {
 };
 
 export interface RateLimiter {
+  /** The store's scope, carried up so the boot check has one thing to read. */
+  readonly scope: RateLimitScope;
+  /**
+   * The table this limiter resolves a bucket NAME against. Declared, never inferred — the same
+   * rule as `RateLimitStore.scope` and `@ultimat3/auth`'s `AuthLimiter.policy`, and for the same
+   * reason: `createRateLimiter` closes over its config, so nothing outside can see which buckets
+   * it actually holds. `createPipeline` compares this against the buckets the ROUTES declare, and
+   * an unknown name is refused instead of falling through `bucketFor` to `default`.
+   *
+   * Optional only so an existing external implementation still type-checks; an absent table
+   * cannot be checked, so it is refused exactly as a wrong one is.
+   */
+  readonly buckets?: Readonly<Record<string, Bucket>> | undefined;
   check(key: string, bucketName: string, cost?: number): Promise<RateLimitDecision>;
   headers(decision: RateLimitDecision): Record<string, string>;
   /** Throws `X_RATE_LIMITED` when the bucket is empty. */
@@ -131,6 +302,10 @@ export const createRateLimiter = (options: {
     store.take(key, bucketFor(bucketName), cost, now());
 
   return {
+    scope: store.scope,
+    // Published, not private: this is the table `bucketFor` above reads, and the boot check has
+    // no other way to learn what this limiter can enforce.
+    buckets: options.config.buckets,
     check,
     headers: (decision) => ({
       'ratelimit-limit': String(decision.limit),
@@ -144,3 +319,16 @@ export const createRateLimiter = (options: {
     },
   };
 };
+
+/**
+ * Boot, never the first request. A per-node store under a `'shared'` declaration is a limit that
+ * is quietly N × what the config says — the kind of wrong answer that only shows up as a flood
+ * nobody was throttling, at the worst hour. A process that cannot enforce what it was configured
+ * to enforce must not start; `enabled: false` is checked too, because a limit declared fleet-wide
+ * and then switched off is the same claim with nothing behind it.
+ */
+export const assertRateLimitScope = (config: RateLimitConfig, limiter: RateLimiter): void => {
+  if (config.scope !== 'shared') return;
+  if (!config.enabled) throw rateLimitNotShared('disabled');
+  if (limiter.scope !== 'shared') throw rateLimitNotShared('process');
+};

package/src/redirect.ts

@@ -0,0 +1,29 @@
+// How a handler that cannot return a `Response` still answers with one. An action's return
+// value is its output schema, on every surface — HTTP, MCP, a job — so "answer 303" cannot be
+// a return value without inventing a second protocol for one surface. It is recorded on the
+// request context instead, and the surface that knows what a redirect means reads it back.
+
+import type { RequestContext } from './context';
+import { assertInRequest } from './context';
+import type { RedirectIntent, RedirectStatus } from './response';
+
+/**
+ * Answer this request with a `Location` instead of the handler's return value.
+ *
+ * 303 by default because the caller is a `<form method="post">`: 303 turns the follow-up into a
+ * GET, so a reload does not repost. A 302 here leaves the method up to the browser, and reposts.
+ */
+export const setRedirect = (location: string, status: RedirectStatus = 303): void => {
+  assertInRequest('setRedirect()').redirect = { location, status };
+};
+
+/**
+ * Read and clear. Clearing is the point: the slot outlives the handler that set it, and a
+ * projection that only read it would redirect the *next* thing to look — an idempotent replay,
+ * a second action invoked in the same request — to a location it never asked for.
+ */
+export const takeRedirect = (ctx: RequestContext): RedirectIntent | undefined => {
+  const intent = ctx.redirect;
+  ctx.redirect = undefined;
+  return intent;
+};

package/src/request.ts

@@ -3,8 +3,10 @@
 // context so they cannot drift from what the pipeline resolved.
 
 import type { Actor } from '@ultimat3/core';
+import { readWithinLimit } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bodyInvalid, buildSkew } from './errors';
+import { readCookie } from './locale';
 import type { Schema } from './validate';
 import { validate, validateSync } from './validate';
 
@@ -13,9 +15,19 @@ export type QueryValues = Readonly<Record<string, string | readonly string[]>>;
 const contentTypeOf = (request: Request): string =>
   (request.headers.get('content-type') ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
 
-/** Repeated keys become arrays; everything else stays a string for the schema to coerce. */
+/**
+ * Repeated keys become arrays; everything else stays a string for the schema to coerce.
+ *
+ * `Object.create(null)`, never `{}`: on a plain object `out['__proto__']` never reads as
+ * `undefined` — it reads the inherited `Object.prototype` — so the FIRST `?__proto__=` took the
+ * repeated-key branch below and assigned an array through the `__proto__` SETTER, which accepts an
+ * object and swapped this object's prototype for it. One occurrence was enough. A null prototype
+ * has neither accessor, so `__proto__` is an ordinary key here, and `key in record` — how
+ * `coerceQuery` decides whether to coerce a declared property — stops answering true for every
+ * member of `Object.prototype`.
+ */
 const parseQuery = (url: URL): QueryValues => {
-  const out: Record<string, string | string[]> = {};
+  const out: Record<string, string | string[]> = Object.create(null);
   for (const [key, value] of url.searchParams) {
     const existing = out[key];
     if (existing === undefined) out[key] = value;
@@ -72,15 +84,28 @@ export class UltimateRequest {
     return this.ctx.requestId;
   }
 
-  /** Build id the client thinks it is running. See `assertBuild()`. */
+  /**
+   * Build id the CLIENT thinks it is running. See `assertBuild()`. Not `ctx.buildId`, which is
+   * core's meaning of the word — the build this PROCESS serves — and the one every other layer
+   * reads off the ambient context.
+   */
   get buildId(): string | null {
-    return this.ctx.buildId;
+    return this.ctx.clientBuildId;
   }
 
   header(name: string): string | null {
     return this.raw.headers.get(name);
   }
 
+  /**
+   * One decoded cookie. `hooks.authenticate` is handed this object and nothing else, so this is
+   * the seam a session lookup reads — a hand-rolled `Cookie` split in the app is the second
+   * parser this method exists to prevent.
+   */
+  cookie(name: string): string | null {
+    return readCookie(this.raw.headers.get('cookie'), name);
+  }
+
   param(name: string): string {
     const value = this.ctx.params[name];
     if (value === undefined) {
@@ -124,7 +149,7 @@ export class UltimateRequest {
    */
   assertBuild(): void {
     const server = this.ctx.config.buildId;
-    const client = this.ctx.buildId;
+    const client = this.ctx.clientBuildId;
     if (server === null || client === null || client === server) return;
     throw buildSkew(client, server);
   }
@@ -142,21 +167,30 @@ export class UltimateRequest {
     const type = contentTypeOf(this.raw);
     if (type === '' || declared === 0) return undefined;
 
-    // multipart is streamed by the runtime; the declared length is the only guard.
+    // One capped read for every content type, multipart included: the parser runs on bytes this
+    // process already agreed to hold, never on a stream it hands to the runtime unbounded.
+    const read = await readWithinLimit(this.raw.body, limit);
+    if ('over' in read) {
+      throw bodyInvalid(this.pathname, [`body is at least ${read.over} bytes, limit is ${limit}`]);
+    }
+    if (read.bytes.byteLength === 0) return undefined;
+
     if (type === 'multipart/form-data') {
       try {
-        return Object.fromEntries(await this.raw.formData());
+        // Re-parsed from the capped bytes, so the boundary comes from the header it was announced
+        // in — `Response` is the one multipart parser here, exactly as `Request` was.
+        // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+        // `SharedArrayBuffer`, which `Response` does not accept.
+        const form = await new Response(new Uint8Array(read.bytes), {
+          headers: { 'content-type': this.raw.headers.get('content-type') ?? type },
+        }).formData();
+        return Object.fromEntries(form);
       } catch (error) {
         throw bodyInvalid(this.pathname, [`could not parse ${type}: ${String(error)}`]);
       }
     }
 
-    const buffer = await this.raw.arrayBuffer();
-    if (buffer.byteLength > limit) {
-      throw bodyInvalid(this.pathname, [`body is ${buffer.byteLength} bytes, limit is ${limit}`]);
-    }
-    if (buffer.byteLength === 0) return undefined;
-    const body = new TextDecoder().decode(buffer);
+    const body = new TextDecoder().decode(read.bytes);
     try {
       if (type === 'application/json' || type.endsWith('+json')) return JSON.parse(body);
       if (type === 'application/x-www-form-urlencoded') {

package/src/response.ts

@@ -50,10 +50,22 @@ export const stream = (
 export const noContent = (init?: ResponseInit): Response =>
   new Response(null, { ...init, status: 204 });
 
+/** 301 is absent on purpose: a permanent redirect is a deploy decision, not an app one. */
+export type RedirectStatus = 302 | 303 | 307 | 308;
+
 /** 303 after a mutation, 302 otherwise — never 301 from application code. */
-export const redirect = (location: string, status: 302 | 303 | 307 | 308 = 302): Response =>
+export const redirect = (location: string, status: RedirectStatus = 302): Response =>
   new Response(null, { status, headers: { location } });
 
+/**
+ * A redirect a handler asked for but could not return — see `redirect.ts`. Kept beside
+ * `redirect()` so the intent and the Response it becomes cannot drift on status.
+ */
+export interface RedirectIntent {
+  readonly location: string;
+  readonly status: RedirectStatus;
+}
+
 /**
  * RFC-9457. The body carries the framework's error contract verbatim: `code`,
  * `cause`, `fix`, `docs`. An agent reading a failed response gets the same three
@@ -108,19 +120,33 @@ export const cacheControl = (hint: CacheHint): string => {
   return parts.join(', ');
 };
 
+/**
+ * Adds to the cache key without ever replacing it. `Vary` is a set, and two stages contribute to
+ * it — the cache stage names the request properties a body depends on, the CORS stage names the
+ * origin — so a `set` from the later one silently drops the earlier one's key and a CDN starts
+ * serving one variant for all of them.
+ */
+export const addVary = (response: Response, values: readonly string[]): Response => {
+  if (values.length === 0) return response;
+  const existing = response.headers.get('vary');
+  const merged = new Set([...(existing === null ? [] : existing.split(/,\s*/)), ...values]);
+  response.headers.set('vary', [...merged].join(', '));
+  return response;
+};
+
 /** Mutates the response headers in place — responses are per-request, never shared. */
 export const applyCacheHeaders = (response: Response, hint: CacheHint): Response => {
   response.headers.set('cache-control', cacheControl(hint));
   if (hint.tags !== undefined && hint.tags.length > 0) {
     response.headers.set('x-cache-tags', hint.tags.join(','));
   }
-  const vary = hint.vary ?? (hint.mode === 'public' ? ['accept-language'] : []);
-  if (vary.length > 0) {
-    const existing = response.headers.get('vary');
-    const merged = new Set([...(existing === null ? [] : existing.split(/,\s*/)), ...vary]);
-    response.headers.set('vary', [...merged].join(', '));
-  }
-  return response;
+  // `cookie` is not optional on the shared path. A `public` response is stored by a CDN under the
+  // URL, and every session in this framework travels in a cookie — so without it the first
+  // signed-in render of a public page is what every later visitor is served.
+  return addVary(
+    response,
+    hint.vary ?? (hint.mode === 'public' ? ['accept-language', 'cookie'] : []),
+  );
 };
 
 export const withHeaders = (response: Response, headers: Record<string, string>): Response => {

package/src/router.ts

@@ -12,6 +12,7 @@
 // (`X_ROUTE_CONFLICT`) rather than a coin flip.
 import type { RequestContext } from './context';
 import { routeConflict } from './errors';
+import type { Bucket } from './rate-limit';
 import type { UltimateRequest } from './request';
 import type { CacheHint } from './response';
 import type { Schema } from './validate';
@@ -60,6 +61,14 @@ export interface RouteMeta {
   readonly cache?: CacheHint;
   /** Named bucket from `rateLimit.buckets`. */
   readonly rateLimit?: string;
+  /**
+   * The numbers that bucket MUST hold, when the route brings its own. Naming a bucket nothing
+   * defines is how a declared limit becomes the `default` one: the name fell through
+   * `bucketFor`, so an endpoint declaring 5 ran on 120. `withRouteBuckets` registers this into
+   * the limiter's table at construction — the one point where routes and config meet — and
+   * refuses a configured bucket of the same name that says something else.
+   */
+  readonly rateLimitBucket?: Bucket;
   readonly tags?: readonly string[];
   readonly description?: string;
 }
@@ -84,7 +93,9 @@ export type MatchResult =
       readonly ok: false;
       readonly reason: 'method-not-allowed';
       readonly allow: readonly HttpMethod[];
-    };
+    }
+  /** A param or wildcard segment the request wrote as invalid percent-encoding. */
+  | { readonly ok: false; readonly reason: 'path-invalid'; readonly segment: string };
 
 interface TrieNode {
   readonly statics: Map<string, TrieNode>;
@@ -164,34 +175,65 @@ interface Candidate {
   readonly params: RouteParams;
 }
 
+/** The walk's accumulator: the terminals it reached, and why a branch it could not take failed. */
+interface Search {
+  readonly out: Candidate[];
+  /** First raw segment that would not percent-decode. Only set where a decode was attempted. */
+  undecodable: string | undefined;
+}
+
+/**
+ * `undefined` instead of the bare `URIError` `decodeURIComponent('%ZZ')` throws. A pathname is
+ * whatever the client typed, and an exception from the match would leave the pipeline with
+ * `X_INTERNAL` — a 500, and a page for the on-call, for a request only the caller can fix.
+ */
+const decodeSegment = (segment: string): string | undefined => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+};
+
 /** Terminal nodes reachable for `segments`, in precedence order. */
 const candidates = (
   current: TrieNode,
   segments: readonly string[],
   index: number,
   params: RouteParams,
-  out: Candidate[],
+  search: Search,
 ): void => {
   if (index === segments.length) {
-    if (current.routes.size > 0) out.push({ node: current, params });
+    if (current.routes.size > 0) search.out.push({ node: current, params });
     return;
   }
   const segment = segments[index];
   if (segment === undefined) return;
 
+  // Static segments are compared raw, never decoded, so a malformed escape only ever fails the
+  // branch that would have decoded it: a path that reaches no param or wildcard is the 404 it
+  // always was, and a static route still wins the precedence it always won.
   const staticChild = current.statics.get(segment);
-  if (staticChild !== undefined) candidates(staticChild, segments, index + 1, params, out);
+  if (staticChild !== undefined) candidates(staticChild, segments, index + 1, params, search);
 
   if (current.param !== undefined) {
-    const next = { ...params, [current.param.name]: decodeURIComponent(segment) };
-    candidates(current.param.node, segments, index + 1, next, out);
+    const value = decodeSegment(segment);
+    if (value === undefined) search.undecodable ??= segment;
+    else {
+      const next = { ...params, [current.param.name]: value };
+      candidates(current.param.node, segments, index + 1, next, search);
+    }
   }
 
   if (current.wildcard !== undefined) {
-    const rest = segments.slice(index).map(decodeURIComponent).join('/');
-    const next = { ...params, [current.wildcard.name]: rest };
-    if (current.wildcard.node.routes.size > 0) {
-      out.push({ node: current.wildcard.node, params: next });
+    const tail = segments.slice(index);
+    const decoded = tail.map(decodeSegment);
+    // `-1` indexes to `undefined`, so this is "the first segment that failed, or none".
+    const bad = tail[decoded.indexOf(undefined)];
+    if (bad !== undefined) search.undecodable ??= bad;
+    else if (current.wildcard.node.routes.size > 0) {
+      const next = { ...params, [current.wildcard.name]: decoded.join('/') };
+      search.out.push({ node: current.wildcard.node, params: next });
     }
   }
 };
@@ -206,9 +248,17 @@ const routeFor = (candidate: Candidate, method: HttpMethod): Route | undefined =
 
 export const matchRoute = (table: RouteTable, method: string, pathname: string): MatchResult => {
   const segments = segmentsOf(pathname);
-  const found: Candidate[] = [];
-  candidates(table.root, segments, 0, {}, found);
-  if (found.length === 0) return { ok: false, reason: 'not-found' };
+  const search: Search = { out: [], undecodable: undefined };
+  candidates(table.root, segments, 0, {}, search);
+  const found = search.out;
+  // A refused decode is only the answer when nothing matched: another branch reaching a route
+  // means the request named something real, and the failed decode was a road not taken.
+  if (found.length === 0) {
+    const { undecodable } = search;
+    if (undecodable !== undefined)
+      return { ok: false, reason: 'path-invalid', segment: undecodable };
+    return { ok: false, reason: 'not-found' };
+  }
 
   const wanted = method.toUpperCase() as HttpMethod;
   for (const candidate of found) {