@mandujs/core 0.21.0 → 0.22.0

package/src/middleware/secure/__tests__/secure.test.ts

@@ -0,0 +1,360 @@
+/**
+ * Secure headers middleware tests
+ *
+ * Covers:
+ *   - `buildCsp` directive merging + nonce interpolation
+ *   - `secure` middleware plugin (beforeHandle/afterHandle) applied to a real
+ *     `ManduContext` + `Response`, matching how the lifecycle would drive it
+ *
+ * Fixture style mirrors `tests/middleware/csrf.test.ts` and
+ * `src/middleware/oauth/__tests__/oauth.test.ts`:
+ *   - Real `Request` / `Response` / `ManduContext` — no mocks
+ *   - Middleware is executed manually (before → handler → after) to simulate
+ *     the Elysia-style lifecycle pipeline
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  secure,
+  buildCsp,
+  applySecureHeadersToResponse,
+  DEFAULT_CSP_DIRECTIVES,
+  type SecureMiddlewareOptions,
+  type CspOptions,
+} from "../index";
+import { ManduContext } from "../../../filling/context";
+import type { MiddlewarePlugin } from "../../../filling/filling";
+
+// ========== Helpers ==========
+
+function makeReq(
+  url: string,
+  init: RequestInit & { cookie?: string } = {}
+): Request {
+  const { cookie, headers: rawHeaders, ...rest } = init;
+  const headers = new Headers(rawHeaders as HeadersInit | undefined);
+  if (cookie) headers.set("cookie", cookie);
+  return new Request(url, { ...rest, headers });
+}
+
+function makeCtx(req: Request): ManduContext {
+  return new ManduContext(req);
+}
+
+/**
+ * Drive the full plugin pipeline:
+ *   1. beforeHandle (may mutate ctx)
+ *   2. handler produces a Response
+ *   3. afterHandle (returns possibly-wrapped Response)
+ */
+async function runPlugin(
+  plugin: MiddlewarePlugin,
+  ctx: ManduContext,
+  handler: (ctx: ManduContext) => Response | Promise<Response>
+): Promise<Response> {
+  if (plugin.beforeHandle) {
+    const early = await plugin.beforeHandle(ctx);
+    if (early instanceof Response) return early;
+  }
+  let res = await handler(ctx);
+  if (plugin.afterHandle) {
+    res = await plugin.afterHandle(ctx, res);
+  }
+  return res;
+}
+
+// ============================================
+// buildCsp
+// ============================================
+
+describe("buildCsp", () => {
+  it("emits default directives including default-src 'self'", () => {
+    const built = buildCsp();
+    expect(built.name).toBe("Content-Security-Policy");
+    expect(built.header).toContain("default-src 'self'");
+    expect(built.header).toContain("object-src 'none'");
+    expect(built.header).toContain("frame-ancestors 'none'");
+  });
+
+  it("interpolates {NONCE} into script-src when nonce is enabled", () => {
+    const built = buildCsp({ nonce: true });
+    expect(built.nonce).toBeDefined();
+    expect(built.nonce!.length).toBeGreaterThan(0);
+    // The nonce should appear as part of a `'nonce-...'` token in script-src.
+    const scriptSrcMatch = built.header.match(/script-src ([^;]+)/);
+    expect(scriptSrcMatch).not.toBeNull();
+    expect(scriptSrcMatch![1]).toContain(`'nonce-${built.nonce}'`);
+    // Placeholder literal should NOT leak through.
+    expect(built.header).not.toContain("{NONCE}");
+  });
+
+  it("reuses the same nonce across script-src and style-src", () => {
+    const built = buildCsp({ nonce: true });
+    const nonce = built.nonce!;
+    const scriptMatch = built.header.match(/script-src [^;]*'nonce-([^']+)'/);
+    const styleMatch = built.header.match(/style-src [^;]*'nonce-([^']+)'/);
+    expect(scriptMatch).not.toBeNull();
+    expect(styleMatch).not.toBeNull();
+    expect(scriptMatch![1]).toBe(nonce);
+    expect(styleMatch![1]).toBe(nonce);
+  });
+
+  it("accepts a caller-supplied literal nonce verbatim", () => {
+    const built = buildCsp({ nonce: "mY-NoNcE_123" });
+    expect(built.nonce).toBe("mY-NoNcE_123");
+    expect(built.header).toContain("'nonce-mY-NoNcE_123'");
+  });
+
+  it("flips header name to Content-Security-Policy-Report-Only when reportOnly is set", () => {
+    const built = buildCsp({ reportOnly: true });
+    expect(built.name).toBe("Content-Security-Policy-Report-Only");
+  });
+
+  it("emits bare directive names for empty-array directives", () => {
+    // `upgrade-insecure-requests` is a flag-style directive in defaults.
+    const built = buildCsp();
+    // Should appear as a standalone token, not as "upgrade-insecure-requests ".
+    expect(built.header).toMatch(/\bupgrade-insecure-requests(;|$)/);
+  });
+
+  it("merges caller directives by replacing default values for that key", () => {
+    const built = buildCsp({
+      directives: { "default-src": ["'self'", "https://cdn.example.com"] },
+    });
+    expect(built.header).toContain("default-src 'self' https://cdn.example.com");
+    // Other defaults must survive.
+    expect(built.header).toContain("object-src 'none'");
+  });
+
+  it("preserves literal CSP keywords like 'self' and 'none' exactly", () => {
+    const built = buildCsp({
+      directives: { "script-src": ["'self'", "'none'", "'strict-dynamic'"] },
+    });
+    const match = built.header.match(/script-src ([^;]+)/);
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe("'self' 'none' 'strict-dynamic'");
+  });
+
+  it("normalizes camelCase directive names to kebab-case", () => {
+    const built = buildCsp({
+      directives: { scriptSrc: ["'self'"], frameAncestors: ["'self'"] },
+    });
+    // Normalized directive names should land in the header.
+    expect(built.header).toContain("script-src 'self'");
+    expect(built.header).toContain("frame-ancestors 'self'");
+    // And should NOT appear in their camelCase form.
+    expect(built.header).not.toMatch(/\bscriptSrc\b/);
+  });
+
+  it("strips broken nonce tokens when nonce is disabled (defaults path)", () => {
+    const built = buildCsp({ nonce: false });
+    // No `'nonce-'` token should leak through from defaults.
+    expect(built.header).not.toContain("'nonce-");
+    // The surviving script-src must still list 'self' from defaults.
+    expect(built.header).toContain("script-src 'self'");
+    // Sanity: DEFAULT_CSP_DIRECTIVES declared a placeholder.
+    expect(DEFAULT_CSP_DIRECTIVES["script-src"]).toContain("'nonce-{NONCE}'");
+  });
+});
+
+// ============================================
+// secure() middleware — default behavior
+// ============================================
+
+describe("secure middleware: defaults", () => {
+  it("sets all expected default headers on the response", async () => {
+    const plugin = secure();
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+
+    expect(res.headers.get("Content-Security-Policy")).toBeTruthy();
+    expect(res.headers.get("X-Frame-Options")).toBe("DENY");
+    expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+    expect(res.headers.get("Referrer-Policy")).toBe("strict-origin-when-cross-origin");
+    expect(res.headers.get("Permissions-Policy")).toContain("camera=()");
+    expect(res.headers.get("X-XSS-Protection")).toBe("0");
+    // HSTS requires https — which the fixture uses.
+    expect(res.headers.get("Strict-Transport-Security")).toContain("max-age=");
+  });
+
+  it("omits the CSP header when csp: false", async () => {
+    const plugin = secure({ csp: false });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("Content-Security-Policy")).toBeNull();
+    expect(res.headers.get("Content-Security-Policy-Report-Only")).toBeNull();
+  });
+
+  it("omits Strict-Transport-Security when hsts: false", async () => {
+    const plugin = secure({ hsts: false });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("Strict-Transport-Security")).toBeNull();
+  });
+
+  it("emits HSTS only for HTTPS requests", async () => {
+    const plugin = secure();
+    const httpCtx = makeCtx(makeReq("http://example.com/"));
+    const httpRes = await runPlugin(plugin, httpCtx, (c) => c.ok({ ok: true }));
+    expect(httpRes.headers.get("Strict-Transport-Security")).toBeNull();
+
+    const httpsCtx = makeCtx(makeReq("https://example.com/"));
+    const httpsRes = await runPlugin(plugin, httpsCtx, (c) => c.ok({ ok: true }));
+    expect(httpsRes.headers.get("Strict-Transport-Security")).toContain("max-age=");
+  });
+
+  it("respects x-forwarded-proto: https for HSTS emission", async () => {
+    const plugin = secure();
+    const req = makeReq("http://example.com/", {
+      headers: { "x-forwarded-proto": "https" },
+    });
+    const res = await runPlugin(plugin, makeCtx(req), (c) => c.ok({ ok: true }));
+    expect(res.headers.get("Strict-Transport-Security")).toContain("max-age=15552000");
+    expect(res.headers.get("Strict-Transport-Security")).toContain("includeSubDomains");
+  });
+
+  it("supports frameOptions: SAMEORIGIN", async () => {
+    const plugin = secure({ frameOptions: "SAMEORIGIN" });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("X-Frame-Options")).toBe("SAMEORIGIN");
+  });
+
+  it("omits X-Content-Type-Options when noSniff: false", async () => {
+    const plugin = secure({ noSniff: false });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("X-Content-Type-Options")).toBeNull();
+  });
+
+  it("applies a custom referrerPolicy value", async () => {
+    const plugin = secure({ referrerPolicy: "no-referrer" });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("Referrer-Policy")).toBe("no-referrer");
+  });
+
+  it("emits default Permissions-Policy with deny-by-default list", async () => {
+    const plugin = secure();
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    const pp = res.headers.get("Permissions-Policy");
+    expect(pp).toBeTruthy();
+    expect(pp).toContain("camera=()");
+    expect(pp).toContain("microphone=()");
+    expect(pp).toContain("geolocation=()");
+    expect(pp).toContain("payment=()");
+    expect(pp).toContain("usb=()");
+    expect(pp).toContain("interest-cohort=()");
+  });
+
+  it("sets extra headers verbatim", async () => {
+    const plugin = secure({
+      extra: { "X-Custom-Header": "hello", "X-Build-Id": "abc123" },
+    });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("X-Custom-Header")).toBe("hello");
+    expect(res.headers.get("X-Build-Id")).toBe("abc123");
+  });
+
+  it("stashes the CSP nonce on ctx.get('csp-nonce') during request", async () => {
+    const plugin = secure({ csp: { nonce: true } });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+
+    let nonceDuringHandler: string | undefined;
+    const res = await runPlugin(plugin, ctx, (c) => {
+      nonceDuringHandler = c.get<string>("csp-nonce");
+      return c.ok({ ok: true });
+    });
+
+    expect(nonceDuringHandler).toBeDefined();
+    expect(nonceDuringHandler!.length).toBeGreaterThan(0);
+    // Header must agree with the nonce the handler saw.
+    const cspHeader = res.headers.get("Content-Security-Policy");
+    expect(cspHeader).toContain(`'nonce-${nonceDuringHandler}'`);
+  });
+
+  it("preserves handler-set headers (e.g. Content-Type)", async () => {
+    const plugin = secure();
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, () =>
+      new Response("hi", {
+        status: 200,
+        headers: { "Content-Type": "text/plain; charset=utf-8", "X-App-Header": "keep-me" },
+      })
+    );
+    expect(res.headers.get("Content-Type")).toBe("text/plain; charset=utf-8");
+    expect(res.headers.get("X-App-Header")).toBe("keep-me");
+    // Secure headers still added alongside.
+    expect(res.headers.get("X-Frame-Options")).toBe("DENY");
+  });
+
+  it("is idempotent — running the middleware twice yields the same headers", async () => {
+    const plugin = secure();
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const firstPass = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    // Apply afterHandle a second time to simulate accidental double-wiring.
+    const secondPass = await plugin.afterHandle!(ctx, firstPass);
+    // Each unique header name should have exactly one value.
+    const xfoValues = secondPass.headers.getSetCookie?.() ?? []; // no set-cookie involvement
+    expect(xfoValues.length).toBe(0);
+    expect(secondPass.headers.get("X-Frame-Options")).toBe("DENY");
+    expect(secondPass.headers.get("X-Content-Type-Options")).toBe("nosniff");
+    // Verify CSP is a single header (not duplicated).
+    const csp = secondPass.headers.get("Content-Security-Policy");
+    expect(csp).toBeTruthy();
+    // The value should not contain a semicolon-doubled policy (rough smoke check).
+    expect(csp!.split("default-src").length).toBe(2);
+  });
+
+  it("honors Report-Only mode via csp.reportOnly", async () => {
+    const plugin = secure({ csp: { reportOnly: true } });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("Content-Security-Policy-Report-Only")).toBeTruthy();
+    expect(res.headers.get("Content-Security-Policy")).toBeNull();
+  });
+
+  it("allows disabling X-XSS-Protection via xssProtection: false", async () => {
+    const plugin = secure({ xssProtection: false });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    expect(res.headers.get("X-XSS-Protection")).toBeNull();
+  });
+
+  it("supports custom HSTS maxAge + preload combo", async () => {
+    const plugin = secure({
+      hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
+    });
+    const ctx = makeCtx(makeReq("https://example.com/"));
+    const res = await runPlugin(plugin, ctx, (c) => c.ok({ ok: true }));
+    const hsts = res.headers.get("Strict-Transport-Security");
+    expect(hsts).toBe("max-age=63072000; includeSubDomains; preload");
+  });
+});
+
+// ============================================
+// Stand-alone applySecureHeadersToResponse
+// ============================================
+
+describe("applySecureHeadersToResponse", () => {
+  it("wraps an arbitrary Response with the default header set", () => {
+    const base = new Response("hello", {
+      status: 200,
+      headers: { "Content-Type": "text/plain" },
+    });
+    const { response } = applySecureHeadersToResponse(base, { hsts: false });
+    expect(response.headers.get("X-Frame-Options")).toBe("DENY");
+    expect(response.headers.get("Content-Type")).toBe("text/plain");
+  });
+
+  it("returns the generated nonce when csp.nonce: true", () => {
+    const base = new Response(null, { status: 204 });
+    const { nonce, response } = applySecureHeadersToResponse(base, {
+      hsts: false,
+      csp: { nonce: true },
+    });
+    expect(nonce).toBeDefined();
+    expect(response.headers.get("Content-Security-Policy")).toContain(`'nonce-${nonce}'`);
+  });
+});

