@ultimat3/http 22.5.1 → 22.6.0

package/CLAUDE.md

@@ -57,7 +57,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **`ctx.actor` is never null** — the `auth` stage turns the hook's `null` into `anonymousActor()`.
 - **The context carries the inbound headers, never the `Request`** (`ctx.requestHeaders`,
   `useRequestHeader` / `useRequestCookie`).
-- **`hooks.authenticate` has one declaration site: `configureAuthenticator()`.**
+- **`hooks.authenticate` has one declaration site: `configureAuthenticator()`.** A route may
+  REPLACE it with `meta.authenticate` (never run beside it): `bearerMount` sets it so a session
+  cookie authenticates nothing on `/v1/*`.
+- **`bearerMount` re-serves existing `Route`s, never re-projects them** (`bearer-mount.ts`): same
+  handler, policy, idempotency; adds the credential (bearer only, `WWW-Authenticate` on 401), the
+  cut (outside the token's scopes = `X_ROUTE_NOT_FOUND`, the MCP rule), and a per-token bucket
+  keyed by a SHA-256 of the token. Bad prefix / unknown name / double claim:
+  `X_BEARER_MOUNT_INVALID` at construction.
 - **`hooks.devNotices` is called only inside the `config.dev && wantsOverlay` branch.**
 
 ## Rules — the pipeline
@@ -67,6 +74,11 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `finalize.ts` owns the tail. Imports go `pipeline.ts` → `stages.ts`; a stage reads
   `StageRunnersInput`, never `PipelineDeps`. A new stage is an entry in both `PIPELINE_STAGES` and the
   `Record<StageName, StageRun>` table, with a `why` and a test.
+- **The request span is named by the route PATTERN** (`GET /r/:token`, `routeSpanName`), started
+  as the bare method and renamed after the match; `http.route` is the pattern or `unmatched`. A
+  concrete URL carries tokens and is attacker-chosen — never a span name, attribute or label.
+- **The CSP `connect-src` is `'self' blob:`** — no bare `ws:`/`wss:`. A cross-origin sync node is
+  the boot's `csp.extend` of that origin exactly. `security.hsts` merges key by key.
 - **The two inbound ids are read BEFORE the context and the span** (`correlation.ts`, core's
   `parseTraceparent`). `x-request-id` is gated on `trustProxy`; `traceparent` deliberately is not.
 - **Every proxy-supplied header goes through `forwardedElement(header, hops)`** — the entry at
@@ -211,6 +223,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `webhook-verify.ts` | the INBOUND webhook: the canonical string, the constant-time mac check and the replay window. The outbound half is `webhook()` in `@ultimat3/jobs`, which this package can never import |
 | `locale.ts` | WHERE the request's locale and zone are read from — header and cookie NAMES only, plus `readCookie`. It negotiates nothing |
 | `rate-limit-buckets.ts` | the one point routes and config meet: a route's own bucket, registered or refused |
+| `bearer-mount.ts` | a second door onto existing routes: `Authorization: Bearer` on a prefix, the scope cut, the per-token allowance |
 | `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
 
 ## Commands

package/README.md

@@ -286,6 +286,23 @@ every stage (middleware, finalize, security headers), and an upgraded request mu
 halves above cannot carry a case, the fallback is a long-poll `action` (`GET`-shaped, returning
 `{ frames, cursor }` and re-called on return), which is what the app that asked shipped.
 
+### A second door: `bearerMount` (`/v1/*`)
+
+`As of 22.6.0`. `bearerMount({ prefix, routes, scopes, resolveToken, rateLimit?, rateLimitStore? })`
+re-serves routes the app already projects under a prefix — same handler, same policy — and changes
+exactly three things. Apps declare it through `defineApi({ http: { mounts } })` (`@ultimat3/action`);
+`@ultimat3/cli` builds it in both boots over `apiRoutes()`.
+
+| On the mount | Answer |
+|---|---|
+| credential | `Authorization: Bearer` ONLY — `meta.authenticate` replaces the app's authenticator, so a session cookie authenticates nothing here (and a bearer call needs no CSRF proof) |
+| no / unresolved token | 401, `WWW-Authenticate: Bearer` / `Bearer error="invalid_token"` |
+| a primitive outside the token's `scopes` | 404 `X_ROUTE_NOT_FOUND`, identical to an unknown path — MCP's hidden-tool rule |
+| per-token allowance | `RateLimit-Limit/-Remaining/-Reset` on every answer, 429 + `Retry-After` past it; keyed by a SHA-256 of the token |
+| paths | `/api/<x>` → `<prefix>/<x>`, `/_x/query/<x>` → `GET <prefix>/<x>` (`mountedPath`) |
+
+`RouteMeta.authenticate` is the mechanism: a route that states one is reached only through it.
+
 ## Inbound webhooks
 
 `verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook

package/package.json

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

package/src/bearer-mount.ts

@@ -0,0 +1,200 @@
+// A second door onto routes the app already projects: `Authorization: Bearer` on a prefix
+// (`/v1/*`), exposing a declared cut of them, per token. Built OVER existing `Route`s — the
+// handler, the policy, the idempotency and the input schema are the ones the `/api` route runs,
+// so there is no second projection of an action to drift from the first. What the mount adds is
+// the credential (only the bearer token authenticates here; a session cookie reaches nothing), the
+// cut (a primitive outside the caller's scopes answers 404, the way MCP answers an unknown tool),
+// and a per-token allowance with `RateLimit-*` and `Retry-After`.
+
+import type { Actor, Clock } from '@ultimat3/core';
+import { ACTION_PATH_PREFIX, QUERY_PATH_PREFIX, systemClock } from '@ultimat3/core';
+import type { RequestContext } from './context';
+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 type { UltimateRequest } from './request';
+import type { Route, RouteMeta } from './router';
+
+/**
+ * What a token resolves to. Structurally `@ultimat3/mcp`'s `ResolvedToken`, so an app hands the
+ * ONE resolver its MCP endpoint already uses (`resolveToken`) to this mount unchanged.
+ */
+export interface BearerCaller {
+  readonly actor: Actor;
+  /** What the token was issued to do; matched against the mount's `scopes` map. */
+  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;
+
+export interface BearerMountRateLimit {
+  readonly limit: number;
+  readonly windowMs: number;
+}
+
+export interface BearerMountInput {
+  /** `'/v1'` — lowercase segments; never `/api` or `/_x`, which the framework serves itself. */
+  readonly prefix: string;
+  /** The projected routes the cut is taken from (`apiRoutes()`): matched by `meta.name`. */
+  readonly routes: readonly Route[];
+  /**
+   * Scope → the primitives it covers, BY NAME — the shape `defineAppMcp({ scopes })` takes, so an
+   * app passes one map to both. The union is everything the mount serves; a token sees a
+   * primitive only while it carries the scope that names it.
+   */
+  readonly scopes: Readonly<Record<string, readonly string[]>>;
+  readonly resolveToken: BearerResolver;
+  /** Requests per window per TOKEN (keyed by a hash of the token itself, never the user). */
+  readonly rateLimit?: BearerMountRateLimit | undefined;
+  /** Where the per-token buckets live. Defaults to per-process memory; a fleet passes a shared one. */
+  readonly rateLimitStore?: RateLimitStore | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+/** A mount prefix: `/v1`, `/public/v2`. Lowercase segments, no parameters, no trailing slash. */
+const PREFIX = /^(\/[a-z0-9][a-z0-9._~-]*)+$/;
+
+/** The namespaces a mount may never shadow. */
+const RESERVED = [ACTION_PATH_PREFIX, '/_x'];
+
+/** `Authorization: Bearer <token>`, the only accepted form. No query-string tokens. */
+export function bearerTokenOf(header: string | null): string | null {
+  if (header === null) return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  return match?.[1] ?? null;
+}
+
+/**
+ * The path a projected route is served at under `prefix`: its framework namespace (`/api`,
+ * `/_x/query`) replaced by the prefix, so `POST /api/create-case` is `POST /v1/create-case` and
+ * `GET /_x/query/case-list` is `GET /v1/case-list`. A route outside both keeps its whole path.
+ */
+export function mountedPath(prefix: string, path: string): string {
+  for (const namespace of [QUERY_PATH_PREFIX, ACTION_PATH_PREFIX]) {
+    if (path.startsWith(`${namespace}/`)) return `${prefix}${path.slice(namespace.length)}`;
+  }
+  return `${prefix}${path}`;
+}
+
+/** Hex SHA-256 prefix: a per-token key that never stores or logs the token itself. */
+const tokenKey = (token: string): string =>
+  new Bun.CryptoHasher('sha256').update(token).digest('hex').slice(0, 32);
+
+/**
+ * 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.
+ */
+export function bearerMount(input: BearerMountInput): readonly Route[] {
+  const { prefix } = input;
+  if (!PREFIX.test(prefix)) {
+    throw bearerMountInvalid(prefix, 'the prefix is not a lowercase path like /v1');
+  }
+  for (const reserved of RESERVED) {
+    if (prefix === reserved || prefix.startsWith(`${reserved}/`)) {
+      throw bearerMountInvalid(
+        prefix,
+        `the prefix would shadow ${reserved}, which the framework serves`,
+      );
+    }
+  }
+
+  // name → the scope that covers it. One scope per primitive, as MCP's `withScopes` holds.
+  const scopeOf = new Map<string, string>();
+  for (const [scope, names] of Object.entries(input.scopes)) {
+    for (const name of names) {
+      const claimed = scopeOf.get(name);
+      if (claimed !== undefined && claimed !== scope) {
+        throw bearerMountInvalid(
+          prefix,
+          `${name} is claimed by two scopes, ${claimed} and ${scope}`,
+        );
+      }
+      scopeOf.set(name, scope);
+    }
+  }
+  const byName = new Map<string, Route[]>();
+  for (const route of input.routes) {
+    const list = byName.get(route.meta.name) ?? [];
+    list.push(route);
+    byName.set(route.meta.name, list);
+  }
+  const missing = [...scopeOf.keys()].filter((name) => !byName.has(name)).sort();
+  if (missing.length > 0) {
+    throw bearerMountInvalid(prefix, `no projected route is named ${missing.join(', ')}`);
+  }
+
+  const bucket =
+    input.rateLimit === undefined ? undefined : toBucket(`bearer mount ${prefix}`, input.rateLimit);
+  const store = input.rateLimitStore ?? memoryRateLimitStore();
+  const clock = input.clock ?? systemClock;
+  // The caller each request resolved to, keyed by ITS context — never a module-level slot two
+  // 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;
+  };
+
+  const spend = async (key: string, ctx: RequestContext): Promise<void> => {
+    if (bucket === undefined) return;
+    const decision: RateLimitDecision = await store.take(
+      `${prefix}|token:${key}`,
+      bucket,
+      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))),
+    );
+    // `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);
+  };
+
+  const mounted: Route[] = [];
+  const seen = new Map<string, string>();
+  for (const [name, scope] of [...scopeOf.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    for (const route of byName.get(name) ?? []) {
+      const path = mountedPath(prefix, route.path);
+      const slot = `${route.method} ${path}`;
+      const owner = seen.get(slot);
+      if (owner !== undefined) {
+        throw bearerMountInvalid(prefix, `${name} and ${owner} would both be served at ${slot}`);
+      }
+      seen.set(slot, name);
+      mounted.push({
+        method: route.method,
+        path,
+        meta: { ...route.meta, auth: 'required', authenticate },
+        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.
+          if (resolved === undefined || !resolved.caller.scopes.has(scope)) {
+            throw routeNotFound(ctx.method, ctx.url.pathname);
+          }
+          await spend(resolved.key, ctx);
+          return await route.handler(request, ctx);
+        },
+      });
+    }
+  }
+  return mounted;
+}

