@ultimat3/http 23.0.0 → 25.0.0

package/src/auth-redirect.ts

@@ -41,33 +41,48 @@ export function signInRedirect(input: {
 /**
  * The other half of the round trip: where to send someone once they HAVE signed in.
  *
+ * `raw` is the value a query or form parser already decoded ONCE — `props.query.next`, an action's
+ * `next` input, `url.searchParams.get('next')` — so it is screened as it arrived and never
+ * decoded again. A second decode changed the destination: `signInRedirect` carried
+ * `/search?q=a%26b`, the parser handed back exactly that, and decoding it again landed on
+ * `?q=a&b`, a different query; `?label=100%25done` threw and fell back. Normalising (below) removes
+ * dot segments only; it never decodes, so `%26` is still `%26`.
+ *
  * Everything except a same-origin path is refused and `fallback` is used instead. `?next=`
  * arrives from the URL bar, so it is attacker-controlled by definition — an unchecked value here
  * is an open redirect on a page whose entire job is to hold a session, which is the exact shape
  * phishing wants: a real domain, a real login, a hop to somewhere else.
  *
  * Refused: an absolute URL (`https://evil.test/x`), a scheme-relative one (`//evil.test`), a
- * backslash the browser normalises to a slash (`/\evil.test`), a value carrying a TAB, CR or LF,
- * and anything not starting `/`.
+ * backslash the browser normalises to a slash (`/\evil.test`), a value carrying any control
+ * character, and anything not starting `/`. A percent-encoded `%2F%2F`, `%5C` or `%09` is NOT
+ * refused, because it is not decoded: a browser resolves a `Location` without decoding it, so
+ * each is an ordinary path segment on this origin — and the final parse below proves it.
  *
  * The control characters are not cosmetic. A browser DELETES tab, CR and LF from a `Location`
- * before it parses one, so `/%09/evil.test` decodes to `/\t/evil.test` — which starts with a
- * single slash, passes a prefix check, and is then parsed as `//evil.test`. The URL parser
- * strips them the same way, which is why the last word here is the parse: whatever a client
- * would actually resolve has to still be a path on this origin.
+ * before it parses one, so `/\t/evil.test` — which starts with a single slash and passes a prefix
+ * check — is parsed as `//evil.test`. NUL, ESC and DEL are not stripped, they are refused by
+ * `Headers`, which is a 500 on the sign-in page. The URL parser strips the first three the same way
+ * a browser does, which is why the last word here is the parse: whatever a client would actually
+ * resolve has to still be a path on this origin.
+ *
+ * The answer is the RESOLVED path, query and fragment — dot segments removed, never the raw
+ * string: a value checked by its resolution and returned unresolved let `/.//evil.test` pass as
+ * same-origin and reach the client router as `//evil.test`. A resolved pathname starting `//` is
+ * refused outright.
+ *
+ * Before the parse, a code point above U+007F is percent-encoded as UTF-8. The parser hands `/日本`
+ * over decoded, `Headers` refuses anything above U+00FF, and a Latin-1 byte in a `Location` is read
+ * as UTF-8 by the browser — so the raw form is not a destination any client can follow. A lone
+ * surrogate has no UTF-8 encoding and falls back.
  */
 export function nextAfterSignIn(raw: string | null | undefined, fallback: string): string {
   if (raw === null || raw === undefined || raw === '') return fallback;
-  // `?next=%` is a bare `URIError`, and this runs while the pipeline is already rendering a 401.
-  let value: string;
-  try {
-    value = decodeURIComponent(raw);
-  } catch {
-    return fallback;
-  }
-  if (!value.startsWith('/')) return fallback;
-  if (value.startsWith('//') || value.startsWith('/\\')) return fallback;
-  if (/[\t\r\n]/.test(value)) return fallback;
+  if (!raw.startsWith('/')) return fallback;
+  if (raw.startsWith('//') || raw.startsWith('/\\')) return fallback;
+  if (hasControlCharacter(raw)) return fallback;
+  const value = encodeNonAscii(raw);
+  if (value === undefined) return fallback;
   // An origin no relative path could reach, so any value that resolves off it left this origin.
   const base = 'http://x.invalid';
   let resolved: URL;
@@ -77,5 +92,29 @@ export function nextAfterSignIn(raw: string | null | undefined, fallback: string
     return fallback;
   }
   if (resolved.origin !== base) return fallback;
-  return value;
+  // Dot segments can hide a `//`: `/.//evil.test` resolves on this origin with the pathname
+  // `//evil.test`, which is another host the moment anything re-reads it without the base.
+  if (resolved.pathname.startsWith('//')) return fallback;
+  // The CHECKED string is the returned one. Returning `value` after checking its resolution let
+  // the two differ, and the router re-resolved the difference off-site.
+  return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+
+/** C0 controls and DEL — the bytes a browser strips from a `Location` or a header refuses. */
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/** Every run outside printable ASCII as UTF-8 percent-encoding, or `undefined` for a lone surrogate. */
+function encodeNonAscii(value: string): string | undefined {
+  try {
+    // Controls are already refused, so everything this class matches is above U+007E.
+    return value.replace(/[^ -~]+/g, (run) => encodeURI(run));
+  } catch {
+    return undefined;
+  }
 }

package/src/bearer-mount.ts

@@ -13,8 +13,12 @@ import { bearerMountInvalid, routeNotFound } from './errors';
 import type { RateLimitDecision, RateLimitStore } from './rate-limit';
 import { memoryRateLimitStore, toBucket } from './rate-limit';
 import { rateLimited } from './rate-limit-errors';
+import { rateLimitHeaders } from './rate-limit-headers';
 import type { UltimateRequest } from './request';
+import type { RequestFacts } from './request-facts';
+import { requestFacts } from './request-facts';
 import type { Route, RouteMeta } from './router';
+import { HTTP_METHODS } from './router';
 
 /**
  * What a token resolves to. Structurally `@ultimat3/mcp`'s `ResolvedToken`, so an app hands the
@@ -26,8 +30,16 @@ export interface BearerCaller {
   readonly scopes: ReadonlySet<string>;
 }
 
-/** `null` for a malformed, unknown, revoked or expired token — all one indistinguishable 401. */
-export type BearerResolver = (token: string) => Promise<BearerCaller | null> | BearerCaller | null;
+/**
+ * `null` for a malformed, unknown, revoked or expired token — all one indistinguishable 401.
+ * `facts` is how the request arrived (`RequestFacts`: the pipeline's address, user agent, `Origin`,
+ * path) — the same shape `@ultimat3/mcp` hands its resolver, so one resolver serves both. A
+ * one-argument resolver is still one.
+ */
+export type BearerResolver = (
+  token: string,
+  facts: RequestFacts,
+) => Promise<BearerCaller | null> | BearerCaller | null;
 
 export interface BearerMountRateLimit {
   readonly limit: number;
@@ -86,6 +98,9 @@ const tokenKey = (token: string): string =>
  * The mounted routes. Refuses at construction (`X_BEARER_MOUNT_INVALID`) a prefix that is not a
  * plain path or would shadow `/api` / `/_x`, a scope naming a primitive no route carries, and two
  * primitives that would land on one mounted path.
+ *
+ * The last routes returned are the prefix's catch-all (`<prefix>/*rest`, every method), so no
+ * path under the prefix answers differently for being served: see `opaquePrefix`.
  */
 export function bearerMount(input: BearerMountInput): readonly Route[] {
   const { prefix } = input;
@@ -134,20 +149,38 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
   // concurrent requests could share.
   const callers = new WeakMap<RequestContext, { caller: BearerCaller; key: string }>();
 
-  const authenticate: NonNullable<RouteMeta['authenticate']> = async (request, ctx) => {
-    const token = bearerTokenOf(request.header('authorization'));
-    if (token === null) {
-      ctx.headers.set('www-authenticate', 'Bearer');
-      return null;
-    }
-    const caller = await input.resolveToken(token);
-    if (caller === null) {
-      ctx.headers.set('www-authenticate', 'Bearer error="invalid_token"');
-      return null;
-    }
-    callers.set(ctx, { caller, key: tokenKey(token) });
-    return caller.actor;
-  };
+  // One authenticator per mounted route, closed over ITS scope, so the cut is decided in the `auth`
+  // stage — before `body` and `authz`. Decided in the handler, an out-of-scope token was answered
+  // 422 with the schema's issues or 403 with the policy's reason, both confirming the primitive.
+  // `null` is the catch-all's: a scope no token holds, so a valid token is told 404 exactly where
+  // an out-of-scope one is, and a missing or bad one gets the same challenge as on a served path.
+  const authenticatorOf =
+    (scope: string | null): NonNullable<RouteMeta['authenticate']> =>
+    async (request, ctx) => {
+      const token = bearerTokenOf(request.header('authorization'));
+      if (token === null) {
+        ctx.headers.set('www-authenticate', 'Bearer');
+        return null;
+      }
+      // `ctx.ip` is the pipeline's trusted-hop answer — the facts never read a forwarding header.
+      const facts = requestFacts({ headers: request.raw.headers, url: ctx.url, address: ctx.ip });
+      const caller = await input.resolveToken(token, facts);
+      if (caller === null) {
+        ctx.headers.set('www-authenticate', 'Bearer error="invalid_token"');
+        return null;
+      }
+      // Hidden, never forbidden: a 403 would confirm the primitive exists to a token that was
+      // not issued for it — the enumeration MCP's catalog refuses the same way.
+      // And never free: the refusal spends the token's allowance as a served call does (which the
+      // handler charges, once, so the two paths never both spend) — else a token walks the cut
+      // unmetered, and `RateLimit-*` on one 404 but not another tells hidden from unknown.
+      if (scope === null || !caller.scopes.has(scope)) {
+        await spend(tokenKey(token), ctx);
+        throw routeNotFound(ctx.method, ctx.url.pathname);
+      }
+      callers.set(ctx, { caller, key: tokenKey(token) });
+      return caller.actor;
+    };
 
   const spend = async (key: string, ctx: RequestContext): Promise<void> => {
     if (bucket === undefined) return;
@@ -157,12 +190,9 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       1,
       clock.now().getTime(),
     );
-    ctx.headers.set('ratelimit-limit', String(decision.limit));
-    ctx.headers.set('ratelimit-remaining', String(decision.remaining));
-    ctx.headers.set(
-      'ratelimit-reset',
-      String(Math.max(0, Math.ceil((decision.resetAtMs - clock.now().getTime()) / 1000))),
-    );
+    for (const [name, value] of Object.entries(rateLimitHeaders(decision, clock.now().getTime()))) {
+      ctx.headers.set(name, value);
+    }
     // `rateLimited` carries the seconds in `meta`, which the error-map stage turns into
     // `Retry-After` — the same 429 every other limit in the framework answers.
     if (!decision.allowed) throw rateLimited(`${prefix}|token`, decision.retryAfterSeconds);
@@ -182,11 +212,11 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       mounted.push({
         method: route.method,
         path,
-        meta: { ...route.meta, auth: 'required', authenticate },
+        meta: { ...route.meta, auth: 'required', authenticate: authenticatorOf(scope) },
         handler: async (request: UltimateRequest, ctx: RequestContext) => {
           const resolved = callers.get(ctx);
-          // Hidden, never forbidden: a 403 would confirm the primitive exists to a token that
-          // was not issued for it — the enumeration MCP's catalog refuses the same way.
+          // The authenticator already answered an out-of-scope token; this is the fail-closed
+          // floor for a handler driven without the `auth` stage.
           if (resolved === undefined || !resolved.caller.scopes.has(scope)) {
             throw routeNotFound(ctx.method, ctx.url.pathname);
           }
@@ -196,5 +226,30 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       });
     }
   }
-  return mounted;
+  return [...mounted, ...opaquePrefix(prefix, authenticatorOf(null))];
 }
+
+/** Every method a client can send. HEAD is GET's (`router.ts`'s `routeFor`), never its own route. */
+const CATCH_ALL_METHODS = HTTP_METHODS.filter((method) => method !== 'HEAD');
+
+/**
+ * `<prefix>/*rest` for every method, behind the mount's own authenticator. Without it a request
+ * with no token answered 401 on a served path and 404 — or 405 naming the served methods — on
+ * every other, so an anonymous walk of the prefix listed the cut. 401 with the `Bearer` challenge
+ * is the uniform answer because it is the TRUE one for a real client anywhere under the prefix:
+ * nothing there is reachable without a token. A static or param route still outranks a wildcard,
+ * so the mounted routes, and any route the app serves under the prefix itself, keep answering.
+ */
+const opaquePrefix = (
+  prefix: string,
+  authenticate: NonNullable<RouteMeta['authenticate']>,
+): readonly Route[] =>
+  CATCH_ALL_METHODS.map((method) => ({
+    method,
+    path: `${prefix}/*rest`,
+    meta: { name: `bearer-mount:${prefix}`, auth: 'required', authenticate },
+    // Reached only if the authenticator did not run: fail closed, with the miss it stands for.
+    handler: (_request: UltimateRequest, ctx: RequestContext) => {
+      throw routeNotFound(ctx.method, ctx.url.pathname);
+    },
+  }));

package/src/cache-policy.ts

@@ -16,14 +16,22 @@ export const PRIVATE_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
 // for every signed-in user.
 const OFFERS_SHARED = /(?:^|,)\s*(?:public\b|s-maxage=)/i;
 const IMMUTABLE = /(?:^|,)\s*immutable\b/i;
+// RFC 9111 §3: a shared cache may store a response to a request without `Authorization` — which
+// is every cookie session — as soon as it carries explicit freshness or a revalidation rule. So
+// `max-age=3600` alone is an offer too, unless the same header withholds it.
+const STATES_FRESHNESS = /(?:^|,)\s*(?:max-age=|must-revalidate\b|proxy-revalidate\b)/i;
+const WITHHOLDS = /(?:^|,)\s*(?:private\b|no-store\b)/i;
 
 /**
  * Whether a `cache-control` a HANDLER wrote offers the response to a shared cache. A render mode
  * states the MODE's intent — `ssr` offers an ungated page to a CDN for 30 seconds — and the actor
  * is the half it cannot see, so the stage reviews the declaration rather than deferring to it.
  */
-export const offersSharedCache = (declared: string): boolean =>
-  OFFERS_SHARED.test(declared) && !IMMUTABLE.test(declared);
+export const offersSharedCache = (declared: string): boolean => {
+  if (IMMUTABLE.test(declared)) return false;
+  if (OFFERS_SHARED.test(declared)) return true;
+  return STATES_FRESHNESS.test(declared) && !WITHHOLDS.test(declared);
+};
 
 /**
  * Authenticated responses are never shared-cacheable; that default is not overridable.

package/src/config.ts

@@ -3,10 +3,20 @@
 // `app.config.ts`, which this file claimed for four majors while `AppConfig` has never carried an
 // `http` key: an app declares its half through `configureHttp()` (`app-config.ts`) and the boot
 // lays its own facts over it before calling this.
-import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import {
+  DEFAULT_ENVIRONMENT,
+  DEFAULT_HEALTH_DETAIL_PEERS,
+  tryResolveEnvironment,
+} from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';
-import { httpCountInvalid, trustProxyUnset } from './errors';
+import {
+  buildIdHeaderDeleted,
+  drainTimeoutDeleted,
+  httpCountInvalid,
+  trustProxyUnset,
+} from './errors';
+import { assertHealthDetailPeers } from './health-disclosure';
 import {
   DEFAULT_LOCALE_CONFIG,
   DEFAULT_TZ_CONFIG,
@@ -23,7 +33,6 @@ export interface HttpConfig {
   readonly basePath: string;
   /** Build id this process serves; `null` disables skew detection (dev). */
   readonly buildId: string | null;
-  readonly buildIdHeader: string;
   readonly dev: boolean;
   /**
    * Where a browser that failed `auth: 'required'` is sent, or `null` to answer it with the
@@ -45,6 +54,20 @@ export interface HttpConfig {
    * `0` when nothing is trusted.
    */
   readonly trustedProxyHops: number;
+  /**
+   * Read Envoy's `x-forwarded-client-cert` into `ctx.peer`. Its OWN declaration, `false` until an
+   * app makes it: `trustProxy` says the proxy appends to `x-forwarded-for`, which is no promise
+   * that it strips or overwrites a certificate header the client sent — and this one names an
+   * identity. Read at `trustedProxyHops`, so it does nothing without `trustProxy`.
+   */
+  readonly trustClientCertHeader: boolean;
+  /**
+   * Who `/healthz` and `/readyz` tell more than the verdict: each entry an address class
+   * (`'loopback'`, `'private'`, …) or one exact address. Everyone else gets `state`, `ready` and
+   * `role` — the endpoints answer outside the pipeline, so the build id, the in-flight count and
+   * the readiness check names were otherwise any stranger's to read. `[]` tells nobody.
+   */
+  readonly healthDetailPeers: readonly string[];
   readonly bodyLimitBytes: number;
   /**
    * How long one request may run before it is aborted and answered `X_TIMEOUT` (504). `0`
@@ -59,18 +82,6 @@ export interface HttpConfig {
    * retries multiply the load.
    */
   readonly maxInflight: number;
-  /**
-   * How long SIGTERM waits for in-flight requests before hard-stopping, or `null` when this app
-   * has not said and core's own deadline stands.
-   *
-   * `null` and not a 15s default, because the two are different claims and only one of them may
-   * reach `configureLifecycle`. `createServer` applied the resolved number unconditionally, so an
-   * app that had already written `configureLifecycle({ deadlineMs: 600_000 })` — the edit
-   * `X_SHUTDOWN_TIMEOUT`'s own `fix:` line prints — had it silently reverted by the next line of
-   * boot, in every process that serves web. Declaring this key IS declaring the drain budget for
-   * the whole process; leaving it out is declining to.
-   */
-  readonly drainTimeoutMs: number | null;
   readonly locale: LocaleConfig;
   readonly tz: TimeZoneConfig;
   readonly cors: CorsConfig;
@@ -84,15 +95,15 @@ export interface HttpConfigInput {
   readonly hostname?: string;
   readonly basePath?: string;
   readonly buildId?: string | null;
-  readonly buildIdHeader?: string;
   readonly dev?: boolean;
   readonly signInPath?: string | null;
   readonly trustProxy?: boolean;
   readonly trustedProxyHops?: number;
+  readonly trustClientCertHeader?: boolean;
+  readonly healthDetailPeers?: readonly string[];
   readonly bodyLimitBytes?: number;
   readonly requestTimeoutMs?: number;
   readonly maxInflight?: number;
-  readonly drainTimeoutMs?: number;
   readonly locale?: Partial<LocaleConfig>;
   readonly tz?: Partial<TimeZoneConfig>;
   readonly cors?: Partial<CorsConfig>;
@@ -170,6 +181,13 @@ const assertFiniteCount = (
 
 const MAX_PORT = 65_535;
 
+/**
+ * The longest delay a timer holds: a signed 32-bit count of milliseconds, about 24.8 days. Past
+ * it `setTimeout` arms ~1 ms, so a "longer" request budget timed every request out at once.
+ * `requestTimeoutMs` is screened against it and `deadline.ts` reads the inbound header by it.
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
+
 /**
  * Nobody has 64 proxies in front of one process; a bigger number is a typo, not a topology.
  *
@@ -211,7 +229,22 @@ const resolveTrustedProxyHops = (trustProxy: boolean, declared: number | undefin
   );
 };
 
+/**
+ * Keys this config once carried and no longer reads. A typed caller is stopped by
+ * `HttpConfigInput` itself; this is for the one that is not — plain JS, a spread of a parsed
+ * object, a cast — so a deleted knob is an instruction rather than a number ignored in silence.
+ */
+export const refuseDeletedHttpKeys = (input: object): void => {
+  // Core's rule for a removed key (`core/src/config-removed.ts`): `undefined` is a layer not
+  // saying, so a spread carrying the key unset passes on both surfaces; any other value is written.
+  const written = (key: string): boolean =>
+    Object.hasOwn(input, key) && (input as Record<string, unknown>)[key] !== undefined;
+  if (written('drainTimeoutMs')) throw drainTimeoutDeleted();
+  if (written('buildIdHeader')) throw buildIdHeaderDeleted();
+};
+
 export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
+  refuseDeletedHttpKeys(input);
   // `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
@@ -241,14 +274,21 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
       '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',
+    // Never `HOSTNAME`: Docker sets it to the container id, which is not an address to bind. The
+    // boot passes what `HOST` says (`@ultimat3/cli`'s `hostnameFromEnv`); an embedder passes its own.
+    hostname: input.hostname ?? '0.0.0.0',
     basePath: input.basePath ?? '/',
-    buildId: input.buildId ?? env('BUILD_ID') ?? null,
-    buildIdHeader: input.buildIdHeader ?? 'x-ultimate-build',
+    // `undefined` falls back to the environment; an explicit `null` is the declaration that
+    // switches skew detection off, and `??` would have read it as unset.
+    buildId: input.buildId === undefined ? (env('BUILD_ID') ?? null) : input.buildId,
     dev,
     signInPath: input.signInPath ?? null,
     trustProxy,
     trustedProxyHops,
+    trustClientCertHeader: input.trustClientCertHeader === true,
+    healthDetailPeers: assertHealthDetailPeers(
+      input.healthDetailPeers === undefined ? DEFAULT_HEALTH_DETAIL_PEERS : input.healthDetailPeers,
+    ),
     bodyLimitBytes: assertFiniteCount(
       'bodyLimitBytes',
       input.bodyLimitBytes ?? 1_048_576,
@@ -261,8 +301,8 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     requestTimeoutMs: assertFiniteCount(
       'requestTimeoutMs',
       input.requestTimeoutMs ?? 30_000,
-      Number.MAX_SAFE_INTEGER,
-      'a whole number of milliseconds, where 0 means no deadline',
+      MAX_TIMER_MS,
+      `a whole number of milliseconds up to ${MAX_TIMER_MS} (the longest a timer holds), where 0 means no deadline`,
       'requestTimeoutMs: 30_000',
     ),
     maxInflight: assertFiniteCount(
@@ -272,16 +312,6 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
       '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/context.ts

@@ -6,22 +6,22 @@ import {
   anonymousActor,
   type Clock,
   type Ctx,
-  createContext,
+  ctxOf,
   isAnonymous,
   type Logger,
   traceId as newTraceId,
   type Role,
+  readCookie,
   type ServiceBag,
   systemClock,
   useContext,
-  uuid,
+  uuidV7,
 } 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 { bindRequestServices } from './request-services';
@@ -36,8 +36,8 @@ import type { Route, RouteParams } from './router';
  * `CtxServices` with `declare module` to declare `ctx.posts`, and every service it declared then
  * became a required member of every context literal in the framework — this file failed to
  * compile inside `examples/dummy` with `TS2739: missing posts, orgs` while the framework's own
- * gate, which augments nothing, stayed green. `createRequestContext` now spreads
- * `createContext()`'s result, so the members only an app's boot can supply arrive with it and the
+ * gate, which augments nothing, stayed green. `requestContext` now spreads
+ * `ctxOf()`'s result, so the members only an app's boot can supply arrive with it and the
  * literal below is checked in full.
  *
  * The `extends` is therefore back to doing what it was always claimed to do: a member core adds
@@ -118,7 +118,7 @@ export interface RequestContext extends Ctx {
    */
   pathLocale: string | undefined;
   tz: string;
-  /** What the CLIENT says it is running, from `config.buildIdHeader`. `assertBuild()` reads it. */
+  /** What the CLIENT says it is running, from core's `BUILD_ID_HEADER`. `assertBuild()` reads it. */
   clientBuildId: string | null;
   input: unknown;
   authz: AuthzDecision | undefined;
@@ -166,15 +166,15 @@ export interface RequestContextInit {
   readonly services?: ServiceBag;
 }
 
-export const createRequestContext = (init: RequestContextInit): RequestContext => {
+export const requestContext = (init: RequestContextInit): RequestContext => {
   const clock = init.clock ?? systemClock;
-  const requestId = init.requestId ?? uuid(clock);
+  const requestId = init.requestId ?? uuidV7(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();
   // COMPOSED from core's constructor rather than built beside it, and that is what deletes the
-  // last cast in this file. `createContext` returns a `Ctx` that already carries the app's
+  // last cast in this file. `ctxOf` returns a `Ctx` that already carries the app's
   // `CtxServices` augmentation, so spreading it hands this literal the members only the app's boot
   // could supply — and the return below is checked in full, with nothing asserted anywhere.
   //
@@ -186,8 +186,8 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
   // `ctx.services.posts` beside it was populated. Composing makes that class of drift unwritable.
   //
   // `defineService` factories now install on this surface too, for the same reason: they are
-  // `createContext`'s and this is `createContext`.
-  const base = createContext({
+  // `ctxOf`'s and this is `ctxOf`.
+  const base = ctxOf({
     requestId,
     traceId,
     role: init.role,

package/src/correlation.ts

@@ -3,7 +3,7 @@
 // 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 { traceId as newTraceId, parseTraceparent, type SpanContext, uuidV7 } from '@ultimat3/core';
 import type { HttpConfig } from './config';
 
 /**
@@ -33,7 +33,7 @@ export interface InboundCorrelation {
  */
 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 requestId = inboundId !== null && REQUEST_ID.test(inboundId) ? inboundId : uuidV7();
   // Deliberately NOT gated on `trustProxy`, unlike the id above, and the asymmetry is the rule:
   // `x-request-id` is ECHOED back as this response's identity, so an untrusted caller choosing it
   // poisons log correlation for everyone — while `traceparent` is W3C context continuation, which

package/src/cors.ts

@@ -1,6 +1,7 @@
 // CORS with a locked default: same-origin only. Cross-origin access is a decision the app makes
 // once, in `configureHttp({ cors })`, never something a route can quietly opt into.
 
+import { BUILD_ID_HEADER } from '@ultimat3/core';
 import { corsConfigInvalid } from './errors';
 
 export interface CorsConfig {
@@ -16,8 +17,8 @@ export interface CorsConfig {
 export const DEFAULT_CORS: CorsConfig = {
   origins: [],
   methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'],
-  allowHeaders: ['content-type', 'authorization', 'x-ultimate-build', 'x-request-id'],
-  exposeHeaders: ['x-request-id', 'x-ultimate-build', 'retry-after'],
+  allowHeaders: ['content-type', 'authorization', BUILD_ID_HEADER, 'x-request-id'],
+  exposeHeaders: ['x-request-id', BUILD_ID_HEADER, 'retry-after'],
   credentials: true,
   maxAgeSeconds: 600,
 };

package/src/csrf.ts

@@ -1,5 +1,5 @@
-// 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
+// Whether an unsafe request a BROWSER sent — with the session cookie, or to obtain one — 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
@@ -34,7 +34,11 @@ export interface CsrfCheckInput {
   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. */
+  /**
+   * No session resolved. NOT an exemption: a sign-in form is forgeable too (login CSRF — the
+   * visitor ends up in the attacker's account), so an anonymous write that carries browser
+   * evidence is judged exactly as a credentialed one. See `checkCsrf` for the one thing it buys.
+   */
   readonly anonymous: boolean;
   readonly cors: CorsConfig;
   readonly config: CsrfConfig;
@@ -50,12 +54,17 @@ export type CsrfVerdict =
  * `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.
+ *
+ * An ANONYMOUS request carrying neither is the one case let through: there is no ambient
+ * credential to ride and no browser evidence to judge, which is an inbound webhook or a
+ * server-to-server call, never a page a hostile site can drive — every browser that can submit a
+ * cross-site form sends `Origin` on it. Either header present, and it is judged like any other.
  */
 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 };
+  if (input.anonymous && input.origin === null && input.secFetchSite === null) return { ok: true };
 
   // The rule itself is core's, shared with the sync node's upgrade: one answer to "did this
   // come from this app?" on every surface an ambient credential reaches.
@@ -79,8 +88,8 @@ export const selfOrigin = (url: URL, https: boolean): string =>
   `${https ? 'https' : 'http'}://${url.host}`;
 
 /**
- * A write that arrived with the browser's ambient credential and could not be shown to come from
- * this app. Never a 401: the caller IS signed in, which is precisely the problem.
+ * A write a browser sent — with its ambient credential, or anonymously to obtain one — that could
+ * not be shown to come from this app. Never a 401: who is calling was never the question.
  *
  * From a LOOPBACK `ip` the caller is `curl` against `x dev`: it sends neither
  * header, and the remedies below name a token or a config change dev does not need. The header a
@@ -95,11 +104,11 @@ export const csrfBlocked = (
   ip !== null && classifyAddress(ip) === 'loopback'
     ? new HttpError({
         code: 'X_CSRF_BLOCKED',
-        cause: `${pathname} refused a credentialed write: ${reason}`,
+        cause: `${pathname} refused a write it could not show came from this app: ${reason}`,
         fix: "curl -H 'sec-fetch-site: same-origin' -X POST http://localhost:3000/the-path-above   # a local client proves same-origin the way a browser does; the session cookie still decides who is calling",
       })
     : new HttpError({
         code: 'X_CSRF_BLOCKED',
-        cause: `${pathname} refused a credentialed write: ${reason}`,
+        cause: `${pathname} refused a write it could not show came from this app: ${reason}`,
         fix: "call it with an Authorization header instead of the session cookie, add the calling origin to configureHttp({ cors: { origins } }), or configureHttp({ csrf: { mode: 'off' } }) if this app has no cookie session at all",
       });