package/src/middleware/secure/csp.ts

@@ -0,0 +1,193 @@
+/**
+ * Content-Security-Policy builder
+ *
+ * Standalone because CSP has many directives, user overrides need to merge
+ * deterministically with defaults, and per-request nonce interpolation needs
+ * a single authoritative code path so `script-src` and `style-src` are
+ * guaranteed to share the same nonce (OWASP recommendation — one nonce per
+ * request, reused across directives).
+ *
+ * Consumers:
+ *   - `secure()` middleware (via `buildCsp`)
+ *   - Callers who want ONLY CSP (public re-export from the secure barrel)
+ *
+ * @see https://www.w3.org/TR/CSP3/
+ * @see https://owasp.org/www-project-secure-headers/
+ */
+
+// ========== Types ==========
+
+export interface CspOptions {
+  /** Directive map. Values are joined with space. Merged over defaults. */
+  directives?: Record<string, string[]>;
+  /** When true, emits `Content-Security-Policy-Report-Only` instead. */
+  reportOnly?: boolean;
+  /**
+   * Nonce source:
+   *   - `true`  → generate a fresh 128-bit random nonce per call
+   *   - string  → use the provided literal nonce value (must be base64url-safe)
+   *   - `false` / undefined → no nonce; any `{NONCE}` placeholder is stripped
+   */
+  nonce?: boolean | string | false;
+}
+
+export interface BuiltCsp {
+  /** Final header value. */
+  header: string;
+  /** Which header name to set. */
+  name: "Content-Security-Policy" | "Content-Security-Policy-Report-Only";
+  /** Populated only when `nonce` resolved to a concrete value. */
+  nonce?: string;
+}
+
+// ========== Defaults ==========
+
+/**
+ * Production-safe SSR + islands defaults.
+ *
+ * Key choices:
+ *   - `'strict-dynamic'` on `script-src` means: once a trusted nonce-authorized
+ *     script loads, further scripts it creates inherit trust. This allows
+ *     hydration bundles to lazy-load chunks without reloading their nonce.
+ *     Modern browsers (CSP 3+) honor this; older browsers fall back to the
+ *     nonce allowlist, which still works for the SSR-emitted scripts.
+ *   - `frame-ancestors 'none'` supersedes `X-Frame-Options: DENY` for modern
+ *     browsers. We still emit XFO for legacy clients.
+ *   - `upgrade-insecure-requests` silently rewrites `http:` subresources to
+ *     `https:`. Safe default for modern apps; cheap insurance against mixed
+ *     content from third-party embeds.
+ *   - NO `'unsafe-inline'` / `'unsafe-eval'`. If your app needs them, opt in
+ *     explicitly via `directives` — don't let them sneak in as defaults.
+ */
+export const DEFAULT_CSP_DIRECTIVES: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  "default-src": ["'self'"],
+  "script-src": ["'self'", "'nonce-{NONCE}'", "'strict-dynamic'"],
+  "style-src": ["'self'", "'nonce-{NONCE}'", "https://fonts.googleapis.com"],
+  "font-src": ["'self'", "https://fonts.gstatic.com", "data:"],
+  "img-src": ["'self'", "data:", "https:"],
+  "connect-src": ["'self'"],
+  "frame-ancestors": ["'none'"],
+  "base-uri": ["'self'"],
+  "form-action": ["'self'"],
+  "object-src": ["'none'"],
+  "upgrade-insecure-requests": [],
+});
+
+/** Placeholder literal that `buildCsp` rewrites to the real nonce value. */
+export const NONCE_PLACEHOLDER = "{NONCE}";
+
+// ========== Public API ==========
+
+/**
+ * Build a single `Content-Security-Policy` header from defaults + overrides.
+ *
+ * Merge semantics:
+ *   - User-supplied directives REPLACE the default values for that directive
+ *     (caller owns the full value list). We do not concatenate, because CSP
+ *     parsing is order-sensitive and partial merges surprise callers.
+ *   - Directive names are normalized to lowercase-kebab. Caller may supply
+ *     either `"script-src"` or `"scriptSrc"`; both map to `script-src`.
+ *   - Empty-array directives emit as bare directive names (e.g.
+ *     `upgrade-insecure-requests`) — required by the CSP grammar for flag
+ *     directives.
+ *
+ * Nonce handling:
+ *   - If `nonce === true`, we generate a per-call nonce via
+ *     `crypto.getRandomValues` (16 bytes → 128 bits of entropy, base64url).
+ *   - If `nonce === string`, we trust the caller's value verbatim. Useful for
+ *     integrating with a pre-existing per-request nonce generator.
+ *   - The SAME nonce is substituted into every `{NONCE}` occurrence across
+ *     ALL directives (script-src, style-src, ...). Per OWASP guidance.
+ *   - If no nonce, `{NONCE}` placeholders are stripped along with their
+ *     surrounding `'nonce-...'` wrapper to avoid emitting broken tokens.
+ */
+export function buildCsp(options: CspOptions = {}): BuiltCsp {
+  const nonce = resolveNonce(options.nonce);
+
+  // Normalize + merge.
+  const merged: Record<string, string[]> = {};
+  for (const [k, v] of Object.entries(DEFAULT_CSP_DIRECTIVES)) {
+    merged[normalizeDirectiveName(k)] = [...v];
+  }
+  if (options.directives) {
+    for (const [k, v] of Object.entries(options.directives)) {
+      if (!Array.isArray(v)) continue;
+      merged[normalizeDirectiveName(k)] = [...v];
+    }
+  }
+
+  const parts: string[] = [];
+  for (const [name, values] of Object.entries(merged)) {
+    const processed = values
+      .map((v) => interpolateNonce(v, nonce))
+      // Strip broken nonce tokens when no nonce was produced.
+      .filter((v): v is string => v !== null);
+
+    if (processed.length === 0) {
+      // Flag-style directive (no value list) — emit bare name.
+      parts.push(name);
+    } else {
+      parts.push(`${name} ${processed.join(" ")}`);
+    }
+  }
+
+  return {
+    header: parts.join("; "),
+    name: options.reportOnly
+      ? "Content-Security-Policy-Report-Only"
+      : "Content-Security-Policy",
+    nonce,
+  };
+}
+
+// ========== Internal ==========
+
+/**
+ * Resolve the `nonce` option to a concrete string (or undefined for "off").
+ * Generation uses `crypto.getRandomValues` rather than `crypto.randomUUID`
+ * to match OWASP's recommendation of ≥128 bits of entropy with raw random
+ * bytes (UUIDs have lower effective entropy due to version/variant bits).
+ */
+function resolveNonce(opt: CspOptions["nonce"]): string | undefined {
+  if (opt === true) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return base64UrlEncode(bytes);
+  }
+  if (typeof opt === "string" && opt.length > 0) {
+    return opt;
+  }
+  return undefined;
+}
+
+/**
+ * Replace `{NONCE}` in a single directive value.
+ *
+ * Returns `null` to signal "this value depended on a nonce that was never
+ * produced — drop it entirely" so callers don't emit `'nonce-'` (broken
+ * token). Returns the original value when no placeholder is present.
+ */
+function interpolateNonce(value: string, nonce: string | undefined): string | null {
+  if (!value.includes(NONCE_PLACEHOLDER)) return value;
+  if (!nonce) return null;
+  return value.split(NONCE_PLACEHOLDER).join(nonce);
+}
+
+/**
+ * Accepts `"scriptSrc"` / `"script-src"` / `"Script-Src"` → `"script-src"`.
+ * camelCase → kebab-case via the standard regex; already-kebab inputs are
+ * lowercased without further transformation.
+ */
+function normalizeDirectiveName(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}