@ultimat3/http 22.15.0 → 24.0.0

package/src/request.ts

@@ -3,10 +3,9 @@
 // context so they cannot drift from what the pipeline resolved.
 
 import type { Actor } from '@ultimat3/core';
-import { readWithinLimit, renderThrowable } from '@ultimat3/core';
+import { readCookie, readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bodyInvalid, buildSkew } from './errors';
-import { readCookie } from './locale';
 import type { Schema } from './validate';
 import { validate, validateSync } from './validate';
 
@@ -203,7 +202,15 @@ export class UltimateRequest {
     // An EMPTY form is a form with no fields, never "no input": a button-only `<form>` posts
     // `content-length: 0`, and reading that as `undefined` failed every schema with 400.
     const form = type === 'application/x-www-form-urlencoded' || type === 'multipart/form-data';
-    if (type === '') return undefined;
+    // No declared type is only "no body" when there are no bytes. `{"a":1}` sent bare used to
+    // read as `undefined`, so a schema whose fields are all optional validated a request nobody
+    // parsed. `bodyBytes()` stays the door for a body that is bytes by design (a signed upload).
+    if (type === '') {
+      if (declared === 0 || (await this.bodyBytes()).byteLength === 0) return undefined;
+      throw bodyInvalid(this.pathname, [
+        'the request carries a body and no content-type header saying what it is',
+      ]);
+    }
     // A multipart body is only a FORM with the boundary its header must announce. Checked before
     // the empty-form shortcut below, so a zero-length body cannot launder a malformed header into
     // `{}` — without it the parser would have refused, and an empty body must refuse the same.

package/src/response.ts

@@ -216,6 +216,14 @@ export const applyCacheHeaders = (response: Response, hint: CacheHint): Response
     response.headers.set('surrogate-key', hint.tags.join(' '));
     response.headers.set('cache-tag', hint.tags.join(','));
   }
+  // A response REWRITTEN to private or no-store may already carry keys: the `cache-headers` stage
+  // turns an `isr` document's shared header into `private` for a signed-in visitor, and the keys
+  // the render wrote beside it would stay on what is now a per-user document — purge keys an
+  // intermediary has no business storing it under.
+  if (!shared) {
+    response.headers.delete('surrogate-key');
+    response.headers.delete('cache-tag');
+  }
   // `cookie` is not optional on the shared path. A `public` response is stored by a CDN under the
   // URL, and every session in this framework travels in a cookie — so without it the first
   // signed-in render of a public page is what every later visitor is served. `SHARED_CACHE_VARY`

package/src/router.ts

@@ -5,7 +5,7 @@
 // PRECEDENCE (deterministic, tested in router.test.ts):
 //   1. static segment   `/posts/new`
 //   2. param segment    `/posts/:id`
-//   3. wildcard segment `/posts/*rest`  (matches ONE OR MORE remaining segments)
+//   3. wildcard segment `/posts/*rest`  (matches ZERO or more remaining segments)
 // Depth-first with backtracking: `/posts/new` beats `/posts/:id` even though the
 // 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
@@ -241,19 +241,32 @@ const candidates = (
 ): void => {
   if (index === segments.length) {
     if (current.routes.size > 0) search.out.push({ node: current, params });
+    // A catch-all with an EMPTY rest: `/docs` for `/docs/*path`, after any static route at
+    // `/docs` itself. It is the path `@ultimat3/render`'s static build writes for that page
+    // (`fillPath` fills an absent rest with `''`), and its `compilePattern` matches it — a server
+    // that 404ed it served a page the export and the ISR lookup both said existed.
+    const rest = current.wildcard;
+    if (rest !== undefined && rest.node.routes.size > 0) {
+      search.out.push({ node: rest.node, params: { ...params, [rest.name]: '' } });
+    }
     return;
   }
   const segment = segments[index];
   if (segment === undefined) return;
+  // Decoded ONCE, for every branch. `undefined` is a malformed escape, which fails only the
+  // branches that needed the decoded form: the raw static lookup below still runs.
+  const decoded = decodeSegment(segment);
 
-  // Static segments are compared raw, never decoded, so a malformed escape only ever fails the
-  // branch that would have decoded it: a path that reaches no param or wildcard is the 404 it
-  // always was, and a static route still wins the precedence it always won.
-  const staticChild = current.statics.get(segment);
+  // Raw first, then the decoded spelling: a route file is named in Unicode (`precios-españa`) and
+  // `URL.pathname` encodes it (`precios-espa%C3%B1a`), so a raw-only lookup 404ed every non-ASCII
+  // literal. A static route still wins the precedence it always won.
+  const staticChild =
+    current.statics.get(segment) ??
+    (decoded !== undefined && decoded !== segment ? current.statics.get(decoded) : undefined);
   if (staticChild !== undefined) candidates(staticChild, segments, index + 1, params, search);
 
   if (current.param !== undefined) {
-    const value = decodeSegment(segment);
+    const value = decoded;
     if (value === undefined) search.undecodable ??= segment;
     else {
       const next = { ...params, [current.param.name]: value };
@@ -330,7 +343,7 @@ const paramsOf = (path: string): readonly string[] =>
     .filter((segment) => segment.startsWith(':') || segment.startsWith('*'))
     .map((segment) => segment.slice(1));
 
-/** Feeds the `/_x` dashboard, the manifest emitter and `x routes list --json`. */
+/** Feeds the `/_x` dashboard, the manifest emitter and `x routes --json`. */
 export const describeRoutes = (table: RouteTable): readonly RouteDescription[] =>
   table.routes
     .map((route) => ({

package/src/server.ts

@@ -7,6 +7,7 @@ import {
   beginWork,
   configureLifecycle,
   drain,
+  healthBody,
   healthzPayload,
   lifecycleState,
   logger,
@@ -18,6 +19,7 @@ import {
 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';
@@ -39,7 +41,7 @@ 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. */
@@ -98,6 +100,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;
 }
 
 /**
@@ -193,10 +197,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 =>
+  const healthResponse = (payload: HealthPayload, request: Request, socket: BunServer): Response =>
     json(
-      { ...payload.body, role },
+      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 +247,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 +307,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,
             ),
         },
       };

package/src/stages.ts

@@ -15,7 +15,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,8 +38,12 @@ 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';
@@ -93,6 +97,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
@@ -181,7 +189,9 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       if (routed instanceof Response) return routed;
       const match = matchRoute(input.table, ctx.method, routed);
       if (!match.ok) {
-        if (match.reason === 'not-found') throw routeNotFound(ctx.method, pathname);
+        if (match.reason === 'not-found') {
+          throw hooks.explainMiss?.(ctx.method, pathname) ?? routeNotFound(ctx.method, pathname);
+        }
         if (match.reason === 'path-invalid') throw pathInvalid(pathname, match.segment);
         ctx.headers.set('allow', match.allow.join(', '));
         throw methodNotAllowed(ctx.method, pathname, match.allow);
@@ -208,6 +218,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.
@@ -219,53 +234,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;
     },
 
@@ -444,7 +427,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')),
       )) {
@@ -460,7 +448,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;