@ultimat3/http 29.3.2 → 30.0.0

package/src/stages.ts

@@ -1,7 +1,7 @@
 // One function per stage name: what each stage of the lifecycle DOES. The package's three-way
 // split, each file naming the other two — `pipeline.ts` owns the ORDER the stages run in and the
 // run itself, `finalize.ts` owns the promise that the tail cannot reject, and this file owns the
-// work. The vocabulary (`StageName`, `Stage`) lives here too, beside the fourteen implementations
+// work. The vocabulary (`StageName`, `Stage`) lives here too, beside the fifteen implementations
 // it names, so `Record<StageName, StageRun>` below is the build error that catches a missing one.
 
 import {
@@ -15,6 +15,7 @@ import {
 } from '@ultimat3/core';
 import { signInRedirect } from './auth-redirect';
 import { finalizeCacheHeaders } from './cache-stage';
+import { compressResponse } from './compress';
 import { type HttpConfig, stripBasePath } from './config';
 import { elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
@@ -66,7 +67,8 @@ export type StageName =
   | 'handler'
   | 'cache-headers'
   | 'error-map'
-  | 'response';
+  | 'response'
+  | 'compress';
 
 /**
  * `request`  may short-circuit by returning a Response.
@@ -79,7 +81,7 @@ export type StagePhase = 'request' | 'terminal' | 'recover' | 'finalize';
 export interface StageDoc {
   readonly name: StageName;
   readonly phase: StagePhase;
-  /** Why the stage sits at this index. Rendered verbatim by the dev dashboard. */
+  /** Why the stage sits at this index, read by `pipeline.test.ts` and anyone reading the list. */
   readonly why: string;
 }
 
@@ -265,12 +267,15 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         selfOrigin: selfOrigin(ctx.url, ctx.https),
         origin: request.header('origin'),
         secFetchSite: request.header('sec-fetch-site'),
-        hasAuthorizationHeader: request.header('authorization') !== null,
+        authorization: request.header('authorization'),
         anonymous: isAnonymous(ctx.actor),
+        cookieless: ctx.route?.meta.csrf === 'cookieless',
         cors: config.cors,
         config: config.csrf,
       });
-      if (!verdict.ok) throw csrfBlocked(ctx.url.pathname, verdict.reason, ctx.ip);
+      if (!verdict.ok) {
+        throw csrfBlocked(ctx.url.pathname, verdict.reason, ctx.ip, selfOrigin(ctx.url, ctx.https));
+      }
       return undefined;
     },
 
@@ -461,11 +466,23 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         // 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);
+        // The strictest referrer policy a handler set is KEPT for the same reason — it narrows: a
+        // file served at a bearer URL (a query's download) must name that URL to nobody.
+        else if (name === 'referrer-policy' && response.headers.get(name) === 'no-referrer')
+          continue;
         else response.headers.set(name, value);
       }
       response.headers.set('server-timing', `total;dur=${elapsedMs(ctx)}`);
       return undefined;
     },
+
+    compress: (request, ctx) =>
+      ctx.response === undefined
+        ? undefined
+        : compressResponse(request.raw, ctx.response, {
+            anonymous: isAnonymous(ctx.actor),
+            signal: ctx.signal,
+          }),
   };
   return table;
 };

package/src/stored-object-headers.ts

