@ultimat3/http 1.2.0 → 2.0.0

package/src/config.ts

@@ -1,13 +1,16 @@
 // The HTTP slice of `app.config.ts`. One resolver, so a value is either a locked
 // default or an explicit override — never "whatever the first caller passed".
-import { type CorsConfig, DEFAULT_CORS } from './cors';
+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 {
   DEFAULT_LOCALE_CONFIG,
   DEFAULT_TZ_CONFIG,
   type LocaleConfig,
   type TimeZoneConfig,
 } from './locale';
-import { DEFAULT_RATE_LIMIT, type RateLimitConfig } from './rate-limit';
+import { type RateLimitConfig, resolveRateLimitConfig } from './rate-limit';
 import { DEFAULT_SECURITY, type SecurityConfig } from './security-headers';
 
 export interface HttpConfig {
@@ -19,14 +22,46 @@ export interface HttpConfig {
   readonly buildId: string | null;
   readonly buildIdHeader: string;
   readonly dev: boolean;
-  /** Read `x-forwarded-for` / `x-forwarded-proto`. Only safe behind our own proxy. */
+  /**
+   * Where a browser that failed `auth: 'required'` is sent, or `null` to answer it with the
+   * problem document. `null` by default: guessing `/signin` sends an app that spells it `/login`
+   * to a 404, and a framework may not invent one of its app's routes.
+   */
+  readonly signInPath: string | null;
+  /**
+   * Read `x-forwarded-for` / `x-forwarded-proto`, and echo an inbound `x-request-id`. A claim
+   * about the DEPLOYMENT, so it is `false` until an app makes it — it used to default `true`,
+   * which let any direct caller choose its own request id and poison log correlation. Setting it
+   * requires `trustedProxyHops`.
+   */
   readonly trustProxy: boolean;
+  /**
+   * How many proxies APPEND to `x-forwarded-for` between the client and this process — 1 for a
+   * single ingress or ALB, 2 for a CDN in front of one. The header is read at
+   * `entries.length - hops`, never at `[0]`: the leftmost value is whatever the client typed.
+   * `0` when nothing is trusted.
+   */
+  readonly trustedProxyHops: number;
   readonly bodyLimitBytes: number;
+  /**
+   * How long one request may run before it is aborted and answered `X_TIMEOUT` (504). `0`
+   * disables it, which is a deployment saying it would rather hold a connection forever than
+   * cut one short. A caller may ask for LESS with `x-request-timeout-ms`, never for more.
+   */
+  readonly requestTimeoutMs: number;
+  /**
+   * Requests this process will hold at once before shedding with `X_OVERLOADED` (503) before any
+   * work. `0` disables it. The ceiling is not a capacity plan — it is the difference between
+   * degrading and collapsing, because past it every request queues behind the same pool and the
+   * retries multiply the load.
+   */
+  readonly maxInflight: number;
   /** How long SIGTERM waits for in-flight requests before hard-stopping. */
   readonly drainTimeoutMs: number;
   readonly locale: LocaleConfig;
   readonly tz: TimeZoneConfig;
   readonly cors: CorsConfig;
+  readonly csrf: CsrfConfig;
   readonly security: SecurityConfig;
   readonly rateLimit: RateLimitConfig;
 }
@@ -38,12 +73,17 @@ export interface HttpConfigInput {
   readonly buildId?: string | null;
   readonly buildIdHeader?: string;
   readonly dev?: boolean;
+  readonly signInPath?: string | null;
   readonly trustProxy?: boolean;
+  readonly trustedProxyHops?: number;
   readonly bodyLimitBytes?: number;
+  readonly requestTimeoutMs?: number;
+  readonly maxInflight?: number;
   readonly drainTimeoutMs?: number;
   readonly locale?: Partial<LocaleConfig>;
   readonly tz?: Partial<TimeZoneConfig>;
   readonly cors?: Partial<CorsConfig>;
+  readonly csrf?: Partial<CsrfConfig>;
   readonly security?: Partial<Omit<SecurityConfig, 'csp'>> & {
     readonly csp?: Partial<SecurityConfig['csp']>;
   };
@@ -69,7 +109,20 @@ const env = (name: string): string | undefined => {
 };
 
 export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
-  const dev = input.dev ?? env('NODE_ENV') !== 'production';
+  // `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
+  // the dev overlay and a report-only CSP. Non-throwing and `?? DEFAULT_ENVIRONMENT`, the same
+  // expression `@ultimat3/policy`'s `traceByDefault` uses: a malformed `ULTIMATE_ENV` is its own
+  // error with its own fix and must never be raised for the first time by a config default.
+  const dev = input.dev ?? (tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT) !== 'production';
+  const cors = { ...DEFAULT_CORS, ...input.cors };
+  // The one resolver is the one place a resolved combination can be judged: an override is merged
+  // over defaults the author never restated, so `origins: ['*']` alone is what reaches this.
+  assertCorsConfig(cors);
+  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();
   return {
     port: input.port ?? Number.parseInt(env('PORT') ?? '3000', 10),
     hostname: input.hostname ?? env('HOSTNAME') ?? '0.0.0.0',
@@ -77,17 +130,24 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     buildId: input.buildId ?? env('BUILD_ID') ?? null,
     buildIdHeader: input.buildIdHeader ?? 'x-ultimate-build',
     dev,
-    trustProxy: input.trustProxy ?? true,
+    signInPath: input.signInPath ?? null,
+    trustProxy,
+    trustedProxyHops: trustProxy ? Math.max(0, Math.floor(input.trustedProxyHops ?? 0)) : 0,
     bodyLimitBytes: input.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 ?? 15_000,
     locale: { ...DEFAULT_LOCALE_CONFIG, ...input.locale },
     tz: { ...DEFAULT_TZ_CONFIG, ...input.tz },
-    cors: { ...DEFAULT_CORS, ...input.cors },
+    cors,
+    csrf: { ...DEFAULT_CSRF, ...input.csrf },
     security: {
       ...DEFAULT_SECURITY,
       ...input.security,
       csp: { ...DEFAULT_SECURITY.csp, reportOnly: dev, ...input.security?.csp },
     },
-    rateLimit: { ...DEFAULT_RATE_LIMIT, ...input.rateLimit },
+    rateLimit: resolveRateLimitConfig(input.rateLimit),
   };
 };

package/src/context.ts

@@ -4,19 +4,41 @@
 import {
   type Actor,
   anonymousActor,
+  type Clock,
   type Ctx,
   isAnonymous,
+  type Logger,
+  traceId as newTraceId,
   type Role,
+  logger as rootLogger,
+  type ServiceBag,
+  systemClock,
   useContext,
   uuid,
 } from '@ultimat3/core';
+import { localeConfig } from '@ultimat3/i18n';
+import { timeConfig } from '@ultimat3/time';
 import type { HttpConfig } from './config';
+import { noRequest } from './errors';
 import type { AuthzDecision } from './hooks';
+import { readCookie } from './locale';
+import type { PeerIdentity } from './peer-identity';
 import type { RateLimitDecision } from './rate-limit';
-import type { CacheHint } from './response';
+import type { CacheHint, RedirectIntent } from './response';
 import type { Route, RouteParams } from './router';
 
-export interface RequestContext {
+/**
+ * The per-request context, and — through `asCtx` — core's `Ctx` itself. Every member `Ctx`
+ * declares is declared here and SET by `createRequestContext`, because `asCtx` used to be
+ * `as unknown as Ctx` over an object missing five of them (`clock`, `now`, `logger`, `signal`,
+ * `services`). The assertion type-checked and every reader threw at runtime: `ctx.now()` in
+ * `@ultimat3/action`'s audit trail, `useService()`, `throwIfAborted()`. The cast is gone, so
+ * a member core adds is a build error in this file until it is set. The `extends` is what makes
+ * that true rather than aspirational — and it carries `CtxServices`' index signature, which is
+ * what an app augments for `ctx.posts`; `noPropertyAccessFromIndexSignature` keeps `ctx.typo` a
+ * build error all the same.
+ */
+export interface RequestContext extends Ctx {
   /** `performance.now()` at accept time; used for the server-timing header. */
   readonly startedAt: number;
   readonly url: URL;
@@ -25,14 +47,46 @@ export interface RequestContext {
   readonly config: HttpConfig;
   readonly ip: string | null;
   readonly https: boolean;
+  /**
+   * What the mesh's proxy asserted about the peer's certificate, or `null` — for an untrusted
+   * deployment, a missing header and a chain shorter than declared alike. Never an actor:
+   * `hooks.authenticate` is the one place an identity becomes `ctx.actor`, through
+   * `verifyWorkloadToken()` -> `actorFromService()` in `@ultimat3/auth`.
+   */
+  readonly peer: PeerIdentity | null;
   /** Response headers accumulated by stages before a Response exists. */
   readonly headers: Headers;
+  /**
+   * The INBOUND headers, the request's own. Headers and not the `Request`: they are the only
+   * part of a request that is already fully read, immutable and safe to hand out. The body is
+   * not — `UltimateRequest` size-caps it, parses it by content-type and caches the result, and a
+   * raw `Request` on the context would be a second body reader past all three. Set once at
+   * construction; a context built outside a request (a job, a test) carries an empty `Headers`.
+   */
+  readonly requestHeaders: Headers;
+
+  // --- core's `Ctx`, in full. Set at construction, never by a stage: `asCtx` publishes THIS
+  // object through core's ALS, so anything absent here is `undefined` in every handler.
+  /**
+   * The build of the APP this process serves — core's meaning of the word, and what a job and a
+   * request must agree on. NOT what the client claims to be running: that is `clientBuildId`,
+   * and the two shared this name until `asCtx` was checked, which published the caller's header
+   * to every `ctx.buildId` reader in the framework.
+   */
+  readonly buildId: string;
+  readonly clock: Clock;
+  now(): Date;
+  /** Request-scoped: a child of the root logger carrying `requestId` and `traceId`. */
+  readonly logger: Logger;
+  /** Aborted when the caller goes away or the request deadline passes. See `deadline.ts`. */
+  readonly signal: AbortSignal;
+  readonly services: ServiceBag;
 
   // Mutable slots, each filled by exactly one pipeline stage. Kept mutable (and
   // documented) rather than rebuilt per stage so a stage list stays a flat array.
-  /** Set by the `request-id` stage; seeded so a crash before it still correlates. */
+  /** Resolved from the inbound headers before the context exists (`correlation.ts`). */
   requestId: string;
-  /** Set by the `trace` stage from an inbound `traceparent`, if any. */
+  /** W3C trace id, continued from an inbound `traceparent` — 32 hex, never a UUID. */
   traceId: string;
   parentSpanId: string | null;
   params: RouteParams;
@@ -45,11 +99,20 @@ export interface RequestContext {
   actor: Actor;
   locale: string;
   tz: string;
-  buildId: string | null;
+  /** What the CLIENT says it is running, from `config.buildIdHeader`. `assertBuild()` reads it. */
+  clientBuildId: string | null;
   input: unknown;
   authz: AuthzDecision | undefined;
   rateLimit: RateLimitDecision | undefined;
   cache: CacheHint | undefined;
+  /**
+   * The one slot app code fills rather than a stage: `setRedirect()` records that this call
+   * should answer with a `Location` instead of its return value, and the route projection that
+   * generated the handler reads it back with `takeRedirect()`. An action has no way to return a
+   * `Response` — its return value is its output schema — so a side channel is the only place
+   * "answer 303" can live without a second return protocol.
+   */
+  redirect: RedirectIntent | undefined;
   response: Response | undefined;
   error: unknown;
 }
@@ -61,45 +124,133 @@ export interface RequestContextInit {
   readonly config: HttpConfig;
   readonly requestId?: string;
   readonly traceId?: string;
+  /** The caller's span id, from an inbound `traceparent`. Resolved before this call. */
+  readonly parentSpanId?: string | null;
   readonly ip?: string | null;
   readonly https?: boolean;
+  readonly peer?: PeerIdentity | null;
+  /** The inbound headers. Absent means "not an HTTP request" and reads as empty. */
+  readonly requestHeaders?: HeadersInit;
+  readonly clock?: Clock;
+  readonly logger?: Logger;
+  /** The deadline/disconnect signal. Absent means a request nothing can cancel. */
+  readonly signal?: AbortSignal;
+  readonly services?: ServiceBag;
 }
 
-export const createRequestContext = (init: RequestContextInit): RequestContext => ({
-  requestId: init.requestId ?? uuid(),
-  traceId: init.traceId ?? uuid(),
-  startedAt: performance.now(),
-  url: init.url,
-  method: init.method.toUpperCase(),
-  role: init.role,
-  config: init.config,
-  ip: init.ip ?? null,
-  https: init.https ?? init.url.protocol === 'https:',
-  headers: new Headers(),
-  parentSpanId: null,
-  params: {},
-  route: undefined,
-  actor: anonymousActor(),
-  locale: init.config.locale.default,
-  tz: init.config.tz.default,
-  buildId: null,
-  input: undefined,
-  authz: undefined,
-  rateLimit: undefined,
-  cache: undefined,
-  response: undefined,
-  error: undefined,
-});
+/**
+ * One signal for every context built without one, so "no cancellation here" costs no allocation
+ * and `ctx.signal.aborted` is still a read rather than a `TypeError`. The same shape core uses.
+ */
+const NEVER_ABORTED: AbortSignal = new AbortController().signal;
+
+export const createRequestContext = (init: RequestContextInit): RequestContext => {
+  const clock = init.clock ?? systemClock;
+  const requestId = init.requestId ?? uuid(clock);
+  // core's `traceId()`, never `uuid()`: a dashed UUIDv7 is not a 32-hex W3C trace id, and a
+  // collector rejects the span that carries one — while the log lines beside it, which quote the
+  // same field, look fine. Two ids for one request that cannot be joined.
+  const traceId = init.traceId ?? newTraceId();
+  return {
+    requestId,
+    traceId,
+    parentSpanId: init.parentSpanId ?? null,
+    startedAt: performance.now(),
+    url: init.url,
+    method: init.method.toUpperCase(),
+    role: init.role,
+    config: init.config,
+    ip: init.ip ?? null,
+    https: init.https ?? init.url.protocol === 'https:',
+    peer: init.peer ?? null,
+    headers: new Headers(),
+    requestHeaders: new Headers(init.requestHeaders),
+    // The build this PROCESS serves, resolved the way core resolves it. The client's claim goes
+    // to `clientBuildId` below, where only `assertBuild()` reads it.
+    buildId: init.config.buildId ?? 'dev',
+    clock,
+    now: () => clock.now(),
+    // A child, so `ctx.logger` carries the ids even where core's ALS injector cannot see the
+    // context — a callback that outlived the request scope, a logger passed to a driver.
+    logger: (init.logger ?? rootLogger).child({ requestId, traceId }),
+    signal: init.signal ?? NEVER_ABORTED,
+    // Frozen and explicit. `defineService` factories are NOT installed here: core does not
+    // export the installer, so the honest answer for a service nothing passed is
+    // `X_SERVICE_MISSING` from `useService()` — which is what it exists to raise — rather than
+    // the `TypeError: undefined is not an object` a missing bag produced.
+    services: Object.freeze({ ...(init.services ?? {}) }),
+    params: {},
+    route: undefined,
+    actor: anonymousActor(),
+    // What the request gets before the `locale` stage runs, and what it keeps if the stage is
+    // never reached (a refusal in `admit`). The owners' configured fallbacks, never a third one.
+    locale: localeConfig().fallback,
+    tz: timeConfig().defaultZone,
+    clientBuildId: null,
+    input: undefined,
+    authz: undefined,
+    rateLimit: undefined,
+    cache: undefined,
+    redirect: undefined,
+    response: undefined,
+    error: undefined,
+  };
+};
 
 /**
- * `Ctx` is owned by `@ultimat3/core` and grows service handles by module
- * augmentation. This is the single adapter between the HTTP request context and
- * core's ALS payload, so a change to `Ctx` touches one line of this package.
+ * The single adapter between the HTTP request context and core's ALS payload. It is a WIDENING
+ * the compiler checks, not an assertion: `as unknown as Ctx` here shipped a context missing
+ * `clock`, `now`, `logger`, `signal` and `services`, so `ctx.now()` threw on every audited
+ * action served over HTTP. Never reintroduce a cast — the type error IS the enforcement.
  */
-export const asCtx = (ctx: RequestContext): Ctx => ctx as unknown as Ctx;
+export const asCtx = (ctx: RequestContext): Ctx => ctx;
+
+/**
+ * The ambient `Ctx`, WIDENED to the request shape and not yet proven to be one. Private for that
+ * reason: every export below runs it through `assertInRequest` first. The cast is the inverse of
+ * `asCtx` and the only one in this file that cannot be a checked widening — core's `Ctx` genuinely
+ * does not carry `requestHeaders`, which is precisely what makes the proof necessary.
+ */
+const ambientContext = (): RequestContext => useContext() as unknown as RequestContext;
+
+/**
+ * The ambient context, proven to be an HTTP request's rather than a job's or a task's.
+ * `requestHeaders` is the discriminator because it is the one field only the pipeline sets, and
+ * core's `Ctx` is frozen — so without this a write to a request-only slot is a bare
+ * `TypeError: object is not extensible`, which is not an instruction. Not exported from the
+ * package: callers want a header, a cookie or a redirect, never the proof.
+ */
+export const assertInRequest = (member: string, ctx = ambientContext()): RequestContext => {
+  if ((ctx.requestHeaders as Headers | undefined) === undefined) throw noRequest(member);
+  return ctx;
+};
+
+/**
+ * Read the ambient request context. Throws outside a request via core's ALS — and, since a job, a
+ * task, a scheduler round and a CLI command all supply an ordinary `Ctx`, throws `X_NO_REQUEST`
+ * there too rather than handing back an object whose non-optional fields are `undefined`. That is
+ * what it used to do, so the first read (`ctx.requestHeaders.get(...)`) was a bare `TypeError`
+ * from a public API. `member` names what the caller was after, so the refusal instructs.
+ */
+export const useRequestContext = (member = 'the request context'): RequestContext =>
+  assertInRequest(member, ambientContext());
+
+/**
+ * The inbound headers of the request in scope. `use*` because it reads core's ALS, like
+ * `useContext` and `useService` — an action handler and a page get a `Ctx`, never the
+ * `UltimateRequest`, so an ambient reader is the only seam that reaches them both.
+ *
+ * Throws rather than answering `null` off a job's context: "there is no request here" and
+ * "the caller sent no such header" are different facts, and folding them into one is how a
+ * job silently authenticates as nobody.
+ */
+export const useRequestHeaders = (): Headers => assertInRequest('request headers').requestHeaders;
+
+export const useRequestHeader = (name: string): string | null => useRequestHeaders().get(name);
 
-/** Read the ambient request context. Throws outside a request via core's ALS. */
-export const useRequestContext = (): RequestContext => useContext() as unknown as RequestContext;
+/** The one way app code reads a cookie the browser sent — a session cookie included. */
+export const useRequestCookie = (name: string): string | null =>
+  readCookie(useRequestHeaders().get('cookie'), name);
 
 export const elapsedMs = (ctx: RequestContext): number =>
   Math.round((performance.now() - ctx.startedAt) * 100) / 100;

package/src/correlation.ts

@@ -0,0 +1,44 @@
+// The two ids a caller may bring, read from the raw headers BEFORE the context or the root span
+// exists. Both used to be parsed by a stage that ran one frame after `withSpan` had already
+// frozen the span's context: the caller's trace was discarded, the root span carried a fresh
+// UUIDv7 no collector accepts as a trace id, and the log lines quoted a third value.
+
+import { traceId as newTraceId, parseTraceparent, type SpanContext, uuid } from '@ultimat3/core';
+import type { HttpConfig } from './config';
+
+/**
+ * What an inbound `x-request-id` must look like to be echoed. A caller choosing this value
+ * chooses a key in the log store, so it is bounded and boring on purpose — and only read at all
+ * when `trustProxy` says a proxy in front of us is what writes it.
+ */
+const REQUEST_ID = /^[\w.:-]{8,128}$/;
+
+export interface InboundCorrelation {
+  readonly requestId: string;
+  /** W3C trace id: the caller's when it sent one, otherwise a fresh 32-hex id. */
+  readonly traceId: string;
+  readonly parentSpanId: string | null;
+  /**
+   * The caller's span, to hand to `withSpan({ parent })`. `undefined` starts a new trace —
+   * `startSpan` must not fall back to `currentSpanContext()` for a request, because that reads
+   * the context's own `traceId` and produces a root span with no parent and a made-up trace.
+   */
+  readonly parent: SpanContext | undefined;
+}
+
+/**
+ * Read once per request, before `runWithContext`. `parseTraceparent` is core's — one regex for
+ * the wire format, in the package that also writes it (`traceparent()`), so an outbound header
+ * and an inbound one cannot drift.
+ */
+export const readCorrelation = (headers: Headers, config: HttpConfig): InboundCorrelation => {
+  const inboundId = config.trustProxy ? headers.get('x-request-id') : null;
+  const requestId = inboundId !== null && REQUEST_ID.test(inboundId) ? inboundId : uuid();
+  const parent = parseTraceparent(headers.get('traceparent'));
+  return {
+    requestId,
+    traceId: parent?.traceId ?? newTraceId(),
+    parentSpanId: parent?.spanId ?? null,
+    parent,
+  };
+};

package/src/cors.ts

@@ -1,6 +1,8 @@
 // CORS with a locked default: same-origin only. Cross-origin access is a decision
 // the app makes in app.config.ts, never something a route can quietly opt into.
 
+import { corsConfigInvalid } from './errors';
+
 export interface CorsConfig {
   /** Exact origins. `'*'` is allowed only when `credentials` is false. */
   readonly origins: readonly string[];
@@ -20,19 +22,45 @@ export const DEFAULT_CORS: CorsConfig = {
   maxAgeSeconds: 600,
 };
 
-const allowedOrigin = (config: CorsConfig, origin: string | null): string | null => {
+/**
+ * The one combination the browser refuses — `*` with credentials — refused HERE instead, at the
+ * one moment an author can act on it. It used to resolve to "no CORS headers at all": the natural
+ * "open it up" edit produced total, silent CORS failure and a console full of unexplained blocks,
+ * with `DEFAULT_CORS.credentials` (true) as the half nobody thinks to look at.
+ */
+export const assertCorsConfig = (config: CorsConfig): void => {
+  if (config.origins.includes('*') && config.credentials) {
+    throw corsConfigInvalid(
+      "origins includes '*' while credentials is true — no browser accepts that pair",
+    );
+  }
+};
+
+/**
+ * The one answer to "may this origin talk to us?". Exported for `csrf.ts`, which asks the same
+ * question about a *request* rather than a response — a second list of allowed origins would be
+ * a CORS policy and a CSRF policy that quietly disagree.
+ */
+export const allowedOrigin = (config: CorsConfig, origin: string | null): string | null => {
   if (origin === null) return null;
   if (config.origins.includes('*')) return config.credentials ? null : '*';
   return config.origins.includes(origin) ? origin : null;
 };
 
-/** Headers to merge into every response, preflight or not. */
+/**
+ * Headers to merge into every response, preflight or not.
+ *
+ * A refused origin still gets `vary: origin`, which is the header that keeps the answer *out* of a
+ * shared cache's un-keyed slot: without it a CDN stores the un-CORS'd body under the URL alone and
+ * hands it to an allowed origin next, whose fetch then fails for a reason nothing in that request
+ * explains.
+ */
 export const corsHeaders = (config: CorsConfig, origin: string | null): Record<string, string> => {
   const allow = allowedOrigin(config, origin);
-  if (allow === null) return {};
+  // Caches must not serve one origin's response to another — refusal included.
+  if (allow === null) return { vary: 'origin' };
   const headers: Record<string, string> = {
     'access-control-allow-origin': allow,
-    // Caches must not serve one origin's response to another.
     vary: 'origin',
   };
   if (config.credentials) headers['access-control-allow-credentials'] = 'true';
@@ -52,7 +80,7 @@ export const preflight = (request: Request, config: CorsConfig): Response | unde
   if (requested === null) return undefined;
   const origin = request.headers.get('origin');
   const allow = allowedOrigin(config, origin);
-  if (allow === null) return new Response(null, { status: 403 });
+  if (allow === null) return new Response(null, { status: 403, headers: { vary: 'origin' } });
   const headers = new Headers(corsHeaders(config, origin));
   headers.set('access-control-allow-methods', config.methods.join(', '));
   headers.set('access-control-allow-headers', config.allowHeaders.join(', '));

package/src/csrf.ts

@@ -0,0 +1,85 @@
+// Whether an unsafe request carrying an AMBIENT credential came from somewhere allowed to make
+// it. CORS does not answer this: `application/x-www-form-urlencoded` is a CORS-simple content
+// type, so `<form method="post">` on evil.test is SENT and EXECUTED with the session cookie
+// attached — `cors.origins: []` only stops the attacker reading the reply, long after the refund
+// went through. `setRedirect` exists so those form posts work without JS, which makes them a
+// first-class surface here rather than a legacy one.
+
+import type { CorsConfig } from './cors';
+import { allowedOrigin } from './cors';
+
+export type CsrfMode = 'origin' | 'off';
+
+export interface CsrfConfig {
+  /**
+   * `'origin'` — an unsafe method from a credentialed browser must prove same-origin, through
+   * `sec-fetch-site` or an `Origin` the app already allows. Costs a client nothing.
+   * `'off'` — for an API with no cookie session at all; say so, do not discover it.
+   */
+  readonly mode: CsrfMode;
+}
+
+export const DEFAULT_CSRF: CsrfConfig = { mode: 'origin' };
+
+/** Methods with no side effects, per RFC 9110. A CSRF check on these is a check on nothing. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+
+/** The complete `Sec-Fetch-Site` vocabulary. Anything else was written by a non-browser. */
+const KNOWN_SITES = new Set(['same-origin', 'same-site', 'cross-site', 'none']);
+
+export interface CsrfCheckInput {
+  readonly method: string;
+  /** The origin this app was reached on — scheme from `ctx.https`, host from the request URL. */
+  readonly selfOrigin: string;
+  readonly origin: string | null;
+  readonly secFetchSite: string | null;
+  /** A bearer token is not ambient: a cross-site page cannot make the browser attach one. */
+  readonly hasAuthorizationHeader: boolean;
+  /** Anonymous callers have no credential to ride, so nothing to forge. */
+  readonly anonymous: boolean;
+  readonly cors: CorsConfig;
+  readonly config: CsrfConfig;
+}
+
+export type CsrfVerdict =
+  | { readonly ok: true }
+  /** Why it was refused, in terms the caller can act on. Never echoes a header verbatim. */
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * `sec-fetch-site` first because it is the browser's own answer and cannot be set by script;
+ * `Origin` second, so an app that lists a sibling origin in `cors.origins` keeps working. A
+ * request with neither — a non-browser client with a cookie, or a browser too old to send
+ * either — is refused: "we could not tell" is the case this exists for.
+ */
+export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
+  if (input.config.mode === 'off') return { ok: true };
+  if (SAFE_METHODS.has(input.method)) return { ok: true };
+  if (input.anonymous) return { ok: true };
+  if (input.hasAuthorizationHeader) return { ok: true };
+
+  const site = input.secFetchSite;
+  if (site === 'same-origin' || site === 'none') return { ok: true };
+  if (input.origin === input.selfOrigin) return { ok: true };
+  if (input.origin !== null && allowedOrigin(input.cors, input.origin) !== null) {
+    return { ok: true };
+  }
+  // Only the four values a browser can send are quoted back. Anything else is a client that
+  // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
+  // store and the response body — the same defect the error-map stage's log line had.
+  if (site !== null) {
+    const known = KNOWN_SITES.has(site) ? site : 'a value no browser sends';
+    return { ok: false, reason: `the request reported sec-fetch-site: ${known}` };
+  }
+  return {
+    ok: false,
+    reason:
+      input.origin === null
+        ? 'the request carried neither sec-fetch-site nor origin, so it cannot be shown to be same-origin'
+        : 'the origin it declares is not this app and is not listed in http.cors.origins',
+  };
+};
+
+/** The origin a browser compares against — the PUBLIC one, so a TLS-terminating proxy agrees. */
+export const selfOrigin = (url: URL, https: boolean): string =>
+  `${https ? 'https' : 'http'}://${url.host}`;