@zerotal/core 1.0.0

package/src/http/negotiate.ts

@@ -0,0 +1,213 @@
+/**
+ * Content negotiation: detects whether a request is a browser, API, or CLI
+ * client and dispatches to the matching handler, giving each branch a context
+ * tailored to that channel (session helpers for web, ANSI output for CLI, …).
+ */
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+
+// ── ANSI helpers ───────────────────────────────────────────────────────────────
+
+const ANSI: Record<string, string> = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+/** A supported ANSI text color for CLI output. */
+export type AnsiColor = "red" | "green" | "yellow" | "blue" | "cyan" | "dim";
+
+// ── Channel detection ──────────────────────────────────────────────────────────
+
+/** The client channel a request arrived on. */
+export type Channel = "web" | "json" | "cli";
+
+/**
+ * Detect which channel the current request is coming from.
+ *
+ * Priority:
+ * 1. `X-Zerotal-Channel: cli` — set by the Zerotal CLI binary
+ * 2. CLI user-agent patterns: curl, wget, HTTPie
+ * 3. `Accept: application/json` — API / SPA client
+ * 4. Default: web browser
+ */
+export function detectChannel(ctx: HttpContext): Channel {
+  if (ctx.header("X-Zerotal-Channel") === "cli") return "cli";
+
+  const userAgent = ctx.header("User-Agent") ?? "";
+  if (/^(curl|wget|httpie)\//i.test(userAgent)) return "cli";
+
+  if (ctx.wantsJson()) return "json";
+
+  return "web";
+}
+
+// ── Channel-specific context interfaces ───────────────────────────────────────
+
+/**
+ * Context passed to the `web` branch of `negotiate()`.
+ *
+ * Exposes session-aware helpers (flash, redirect-back). Session access is only
+ * safe here because the web channel guarantees a Cookie-based session is present.
+ */
+export interface WebContext {
+  readonly ctx: HttpContext;
+  redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): void;
+  back(status?: 301 | 302 | 303 | 307 | 308): void;
+  view(markup: string | { toString(): string }, status?: number): void;
+  html(markup: string | { toString(): string }, status?: number): void;
+  json(data: unknown, status?: number): void;
+  flash(key: string, value: unknown): void;
+  flashed<T = unknown>(key: string): T | undefined;
+}
+
+/**
+ * Context passed to the `json` branch of `negotiate()`.
+ *
+ * Stateless — no session, no cookies. Caller is an API client or SPA.
+ */
+export interface ApiContext {
+  readonly ctx: HttpContext;
+  json(data: unknown, status?: number): void;
+  bearerToken(): string | null;
+}
+
+/**
+ * Context passed to the `cli` branch of `negotiate()`.
+ *
+ * Terminal-oriented. Exposes ANSI helpers and plain-text HTTP responses.
+ * Session and redirect helpers are intentionally absent.
+ */
+export interface CliContext {
+  readonly ctx: HttpContext;
+  /** Set a plain-text HTTP response with explicit status. */
+  text(content: string, status?: number): void;
+  /** Write to stdout without affecting the HTTP response. */
+  write(content: string): void;
+  writeln(content: string): void;
+  /** Write a colored line to stdout without affecting the HTTP response. */
+  line(content: string, color?: AnsiColor): void;
+  /** Set a 500 plain-text response with ANSI red message. */
+  error(message: string): void;
+  /** Set a 200 plain-text response with ANSI green message. */
+  success(message: string): void;
+  /** Set a 200 plain-text response with ANSI yellow message. */
+  warn(message: string): void;
+  /** Set a 200 plain-text response with ANSI blue message. */
+  info(message: string): void;
+}
+
+// ── Context factories ─────────────────────────────────────────────────────────
+
+function makeWebContext(ctx: HttpContext): WebContext {
+  return {
+    ctx,
+    redirect: (url, status) => ctx.redirect(url, status),
+    back: (status) => ctx.back(status),
+    view: (markup, status) => ctx.view(markup, status),
+    html: (markup, status) => ctx.html(markup, status),
+    json: (data, status) => ctx.json(data, status),
+    flash: (key, value) => ctx.flash(key, value),
+    flashed: (key) => ctx.flashed(key),
+  };
+}
+
+function makeApiContext(ctx: HttpContext): ApiContext {
+  return {
+    ctx,
+    json: (data, status) => ctx.json(data, status),
+    bearerToken: () => ctx.bearerToken(),
+  };
+}
+
+function makeCliContext(ctx: HttpContext): CliContext {
+  const colorize = (text: string, color: AnsiColor): string =>
+    `${ANSI[color]}${text}${ANSI["reset"]}`;
+
+  const textResponse = (content: string, status = 200): void => {
+    ctx.response = new Response(content + "\n", {
+      status,
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+  };
+
+  return {
+    ctx,
+    text: textResponse,
+    write: (content) => {
+      process.stdout.write(content);
+    },
+    writeln: (content) => {
+      process.stdout.write(content + "\n");
+    },
+    line: (content, color) => {
+      process.stdout.write((color ? colorize(content, color) : content) + "\n");
+    },
+    error: (message) => textResponse(colorize(message, "red"), 500),
+    success: (message) => textResponse(colorize(message, "green"), 200),
+    warn: (message) => textResponse(colorize(message, "yellow"), 200),
+    info: (message) => textResponse(colorize(message, "blue"), 200),
+  };
+}
+
+// ── negotiate() ───────────────────────────────────────────────────────────────
+
+/** The per-channel handlers passed to `negotiate()`; `cli` falls back to `json` when omitted. */
+export interface NegotiateMap<TWeb = void, TJson = void, TCli = void> {
+  web: (web: WebContext) => TWeb | Promise<TWeb>;
+  json: (api: ApiContext) => TJson | Promise<TJson>;
+  cli?: (cli: CliContext) => TCli | Promise<TCli>;
+}
+
+/**
+ * Polymorphic execution primitive — routes handling to the channel-appropriate
+ * closure based on how the request arrived.
+ *
+ * Works in controllers to return channel-appropriate responses:
+ * @example
+ * async store(ctx: HttpContext) {
+ *   const post = await Post.create(await ctx.body());
+ *   return negotiate(ctx)({
+ *     web:  (w) => { w.flash('success', 'Post created!'); w.redirect('/posts'); },
+ *     json: (a) => a.json({ data: post }, 201),
+ *     cli:  (c) => c.success(`Post #${post.id} created.`),
+ *   });
+ * }
+ *
+ * Works in middleware to block, redirect, or pass through per channel:
+ * @example
+ * async handle(ctx, next) {
+ *   if (!ctx.user) {
+ *     await negotiate(ctx)({
+ *       web:  (w) => w.redirect('/login'),
+ *       json: (a) => a.json({ message: 'Unauthenticated.' }, 401),
+ *       cli:  (c) => c.error('Authentication required.'),
+ *     });
+ *     return ctx; // short-circuit — response is already set
+ *   }
+ *   return next(ctx);
+ * }
+ *
+ * When no `cli` handler is provided, CLI requests fall back to the `json` branch
+ * (curl / wget users expect structured output).
+ */
+export function negotiate(ctx: HttpContext) {
+  const channel = detectChannel(ctx);
+
+  return async function <TWeb = void, TJson = void, TCli = void>(
+    map: NegotiateMap<TWeb, TJson, TCli>,
+  ): Promise<TWeb | TJson | TCli | void> {
+    if (channel === "cli" && map.cli) {
+      return map.cli(makeCliContext(ctx));
+    }
+
+    if (channel === "json" || channel === "cli") {
+      return map.json(makeApiContext(ctx));
+    }
+
+    return map.web(makeWebContext(ctx));
+  };
+}

package/src/http/originGuard.ts

@@ -0,0 +1,76 @@
+/**
+ * Origin checking for endpoints that bypass the normal middleware pipeline.
+ *
+ * Two request shapes in the framework are not protected by `CsrfMiddleware`:
+ *
+ *  - **WebSocket upgrades.** The handshake is exempt from the same-origin policy but still
+ *    carries cookies, so `evil.com` opening `wss://app/...` gets a fully authenticated socket.
+ *    That is cross-site WebSocket hijacking, and an `Origin` check is the standard defence —
+ *    browsers always send the header on a WS handshake and script cannot forge it.
+ *
+ *  - **Raw routes** registered via `Router.raw()`, which are stored outside the pipeline.
+ *    Flow's `/__flow/http` action fallback is one: a cross-origin `fetch` with
+ *    `credentials: "include"` and the default `text/plain` content type is a CORS-*simple*
+ *    request, so there is no preflight to stop it and no CSRF middleware in its path.
+ *
+ * The check is deliberately conservative about non-browser clients: a request with no `Origin`
+ * header is allowed, because native/CLI clients do not send one and are not subject to
+ * cross-site request forgery in the first place. Anything that *does* declare an origin must
+ * declare one we recognise.
+ */
+
+/**
+ * Whether a request's `Origin` header is acceptable for a credentialed, pipeline-bypassing
+ * endpoint.
+ *
+ * @param request - The incoming request. Its own URL supplies the server origin.
+ * @param allowedOrigins - Additional origins to accept, for deployments where the browser
+ *   app is served from a different host than the API (e.g. an SPA on `app.example.com`
+ *   talking to `api.example.com`). Compared exactly — no wildcards, no suffix matching,
+ *   because `endsWith(".example.com")` also matches `evil-example.com`.
+ * @returns `true` when the request may proceed.
+ *
+ * @example
+ * ```ts
+ * if (!isAllowedOrigin(req, config('app.wsAllowedOrigins'))) {
+ *   return new Response('Forbidden origin', { status: 403 });
+ * }
+ * ```
+ */
+export function isAllowedOrigin(request: Request, allowedOrigins: string[] = []): boolean {
+  const origin = request.headers.get("origin");
+
+  // No Origin: not a browser-initiated cross-site request. Native clients, server-to-server
+  // callers and most CLI tooling omit it entirely.
+  if (origin === null || origin === "") return true;
+
+  // "null" is what a sandboxed iframe, a `data:` document or a redirected cross-origin request
+  // sends. It is never a legitimate first-party caller, so it is refused explicitly rather than
+  // falling through to the URL comparison below (where `new URL("null")` would throw).
+  if (origin === "null") return false;
+
+  let selfOrigin: string;
+  try {
+    selfOrigin = new URL(request.url).origin;
+  } catch {
+    return false;
+  }
+
+  if (origin === selfOrigin) return true;
+  return allowedOrigins.includes(origin);
+}
+
+/**
+ * Read the configured extra origins for pipeline-bypassing endpoints.
+ *
+ * Kept separate from {@link isAllowedOrigin} so the check itself stays pure and trivially
+ * testable. Returns an empty list when unset or malformed — i.e. same-origin only, which is
+ * the safe default.
+ *
+ * @param config - The resolved `app` config object, or anything shaped like it.
+ */
+export function allowedOriginsFrom(config: unknown): string[] {
+  const value = (config as { allowedOrigins?: unknown } | null | undefined)?.allowedOrigins;
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+}

package/src/http/sniffContentType.ts

@@ -0,0 +1,105 @@
+/**
+ * Content-type detection from a file's own bytes.
+ *
+ * An upload arrives with two client-supplied claims about what it is — the filename's
+ * extension and the multipart part's `Content-Type` — and neither is evidence. Storing
+ * either verbatim is how `avatar` with filename `x.html` and `Content-Type: text/html`
+ * becomes stored XSS on the asset origin. These helpers read the leading bytes instead.
+ */
+
+/** Signature table: leading bytes → the content type they identify. */
+interface Signature {
+  /** Byte prefix, or `null` for positions that may hold anything. */
+  magic: (number | null)[];
+  /** Offset the prefix starts at. */
+  offset?: number;
+  type: string;
+  extension: string;
+  /** Extra check for formats whose prefix alone is ambiguous (RIFF, ISO-BMFF). */
+  verify?: (bytes: Uint8Array) => boolean;
+}
+
+const _ascii = (s: string): number[] => [...s].map((c) => c.charCodeAt(0));
+
+const _at = (bytes: Uint8Array, offset: number, text: string): boolean =>
+  _ascii(text).every((code, i) => bytes[offset + i] === code);
+
+/**
+ * Ordered most-specific first. Deliberately narrow: this covers the formats an app
+ * actually accepts as uploads, and everything else falls through to a type that browsers
+ * will not execute.
+ */
+const SIGNATURES: Signature[] = [
+  { magic: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], type: "image/png", extension: "png" },
+  { magic: [0xff, 0xd8, 0xff], type: "image/jpeg", extension: "jpg" },
+  { magic: _ascii("GIF87a"), type: "image/gif", extension: "gif" },
+  { magic: _ascii("GIF89a"), type: "image/gif", extension: "gif" },
+  {
+    magic: _ascii("RIFF"),
+    type: "image/webp",
+    extension: "webp",
+    verify: (b) => _at(b, 8, "WEBP"),
+  },
+  { magic: [0x42, 0x4d], type: "image/bmp", extension: "bmp" },
+  { magic: [0x00, 0x00, 0x01, 0x00], type: "image/x-icon", extension: "ico" },
+  { magic: _ascii("%PDF-"), type: "application/pdf", extension: "pdf" },
+  { magic: [0x1f, 0x8b], type: "application/gzip", extension: "gz" },
+  // ISO base media format: the box size occupies bytes 0-3, the brand starts at 4.
+  { magic: _ascii("ftyp"), offset: 4, type: "video/mp4", extension: "mp4" },
+  { magic: _ascii("OggS"), type: "audio/ogg", extension: "ogg" },
+  { magic: [0x49, 0x44, 0x33], type: "audio/mpeg", extension: "mp3" },
+  {
+    magic: _ascii("RIFF"),
+    type: "audio/wav",
+    extension: "wav",
+    verify: (b) => _at(b, 8, "WAVE"),
+  },
+  // ZIP container. Also the envelope for docx/xlsx/pptx, which is why the extension it
+  // reports is the neutral one — distinguishing them needs the central directory.
+  { magic: [0x50, 0x4b, 0x03, 0x04], type: "application/zip", extension: "zip" },
+];
+
+/** Type stored when the bytes match nothing known. Browsers never execute it. */
+export const FALLBACK_CONTENT_TYPE = "application/octet-stream";
+
+/** Extension stored when the bytes match nothing known. */
+export const FALLBACK_EXTENSION = "bin";
+
+/** What {@link sniffContentType} determined about a file. */
+export interface SniffedType {
+  /** The detected media type, or {@link FALLBACK_CONTENT_TYPE} when unrecognised. */
+  contentType: string;
+  /** The canonical extension for that type, or {@link FALLBACK_EXTENSION}. */
+  extension: string;
+  /** Whether the bytes actually matched a signature, as opposed to falling back. */
+  recognised: boolean;
+}
+
+/**
+ * Identify a file from its leading bytes.
+ *
+ * Recognises the common image, document, archive and media formats. Anything else — a
+ * text file, a format not in the table, or a crafted polyglot — reports
+ * {@link FALLBACK_CONTENT_TYPE}, which is the safe answer: an unrecognised upload served
+ * as `application/octet-stream` downloads, it does not execute.
+ *
+ * @param bytes - The file's contents (only the first 16 bytes are read).
+ * @returns The detected type, extension, and whether detection actually succeeded.
+ *
+ * @example
+ * const { contentType, extension } = sniffContentType(await file.bytes());
+ */
+export function sniffContentType(bytes: Uint8Array): SniffedType {
+  for (const sig of SIGNATURES) {
+    const offset = sig.offset ?? 0;
+    const matches = sig.magic.every((byte, i) => byte === null || bytes[offset + i] === byte);
+    if (!matches) continue;
+    if (sig.verify && !sig.verify(bytes)) continue;
+    return { contentType: sig.type, extension: sig.extension, recognised: true };
+  }
+  return {
+    contentType: FALLBACK_CONTENT_TYPE,
+    extension: FALLBACK_EXTENSION,
+    recognised: false,
+  };
+}

package/src/http/url.ts

@@ -0,0 +1,204 @@
+/**
+ * The application URL service — generation **and** signing in one place.
+ *
+ * There are two URL constructs in Zerotal; this is the high-level one:
+ *
+ *  - {@link Uri} (`uri()`) — a low-level, immutable URI *value object*: parse a URL and
+ *    fluently rewrite its scheme/host/path/query/fragment. Use it to manipulate any URL.
+ *  - **`Url` / `url()`** (this file) — the app-aware URL *service*: build fully-qualified
+ *    URLs for paths, named routes, the current/previous request, the `intended` URL, AND
+ *    generate/verify HMAC-signed, time-limited links.
+ *
+ * `Url` and `url()` are the same object — `url()` is the function form, `Url` the facade.
+ *
+ * @example
+ * url("user/profile");          // "https://app.test/user/profile"
+ * url("user/profile", [1]);     // "https://app.test/user/profile/1"  (extra path segments)
+ *
+ * Url.current();                // current URL, without the query string
+ * Url.full();                   // current URL, with the query string
+ * Url.to("posts", [42]);        // "https://app.test/posts/42"
+ * Url.route("posts.show", { id: 42 });
+ * Url.intended("/dashboard");   // the post-login target, with open-redirect guard
+ *
+ * // Signed, time-limited links (uses APP_KEY unless a secret is passed):
+ * const link = Url.sign("https://app.test/verify", { email }, 15); // expires in 15 min
+ * if (Url.verify(link)) { ... }                                    // false if tampered/expired
+ */
+import { RequestContext } from "../context/RequestContext.ts";
+import { route } from "../router/Router.ts";
+import { ZerotalError } from "../errors/ZerotalError.ts";
+import { URLSigner } from "../crypt/URLSigner.ts";
+import { Uri, appBaseUrl, type QueryInput } from "./Uri.ts";
+
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+// ── Signing ──────────────────────────────────────────────────────────────────
+// HMAC-SHA256 signed URLs for email verification, password resets, invite/one-time
+// links. Signs with APP_KEY by default (the same key as `Crypt`), or an explicit secret.
+
+/** Raised when signing is used without an `APP_KEY` configured and no explicit secret. */
+export class UrlKeyMissingError extends ZerotalError {
+  constructor() {
+    super(
+      "[Zerotal] URL signing requires APP_KEY. Generate one with `zerotal key:generate`.",
+      "E_URL_NO_KEY",
+      500,
+    );
+  }
+}
+
+let _secret: string | null = null;
+let _signer: URLSigner | null = null;
+
+function _signerFor(secret?: string): URLSigner {
+  if (secret) return new URLSigner(secret);
+  if (_signer) return _signer;
+  const key = _secret ?? Bun.env["APP_KEY"];
+  if (!key) throw new UrlKeyMissingError();
+  _signer = new URLSigner(key);
+  return _signer;
+}
+
+/** Resolve the base origin: configured app URL, else the current request's origin, else "". */
+function base(): string {
+  const configured = appBaseUrl();
+  if (configured) return configured;
+  return RequestContext.tryGet()?.url.origin ?? "";
+}
+
+/** Join a path with extra segments: ("user/profile", [1]) → "/user/profile/1". */
+function joinPath(path: string, extra: (string | number)[] = []): string {
+  if (SCHEME_RE.test(path)) {
+    const tail = extra.map((e) => encodeURIComponent(String(e))).join("/");
+    return tail ? `${path.replace(/\/+$/, "")}/${tail}` : path;
+  }
+  const head = path.replace(/^\/+|\/+$/g, "");
+  const segs = extra.map((e) => encodeURIComponent(String(e)));
+  return "/" + [head, ...segs].filter((s) => s !== "").join("/");
+}
+
+/** Build a fully-qualified URL string for a path (+ optional extra segments). */
+function toUrl(path: string, extra: (string | number)[] = [], secure = false): string {
+  const joined = joinPath(path, extra);
+  if (SCHEME_RE.test(joined)) {
+    return secure ? Uri.of(joined).withScheme("https").value() : joined;
+  }
+  const origin = base();
+  const abs = origin ? `${origin}${joined}` : joined;
+  return secure ? Uri.of(abs).withScheme("https").value() : abs;
+}
+
+/** Returned by `url()` (no arguments) — the URL generator surface. */
+export interface UrlGenerator {
+  /** Checks if the current URL matches a given path. */
+  is(path: string): boolean;
+  /** The current request URL, WITHOUT the query string. */
+  current(): string;
+  /** The current request URL, WITH the query string. */
+  full(): string;
+  /** The previous URL (the `Referer` header), falling back to `fallback`. */
+  previous(fallback?: string): string;
+  /** A fully-qualified URL for a path (+ optional extra path segments). */
+  to(path: string, extra?: (string | number)[], secure?: boolean): string;
+  /** A fully-qualified HTTPS URL. */
+  secure(path: string, extra?: (string | number)[]): string;
+  /** A fully-qualified URL with a query string appended. */
+  query(path: string, query: QueryInput, extra?: (string | number)[]): string;
+  /** A fully-qualified URL for a named route. */
+  route(name: string, params?: Record<string, string | number>): string;
+  /**
+   * The URL the user was heading to before authentication (the session's `intended_url`),
+   * falling back to `fallback`. Cross-origin stored URLs are rejected (open-redirect guard).
+   * Returns a plain string.
+   *
+   * @example
+   * url().intended("/dashboard");
+   */
+  intended(fallback?: string): string;
+
+  // ── Signed URLs ──────────────────────────────────────────────────────────────
+
+  /**
+   * Build an HMAC-signed, time-limited URL. Signs with `APP_KEY` unless `secret` is given.
+   *
+   * @param base   The base URL (scheme + host + path).
+   * @param params Extra query parameters to include (encoded into the signature).
+   * @param expiresInMinutes Minutes until the link expires. Default 60.
+   * @param secret Sign with this key instead of `APP_KEY`.
+   */
+  sign(
+    base: string,
+    params?: Record<string, string>,
+    expiresInMinutes?: number,
+    secret?: string,
+  ): string;
+  /** Verify a signed URL — `false` if tampered, expired, or unsigned. */
+  verify(signedUrl: string, secret?: string): boolean;
+  /** Override the default signing secret (otherwise derived from `APP_KEY`). */
+  setSecret(secret: string): void;
+}
+
+const generator: UrlGenerator = {
+  is(path) {
+    if (path.endsWith("*")) {
+      const prefix = path.slice(0, -1);
+      return Uri.current().value().startsWith(prefix);
+    }
+    return Uri.current().value() === toUrl(path);
+  },
+  current() {
+    return Uri.current().replaceQuery({}).withFragment(undefined).value();
+  },
+  full() {
+    return RequestContext.get().fullUrl();
+  },
+  previous(fallback = "/") {
+    const ctx = RequestContext.tryGet();
+    const referer = ctx?.request.headers.get("referer") ?? ctx?.request.headers.get("referrer");
+    return referer ?? toUrl(fallback);
+  },
+  to(path, extra = [], secure = false) {
+    return toUrl(path, extra, secure);
+  },
+  secure(path, extra = []) {
+    return toUrl(path, extra, true);
+  },
+  query(path, query, extra = []) {
+    return Uri.of(toUrl(path, extra)).withQuery(query).value();
+  },
+  route(name, params = {}) {
+    return toUrl(route(name, params));
+  },
+  intended(fallback = "/") {
+    // Uri.intended reads (and clears) the session's intended_url with an open-redirect guard.
+    return Uri.of("/").intended(fallback).value();
+  },
+  sign(base, params = {}, expiresInMinutes = 60, secret) {
+    return _signerFor(secret).sign(base, params, expiresInMinutes);
+  },
+  verify(signedUrl, secret) {
+    return _signerFor(secret).verify(signedUrl);
+  },
+  setSecret(secret) {
+    _secret = secret;
+    _signer = null;
+  },
+};
+
+/**
+ * The application URL facade — the same object {@link url} returns, exported for direct
+ * `Url.to(...)` / `Url.route(...)` / `Url.sign(...)` calls. Generation + signing in one place.
+ */
+export const Url: UrlGenerator = generator;
+
+export function url(): UrlGenerator;
+export function url(path: string, extra?: (string | number)[], secure?: boolean): string;
+export function url(
+  path?: string,
+  extra: (string | number)[] = [],
+  secure = false,
+): string | UrlGenerator {
+  if (path === undefined) return generator;
+  return toUrl(path, extra, secure);
+}

package/src/http/withHeaders.ts

@@ -0,0 +1,24 @@
+/**
+ * Return a copy of `res` with the given headers added/overwritten.
+ *
+ * A `Response` produced by `Response.redirect()` (or `Response.error()`) has an
+ * **immutable** headers guard — calling `res.headers.set(...)` on it throws.
+ * Middleware that decorates the downstream response (CORS, security headers,
+ * rate-limit info, …) must therefore reconstruct rather than mutate in place.
+ * `new Response(body, ...)` always yields a mutable guard, so the copy is safe.
+ *
+ * @example
+ * async handle(_, next) {
+ *   const res = await next();
+ *   return res ? withHeaders(res, { "X-Frame-Options": "DENY" }) : res;
+ * }
+ */
+export function withHeaders(res: Response, headers: Record<string, string>): Response {
+  const merged = new Headers(res.headers);
+  for (const [name, value] of Object.entries(headers)) merged.set(name, value);
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers: merged,
+  });
+}