@ultimat3/http 22.15.0 → 24.0.0

package/src/hooks.ts

@@ -3,7 +3,7 @@
 // be imported here), and — a seam of a different kind, deciding nothing — what a dev diagnostic
 // found. All three are declared structurally, which keeps the import boundary intact and keeps
 // the pipeline testable.
-import type { Actor } from '@ultimat3/core';
+import type { Actor, UltimateError } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import type { OverlayNotice } from './overlay';
 import type { UltimateRequest } from './request';
@@ -51,6 +51,17 @@ export interface ServerHooks {
     status: number,
     ctx: RequestContext,
   ) => Promise<string | undefined> | string | undefined;
+  /**
+   * Why nothing is routed at this path, when a higher tier knows more than "no route". Consulted
+   * ONLY on a miss — never for a matched route, a refused method or an unreadable path — and the
+   * error it returns is thrown in place of `X_ROUTE_NOT_FOUND`; `undefined` keeps the plain miss.
+   * `@ultimat3/action` answers here for a path that is one of its actions under a path style this
+   * server does not serve.
+   *
+   * Synchronous and given only the request line: a miss is reached by any anonymous caller, so
+   * what runs on it must not read a body, a session or a database.
+   */
+  readonly explainMiss?: (method: string, pathname: string) => UltimateError | undefined;
 }
 
 export type Authenticator = NonNullable<ServerHooks['authenticate']>;

package/src/html-render.ts

@@ -1,20 +1,6 @@
-// The two questions every HTML answer this package renders has to ask, in one place: is the caller
-// a browser, and how does a value become markup. Both were the dev overlay's private helpers while
-// the production error page needs the identical answers — a second accept sniff would let a client
-// get the overlay in dev and JSON in production, and a second escape set is one hole away.
-
-/**
- * `'` is escaped even though every attribute the renderers write is double-quoted: the escape set
- * is what the next author reads as the guarantee, and a single-quoted attribute written later
- * would inherit a hole nothing here would have flagged.
- */
-export const escapeHtml = (value: string): string =>
-  value
-    .replaceAll('&', '&')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
+// Is the caller a browser? One sniff for every HTML answer this package renders — the dev overlay
+// and the production error page need the identical answer, and a second sniff would let a client
+// get the overlay in dev and JSON in production. How a value becomes markup is core's `escapeHtml`.
 
 /**
  * Does this caller render HTML? One sniff, three readers — the dev overlay, the production error

package/src/index.ts

@@ -1,12 +1,14 @@
 // The public surface of @ultimat3/http. Explicit, never `export *`: what is not
 // listed here is an implementation detail and may change without a major bump.
 
-export type { RenderMode } from '@ultimat3/core';
+export type { PgExecutor, RenderMode } from '@ultimat3/core';
 // The wire format is `@ultimat3/core`'s and is RE-EXPORTED, never re-declared: it is one module at
 // the tier both halves can reach, because `@ultimat3/jobs` signs a delivery, this package verifies
 // one, and neither may import the other. Re-exported here so a receiver route needs one import.
 export {
+  escapeHtml,
   isCanonicalWebhookField,
+  readCookie,
   WEBHOOK_ID_HEADER,
   WEBHOOK_SIGNATURE_HEADER,
   WEBHOOK_SIGNATURE_VERSION,
@@ -105,9 +107,8 @@ export {
 } from './forwarded';
 export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
 export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
-export { escapeHtml } from './html-render';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
-export { DEFAULT_LOCALE_CONFIG, readCookie } from './locale';
+export { DEFAULT_LOCALE_CONFIG } from './locale';
 export type { Middleware } from './middleware';
 export { compose } from './middleware';
 export type { NavigationPurpose } from './navigation';
@@ -161,11 +162,9 @@ export {
   rateLimitStoreUnavailable,
   tenantBucketUnknown,
 } from './rate-limit-errors';
-export type {
-  PgExecutor,
-  PostgresRateLimitStore,
-  PostgresRateLimitStoreOptions,
-} from './rate-limit-postgres';
+export type { RateLimitPeek } from './rate-limit-peek';
+export { rateLimitPeek, refilledTokens } from './rate-limit-peek';
+export type { PostgresRateLimitStore, PostgresRateLimitStoreOptions } from './rate-limit-postgres';
 export {
   postgresRateLimitStore,
   SQL_RATE_LIMIT_TABLE,

package/src/locale-prefix.ts

@@ -5,6 +5,7 @@
 
 import { type LocaleSources, localeConfig, resolveLocale, splitLocalePrefix } from '@ultimat3/i18n';
 import type { RequestContext } from './context';
+import { normalizePath } from './router';
 
 /** Methods whose redirect may change nothing but the URL. Anything else is a 308, never a 301. */
 const SAFE_METHODS = new Set(['GET', 'HEAD']);