@@ -0,0 +1,43 @@
+// How a stored object may be presented when the app's own origin serves it (plan 101, s1-sec L6):
+// inline only for a type a browser renders without running anything, a sandboxed download otherwise.
+// Read by `objectResponse`, the one way a stored object is answered.
+
+/**
+ * Raster images, audio and video: what an `<img>`, `<audio>` or `<video>` presents and nothing
+ * executes. NOT `image/svg+xml` (it carries `<script>`), `text/html`, `application/xml` or PDF —
+ * any of them opened from the app's origin runs with the app's cookies and its `'self'` sources.
+ */
+const INLINE_TYPES: ReadonlySet<string> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'audio/mpeg',
+  'audio/ogg',
+  'audio/wav',
+  'audio/webm',
+  'video/mp4',
+  'video/webm',
+  'video/ogg',
+]);
+
+/** `image/PNG; charset=…` is `image/png`: parameters and case never widen the list. */
+const essenceOf = (contentType: string): string =>
+  (contentType.split(';')[0] ?? '').trim().toLowerCase();
+
+export const isInlineSafe = (contentType: string): boolean =>
+  INLINE_TYPES.has(essenceOf(contentType));
+
+/**
+ * The headers a stored object is served with beyond its type. `attachment` makes a navigation to an
+ * uploaded `text/html` a download instead of a page on the app's origin; an embedding element
+ * (`<img>`, `<video>`) ignores it, so nothing that displays an object inline stops working. The
+ * `sandbox` policy is for the browser that renders it anyway: an opaque origin, no script, no
+ * cookies. The security stage keeps it and adds the app's policy beside it.
+ */
+export function storedObjectHeaders(contentType: string): Readonly<Record<string, string>> {
+  return isInlineSafe(contentType)
+    ? {}
+    : { 'content-disposition': 'attachment', 'content-security-policy': 'sandbox' };
+}

package/src/webhook-hmac.ts

@@ -0,0 +1,73 @@
+// `verifyBodyHmac`: the one vendor-neutral check many inbound webhooks share — HMAC-SHA256 under a
+// UTF-8 secret over bytes the caller names, compared in constant time, under any secret of a
+// rotation list. It does not decode a secret (Svix's base64 `whsec_` key is the mail receivers'),
+// and the bytes and the header are the vendor's: no vendor verifier ships (axiom 8).
+
+import { hmac, timingSafeEqual } from '@ultimat3/core';
+import { webhookSignatureInvalid } from './errors';
+import { assertWebhookSecrets } from './webhook-verify';
+
+export interface BodyHmacOptions {
+  /** The bytes the vendor signed. A string is its UTF-8 encoding. */
+  readonly bytes: Uint8Array | string;
+  /** The shared secret, or the list a rotation keeps live — any one of them verifies. */
+  readonly secret: string | readonly string[];
+  /** The mac the request carried, header value as sent. Absent or empty is a refusal. */
+  readonly given: string | null | undefined;
+  readonly encoding: 'hex' | 'base64';
+  /** What precedes the mac in `given`: `sha256=` (GitHub), `v0=` (Slack). Compared, not stripped. */
+  readonly prefix?: string;
+}
+
+/**
+ * What a passing check answers: the bytes it verified, and their text when they are UTF-8. Read
+ * the event id from HERE, never from an unsigned header — an id outside the mac lets one captured
+ * signature replay under any id the attacker picks.
+ */
+export interface VerifiedBody {
+  readonly bytes: Uint8Array;
+  readonly text: string | null;
+}
+
+/** `fatal`: invalid UTF-8 is `null` text, never replacement characters an id could be read from. */
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+/**
+ * Prove `given` is `prefix + HMAC-SHA256(secret, bytes)` for one of the secrets, and answer what
+ * was verified. Throws `X_WEBHOOK_SIGNATURE_INVALID` (401) on a mismatch and `X_CONFIG_INVALID`
+ * for no usable secret.
+ */
+export function verifyBodyHmac(options: BodyHmacOptions): VerifiedBody {
+  const secrets = assertWebhookSecrets(options.secret, 'verifyBodyHmac');
+  const given = options.given ?? '';
+  if (given === '') {
+    throw webhookSignatureInvalid(
+      'verifyBodyHmac',
+      'the request carried no signature',
+      'verifyBodyHmac',
+    );
+  }
+  const prefix = options.prefix ?? '';
+  let matched = false;
+  // Every secret is tried, even after a match: which one matched is not worth a timing signal.
+  for (const secret of secrets) {
+    const expected = `${prefix}${hmac('sha256', secret, options.bytes, options.encoding)}`;
+    if (timingSafeEqual(expected, given)) matched = true;
+  }
+  if (!matched) {
+    throw webhookSignatureInvalid(
+      'verifyBodyHmac',
+      `no ${options.encoding} sha256 mac${prefix === '' ? '' : ` behind the "${prefix}" prefix`} under the ${secrets.length} configured secret(s) matches the bytes`,
+      'verifyBodyHmac',
+    );
+  }
+  const bytes =
+    typeof options.bytes === 'string' ? new TextEncoder().encode(options.bytes) : options.bytes;
+  let text: string | null;
+  try {
+    text = typeof options.bytes === 'string' ? options.bytes : strictUtf8.decode(bytes);
+  } catch {
+    text = null;
+  }
+  return { bytes, text };
+}

