@ultimat3/http 23.0.0 → 25.0.0

package/src/server.ts

@@ -7,6 +7,7 @@ import {
   beginWork,
   configureLifecycle,
   drain,
+  healthBody,
   healthzPayload,
   lifecycleState,
   logger,
@@ -14,17 +15,20 @@ import {
   markReady,
   onShutdown,
   readyzPayload,
+  systemClock,
 } from '@ultimat3/core';
 import type { Server } from 'bun';
 import { defineHttpConfig, type HttpConfig } from './config';
 import { HttpError, serverNotStarted } from './errors';
+import { disclosesHealthDetail } from './health-disclosure';
 import type { ServerHooks } from './hooks';
 import type { Middleware } from './middleware';
-import { createPipeline, type Pipeline } from './pipeline';
-import { createRateLimiter, type RateLimitStore } from './rate-limit';
+import { httpPipeline, type Pipeline } from './pipeline';
+import { type RateLimitStore, rateLimiter } from './rate-limit';
 import { withRouteBuckets } from './rate-limit-buckets';
-import { json } from './response';
-import { createRouter, describeRoutes, type Route, type RouteDescription } from './router';
+import { adoptRateLimitStore } from './rate-limit-installed';
+import { jsonResponse } from './response';
+import { describeRoutes, httpRouter, type Route, type RouteDescription } from './router';
 
 /**
  * Beside its one caller rather than in `errors.ts`, which is at the 500-line ceiling — the
@@ -33,13 +37,13 @@ import { createRouter, describeRoutes, type Route, type RouteDescription } from
  * A websocket mount and something already answering its path. Same code as two routes claiming
  * one, because it is the same fact: one path, two declarations, and the framework picks — Bun's
  * native route table is matched BEFORE `fetch`, so the route wins and the upgrade never reaches
- * the mount. Refused at `createServer`, not discovered as a socket that will not open.
+ * the mount. Refused at `httpServer`, not discovered as a socket that will not open.
  */
 const websocketPathTaken = (path: string, answered: string): HttpError =>
   new HttpError({
     code: 'X_ROUTE_CONFLICT',
     cause: `the websocket mount claims ${path}, and ${answered} already answers it — Bun matches its native route table before \`fetch\`, so the upgrade would never reach the mount`,
-    fix: `x routes list --json   # then move the mount's path, or the declaration at ${path}`,
+    fix: `x routes --json   # then move the mount's path, or the declaration at ${path}`,
   });
 
 /** Core owns the state machine; this alias exists so callers need one import. */
@@ -61,7 +65,7 @@ export interface ServerOptions {
    * Where the rate limiter keeps its counters. Omitted means `memoryRateLimitStore()`, which is
    * one process' worth of state — correct for dev and tests, and N × every configured number for
    * N replicas. An app that runs more than one process declares `rateLimit.scope: 'shared'` and
-   * passes a store that says the same, or `createServer` refuses here.
+   * passes a store that says the same, or `httpServer` refuses here.
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
@@ -98,6 +102,8 @@ export interface ServerOptions {
  */
 export interface UpgradeTarget {
   upgrade(request: Request, options: { data: unknown }): boolean;
+  /** The peer's socket address — a mount that answers its own health paths decides detail by it. */
+  requestIP(request: Request): { readonly address: string } | null;
 }
 
 /**
@@ -138,7 +144,7 @@ export interface ServerHandle {
   url(): string;
   describe(): readonly RouteDescription[];
   start(): ServerHandle;
-  /** Runs core's three-phase drain. The deadline is `config.drainTimeoutMs`. */
+  /** Runs core's three-phase drain, on the deadline `drain.deadlineMs` set (`lifecycleForRole`). */
   stop(): Promise<void>;
   /**
    * Runs one request through the entire lifecycle with no socket. This is the
@@ -147,20 +153,41 @@ export interface ServerHandle {
   fetch(request: Request): Promise<Response>;
 }
 
+/** How often the `inflight` hook re-reads Bun's count of unfinished responses. */
+const BODY_POLL_MS = 5;
+
 const roleFromEnv = (): Role => (Bun.env['ROLE'] ?? 'web') as Role;
 
-export const createServer = (options: ServerOptions): ServerHandle => {
+export const httpServer = (options: ServerOptions): ServerHandle => {
+  // The store this server is handed is also the one actions and queries spend their declared
+  // `rateLimit:` from — adopted BEFORE the pipeline, whose boot check reads it, and never over a
+  // store the boot already chose (`keepChosen`). Given back on `stop()`, or by ANY refusal from
+  // here to the handle — the pipeline's checks, `configureLifecycle`, `assertMountPathFree` — so a
+  // boot that never produced a server leaves nothing behind it.
+  const releaseStore =
+    options.rateLimitStore === undefined
+      ? () => undefined
+      : adoptRateLimitStore(options.rateLimitStore, { keepChosen: true });
+  try {
+    return buildServer(options, releaseStore);
+  } catch (error) {
+    releaseStore();
+    throw error;
+  }
+};
+
+const buildServer = (options: ServerOptions, releaseStore: () => void): ServerHandle => {
   const role = options.role ?? roleFromEnv();
-  const table = createRouter(options.routes);
-  // Merged here as well as in `createPipeline`, and for the store's sake: the limiter below is
+  const table = httpRouter(options.routes);
+  // Merged here as well as in `httpPipeline`, and for the store's sake: the limiter below is
   // built from `config.rateLimit`, so a table without the routes' own buckets would resolve a
   // declared name to `default` — the very hole this closes. `withRouteBuckets` is idempotent, so
   // the pipeline's second pass changes nothing. `handle.config` is the merged one for the same
   // reason: `server.config.rateLimit.buckets` has to be what the limiter runs on.
   const config = withRouteBuckets(options.config ?? defineHttpConfig(), table.routes);
   // The store feeds the limiter seam `PipelineDeps` already had, rather than becoming a second
-  // one: the bucket maths stays in `createRateLimiter`, so every driver agrees on the numbers.
-  const pipeline = createPipeline({
+  // one: the bucket maths stays in `rateLimiter`, so every driver agrees on the numbers.
+  const pipeline = httpPipeline({
     table,
     config,
     ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
@@ -168,17 +195,14 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     ...(options.rateLimitStore === undefined
       ? {}
       : {
-          limiter: createRateLimiter({ config: config.rateLimit, store: options.rateLimitStore }),
+          limiter: rateLimiter({ config: config.rateLimit, store: options.rateLimitStore }),
         }),
   });
 
-  // The one HTTP-owned knob feeds core's deadline, so there is a single drain budget — and only
-  // when this app DECLARED it. Unconditional, with `defineHttpConfig` defaulting the number, this
-  // line reverted `configureLifecycle({ deadlineMs: 600_000 })` — the edit `X_SHUTDOWN_TIMEOUT`'s
-  // own `fix:` prints — back to 15s on every boot that serves web, silently. "Nobody said" and
-  // "the app said 15 seconds" are different claims and `null` is what keeps them apart.
-  if (config.drainTimeoutMs !== null) configureLifecycle({ deadlineMs: config.drainTimeoutMs });
-  // Same rule: only a declared grace is applied. Core waits it out between the readiness flip and
+  // No deadline is set here. `drain.deadlineMs` is the one budget, applied per role by
+  // `lifecycleForRole` before any server exists; `http.drainTimeoutMs` re-set it on the web role
+  // only, after that, and was deleted in 25.0.0 for being a second answer (axiom 1).
+  // Only a declared grace is applied. Core waits it out between the readiness flip and
   // the `accept` hook below, so endpoints stop routing here before the socket closes.
   const readinessGraceMs = options.drain?.readinessGraceMs;
   if (readinessGraceMs !== undefined) configureLifecycle({ readinessGraceMs });
@@ -186,6 +210,7 @@ export const createServer = (options: ServerOptions): ServerHandle => {
   const mount = options.websocket;
   let server: BunServer | undefined;
   let unregister: (() => void) | undefined;
+  let unregisterBodies: (() => void) | undefined;
   let unregisterClose: (() => void) | undefined;
   let stopListening: (() => void) | undefined;
 
@@ -193,10 +218,21 @@ export const createServer = (options: ServerOptions): ServerHandle => {
    * Core owns the health state, the in-flight count and the drain deadline so every
    * role reports identically. `HealthPayload` is `{ ok, status, body }` — core stays
    * HTTP-free and hands us the status code as data, which we render here.
+   *
+   * The STATUS is everyone's, which is all a probe reads. The body beyond the verdict is for a
+   * peer `healthDetailPeers` lists: these two paths answer outside the pipeline, unauthenticated.
    */
-  const healthResponse = (payload: HealthPayload): Response =>
-    json(
-      { ...payload.body, role },
+  const healthResponse = (payload: HealthPayload, request: Request, socket: BunServer): Response =>
+    jsonResponse(
+      healthBody(
+        payload.body,
+        role,
+        disclosesHealthDetail({
+          config,
+          headers: request.headers,
+          socketAddress: socket.requestIP(request)?.address ?? null,
+        }),
+      ),
       { status: payload.status, headers: { 'cache-control': 'no-store' } },
     );
 
@@ -232,7 +268,10 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     const out: Record<string, NativeHandler> = {};
     for (const description of describeRoutes(table)) {
       if (description.params.length > 0) continue;
-      out[`${prefix}${description.path}`] = dispatch;
+      // `encodeURI`: `Bun.serve` refuses a non-ASCII key with a bare `TypeError`, so one route named
+      // `/precios-españa` kept the whole server from starting. Encoded as `URL.pathname` spells
+      // it; any other spelling falls through to `fetch`, where the router decodes it.
+      out[encodeURI(`${prefix}${description.path}`)] = dispatch;
     }
     return out;
   };
@@ -289,11 +328,14 @@ export const createServer = (options: ServerOptions): ServerHandle => {
           ...nativeRoutes(),
           // Health endpoints answer outside the pipeline on purpose: a draining or
           // rate-limited process must still be able to say what it is doing.
-          '/healthz': () => healthResponse(healthzPayload()),
+          '/healthz': (request: Request, socket: BunServer) =>
+            healthResponse(healthzPayload(), request, socket),
           // `?deep=1` always answers on the dependencies, whatever `health.readiness` says.
-          '/readyz': (request: Request) =>
+          '/readyz': (request: Request, socket: BunServer) =>
             healthResponse(
               readyzPayload({ deep: new URL(request.url).searchParams.get('deep') === '1' }),
+              request,
+              socket,
             ),
         },
       };
@@ -321,14 +363,40 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       // 'accept' runs first on SIGTERM, but only after core's readiness grace: readyz flips to
       // 503 the moment the drain starts, the socket stays open for `readinessGraceMs`, so the
       // endpoints controller stops routing here before this closes it — not a 502 in between.
+      //
+      // NOT awaited: Bun's `stop(false)` stops the listener at once but resolves only when every
+      // request AND every websocket on it has closed — so one open browser tab held this hook, and
+      // every `accept` hook after it (worker, scheduler), until the drain deadline, leaving the
+      // `close` hooks 0 ms. Handlers are core's to wait for (`beginWork()`), bodies the `inflight`
+      // hook's below, sockets the `close` hook's `stop(true)`. The same shape as
+      // `realtime/src/sync-listen.ts`. A rejection is the close hook's to surface, not this one's.
       unregister = onShutdown(
         `http:${role}`,
-        async () => {
-          await server?.stop(false);
+        () => {
+          server?.stop(false).catch(() => undefined);
         },
         { phase: 'accept' },
       );
-      // 'close' runs after core has waited out the in-flight phase.
+      // The BODIES. `beginWork()` ends when a handler returns its Response, and a streamed body —
+      // a page render, a file, an LLM stream — is still being written after that; awaiting
+      // `stop(false)` above was what used to wait for it, websockets and all. Bun's
+      // `pendingRequests` counts exactly the responses not yet finished (a client that went away
+      // included as finished), never an upgraded socket, so this waits for bodies alone and costs
+      // the request path nothing. Polled, and bounded by the drain's own deadline: a body that
+      // never ends (SSE) is cut by the `close` hook's `stop(true)`, not waited on forever.
+      unregisterBodies = onShutdown(
+        `http:${role}:bodies`,
+        async (reason) => {
+          while (
+            (server?.pendingRequests ?? 0) > 0 &&
+            systemClock.monotonic() < reason.deadlineAt
+          ) {
+            await Bun.sleep(BODY_POLL_MS);
+          }
+        },
+        { phase: 'inflight' },
+      );
+      // 'close' runs after core has waited out the in-flight phase, bodies included.
       unregisterClose = onShutdown(
         `http:${role}:close`,
         async () => {
@@ -350,9 +418,12 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       // core's `shutdownHookCount()` exists to make visible. The shape `worker.ts`'s teardown
       // holds: the unregisters are the closure's, not the drain's.
       const releaseHooks = (): void => {
+        releaseStore();
         unregister?.();
+        unregisterBodies?.();
         unregisterClose?.();
         unregister = undefined;
+        unregisterBodies = undefined;
         unregisterClose = undefined;
       };
       if (server === undefined) {

package/src/set-cookie.ts

@@ -0,0 +1,60 @@
+// How a route handler, a page loader or an action sets a cookie on the response it cannot build:
+// one serialized line, from core's one serializer, appended to the context's response-header bag —
+// the bag the `response` stage APPENDS `set-cookie` from, so two cookies are two lines, never one.
+
+import { CookieInvalidError, type SetCookieOptions, serializeSetCookie } from '@ultimat3/core';
+import { assertInRequest } from './context';
+
+/**
+ * What identifies the cookie being cleared, plus the attributes its prefix or partition requires.
+ * A browser deletes only the cookie whose name, `Path` and `Domain` all match — `Partitioned` too
+ * for a CHIPS cookie — so these must be what `setCookie` was given. No `maxAge`, `expires` or
+ * `priority`: the clearing line decides those itself.
+ */
+export type DeleteCookieOptions = Pick<
+  SetCookieOptions,
+  'path' | 'domain' | 'secure' | 'httpOnly' | 'sameSite' | 'partitioned'
+>;
+
+const DELETE_FIX = 'deleteCookie(name, { path, domain })   # the one way to clear a cookie';
+
+/**
+ * Clearing has ONE spelling, `deleteCookie`, so a reader searching for where a cookie dies finds
+ * every site. `maxAge: 0` and an `expires` already past both clear in a browser, so both are
+ * refused here rather than left as a second, unsearchable way to do the same thing.
+ */
+function refuseClearing(name: string, options: SetCookieOptions, now: Date): void {
+  if (options.maxAge === 0) {
+    throw new CookieInvalidError('maxAge', name, 'is 0, which deletes the cookie', DELETE_FIX);
+  }
+  const { expires } = options;
+  if (expires instanceof Date && expires.getTime() <= now.getTime()) {
+    throw new CookieInvalidError(
+      'expires',
+      name,
+      'is not after now, so it deletes the cookie',
+      DELETE_FIX,
+    );
+  }
+}
+
+/**
+ * Set cookie `name` on the response to the request in scope. Defaults are core's:
+ * `Path=/; HttpOnly; Secure; SameSite=Lax`. Every call APPENDS a line — the same name on two
+ * paths is two cookies — and an invalid cookie is `X_COOKIE_INVALID` before anything is appended.
+ * Outside a request it throws `X_NO_REQUEST`: a cookie nobody will receive is a silent failure.
+ */
+export const setCookie = (name: string, value: string, options: SetCookieOptions = {}): void => {
+  const ctx = assertInRequest('setCookie()');
+  refuseClearing(name, options, ctx.now());
+  ctx.headers.append('set-cookie', serializeSetCookie(name, value, options));
+};
+
+/**
+ * Clear cookie `name`: an empty value and `Max-Age=0`, with the `Path` and `Domain` it was set
+ * with (defaults the same as `setCookie`'s, so a cookie set with none is cleared with none).
+ */
+export const deleteCookie = (name: string, options: DeleteCookieOptions = {}): void => {
+  const ctx = assertInRequest('deleteCookie()');
+  ctx.headers.append('set-cookie', serializeSetCookie(name, '', { ...options, maxAge: 0 }));
+};

package/src/stages.ts

@@ -6,6 +6,7 @@
 
 import {
   anonymousActor,
+  BUILD_ID_HEADER,
   inflightCount,
   isAnonymous,
   isDraining,
@@ -15,7 +16,7 @@ import {
 import { signInRedirect } from './auth-redirect';
 import { finalizeCacheHeaders } from './cache-stage';
 import { type HttpConfig, stripBasePath } from './config';
-import { actorView, elapsedMs, type RequestContext } from './context';
+import { elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
 import { checkCsrf, csrfBlocked, selfOrigin } from './csrf';
 import { factsOf, retryAfterOf } from './error-facts';
@@ -38,13 +39,17 @@ import { compose, type Middleware } from './middleware';
 import { navigationGate, redirectForRouter } from './navigation';
 import { overlayResponse } from './overlay';
 import { resolvePreferences } from './preferences';
-import { type RateLimitDecision, type RateLimiter, rateLimitSpends } from './rate-limit';
-import { rateLimited } from './rate-limit-errors';
+import type { RateLimiter } from './rate-limit';
+import {
+  refuseExhaustedAddress,
+  spendRequestBuckets,
+  spendUnauthenticated,
+} from './rate-limit-stage';
 import type { UltimateRequest } from './request';
 import { addVary, problem, redirect } from './response';
 import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
 import { responseSecurityHeaders } from './security-headers';
-import { validate } from './validate';
+import { validateBody } from './validate';
 
 export type StageName =
   | 'request-id'
@@ -93,6 +98,10 @@ export interface Stage extends StageDoc {
  */
 const SHED_RETRY_AFTER_SECONDS = '1';
 
+/** The two names a policy travels under — the enforced one and `reportOnly`'s. */
+const isCspHeader = (name: string): boolean =>
+  name === 'content-security-policy' || name === 'content-security-policy-report-only';
+
 /**
  * The one label a request with no matched route may carry. Every 404 and every scan of `/wp-admin`
  * would otherwise be its own rate-limit bucket and its own metric series — an attacker choosing
@@ -165,12 +174,12 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       const answered = preflight(request.raw, config.cors);
       if (answered !== undefined) return answered;
 
-      ctx.clientBuildId = request.header(config.buildIdHeader);
+      ctx.clientBuildId = request.header(BUILD_ID_HEADER);
       // Stamped BEFORE the assertion, so the refusal carries it too. A skew answer that
       // withholds the server's own id tells a client it is stale without telling it what to
       // become — and the one caller that can act on that, the service worker holding the
       // stale id, then has no way to tell this 409 from any other.
-      if (config.buildId !== null) ctx.headers.set(config.buildIdHeader, config.buildId);
+      if (config.buildId !== null) ctx.headers.set(BUILD_ID_HEADER, config.buildId);
       request.assertBuild();
 
       // A `/<locale>/` prefix is stripped BEFORE the match, never by middleware: middleware wraps
@@ -210,6 +219,11 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       // 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;
+      // A required route is where credentials are guessed: an address that has spent its failures
+      // is refused before the credential store is asked, a right guess included.
+      if (ctx.route?.meta.auth === 'required') {
+        await refuseExhaustedAddress(ctx, limiter, config.rateLimit);
+      }
       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.
@@ -221,53 +235,21 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         }
       }
       if (ctx.route?.meta.auth === 'required' && isAnonymous(ctx.actor)) {
+        // This refusal leaves before `rate-limit` runs, so it is metered here or nowhere: the
+        // address's own allowance, spent only by a failure (`spendUnauthenticated`).
+        await spendUnauthenticated(ctx, limiter, config.rateLimit);
         throw unauthenticated(ctx.url.pathname);
       }
       return undefined;
     },
 
     'rate-limit': async (_request, ctx) => {
-      if (!config.rateLimit.enabled) return undefined;
-      const actor = actorView(ctx.actor);
-      // 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.
-      const spends = rateLimitSpends(
-        {
-          actorId: actor?.id ?? null,
-          orgId: actor?.orgId ?? null,
-          ip: ctx.ip,
-          routeName: ctx.route?.meta.name ?? UNMATCHED_ROUTE,
-        },
-        {
-          route: ctx.route?.meta.rateLimit ?? config.rateLimit.defaultBucket,
-          tenant: config.rateLimit.tenantBucket,
-        },
+      await spendRequestBuckets(
+        ctx,
+        limiter,
+        config.rateLimit,
+        ctx.route?.meta.name ?? UNMATCHED_ROUTE,
       );
-      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) {
-          // The first refusal ends the spend, so a caller its own bucket already refused costs
-          // its tenant nothing — one noisy actor may not drain the allowance it shares.
-          answer = decision;
-          refusedKey = spend.key;
-          break;
-        }
-      }
-      if (answer === undefined) return undefined;
-      // Recorded before the throw so the 429 can carry Retry-After and the
-      // RateLimit-* headers rather than making the client guess.
-      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);
       return undefined;
     },
 
@@ -292,7 +274,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     body: async (request, ctx) => {
       const schema = ctx.route?.meta.input;
       if (schema === undefined) return undefined;
-      const outcome = await validate(schema, await request.bodyRaw());
+      const outcome = await validateBody(schema, await request.bodyRaw());
       if (!outcome.ok) throw bodyInvalid(ctx.url.pathname, outcome.issues);
       ctx.input = outcome.value;
       return undefined;
@@ -394,7 +376,15 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       // never handed a page. Which of the two a browser gets is the ENVIRONMENT — the overlay
       // prints the cause, the fix and the stack, which is what a visitor may never see.
       if (acceptsHtml(request.raw)) {
-        if (config.dev) {
+        // A 4xx is not a defect to debug, it is a page a visitor will see, so dev asks for the
+        // app's own file first (#492, O-492). A 5xx keeps the overlay, and so does a 4xx the app
+        // has no file for: in dev the diagnostic beats the framework's generic page.
+        // A throw from the hook is caught by `recoverWith` and degrades to the problem document.
+        const override =
+          config.dev && facts.status >= 500
+            ? undefined
+            : await hooks.errorPage?.(facts.status, ctx);
+        if (config.dev && override === undefined) {
           // Asked for inside the branch, never above it: the overlay is the only surface a notice
           // has, so a production process — or an agent that asked for json — must not pay a
           // diagnostic's per-request cost to produce findings nothing will render.
@@ -420,10 +410,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
             ...(seconds === undefined ? {} : { retryAfterSeconds: seconds }),
             signInPath: config.signInPath,
           },
-          // The app's own file, read per request by whoever mounted the hook. A throw here is
-          // caught by `recoverWith` and degrades to the problem document, which is the answer a
-          // page whose renderer failed can still give.
-          { override: await hooks.errorPage?.(facts.status, ctx), headers: retryAfter },
+          { override, headers: retryAfter },
         );
       }
       return problem(error, {
@@ -446,7 +433,12 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       if (handedOver !== undefined) ctx.response = handedOver;
       const response = ctx.response;
       if (response === undefined) return undefined;
-      for (const [name, value] of ctx.headers) response.headers.set(name, value);
+      // `Set-Cookie` is the one header that is a LIST of field lines: `set` in this loop kept the
+      // last cookie only, and dropped any the handler had put on its own Response.
+      for (const [name, value] of ctx.headers) {
+        if (name === 'set-cookie') response.headers.append(name, value);
+        else response.headers.set(name, value);
+      }
       for (const [name, value] of Object.entries(
         corsHeaders(config.cors, request.header('origin')),
       )) {
@@ -462,7 +454,11 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       for (const [name, value] of Object.entries(
         responseSecurityHeaders(config.security, ctx.https),
       )) {
-        response.headers.set(name, value);
+        // A policy the handler set is KEPT and the app's is added beside it — comma-joined, two
+        // policies, both enforced — so a handler can only narrow (a `sandbox` on an uploaded file),
+        // never widen. Overwritten, that `sandbox` never reached a browser.
+        if (isCspHeader(name) && response.headers.has(name)) response.headers.append(name, value);
+        else response.headers.set(name, value);
       }
       response.headers.set('server-timing', `total;dur=${elapsedMs(ctx)}`);
       return undefined;

package/src/validate.ts

@@ -55,12 +55,12 @@ const outcome = <Out>(result: {
 export const validateSync = <Out>(schema: Schema<Out>, value: unknown): ValidationOutcome<Out> => {
   const result = schema['~standard'].validate(value);
   if (result instanceof Promise) {
-    return { ok: false, issues: ['schema is async; use validate() for request bodies'] };
+    return { ok: false, issues: ['schema is async; use validateBody() for request bodies'] };
   }
   return outcome<Out>(result);
 };
 
-export const validate = async <Out>(
+export const validateBody = async <Out>(
   schema: Schema<Out>,
   value: unknown,
 ): Promise<ValidationOutcome<Out>> => outcome<Out>(await schema['~standard'].validate(value));