@@ -26,7 +27,10 @@ export function routeLocalePrefix(
   if (prefix === undefined) return pathname;
   if (prefix.isDefault) {
     const mount = basePath === '/' || basePath === '' ? '' : basePath.replace(/\/$/, '');
-    const location = `${mount}${prefix.path}${ctx.url.search}`;
+    // Normalised exactly as the router would match it. The remainder is caller-written, and
+    // `//host/x` in a `Location` is a scheme-relative URL: a permanent, cacheable redirect off
+    // the site, answered before auth. One leading slash, no empty segment.
+    const location = `${mount}${normalizePath(prefix.path)}${ctx.url.search}`;
     // PERMANENT, and so not `redirect()`, whose statuses are an application's (it refuses 301 on
     // purpose: a cached permanent redirect cannot be taken back). This one is the framework's URL
     // scheme, and it IS permanent — the default locale is never prefixed, in any release.

package/src/locale.ts

@@ -32,30 +32,3 @@ export const DEFAULT_TZ_CONFIG: TimeZoneConfig = {
   header: TIMEZONE_HEADER,
   cookie: 'x_timezone',
 };
-
-/**
- * The raw value on a malformed escape, never a throw. `Cookie:` is attacker-controlled and
- * `decodeURIComponent('%')` is a bare `URIError` — thrown from the `locale` stage, which runs on
- * every request, so `curl -H 'Cookie: x-locale=%'` answered 500 and paged the on-call. Nothing is
- * loosened: a locale that is not in `supported` still falls back, and a time zone `Intl` cannot
- * format is still refused. `@ultimat3/auth` guards its own cookie reader the same way and for the
- * same reason; the guard is four lines and this package can never import that one (same tier).
- */
-const decodeCookieValue = (raw: string): string => {
-  try {
-    return decodeURIComponent(raw);
-  } catch {
-    return raw;
-  }
-};
-
-export const readCookie = (header: string | null, name: string): string | null => {
-  if (header === null) return null;
-  for (const part of header.split(';')) {
-    const index = part.indexOf('=');
-    if (index === -1) continue;
-    if (part.slice(0, index).trim() !== name) continue;
-    return decodeCookieValue(part.slice(index + 1).trim());
-  }
-  return null;
-};

package/src/navigation.ts

@@ -24,15 +24,28 @@ export function navigationPurpose(request: Request): NavigationPurpose | null {
 
 const SAFE = new Set(['GET', 'HEAD']);
 
+/** The schemes a navigation may be handed over to. Everything else is not a place to go. */
+const WEB_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:']);
+
 /**
  * What `x-ultimate-location` says. A target on THIS origin is its path, query and fragment and
  * nothing else: behind a TLS-terminating proxy the request URL this process sees is
  * `http://internal…`, so an absolute URL built from it named the public site as `http://` (HSTS
  * hid it; it was still wrong). The router resolves a path against the page it runs in, whose origin
  * is the one the visitor typed. A target on ANOTHER origin is kept exactly as the app gave it.
+ *
+ * Only `http:` and `https:` are ever handed over. The router LOADS what this header says, so a
+ * scheme that runs in the page (`javascript:`, `data:`) would be script in the app's own origin
+ * whenever a redirect target is caller-influenced. Such a target — and one that will not parse —
+ * answers the REQUESTED url instead, as a path: a document load of it re-runs the route, and the
+ * browser's own redirect handling refuses what this refused. Total, never a throw: it runs in the
+ * `response` stage, after the handler.
  */
 export function locationFor(target: string, base: URL): string {
+  const requested = `${base.pathname}${base.search}${base.hash}`;
+  if (!URL.canParse(target, base)) return requested;
   const resolved = new URL(target, base);
+  if (!WEB_PROTOCOLS.has(resolved.protocol)) return requested;
   if (resolved.origin !== base.origin) return target;
   return `${resolved.pathname}${resolved.search}${resolved.hash}`;
 }

package/src/overlay.ts

@@ -2,8 +2,10 @@
 // `--json` emits, so a code/cause/fix string can never differ between the three
 // surfaces. Labels here ("cause", "fix", "notices") are protocol strings from the
 // error contract, not UI copy, so they are not routed through the i18n catalog.
+
+import { escapeHtml } from '@ultimat3/core';
 import { factsOf, renderErrorLines, toProblem } from './error-facts';
-import { acceptsHtml, escapeHtml } from './html-render';
+import { acceptsHtml } from './html-render';
 import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';
 

package/src/peer-identity.ts

@@ -1,8 +1,7 @@
 // Who the MESH says is calling. TLS termination is the mesh's job (axiom 7) so the framework's
-// entire contribution is reading a header it has been TOLD to trust: Envoy's
-// `x-forwarded-client-cert`, at the same hop index `x-forwarded-for` is read at. Untrusted, this
-// header is worse than nothing — it authenticates — so an untrusted read answers `null` and
-// there is no second proxy-trust path to get it wrong in.
+// entire contribution is reading a header it has been TOLD to trust (`trustClientCertHeader`):
+// Envoy's `x-forwarded-client-cert`, at the hop index `x-forwarded-for` is read at. Untrusted,
+// this header is worse than nothing — it authenticates — so an untrusted read answers `null`.
 
 import { FORWARDED_CLIENT_CERT, type ForwardedInput, forwardedElement } from './forwarded';
 
@@ -82,11 +81,16 @@ const pairsOf = (element: string): ReadonlyMap<string, readonly string[]> => {
 };
 
 /**
- * The peer identity a TRUSTED proxy asserted, or `null`. `null` is the answer for an untrusted
- * deployment, a missing header and a chain shorter than `trustedProxyHops` alike: a certificate
+ * The peer identity a TRUSTED proxy asserted, or `null`. `null` is the answer for a deployment
+ * that did not declare `trustClientCertHeader`, an untrusted one, a missing header and a chain
+ * shorter than `trustedProxyHops` alike: a certificate
  * identity read from a hop nobody vouched for is a confident name for an attacker's claim.
  */
 export const peerIdentity = (input: ForwardedInput): PeerIdentity | null => {
+  // Its own declaration, never implied by `trustProxy`: that one says the proxy APPENDS to
+  // `x-forwarded-for`, and plenty of ingresses that do pass a client-sent certificate header
+  // straight through — where the caller would be naming its own identity.
+  if (!input.config.trustClientCertHeader) return null;
   const element = forwardedElement(
     input.headers.get(FORWARDED_CLIENT_CERT),
     input.config.trustedProxyHops,

package/src/pipeline.ts

@@ -3,7 +3,7 @@
 // middleware stack, so nothing can skip a stage and `/_x` and `pipeline.test.ts` can both read it.
 // The other two thirds of the lifecycle are siblings: `stages.ts` owns what each stage does, and
 // `finalize.ts` owns the promise that the tail always answers rather than rejecting.
-import { recordRequest, runWithContext, withSpan } from '@ultimat3/core';
+import { beginWork, recordRequest, runWithContext, withSpan } from '@ultimat3/core';
 import { defineHttpConfig, type HttpConfig } from './config';
 import { asCtx, createRequestContext, elapsedMs, type RequestContext } from './context';
 import { readCorrelation } from './correlation';
@@ -56,7 +56,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'auth',
     phase: 'request',
-    why: 'before rate limiting so the limiter keys per actor and per tenant instead of punishing a shared NAT address',
+    why: 'before rate limiting so the limiter keys per actor and per tenant instead of punishing a shared NAT address — and a request that FAILS a required route is refused here, so this stage spends an allowance keyed on the address alone for it: a failed credential is metered, a signed-in caller behind the same address is not',
   },
   {
     name: 'rate-limit',
@@ -66,7 +66,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'csrf',
     phase: 'request',
-    why: 'after auth so it only judges a caller holding an AMBIENT credential — a bearer token and an anonymous call are both exempt — and before body so a forged write never makes the server allocate its payload. CORS cannot cover this: application/x-www-form-urlencoded is a simple content type, so a cross-site form post is sent and executed and only the RESPONSE is withheld',
+    why: 'after auth so it knows who is calling: a bearer token is exempt (not ambient), and an anonymous write is judged like a signed-in one whenever it carries browser evidence, because a forged sign-in is a forged write — and before body so a forged write never makes the server allocate its payload. CORS cannot cover this: application/x-www-form-urlencoded is a simple content type, so a cross-site form post is sent and executed and only the RESPONSE is withheld',
   },
   {
     name: 'body',
@@ -188,8 +188,23 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
         // own; this race is the half that answers the SOCKET when it does not. `work` keeps its
         // own handler either way — a rejection arriving after the deadline already won is still
         // a rejection, and an unhandled one takes the process down.
-        void work.catch(() => undefined);
-        await Promise.race([work, deadline.expired]);
+        let settled = false;
+        const settle = (): void => {
+          settled = true;
+        };
+        void work.then(settle, settle);
+        try {
+          await Promise.race([work, deadline.expired]);
+        } finally {
+          // The deadline won and the handler is still running: it holds its pool slot and
+          // whatever it was writing. The caller's own count ends when this response leaves, so
+          // the orphan is counted in its own right until it settles — a drain that saw an idle
+          // process here closed the pool under it.
+          if (!settled) {
+            const done = beginWork();
+            void work.then(done, done);
+          }
+        }
       }
     } catch (error) {
       ctx.error = error;

package/src/preferences.ts

@@ -2,10 +2,10 @@
 // and `auth` calls it again once the actor's saved preference is known. WHERE each value is read
 // from is this file's; what a locale or a zone IS stays `@ultimat3/i18n`'s and `@ultimat3/time`'s.
 
+import { readCookie } from '@ultimat3/core';
 import { resolveTimeZone } from '@ultimat3/time';
 import type { HttpConfig } from './config';
 import type { RequestContext } from './context';
-import { readCookie } from './locale';
 import { requestLocale } from './locale-prefix';
 import type { UltimateRequest } from './request';
 

package/src/problem-meta.ts

@@ -12,6 +12,10 @@
 // it was. Measured need: an app's `X_SESSION_CHECKOUT_BUSY` carried `{ sessionId, title, state }`
 // in `meta` and its island recovered the id by running a UUID regex over `cause`.
 
+// The public-cause predicate and both of its tables are `@ultimat3/core`'s (`public-cause.ts`): the
+// MCP error data and the agent `tool_result` ask the question this package's problem document
+// does. This file only WRITES the app half — a reader imports `hasPublicCause` from core.
+import { registerPublicCause, resetPublicCauses } from '@ultimat3/core';
 import { ERROR_STATUS } from './error-map';
 import { problemMetaInvalid } from './errors';
 
@@ -47,20 +51,6 @@ const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
 /** Per app-owned code, the `meta` keys its documents carry. A `Map`, for `APP_ERROR_STATUS`'s reason. */
 const DECLARED = new Map<string, readonly string[]>();
 
-/**
- * The 5xx codes whose `cause` a caller may read. Every other 5xx document carries the code and the
- * request id and a fixed sentence: `X_DB_STATEMENT_FAILED` has a status row, so the old "blank only
- * what nobody classified" rule served the Postgres message and the SQL statement in a production
- * 500. The framework's four are refusals whose cause IS the instruction — back off, retry.
- */
-const FRAMEWORK_PUBLIC_CAUSE: ReadonlySet<string> = new Set([
-  'X_DRAINING',
-  'X_OVERLOADED',
-  'X_FLIGHT_GATE_OVERLOADED',
-  'X_TIMEOUT',
-]);
-const APP_PUBLIC_CAUSE = new Set<string>();
-
 /** Per code: the `meta` keys, a public cause, or both. A bare list is the keys alone. */
 export type ProblemMetaDeclaration =
   | readonly string[]
@@ -98,7 +88,7 @@ export const registerProblemMeta = (
       : ((declaration as { keys?: readonly string[] }).keys ?? []);
     const publicCause = !listed && (declaration as { publicCause?: boolean }).publicCause === true;
     if (!listed && keys.length === 0 && publicCause) {
-      APP_PUBLIC_CAUSE.add(code);
+      registerPublicCause(code);
       continue;
     }
     if (keys.length === 0) {
@@ -122,20 +112,16 @@ export const registerProblemMeta = (
       throw problemMetaInvalid(code, `already declared as [${existing.join(', ')}] by this app`);
     }
     DECLARED.set(code, [...keys]);
-    if (publicCause) APP_PUBLIC_CAUSE.add(code);
+    if (publicCause) registerPublicCause(code);
   }
 };
 
 /** Test seam. Production registers once at boot and never unregisters. */
 export const resetProblemMeta = (): void => {
   DECLARED.clear();
-  APP_PUBLIC_CAUSE.clear();
+  resetPublicCauses();
 };
 
-/** Whether a 5xx document for `code` may carry its authored `cause`. */
-export const hasPublicCause = (code: string): boolean =>
-  FRAMEWORK_PUBLIC_CAUSE.has(code) || APP_PUBLIC_CAUSE.has(code);
-
 /** The keys declared for a code, or `undefined` when nothing was — which is every framework code. */
 export const problemMetaKeysFor = (code: string): readonly string[] | undefined =>
   DECLARED.get(code);

package/src/rate-limit-peek.ts

@@ -0,0 +1,32 @@
+// The READ half of a token bucket: what a key holds now, refill applied, with nothing written.
+// Split from `rate-limit.ts` at the size ceiling; every `RateLimitStore.peek` answers through it.
+
+import type { Bucket } from './rate-limit';
+
+/** A read of a bucket: whole tokens left, and how long until one more is there when none is. */
+export interface RateLimitPeek {
+  readonly remaining: number;
+  /** `0` while a whole token is left; otherwise the seconds until one is, at least 1. */
+  readonly retryAfterSeconds: number;
+}
+
+/**
+ * The peek every store answers from the tokens it computed — exported for the reason
+ * `rateLimitDecision` is: two drivers deriving "when may I come back" separately is two answers.
+ * A bucket that never refills is clamped to a day, as a decision's `Retry-After` is.
+ */
+export const rateLimitPeek = (bucket: Bucket, tokens: number): RateLimitPeek => {
+  if (tokens >= 1) return { remaining: Math.floor(tokens), retryAfterSeconds: 0 };
+  const seconds =
+    bucket.refillPerSecond > 0 ? Math.min(86_400, (1 - tokens) / bucket.refillPerSecond) : 86_400;
+  return { remaining: 0, retryAfterSeconds: Math.max(1, Math.ceil(seconds)) };
+};
+
+/** `stored` tokens last written at `lastMs`, refilled to `nowMs` and capped — no mutation. */
+export const refilledTokens = (
+  bucket: Bucket,
+  stored: number,
+  lastMs: number,
+  nowMs: number,
+): number =>
+  Math.min(bucket.capacity, stored + (Math.max(0, nowMs - lastMs) / 1000) * bucket.refillPerSecond);

package/src/rate-limit-postgres.ts

@@ -1,26 +1,13 @@
-// The shared rate-limit store: one Postgres table, one `insert … on conflict` per take, so N
-// replicas count against one bucket. Without it `config.rateLimit.scope: 'shared'` is a
-// declaration nothing can satisfy while `docker/helm/values.yaml` runs `roles.web.replicas: 3`.
+// The shared rate-limit store: one Postgres table, one `insert … on conflict` per take and a plain
+// `select` per peek, so N replicas count against one bucket. Without it `rateLimit.scope: 'shared'`
+// is a declaration nothing can satisfy while `docker/helm/values.yaml` runs `replicas: 3`.
 // Statements are spelled out so an agent can run the exact one it saw in a log.
 
+import type { PgExecutor } from '@ultimat3/core';
 import type { RateLimitDecision, RateLimitScope, RateLimitStore } from './rate-limit';
 import { rateLimitDecision } from './rate-limit';
 import { rateLimitStoreUnavailable } from './rate-limit-errors';
-
-/**
- * The one thing this store needs from the DB layer, declared structurally rather than imported —
- * `@ultimat3/action`'s `idempotency-postgres.ts` and `@ultimat3/jobs` declare the same shape for
- * the same reason: neither package owns the other's connection. Here it is also the only option:
- * `@ultimat3/http` has no `@ultimat3/db` dependency at all, and taking one to type a single method
- * would put the whole database package in this package's install graph.
- *
- * **`Bun.sql` does not satisfy it** — `Bun.sql.query` is `undefined`; it is a tagged template whose
- * positional form is `unsafe`. What satisfies it is a client that already speaks `(text, values)`,
- * wrapped in one line — `@ultimat3/db`'s `DbClient.query({ text, values })` is the framework's own.
- */
-export interface PgExecutor {
-  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
-}
+import { rateLimitPeek, refilledTokens } from './rate-limit-peek';
 
 /**
  * Installed by the boot, not by an app migration — the same rule `SQL_IDEMPOTENCY_TABLE` follows,
@@ -93,6 +80,13 @@ returning tokens, spent
 
 export const SQL_RATE_LIMIT_RESET = 'delete from x_rate_limit where key = $1';
 
+/**
+ * `peek`: a plain read, never the upsert — it runs on every request to a required route, and a
+ * write there was a row lock and a WAL record per signed-in page. The refill is computed in JS
+ * from the row by `refilledTokens`, the memory store's own arithmetic; no row means full.
+ */
+export const SQL_RATE_LIMIT_PEEK = 'select tokens, last_ms from x_rate_limit where key = $1';
+
 /**
  * The memory store's forget rule, in SQL: a bucket back at capacity answers exactly as a missing
  * one, so dropping it changes no decision. A bucket that never refills
@@ -114,6 +108,12 @@ delete from x_rate_limit
          * refill_per_second >= capacity
 `;
 
+interface PeekRow {
+  /** `double precision` / `bigint`, which some clients hand back as strings. */
+  readonly tokens: number | string;
+  readonly last_ms: number | string;
+}
+
 interface TakeRow {
   /** `double precision`, which some clients hand back as a string. */
   readonly tokens: number | string;
@@ -184,6 +184,15 @@ export function postgresRateLimitStore(
       return rateLimitDecision(bucket, Number(row.tokens), cost, isTrue(row.spent), nowMs);
     },
 
+    async peek(key, bucket, nowMs) {
+      const row = (await exec.query<PeekRow>(SQL_RATE_LIMIT_PEEK, [key]))[0];
+      const tokens =
+        row === undefined
+          ? bucket.capacity
+          : refilledTokens(bucket, Number(row.tokens), Number(row.last_ms), Math.floor(nowMs));
+      return rateLimitPeek(bucket, tokens);
+    },
+
     async reset(key): Promise<void> {
       await exec.query(SQL_RATE_LIMIT_RESET, [key]);
     },

package/src/rate-limit-stage.ts

@@ -0,0 +1,123 @@
+// What the pipeline SPENDS, and when: the `rate-limit` stage's list of keys for a request that
+// has a caller, and the one allowance the `auth` stage spends for a request that failed to have
+// one. Split out of `stages.ts` at the size ceiling; the bucket maths stays in `rate-limit.ts`.
+
+import { actorView, type RequestContext } from './context';
+import {
+  type RateLimitConfig,
+  type RateLimitDecision,
+  type RateLimiter,
+  type RateLimitSpend,
+  rateLimitSpends,
+} from './rate-limit';
+import { rateLimited } from './rate-limit-errors';
+
+/**
+ * The namespace failed credentials are counted in. Not route-scoped, for `TENANT_SCOPE`'s reason:
+ * a per-route key would hand one address its whole allowance again on every required route.
+ */
+export const UNAUTHENTICATED_SCOPE = 'unauthenticated';
+
+/**
+ * Spends each key in order and stops at the first refusal, so a caller its own bucket already
+ * refused costs its tenant nothing. Recorded on the context BEFORE the throw, so the 429 carries
+ * `Retry-After` and the `RateLimit-*` headers rather than making the client guess.
+ */
+const spendAll = async (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  spends: readonly RateLimitSpend[],
+): Promise<void> => {
+  let answer: RateLimitDecision | undefined;
+  let refusedKey: string | undefined;
+  for (const spend of spends) {
+    const decision = await limiter.check(spend.key, spend.bucket);
+    // The bucket closest to refusing is the one the caller has to plan against: reporting
+    // `remaining: 99` off a per-actor bucket while the tenant's holds 2 is a number that tells a
+    // client it may proceed and then refuses its next call.
+    if (answer === undefined || decision.remaining < answer.remaining) answer = decision;
+    if (!decision.allowed) {
+      answer = decision;
+      refusedKey = spend.key;
+      break;
+    }
+  }
+  if (answer === undefined) return;
+  ctx.rateLimit = answer;
+  for (const [name, value] of Object.entries(limiter.headers(answer))) {
+    ctx.headers.set(name, value);
+  }
+  if (refusedKey !== undefined) throw rateLimited(refusedKey, answer.retryAfterSeconds);
+};
+
+/**
+ * The `rate-limit` stage. A LIST, and the second entry is why: the key builder used to pick ONE
+ * subject — actor > org > ip, exclusive — so an authenticated request never touched a tenant
+ * bucket and one org's 8,000 seats each ran their own allowance against one shared pool.
+ */
+export const spendRequestBuckets = async (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  config: RateLimitConfig,
+  routeName: string,
+): Promise<void> => {
+  if (!config.enabled) return;
+  const actor = actorView(ctx.actor);
+  await spendAll(
+    ctx,
+    limiter,
+    rateLimitSpends(
+      { actorId: actor?.id ?? null, orgId: actor?.orgId ?? null, ip: ctx.ip, routeName },
+      {
+        route: ctx.route?.meta.rateLimit ?? config.defaultBucket,
+        tenant: config.tenantBucket,
+      },
+    ),
+  );
+};
+
+/** The one key failed credentials are counted under: the address alone, never the route. */
+const unauthenticatedKey = (ip: string | null): string =>
+  `${UNAUTHENTICATED_SCOPE}|ip:${ip ?? 'unknown'}`;
+
+/**
+ * The `auth` stage's GATE, before `authenticate()` on a required route: an address whose failure
+ * allowance is spent is refused here, a valid credential included. Spending only on failure
+ * answered a wrong guess 429 and still served a right one, so it bounded nothing a guesser cares
+ * about — and every refused guess was still a credential-store read.
+ *
+ * READ ONLY: `RateLimitStore.peek`, never a take — this runs on every request to a required route,
+ * signed-in ones included, and a zero-cost take was a Postgres upsert on each. The refusal carries
+ * the peek's own `Retry-After` (`rateLimitPeek`). With no address there is no key
+ * worth refusing on — `ip:unknown` is everyone at once — so the gate stands aside and the failure
+ * path below still counts.
+ */
+export const refuseExhaustedAddress = async (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  config: RateLimitConfig,
+): Promise<void> => {
+  if (!config.enabled || ctx.ip === null) return;
+  const key = unauthenticatedKey(ctx.ip);
+  const peek = await limiter.peek(key, config.defaultBucket);
+  if (peek.remaining >= 1) return;
+  throw rateLimited(key, peek.retryAfterSeconds);
+};
+
+/**
+ * The `auth` stage's failure path. A request refused 401 never reaches `rate-limit`, so nothing
+ * metered it: a caller with no credential, or a wrong one, could ask the credential store about
+ * tokens without bound. Spent only on FAILURE and keyed on the address ALONE — a signed-in
+ * caller behind the same NAT spends nothing here. Once it is spent, `refuseExhaustedAddress`
+ * refuses that address on required routes, signed-in callers included, until it refills.
+ */
+export const spendUnauthenticated = (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  config: RateLimitConfig,
+): Promise<void> => {
+  if (!config.enabled) return Promise.resolve();
+  return spendAll(ctx, limiter, [
+    { key: unauthenticatedKey(ctx.ip), bucket: config.defaultBucket },
+  ]);
+};

package/src/rate-limit.ts

@@ -11,6 +11,7 @@ import {
   rateLimitScopeUnset,
   tenantBucketUnknown,
 } from './rate-limit-errors';
+import { type RateLimitPeek, rateLimitPeek, refilledTokens } from './rate-limit-peek';
 
 /**
  * Where a limiter's counters live. A store says which it provides; `RateLimitConfig` says which
@@ -36,6 +37,12 @@ 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>;
+  /**
+   * What `key` holds NOW, refill applied — READ ONLY: no write, no row, no entry created. A key
+   * never taken is full. Required, because the `auth` stage asks it on every request to a required
+   * route, and a zero-cost `take` there was a Postgres upsert on every signed-in page.
+   */
+  peek(key: string, bucket: Bucket, nowMs: number): Promise<RateLimitPeek>;
   reset(key: string): Promise<void>;
 }
 
@@ -298,6 +305,14 @@ export const memoryRateLimitStore = (
       if (buckets.size > maxKeys || nowMs - lastSweepMs >= SWEEP_EVERY_MS) sweep(nowMs);
       return Promise.resolve(decision);
     },
+    peek(key, bucket, nowMs) {
+      const state = buckets.get(key);
+      const tokens =
+        state === undefined
+          ? bucket.capacity
+          : refilledTokens(bucket, state.tokens, state.lastMs, nowMs);
+      return Promise.resolve(rateLimitPeek(bucket, tokens));
+    },
     reset(key) {
       buckets.delete(key);
       return Promise.resolve();
@@ -377,6 +392,8 @@ export interface RateLimiter {
    */
   readonly buckets?: Readonly<Record<string, Bucket>> | undefined;
   check(key: string, bucketName: string, cost?: number): Promise<RateLimitDecision>;
+  /** The store's read-only `peek`, against the named bucket. Spends nothing, writes nothing. */
+  peek(key: string, bucketName: string): Promise<RateLimitPeek>;
   headers(decision: RateLimitDecision): Record<string, string>;
   /** Throws `X_RATE_LIMITED` when the bucket is empty. */
   assert(key: string, bucketName: string, cost?: number): Promise<RateLimitDecision>;
@@ -420,6 +437,7 @@ export const createRateLimiter = (options: {
     // no other way to learn what this limiter can enforce.
     buckets: options.config.buckets,
     check,
+    peek: (key, bucketName) => store.peek(key, bucketFor(bucketName), now()),
     headers: (decision) => ({
       'ratelimit-limit': String(decision.limit),
       'ratelimit-remaining': String(decision.remaining),