package/src/webhook-verify.ts

@@ -3,11 +3,10 @@
 // a pipeline stage because a receiver is an ordinary `api/` route — the secret is per sender, and
 // only the route knows which one applies.
 //
-// THE FORMAT IS `@ultimat3/core`'s (`webhook-signature.ts`) and is not re-declared here. That
-// module is at the tier both halves can reach: `@ultimat3/jobs` (tier 3) signs a delivery and its
-// boundary forbids this package, and this package (tier 2) may not reach tier 3. What stays here
-// is the POLICY — what counts as fresh, how large a body may be, and which refusal a receiver
-// answers with.
+// THE FORMAT IS `@ultimat3/core`'s (`webhook-signature.ts`) and is not re-declared here: this
+// package (tier 2) may not reach `@ultimat3/jobs` (tier 3), which signs, so the format sits below
+// both. What stays here is the POLICY — what counts as fresh, how large a body may be, and which
+// refusal a receiver answers with.
 
 import type { Clock } from '@ultimat3/core';
 import {
@@ -22,6 +21,7 @@ import {
   WEBHOOK_TOPIC_HEADER,
   webhookMac,
 } from '@ultimat3/core';
+import type { WebhookVerifier } from './errors';
 import {
   bodyInvalid,
   httpCountInvalid,
@@ -93,6 +93,27 @@ const assertWebhookSecret = (secret: unknown): string => {
   );
 };
 
+/**
+ * The same screen over a rotation list (`verifyBodyHmac`): one entry or several, every one
+ * non-empty, and at least one. One empty entry refuses the list — `[current, process.env.OLD]`
+ * with `OLD` unset would otherwise verify anything under the empty key.
+ */
+export const assertWebhookSecrets = (
+  secret: unknown,
+  via: WebhookVerifier = 'verifyWebhookSignature',
+): readonly string[] => {
+  const list: readonly unknown[] = Array.isArray(secret) ? secret : [secret];
+  if (list.length === 0) throw webhookSecretMissing('an empty list', via);
+  for (const entry of list) {
+    if (typeof entry === 'string' && entry.length > 0) continue;
+    throw webhookSecretMissing(
+      entry === '' ? 'an empty string' : `a value of type ${typeof entry}`,
+      via,
+    );
+  }
+  return list as readonly string[];
+};
+
 export interface WebhookVerifyOptions {
   /** The shared secret for THIS sender. Never logged, never rendered into a refusal. */
   readonly secret: string;

package/src/websocket-mounts.ts

@@ -0,0 +1,104 @@
+// Several websocket mounts on ONE listener. `Bun.serve` takes one `websocket` handler set for every
+// socket it opens, so the mounts are joined here: an upgrade is routed by path, and each socket's
+// events go back to the mount that upgraded it — keyed by the `data` object that mount handed
+// `server.upgrade`, which Bun returns as `ws.data`. No mount's socket is wrapped or proxied.
+
+import { assert } from '@ultimat3/core';
+import type { UpgradeTarget, WebSocketMount } from './server';
+
+/**
+ * A mount's handler set with Bun's optional `drain`: the sync node answers it with its
+ * backpressure gap repair, and a join that dropped it left a refused frame's socket gapped.
+ */
+export type MountHandlers<TSocket> = WebSocketMount<TSocket>['websocket'] & {
+  drain?(ws: TSocket): void;
+};
+
+/** What `httpServer` dispatches: every path the mounts own, one fetch, one handler set. */
+export interface JoinedWebSocketMounts {
+  readonly paths: ReadonlySet<string>;
+  fetch(
+    request: Request,
+    server: UpgradeTarget,
+  ): Promise<Response | undefined> | Response | undefined;
+  readonly websocket: MountHandlers<{ readonly data: unknown }>;
+}
+
+/** Bun's per-listener knobs, joined so no mount gets less than it declared. */
+function joinedLimits(mounts: readonly WebSocketMount<never>[]) {
+  const max = (pick: (mount: WebSocketMount<never>) => number | undefined): number | undefined => {
+    const values = mounts.map(pick).filter((value): value is number => value !== undefined);
+    return values.length === 0 ? undefined : Math.max(...values);
+  };
+  const idleTimeout = max((mount) => mount.websocket.idleTimeout);
+  const backpressureLimit = max((mount) => mount.websocket.backpressureLimit);
+  const maxPayloadLength = max((mount) => mount.websocket.maxPayloadLength);
+  const sendPings = mounts.some((mount) => mount.websocket.sendPings === true);
+  return {
+    ...(idleTimeout === undefined ? {} : { idleTimeout }),
+    ...(backpressureLimit === undefined ? {} : { backpressureLimit }),
+    ...(maxPayloadLength === undefined ? {} : { maxPayloadLength }),
+    ...(sendPings ? { sendPings } : {}),
+  };
+}
+
+/**
+ * The mounts, joined. Two at one path is `X_INVARIANT` here — the same fact `httpServer` refuses
+ * between a mount and a route. The listener's limits are the widest any mount declared, so Bun
+ * enforces only those: a mount whose own bound is tighter (the sync node's `maxFrameBytes`, the
+ * device socket's frame cap) refuses past it in its own `message`, never through Bun alone.
+ */
+export function joinWebSocketMounts(
+  mounts: readonly WebSocketMount<never>[],
+): JoinedWebSocketMounts {
+  const byPath = new Map<string, WebSocketMount<never>>();
+  for (const mount of mounts) {
+    assert(
+      !byPath.has(mount.path),
+      `two websocket mounts claim ${mount.path}, and a path is answered by one of them`,
+      'x routes --json   # then move one mount to a path of its own',
+    );
+    byPath.set(mount.path, mount);
+  }
+  // A socket's owner, by the identity of the data its mount upgraded it with.
+  const owners = new WeakMap<object, WebSocketMount<never>>();
+  const ownerOf = (ws: { readonly data: unknown }): WebSocketMount<never> | undefined =>
+    typeof ws.data === 'object' && ws.data !== null ? owners.get(ws.data) : undefined;
+  // `never` is each mount's own socket type, unknown to this file: the socket handed back is the
+  // one that mount's upgrade produced, so the widening below is the only way to return it.
+  const hand = (ws: { readonly data: unknown }): never => ws as never;
+  // Read through the wider type: `drain` is optional, so every mount's handler set is one.
+  const handlersOf = (mount?: WebSocketMount<never>): MountHandlers<never> | undefined =>
+    mount?.websocket;
+  return {
+    paths: new Set(byPath.keys()),
+    fetch(request, server) {
+      const mount = byPath.get(new URL(request.url).pathname);
+      if (mount === undefined) return new Response('not found', { status: 404 });
+      const recording: UpgradeTarget = {
+        upgrade(upgraded, options) {
+          const { data } = options;
+          assert(
+            typeof data === 'object' && data !== null,
+            `the websocket mount at ${mount.path} upgraded with data that is not an object, so its socket cannot be routed back to it`,
+            'server.upgrade(request, { data: { socketId } })   # an object, in the mount at that path',
+          );
+          owners.set(data, mount);
+          return server.upgrade(upgraded, options);
+        },
+        requestIP: (asked) => server.requestIP(asked),
+      };
+      return mount.fetch(request, recording);
+    },
+    websocket: {
+      open: (ws) => ownerOf(ws)?.websocket.open(hand(ws)),
+      message: (ws, message) => ownerOf(ws)?.websocket.message(hand(ws), message),
+      close: (ws) => ownerOf(ws)?.websocket.close(hand(ws)),
+      // Present only when a mount answers it: Bun calls it once a socket's buffer can take frames.
+      ...(mounts.some((mount) => handlersOf(mount)?.drain !== undefined)
+        ? { drain: (ws) => handlersOf(ownerOf(ws))?.drain?.(hand(ws)) }
+        : {}),
+      ...joinedLimits(mounts),
+    },
+  };
+}