@mandujs/core 0.20.10 → 0.22.0

package/src/middleware/secure/index.ts

@@ -0,0 +1,417 @@
+/**
+ * Secure HTTP Headers Middleware
+ *
+ * A Helmet-equivalent bundle shipping OWASP-recommended defaults for:
+ *   - Content-Security-Policy (CSP) — see `./csp.ts`
+ *   - Strict-Transport-Security (HSTS)
+ *   - X-Frame-Options (legacy; superseded by CSP `frame-ancestors`)
+ *   - X-Content-Type-Options
+ *   - Referrer-Policy
+ *   - Permissions-Policy
+ *   - X-XSS-Protection (legacy; explicitly `"0"` on modern clients)
+ *
+ * Strategy: we implement `MiddlewarePlugin` rather than the bare
+ * `(ctx) => Response | void` signature so we can mutate the outgoing Response
+ * via `afterHandle`. This mirrors `cors.ts` and means we do NOT need any
+ * framework modifications, a new "pending headers" buffer in the context, or
+ * a custom wrapper helper that callers must remember to invoke.
+ *
+ * Ordering vs. session/cookies:
+ *   Unlike session middleware, which must commit BEFORE the response is
+ *   built (DX-3 + Phase 2.3), header-setting middleware can run AFTER the
+ *   response is produced — we use `afterHandle` which receives the fully-
+ *   constructed Response and returns a replacement. No ordering hazard with
+ *   cookies/session state, because we never touch `ctx.cookies`.
+ *
+ * CSP nonce plumbing:
+ *   When `csp.nonce === true`, we compute a fresh nonce in `beforeHandle`
+ *   and stash it on the context under the key `"csp-nonce"`. SSR handlers
+ *   that render inline `<script>` tags can read it with
+ *   `ctx.get<string>("csp-nonce")`. The same nonce is interpolated into the
+ *   CSP header in `afterHandle`, guaranteeing the tag and the header agree.
+ *
+ *   Auto-injection of the nonce into `renderToStream`'s hydration script
+ *   tags is intentionally out of scope for this middleware — see the
+ *   Phase 6.2 follow-up item in `CLAUDE.md`.
+ *
+ * @example
+ * ```ts
+ * import { secure } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(secure())                                 // all defaults
+ *   .get((ctx) => ctx.ok({ hello: "world" }));
+ *
+ * // With CSP nonce:
+ * export default Mandu.filling()
+ *   .use(secure({ csp: { nonce: true } }))
+ *   .get((ctx) => {
+ *     const nonce = ctx.get<string>("csp-nonce");
+ *     // render inline script with nonce={nonce}
+ *     return ctx.ok({ ok: true });
+ *   });
+ * ```
+ */
+import type { MiddlewarePlugin } from "../../filling/filling";
+import type { ManduContext } from "../../filling/context";
+import { buildCsp, type CspOptions } from "./csp";
+
+export { buildCsp, DEFAULT_CSP_DIRECTIVES } from "./csp";
+export type { CspOptions, BuiltCsp } from "./csp";
+
+// ========== Types ==========
+
+export type ReferrerPolicyValue =
+  | "no-referrer"
+  | "no-referrer-when-downgrade"
+  | "origin"
+  | "origin-when-cross-origin"
+  | "same-origin"
+  | "strict-origin"
+  | "strict-origin-when-cross-origin"
+  | "unsafe-url";
+
+export interface HstsOptions {
+  /** max-age in seconds. Default: 15552000 (180 days). */
+  maxAge?: number;
+  /** includeSubDomains directive. Default: true. */
+  includeSubDomains?: boolean;
+  /** preload directive. Default: false — opt-in; implies submitting to the preload list. */
+  preload?: boolean;
+}
+
+export interface SecureMiddlewareOptions {
+  /** Content-Security-Policy options, or `false` to disable. */
+  csp?: CspOptions | false;
+  /** Strict-Transport-Security options, or `false` to disable. */
+  hsts?: HstsOptions | false;
+  /** X-Frame-Options. Default: `"DENY"`. `false` to disable. */
+  frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  /** X-Content-Type-Options: nosniff. Default: true. */
+  noSniff?: boolean;
+  /** Referrer-Policy. Default: `"strict-origin-when-cross-origin"`. */
+  referrerPolicy?: ReferrerPolicyValue | false;
+  /**
+   * Permissions-Policy map. Each entry becomes `feature=(allowlist)`.
+   * Use an empty array to deny a feature entirely (`feature=()`).
+   * `false` disables the header.
+   */
+  permissionsPolicy?: Record<string, string[]> | false;
+  /**
+   * X-XSS-Protection. Default: `"0"` — modern browsers should use CSP; the
+   * legacy auditor has known bypasses and is best disabled. `false` omits.
+   */
+  xssProtection?: "0" | "1" | "1; mode=block" | false;
+  /**
+   * Extra headers to set verbatim. Keys are set as-given (casing preserved
+   * by `Headers` normalization rules). Values overwrite any existing header.
+   */
+  extra?: Record<string, string>;
+}
+
+// ========== Defaults ==========
+
+const DEFAULT_HSTS: Required<HstsOptions> = Object.freeze({
+  maxAge: 15552000, // 180 days — matches Chrome's preload minimum
+  includeSubDomains: true,
+  preload: false,
+});
+
+const DEFAULT_REFERRER_POLICY: ReferrerPolicyValue = "strict-origin-when-cross-origin";
+
+/**
+ * OWASP-recommended deny-by-default for commonly abused browser capabilities.
+ *
+ * - `camera` / `microphone`: prevent drive-by media capture; app pages that
+ *   need these must opt in explicitly via override.
+ * - `geolocation`: prevents third-party scripts from geo-tagging users.
+ * - `payment`: blocks Payment Request API unless you explicitly own it.
+ * - `usb`: blocks WebUSB (e.g. hardware key attacks).
+ * - `interest-cohort`: opts out of FLoC/Topics tracking. Still widely
+ *   respected; cheap insurance.
+ */
+const DEFAULT_PERMISSIONS_POLICY: Record<string, string[]> = Object.freeze({
+  camera: [],
+  microphone: [],
+  geolocation: [],
+  payment: [],
+  usb: [],
+  "interest-cohort": [],
+}) as Record<string, string[]>;
+
+const CSP_NONCE_KEY = "csp-nonce";
+
+// ========== Public API ==========
+
+/**
+ * Build the secure headers middleware. The options argument is consumed
+ * eagerly at construction time — subsequent mutations to the passed object
+ * do not affect the already-installed middleware.
+ *
+ * Returns a `MiddlewarePlugin` with:
+ *   - `beforeHandle`: generates the per-request CSP nonce (if enabled) and
+ *     stashes it on the context for handler use.
+ *   - `afterHandle`: computes the final headers bundle and returns a new
+ *     Response with the headers applied. Existing headers from the handler
+ *     (e.g. `Content-Type`) are preserved.
+ */
+export function secure(options: SecureMiddlewareOptions = {}): MiddlewarePlugin {
+  // Normalize / snapshot options up front so we don't re-read user input on
+  // every request (protects against surprise mutation mid-session).
+  const cfg = normalizeOptions(options);
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<void> => {
+      // If CSP is enabled AND nonce is requested, compute the nonce here so
+      // the handler can read it before producing the response. We build the
+      // full CSP string in `afterHandle` (cheap) using the same nonce so
+      // the header and any handler-rendered <script nonce={...}> agree.
+      if (cfg.csp && cfg.csp.nonce === true) {
+        // buildCsp will synthesize a fresh nonce; we capture it here and
+        // pin it for the afterHandle pass via a per-request override.
+        const built = buildCsp({ ...cfg.csp, nonce: true });
+        if (built.nonce) {
+          ctx.set<string>(CSP_NONCE_KEY, built.nonce);
+        }
+      }
+    },
+
+    afterHandle: async (
+      ctx: ManduContext,
+      response: Response
+    ): Promise<Response> => {
+      const headers = new Headers(response.headers);
+      applySecureHeaders(ctx, headers, cfg);
+
+      // Only re-wrap if we actually added/changed something. In practice the
+      // headers map is always non-empty (we always set at least one header
+      // when options are default), but this keeps us honest about
+      // Response-body identity and matches `cors.ts`'s pattern.
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      });
+    },
+  };
+}
+
+/**
+ * Manual escape hatch: apply secure headers to an arbitrary Response using
+ * the options shape above.
+ *
+ * Prefer `.use(secure(...))` — this helper exists for callers outside the
+ * filling pipeline (e.g. custom error responders, static file handlers).
+ * Since no context is available, CSP nonce mode falls back to the one-shot
+ * nonce generated inside `buildCsp` — the caller is responsible for wiring
+ * that nonce into whatever they render.
+ */
+export function applySecureHeadersToResponse(
+  response: Response,
+  options: SecureMiddlewareOptions = {}
+): { response: Response; nonce?: string } {
+  const cfg = normalizeOptions(options);
+  const headers = new Headers(response.headers);
+
+  // Derive a fresh nonce for this standalone call (no context to cache it on).
+  let emittedNonce: string | undefined;
+  if (cfg.csp && cfg.csp.nonce === true) {
+    const built = buildCsp({ ...cfg.csp, nonce: true });
+    emittedNonce = built.nonce;
+  }
+
+  // Pseudo-context shim so applySecureHeaders can read the nonce consistently.
+  const shim = {
+    request: response as unknown as Request, // only used for URL scheme check; standalone callers skip HSTS logic path below via hsts=false typically
+    get: <T>(_key: string): T | undefined => emittedNonce as T | undefined,
+  };
+  applySecureHeaders(shim as unknown as ManduContext, headers, {
+    ...cfg,
+    // If caller didn't explicitly disable HSTS, keep it — but the scheme
+    // probe will simply no-op on a non-Request shim. Callers who want HSTS
+    // on standalone responses must ensure `response.url` carries an
+    // `https:` URL, or they should pass a pre-built Request with
+    // `x-forwarded-proto: https`.
+  });
+
+  return {
+    response: new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    }),
+    nonce: emittedNonce,
+  };
+}
+
+// ========== Internal: normalization ==========
+
+interface NormalizedOptions {
+  csp: CspOptions | null;
+  hsts: Required<HstsOptions> | null;
+  frameOptions: "DENY" | "SAMEORIGIN" | null;
+  noSniff: boolean;
+  referrerPolicy: ReferrerPolicyValue | null;
+  permissionsPolicy: Record<string, string[]> | null;
+  xssProtection: "0" | "1" | "1; mode=block" | null;
+  extra: Record<string, string>;
+}
+
+function normalizeOptions(options: SecureMiddlewareOptions): NormalizedOptions {
+  return {
+    csp: options.csp === false ? null : options.csp ?? {},
+    hsts:
+      options.hsts === false
+        ? null
+        : { ...DEFAULT_HSTS, ...(options.hsts ?? {}) },
+    frameOptions:
+      options.frameOptions === false
+        ? null
+        : options.frameOptions ?? "DENY",
+    noSniff: options.noSniff !== false,
+    referrerPolicy:
+      options.referrerPolicy === false
+        ? null
+        : options.referrerPolicy ?? DEFAULT_REFERRER_POLICY,
+    permissionsPolicy:
+      options.permissionsPolicy === false
+        ? null
+        : options.permissionsPolicy ?? { ...DEFAULT_PERMISSIONS_POLICY },
+    xssProtection:
+      options.xssProtection === false ? null : options.xssProtection ?? "0",
+    extra: options.extra ?? {},
+  };
+}
+
+// ========== Internal: header application ==========
+
+function applySecureHeaders(
+  ctx: ManduContext,
+  headers: Headers,
+  cfg: NormalizedOptions
+): void {
+  // --- CSP ---
+  if (cfg.csp) {
+    // If a nonce was pre-computed in beforeHandle, reuse it to ensure the
+    // handler's nonce=… values match what we emit in the header.
+    const pinnedNonce = ctx.get<string>(CSP_NONCE_KEY);
+    const effective =
+      pinnedNonce && cfg.csp.nonce === true
+        ? { ...cfg.csp, nonce: pinnedNonce }
+        : cfg.csp;
+
+    const built = buildCsp(effective);
+    headers.set(built.name, built.header);
+  }
+
+  // --- HSTS (only when the request is already HTTPS) ---
+  //
+  // RFC 6797 §7.2: UAs MUST ignore STS on insecure transport, but we also
+  // suppress it server-side to avoid leaking the policy across a plaintext
+  // channel (where an active MITM could strip it for first-visit users
+  // anyway — the "TOFU" problem HSTS is designed to reduce).
+  if (cfg.hsts && isHttps(ctx.request)) {
+    const parts = [`max-age=${Math.floor(cfg.hsts.maxAge)}`];
+    if (cfg.hsts.includeSubDomains) parts.push("includeSubDomains");
+    if (cfg.hsts.preload) parts.push("preload");
+    headers.set("Strict-Transport-Security", parts.join("; "));
+  }
+
+  // --- X-Frame-Options ---
+  if (cfg.frameOptions) {
+    headers.set("X-Frame-Options", cfg.frameOptions);
+  }
+
+  // --- X-Content-Type-Options ---
+  if (cfg.noSniff) {
+    headers.set("X-Content-Type-Options", "nosniff");
+  }
+
+  // --- Referrer-Policy ---
+  if (cfg.referrerPolicy) {
+    headers.set("Referrer-Policy", cfg.referrerPolicy);
+  }
+
+  // --- Permissions-Policy ---
+  if (cfg.permissionsPolicy) {
+    const pp = buildPermissionsPolicy(cfg.permissionsPolicy);
+    if (pp.length > 0) {
+      headers.set("Permissions-Policy", pp);
+    }
+  }
+
+  // --- X-XSS-Protection ---
+  if (cfg.xssProtection !== null) {
+    headers.set("X-XSS-Protection", cfg.xssProtection);
+  }
+
+  // --- Arbitrary extras (caller overrides always win) ---
+  for (const [k, v] of Object.entries(cfg.extra)) {
+    headers.set(k, v);
+  }
+}
+
+/**
+ * Build a Permissions-Policy header value.
+ *
+ * Grammar (simplified): `feature=(allowlist) , feature=(allowlist)`
+ *   - Bare tokens like `self` go inside the parens as-is.
+ *   - Origins (URLs) must be wrapped in double quotes per spec.
+ *   - Empty allowlist `()` denies the feature entirely.
+ *
+ * We accept the caller's array verbatim; they are responsible for quoting
+ * their URL-shaped entries. We do wrap origins that look URL-ish (contain
+ * `://`) when they are unquoted, because that's by far the most common
+ * mistake and the cost of the heuristic is tiny.
+ */
+function buildPermissionsPolicy(map: Record<string, string[]>): string {
+  const entries: string[] = [];
+  for (const [feature, allowlist] of Object.entries(map)) {
+    if (!Array.isArray(allowlist)) continue;
+    const items = allowlist.map(normalizePermissionsItem).join(" ");
+    entries.push(`${feature}=(${items})`);
+  }
+  return entries.join(", ");
+}
+
+function normalizePermissionsItem(raw: string): string {
+  if (raw === "self" || raw === "*") return raw;
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw;
+  if (raw.includes("://")) return `"${raw}"`;
+  return raw;
+}
+
+/**
+ * Determine whether the inbound request is HTTPS.
+ *
+ * Recognizes:
+ *   1. Direct `https:` scheme in `request.url`
+ *   2. `X-Forwarded-Proto: https` (de-facto reverse-proxy header)
+ *   3. `Forwarded: proto=https` (RFC 7239)
+ *
+ * We intentionally don't trust these headers on direct (non-proxied)
+ * connections — but since the caller is the one opting into HSTS, they're
+ * also responsible for running behind a reverse proxy that sanitizes
+ * client-supplied `Forwarded` / `X-Forwarded-*` headers. This matches
+ * Helmet's and express's documented behavior.
+ */
+function isHttps(request: Request): boolean {
+  try {
+    if (request.url.startsWith("https:")) return true;
+  } catch {
+    // Some shims may throw on `.url`; fall through to header checks.
+  }
+  const xfp = safeGetHeader(request, "x-forwarded-proto");
+  if (xfp && xfp.split(",")[0]!.trim().toLowerCase() === "https") return true;
+  const fwd = safeGetHeader(request, "forwarded");
+  if (fwd && /\bproto=https\b/i.test(fwd)) return true;
+  return false;
+}
+
+function safeGetHeader(request: Request, name: string): string | null {
+  try {
+    return request.headers?.get(name) ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/middleware/session.ts

@@ -0,0 +1,174 @@
+/**
+ * Session Middleware Plugin
+ *
+ * Thin wrapper around the existing `SessionStorage` contract
+ * (`packages/core/src/filling/session.ts`). Attaches an already-fetched
+ * {@link Session} to the request context so handlers can do:
+ *
+ *   const session = ctx.get<Session>("session");
+ *   session.set("userId", user.id);
+ *   await saveSession(ctx);
+ *
+ * ...instead of threading storage + cookies through manually.
+ *
+ * Commit is **caller-driven**: the middleware pipeline has no after-response
+ * hook that can mutate the outgoing Response, so auto-commit-on-exit is not
+ * possible. Handlers must call `saveSession(ctx)` or `destroySession(ctx)`
+ * explicitly before returning a response. `loginUser` / `logoutUser`
+ * (Phase 2.4) will wrap those calls.
+ *
+ * @example
+ * ```typescript
+ * import { session, saveSession } from "@mandujs/core/middleware";
+ * import { createCookieSessionStorage } from "@mandujs/core";
+ *
+ * const storage = createCookieSessionStorage({
+ *   cookie: { secrets: [process.env.SESSION_SECRET!] },
+ * });
+ *
+ * export default Mandu.filling()
+ *   .use(session({ storage }))
+ *   .post(async (ctx) => {
+ *     const s = ctx.get<Session>("session");
+ *     s.set("userId", "42");
+ *     await saveSession(ctx);
+ *     return ctx.ok({ ok: true });
+ *   });
+ * ```
+ */
+import type { ManduContext } from "../filling/context";
+import type { Session, SessionStorage } from "../filling/session";
+
+// ========== Types ==========
+
+export interface SessionMiddlewareOptions {
+  /** The storage implementation. Create via `createCookieSessionStorage(...)`. */
+  storage: SessionStorage;
+  /** Context key under which the Session is attached. Default: `"session"`. */
+  attachAs?: string;
+  /** Context key under which the storage is attached (for helpers). Default: `"_sessionStorage"`. */
+  storageKey?: string;
+}
+
+/** Middleware signature matching `jwt.ts` / `csrf.ts`. */
+type Middleware = (ctx: ManduContext) => Promise<Response | void>;
+
+// ========== Defaults ==========
+
+const DEFAULT_ATTACH_KEY = "session";
+const DEFAULT_STORAGE_KEY = "_sessionStorage";
+
+// ========== Middleware ==========
+
+/**
+ * Attach a `Session` (and its storage) to the context for the duration of the
+ * request.
+ *
+ * Does NOT auto-commit on exit — the middleware pipeline has no after-response
+ * hook that can both (a) run after the handler returns and (b) mutate the
+ * outgoing Response. Handlers persist explicitly via {@link saveSession} or
+ * {@link destroySession}.
+ */
+export function session(options: SessionMiddlewareOptions): Middleware {
+  if (!options || !options.storage) {
+    throw new Error("[Mandu Session] `storage` is required (use createCookieSessionStorage)");
+  }
+  const {
+    storage,
+    attachAs = DEFAULT_ATTACH_KEY,
+    storageKey = DEFAULT_STORAGE_KEY,
+  } = options;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    const s = await storage.getSession(ctx.cookies);
+    ctx.set(attachAs, s);
+    ctx.set(storageKey, storage);
+  };
+}
+
+// ========== Helpers ==========
+
+/**
+ * Commit the attached session via its storage, applying the resulting
+ * `Set-Cookie` header to `ctx.cookies` so the next `ctx.json/ok/redirect`
+ * picks it up automatically.
+ *
+ * No-op when the session is not dirty (unless `force: true`). Throws when the
+ * session middleware has not been installed on this request.
+ *
+ * IMPORTANT ordering: `ctx.json()` / `ctx.ok()` snapshot pending cookies at
+ * the moment they build their Response. Call `saveSession` **before** any
+ * response-producing method so the Set-Cookie makes it onto the wire.
+ */
+export async function saveSession(
+  ctx: ManduContext,
+  options?: { force?: boolean; attachAs?: string; storageKey?: string }
+): Promise<void> {
+  const attachAs = options?.attachAs ?? DEFAULT_ATTACH_KEY;
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+
+  const { session: s, storage } = resolveSessionAndStorage(ctx, attachAs, storageKey);
+
+  if (!options?.force && !s.isDirty()) {
+    return;
+  }
+
+  const setCookie = await storage.commitSession(s);
+  ctx.cookies.appendRawSetCookie(setCookie);
+  s.markClean();
+}
+
+/**
+ * Destroy the attached session: clears in-memory data AND emits an
+ * expiring Set-Cookie so the browser drops its copy.
+ *
+ * Throws when the session middleware has not been installed on this request.
+ *
+ * Same ordering caveat as {@link saveSession}: call before the
+ * response-producing method.
+ */
+export async function destroySession(
+  ctx: ManduContext,
+  options?: { attachAs?: string; storageKey?: string }
+): Promise<void> {
+  const attachAs = options?.attachAs ?? DEFAULT_ATTACH_KEY;
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+
+  const { session: s, storage } = resolveSessionAndStorage(ctx, attachAs, storageKey);
+
+  const setCookie = await storage.destroySession(s);
+  // Wipe in-memory state first so subsequent handler code in the same request
+  // sees an empty session (prevents accidental re-use of stale data between
+  // destroy and response emit).
+  s.clear();
+  ctx.cookies.appendRawSetCookie(setCookie);
+  // destroy() emits a new cookie; the session is now "clean" relative to that
+  // just-written state — any further mutation would re-dirty it.
+  s.markClean();
+}
+
+// ========== Internal ==========
+
+/**
+ * Fetch the Session + SessionStorage from context keys, throwing a clear
+ * error when the middleware was not installed.
+ *
+ * Uses a plain `Error` rather than `AuthenticationError` because missing
+ * middleware is a wiring mistake (500-class server error), not an end-user
+ * auth failure (401).
+ */
+function resolveSessionAndStorage(
+  ctx: ManduContext,
+  attachAs: string,
+  storageKey: string
+): { session: Session; storage: SessionStorage } {
+  const s = ctx.get<Session>(attachAs);
+  const storage = ctx.get<SessionStorage>(storageKey);
+  if (!s || !storage) {
+    throw new Error(
+      "[Mandu Session] saveSession/destroySession called without session() middleware installed. " +
+        "Add `.use(session({ storage }))` to your filling chain."
+    );
+  }
+  return { session: s, storage };
+}