package/src/config.ts

@@ -97,12 +97,30 @@ export interface HttpConfigInput {
   readonly tz?: Partial<TimeZoneConfig>;
   readonly cors?: Partial<CorsConfig>;
   readonly csrf?: Partial<CsrfConfig>;
-  readonly security?: Partial<Omit<SecurityConfig, 'csp'>> & {
+  readonly security?: Partial<Omit<SecurityConfig, 'csp' | 'hsts'>> & {
     readonly csp?: Partial<SecurityConfig['csp']>;
+    /**
+     * Merged over `DEFAULT_SECURITY.hsts` key by key, so `{ preload: true }` alone is the preload
+     * opt-in (submit the host at hstspreload.org only after that). `null` sends no HSTS at all.
+     */
+    readonly hsts?: Partial<NonNullable<SecurityConfig['hsts']>> | null;
   };
   readonly rateLimit?: Partial<RateLimitConfig>;
 }
 
+/** Key by key over the default two-year policy; `null` is the one way to send none. */
+const resolveHsts = (
+  input: Partial<NonNullable<SecurityConfig['hsts']>> | null | undefined,
+): SecurityConfig['hsts'] => {
+  if (input === null) return null;
+  const base = DEFAULT_SECURITY.hsts ?? {
+    maxAgeSeconds: 63_072_000,
+    includeSubdomains: true,
+    preload: false,
+  };
+  return { ...base, ...input };
+};
+
 /**
  * `basePath` is stripped before matching so route paths never encode the mount point.
  * Matching is on a segment boundary: a mount at `/api` owns `/api` and `/api/...` but
@@ -268,7 +286,12 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     tz: { ...DEFAULT_TZ_CONFIG, ...input.tz },
     cors,
     csrf: { ...DEFAULT_CSRF, ...input.csrf },
-    security: { ...DEFAULT_SECURITY, ...input.security, csp },
+    security: {
+      ...DEFAULT_SECURITY,
+      ...input.security,
+      csp,
+      hsts: resolveHsts(input.security?.hsts),
+    },
     rateLimit: resolveRateLimitConfig(input.rateLimit),
   };
 };

package/src/error-map.ts

@@ -83,6 +83,15 @@ export const ERROR_STATUS = {
   // `X_UNAUTHENTICATED` alone — a webhook sender is not a browser and has no session to go get.
   X_WEBHOOK_SIGNATURE_INVALID: 401,
   X_WEBHOOK_SIGNATURE_STALE: 401,
+  // Boot refusals of the app's HTTP declaration (a bearer mount, an action's pinned path or the
+  // app's path style, the openapi block, the MCP oauth block, a page's `post`) — never a request's
+  // answer; 500 if one ever escaped into a response: the deployment is wrong, the caller is not.
+  X_BEARER_MOUNT_INVALID: 500,
+  X_ACTION_HTTP_PATH_INVALID: 500,
+  X_ACTION_PATH_STYLE_INVALID: 500,
+  X_OPENAPI_CONFIG_INVALID: 500,
+  X_MCP_OAUTH_INVALID: 500,
+  X_ROUTE_POST_INVALID: 500,
   // @ultimat3/action — the code every primitive throws when the CALLER's input fails the schema
   // the primitive declared. 400 because that is what the published OpenAPI operation promises for
   // it, and because a missing row made a typo'd uuid a 500: the caller was told the server broke,

package/src/errors.ts

@@ -38,6 +38,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_CSRF_BLOCKED',
   'X_WEBHOOK_SIGNATURE_INVALID',
   'X_WEBHOOK_SIGNATURE_STALE',
+  'X_BEARER_MOUNT_INVALID',
 ] as const;
 
 /**
@@ -101,6 +102,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_CSRF_BLOCKED: 'a credentialed write arrived from an origin that is not allowed to make it',
   X_WEBHOOK_SIGNATURE_INVALID: 'the inbound webhook is not signed by the holder of this secret',
   X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
+  X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
 };
 
 // Registered at module load, unconditionally, in one call, so core's registry renders OUR title
@@ -216,6 +218,14 @@ export const bodyInvalid = (
     fix: `x routes --json   # find ${pathname}, then send a body matching its input schema`,
   });
 
+/** At construction: a hole in a scope, or a prefix shadowing `/api` or `/_x`, never serves. */
+export const bearerMountInvalid = (prefix: string, reason: string): HttpError =>
+  new HttpError({
+    code: 'X_BEARER_MOUNT_INVALID',
+    cause: `the bearer mount at ${JSON.stringify(prefix)} cannot be served: ${reason}`,
+    fix: "declare mounts: [{ prefix: '/v1', scopes: { 'cases:read': ['caseList'] }, resolveToken }] in defineApi({ http }) — a prefix of lowercase segments that is not /api or /_x, naming only registered actions and queries (x routes --json lists them)",
+  });
+
 export const unauthenticated = (pathname: string): HttpError =>
   new HttpError({
     code: 'X_UNAUTHENTICATED',

package/src/index.ts

@@ -15,6 +15,13 @@ export {
 export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
 export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
+export type {
+  BearerCaller,
+  BearerMountInput,
+  BearerMountRateLimit,
+  BearerResolver,
+} from './bearer-mount';
+export { bearerMount, bearerTokenOf, mountedPath } from './bearer-mount';
 export type { HttpConfig, HttpConfigInput } from './config';
 export { defineHttpConfig, MAX_PROXY_HOPS } from './config';
 export type { ActorView, RequestContext, RequestContextInit } from './context';
@@ -33,7 +40,7 @@ export type { InboundCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
 export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } from './cors';
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
-export { checkCsrf, csrfBlocked } from './csrf';
+export { checkCsrf, csrfBlocked, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
 export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-facts';
@@ -66,6 +73,7 @@ export {
 } from './error-status';
 export type { HttpErrorCode } from './errors';
 export {
+  bearerMountInvalid,
   bodyInvalid,
   buildSkew,
   draining,

package/src/pipeline.ts

@@ -96,6 +96,13 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   },
 ];
 
+/**
+ * `GET /posts/:id` — the route pattern, or the bare method when nothing matched (OpenTelemetry's
+ * HTTP server span rule). Exported for the test that pins it; never built from `url.pathname`.
+ */
+export const routeSpanName = (method: string, routePath: string | undefined): string =>
+  routePath === undefined ? method : `${method} ${routePath}`;
+
 export interface PipelineDeps {
   readonly table: RouteTable;
   readonly config?: HttpConfig;
@@ -251,7 +258,11 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
       // a handler calls — sees the same context object without threading it by hand.
       return await runWithContext(asCtx(ctx), () =>
         withSpan(
-          `${ctx.method} ${url.pathname}`,
+          // The METHOD alone until the router has spoken — never the concrete path. A URL is
+          // attacker-chosen and carries capability tokens (`/r/<token>`, `/ics/<token>.ics`), and
+          // a span name is exported verbatim to every collector. `routeSpanName` renames it to
+          // the route PATTERN once one matched.
+          ctx.method,
           async (span) => {
             // This package's ONE metrics call site. `finally`, not the happy line: `execute`
             // answers every stage's throw with a problem response, but a counter that skipped the
@@ -262,6 +273,7 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
             try {
               const response = await execute(request, ctx, deadline);
               status = response.status;
+              span.updateName(routeSpanName(ctx.method, ctx.route?.path));
               // The root span of every request carried no attributes at all, so an exporter got a
               // name and a duration and nothing to correlate: which request, which outcome. These
               // four are what a reader joins on — `x-request-id` off the response, the status the
@@ -269,14 +281,16 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
               span.setAttributes({
                 'http.request_id': ctx.requestId,
                 'http.method': ctx.method,
-                'http.route': url.pathname,
+                // The PATTERN (`/r/:token`), the OpenTelemetry meaning of `http.route` — the
+                // concrete path leaked every token a URL carries into the trace store.
+                'http.route': ctx.route?.path ?? UNMATCHED_ROUTE,
                 'http.status_code': response.status,
               });
               return response;
             } finally {
-              // The span may carry the concrete path — a trace is sampled and thrown away. A
-              // metric is a stored series per label set, so this is the route PATTERN
-              // (`/posts/:id`), and `recordRequest` folds the status to its class for the same
+              // The route PATTERN (`/posts/:id`), exactly as the span above is named: a metric is
+              // a stored series per label set, and a concrete path is attacker-chosen and may
+              // carry a token. And `recordRequest` folds the status to its class for the same
               // reason. Nothing here is attacker-chosen or per-user.
               recordRequest({
                 method: ctx.method,

package/src/router.ts

@@ -10,7 +10,7 @@
 // param branch would also match, and a dead end in the static branch still falls
 // back to the param branch. Two routes that would tie are a build error
 // (`X_ROUTE_CONFLICT`) rather than a coin flip.
-import type { RenderMode } from '@ultimat3/core';
+import type { Actor, RenderMode } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { routeConflict } from './errors';
 import type { Bucket } from './rate-limit';
@@ -79,6 +79,16 @@ export interface RouteMeta {
    * serves for `/` cannot negotiate, so the served process must not either.
    */
   readonly localeSource?: 'path' | 'request';
+  /**
+   * THIS route's authenticator, in place of the app's `configureAuthenticator()` — never beside
+   * it. A route that states one is reached only through the credential it names: a bearer mount
+   * (`bearerMount`) sets it so a session cookie authenticates NOTHING there, which is also what
+   * keeps a cross-site form from riding a cookie into it. `null` is anonymous, as the hook's is.
+   */
+  readonly authenticate?: (
+    request: UltimateRequest,
+    ctx: RequestContext,
+  ) => Promise<Actor | null> | Actor | null;
 }
 
 export type RouteHandler = (

package/src/security-headers.ts

@@ -62,8 +62,14 @@ const baseline = (config: SecurityConfig): Record<string, readonly string[]> =>
   'style-src-attr': ["'unsafe-inline'"],
   'img-src': ["'self'", 'data:', 'blob:'],
   'font-src': ["'self'"],
-  // ws:/wss: are required by the realtime tiers; blob: by streamed responses.
-  'connect-src': ["'self'", 'ws:', 'wss:', 'blob:'],
+  // `'self'` and nothing wider. The bare `ws:`/`wss:` schemes this used to carry let a script
+  // injected anywhere on the page open a socket to ANY host — an exfiltration channel the rest of
+  // the policy exists to close. CSP Level 3 matches `'self'` against the page's own host over
+  // ws/wss as well (every evergreen engine, As of 2026-09), which is where the sync node is
+  // served on every rung that shares the page origin. A sync node on ANOTHER origin (`SYNC_URL`)
+  // is added by the boot through `csp.extend` — its origin exactly, never a scheme.
+  // blob: is required by streamed responses.
+  'connect-src': ["'self'", 'blob:'],
   'worker-src': ["'self'", 'blob:'],
   'manifest-src': ["'self'"],
   'media-src': ["'self'", 'blob:'],

package/src/stages.ts

@@ -203,10 +203,13 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     },
 
     auth: async (request, ctx) => {
-      if (hooks.authenticate !== undefined) {
+      // A route's own authenticator REPLACES the app's, never runs beside it: a bearer mount must
+      // not also accept the session cookie the app's hook would resolve (`RouteMeta.authenticate`).
+      const authenticate = ctx.route?.meta.authenticate ?? hooks.authenticate;
+      if (authenticate !== undefined) {
         // The hook says "anonymous" with null; the context says it with core's anonymous actor,
         // because `asCtx` publishes this object as a `Ctx` and `Ctx.actor` is never null.
-        ctx.actor = (await hooks.authenticate(request, ctx)) ?? anonymousActor();
+        ctx.actor = (await authenticate(request, ctx)) ?? anonymousActor();
         // The `user` rung the `locale` stage could not know: re-resolved through the same owners,
         // so a cookie the reader chose still beats a saved locale where i18n's order says it does.
         if (ctx.actor.locale !== undefined || ctx.actor.tz !== undefined) {