npm - @timber-js/app - Versions diffs - 0.1.1 → 0.1.2 - Mend

@timber-js/app 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

package/dist/index.js +5 -2
package/dist/index.js.map +1 -1
package/dist/plugins/entries.d.ts.map +1 -1
package/package.json +2 -1
package/src/adapters/cloudflare.ts +325 -0
package/src/adapters/nitro.ts +366 -0
package/src/adapters/types.ts +63 -0
package/src/cache/index.ts +91 -0
package/src/cache/redis-handler.ts +91 -0
package/src/cache/register-cached-function.ts +99 -0
package/src/cache/singleflight.ts +26 -0
package/src/cache/stable-stringify.ts +21 -0
package/src/cache/timber-cache.ts +116 -0
package/src/cli.ts +201 -0
package/src/client/browser-entry.ts +663 -0
package/src/client/error-boundary.tsx +209 -0
package/src/client/form.tsx +200 -0
package/src/client/head.ts +61 -0
package/src/client/history.ts +46 -0
package/src/client/index.ts +60 -0
package/src/client/link-navigate-interceptor.tsx +62 -0
package/src/client/link-status-provider.tsx +40 -0
package/src/client/link.tsx +310 -0
package/src/client/nuqs-adapter.tsx +117 -0
package/src/client/router-ref.ts +25 -0
package/src/client/router.ts +563 -0
package/src/client/segment-cache.ts +194 -0
package/src/client/segment-context.ts +57 -0
package/src/client/ssr-data.ts +95 -0
package/src/client/types.ts +4 -0
package/src/client/unload-guard.ts +34 -0
package/src/client/use-cookie.ts +122 -0
package/src/client/use-link-status.ts +46 -0
package/src/client/use-navigation-pending.ts +47 -0
package/src/client/use-params.ts +71 -0
package/src/client/use-pathname.ts +43 -0
package/src/client/use-query-states.ts +133 -0
package/src/client/use-router.ts +77 -0
package/src/client/use-search-params.ts +74 -0
package/src/client/use-selected-layout-segment.ts +110 -0
package/src/content/index.ts +13 -0
package/src/cookies/define-cookie.ts +137 -0
package/src/cookies/index.ts +9 -0
package/src/fonts/ast.ts +359 -0
package/src/fonts/css.ts +68 -0
package/src/fonts/fallbacks.ts +248 -0
package/src/fonts/google.ts +332 -0
package/src/fonts/local.ts +177 -0
package/src/fonts/types.ts +88 -0
package/src/index.ts +413 -0
package/src/plugins/adapter-build.ts +118 -0
package/src/plugins/build-manifest.ts +323 -0
package/src/plugins/build-report.ts +353 -0
package/src/plugins/cache-transform.ts +199 -0
package/src/plugins/chunks.ts +90 -0
package/src/plugins/content.ts +136 -0
package/src/plugins/dev-error-overlay.ts +230 -0
package/src/plugins/dev-logs.ts +280 -0
package/src/plugins/dev-server.ts +389 -0
package/src/plugins/dynamic-transform.ts +161 -0
package/src/plugins/entries.ts +207 -0
package/src/plugins/fonts.ts +581 -0
package/src/plugins/mdx.ts +179 -0
package/src/plugins/react-prod.ts +56 -0
package/src/plugins/routing.ts +419 -0
package/src/plugins/server-action-exports.ts +220 -0
package/src/plugins/server-bundle.ts +113 -0
package/src/plugins/shims.ts +168 -0
package/src/plugins/static-build.ts +207 -0
package/src/routing/codegen.ts +396 -0
package/src/routing/index.ts +14 -0
package/src/routing/interception.ts +173 -0
package/src/routing/scanner.ts +487 -0
package/src/routing/status-file-lint.ts +114 -0
package/src/routing/types.ts +100 -0
package/src/search-params/analyze.ts +192 -0
package/src/search-params/codecs.ts +153 -0
package/src/search-params/create.ts +314 -0
package/src/search-params/index.ts +23 -0
package/src/search-params/registry.ts +31 -0
package/src/server/access-gate.tsx +142 -0
package/src/server/action-client.ts +473 -0
package/src/server/action-handler.ts +325 -0
package/src/server/actions.ts +236 -0
package/src/server/asset-headers.ts +81 -0
package/src/server/body-limits.ts +102 -0
package/src/server/build-manifest.ts +234 -0
package/src/server/canonicalize.ts +90 -0
package/src/server/client-module-map.ts +58 -0
package/src/server/csrf.ts +79 -0
package/src/server/deny-renderer.ts +302 -0
package/src/server/dev-logger.ts +419 -0
package/src/server/dev-span-processor.ts +78 -0
package/src/server/dev-warnings.ts +282 -0
package/src/server/early-hints-sender.ts +55 -0
package/src/server/early-hints.ts +142 -0
package/src/server/error-boundary-wrapper.ts +69 -0
package/src/server/error-formatter.ts +184 -0
package/src/server/flush.ts +182 -0
package/src/server/form-data.ts +176 -0
package/src/server/form-flash.ts +93 -0
package/src/server/html-injectors.ts +445 -0
package/src/server/index.ts +222 -0
package/src/server/instrumentation.ts +136 -0
package/src/server/logger.ts +145 -0
package/src/server/manifest-status-resolver.ts +215 -0
package/src/server/metadata-render.ts +527 -0
package/src/server/metadata-routes.ts +189 -0
package/src/server/metadata.ts +263 -0
package/src/server/middleware-runner.ts +32 -0
package/src/server/nuqs-ssr-provider.tsx +63 -0
package/src/server/pipeline.ts +555 -0
package/src/server/prerender.ts +139 -0
package/src/server/primitives.ts +264 -0
package/src/server/proxy.ts +43 -0
package/src/server/request-context.ts +554 -0
package/src/server/route-element-builder.ts +395 -0
package/src/server/route-handler.ts +153 -0
package/src/server/route-matcher.ts +316 -0
package/src/server/rsc-entry/api-handler.ts +112 -0
package/src/server/rsc-entry/error-renderer.ts +177 -0
package/src/server/rsc-entry/helpers.ts +147 -0
package/src/server/rsc-entry/index.ts +688 -0
package/src/server/rsc-entry/ssr-bridge.ts +18 -0
package/src/server/slot-resolver.ts +359 -0
package/src/server/ssr-entry.ts +161 -0
package/src/server/ssr-render.ts +200 -0
package/src/server/status-code-resolver.ts +282 -0
package/src/server/tracing.ts +281 -0
package/src/server/tree-builder.ts +354 -0
package/src/server/types.ts +150 -0
package/src/shims/font-google.ts +67 -0
package/src/shims/headers.ts +11 -0
package/src/shims/image.ts +48 -0
package/src/shims/link.ts +9 -0
package/src/shims/navigation-client.ts +52 -0
package/src/shims/navigation.ts +31 -0
package/src/shims/server-only-noop.js +5 -0
package/src/utils/directive-parser.ts +529 -0
package/src/utils/format.ts +10 -0
package/src/utils/startup-timer.ts +102 -0

package/src/server/body-limits.ts ADDED Viewed

@@ -0,0 +1,102 @@
+/**
+ * Request body size limits — returns 413 when exceeded.
+ * See design/08-forms-and-actions.md §"FormData Limits"
+ */
+export interface BodyLimitsConfig {
+  limits?: {
+    actionBodySize?: string;
+    uploadBodySize?: string;
+    maxFields?: number;
+  };
+}
+export type BodyLimitResult = { ok: true } | { ok: false; status: 411 | 413 };
+export type BodyKind = 'action' | 'upload';
+const KB = 1024;
+const MB = 1024 * KB;
+const GB = 1024 * MB;
+export const DEFAULT_LIMITS = {
+  actionBodySize: 1 * MB,
+  uploadBodySize: 10 * MB,
+  maxFields: 100,
+} as const;
+const SIZE_PATTERN = /^(\d+(?:\.\d+)?)\s*(kb|mb|gb)?$/i;
+/** Parse a human-readable size string ("1mb", "512kb", "1024") into bytes. */
+export function parseBodySize(size: string): number {
+  const match = SIZE_PATTERN.exec(size.trim());
+  if (!match) {
+    throw new Error(
+      `Invalid body size format: "${size}". Expected format like "1mb", "512kb", or "1024".`
+    );
+  }
+  const value = Number.parseFloat(match[1]);
+  const unit = (match[2] ?? '').toLowerCase();
+  switch (unit) {
+    case 'kb':
+      return Math.floor(value * KB);
+    case 'mb':
+      return Math.floor(value * MB);
+    case 'gb':
+      return Math.floor(value * GB);
+    case '':
+      return Math.floor(value);
+    default:
+      throw new Error(`Unknown size unit: "${unit}"`);
+  }
+}
+/** Check whether a request body exceeds the configured size limit (stateless, no ALS). */
+export function enforceBodyLimits(
+  req: Request,
+  kind: BodyKind,
+  config: BodyLimitsConfig
+): BodyLimitResult {
+  const contentLength = req.headers.get('Content-Length');
+  if (!contentLength) {
+    // Reject requests without Content-Length — prevents body limit bypass via
+    // chunked transfer-encoding. Browsers always send Content-Length for form POSTs.
+    return { ok: false, status: 411 };
+  }
+  const bodySize = Number.parseInt(contentLength, 10);
+  if (Number.isNaN(bodySize)) {
+    return { ok: false, status: 411 };
+  }
+  const limit = resolveLimit(kind, config);
+  return bodySize <= limit ? { ok: true } : { ok: false, status: 413 };
+}
+/** Check whether a FormData payload exceeds the configured field count limit. */
+export function enforceFieldLimit(formData: FormData, config: BodyLimitsConfig): BodyLimitResult {
+  const maxFields = config.limits?.maxFields ?? DEFAULT_LIMITS.maxFields;
+  // Count unique keys — FormData.keys() yields duplicates for multi-value fields,
+  // so we use a Set to count distinct field names.
+  const fieldCount = new Set(formData.keys()).size;
+  return fieldCount <= maxFields ? { ok: true } : { ok: false, status: 413 };
+}
+/**
+ * Resolve the byte limit for a given body kind, using config overrides or defaults.
+ */
+function resolveLimit(kind: BodyKind, config: BodyLimitsConfig): number {
+  const userLimits = config.limits;
+  if (kind === 'action') {
+    return userLimits?.actionBodySize
+      ? parseBodySize(userLimits.actionBodySize)
+      : DEFAULT_LIMITS.actionBodySize;
+  }
+  return userLimits?.uploadBodySize
+    ? parseBodySize(userLimits.uploadBodySize)
+    : DEFAULT_LIMITS.uploadBodySize;
+}

package/src/server/build-manifest.ts ADDED Viewed

@@ -0,0 +1,234 @@
+/**
+ * Build manifest types and utilities for CSS and JS asset tracking.
+ *
+ * The build manifest maps route segment file paths to their output
+ * chunks from Vite's client build. This enables:
+ * - <link rel="stylesheet"> injection in HTML <head>
+ * - <script type="module"> with hashed URLs in production
+ * - <link rel="modulepreload"> for client chunk dependencies
+ * - Link preload headers for Early Hints (103)
+ *
+ * In dev mode, Vite's HMR client handles CSS/JS injection, so the build
+ * manifest is empty. In production, it's populated from Vite's
+ * .vite/manifest.json after the client build.
+ *
+ * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
+ */
+/** A font asset entry in the build manifest. */
+export interface ManifestFontEntry {
+  /** URL path to the font file (e.g. `/_timber/fonts/inter-latin-400-abc123.woff2`). */
+  href: string;
+  /** Font format (e.g. `woff2`). */
+  format: string;
+  /** Crossorigin attribute — always `anonymous` for fonts. */
+  crossOrigin: string;
+}
+/** Build manifest mapping input file paths to output asset URLs. */
+export interface BuildManifest {
+  /** Map from input file path (relative to project root) to output CSS URLs. */
+  css: Record<string, string[]>;
+  /** Map from input file path to output JS chunk URL (hashed filename). */
+  js: Record<string, string>;
+  /** Map from input file path to transitive JS dependency URLs for modulepreload. */
+  modulepreload: Record<string, string[]>;
+  /** Map from input file path to font assets used by that module. */
+  fonts: Record<string, ManifestFontEntry[]>;
+}
+/** Empty build manifest used in dev mode. */
+export const EMPTY_BUILD_MANIFEST: BuildManifest = {
+  css: {},
+  js: {},
+  modulepreload: {},
+  fonts: {},
+};
+/** Segment shape expected by collectRouteCss (matches ManifestSegmentNode). */
+interface SegmentWithFiles {
+  layout?: { filePath: string };
+  page?: { filePath: string };
+}
+/**
+ * Collect all CSS files needed for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting CSS for each layout and page.
+ * Deduplicates while preserving order (root layout CSS first).
+ */
+export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildManifest): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const segment of segments) {
+    for (const file of [segment.layout, segment.page]) {
+      if (!file) continue;
+      const cssFiles = manifest.css[file.filePath];
+      if (!cssFiles) continue;
+      for (const url of cssFiles) {
+        if (!seen.has(url)) {
+          seen.add(url);
+          result.push(url);
+        }
+      }
+    }
+  }
+  return result;
+}
+/**
+ * Generate <link rel="stylesheet"> tags for CSS URLs.
+ *
+ * Returns an HTML string to prepend to headHtml for injection
+ * via injectHead() before </head>.
+ */
+export function buildCssLinkTags(cssUrls: string[]): string {
+  return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
+}
+/**
+ * Generate a Link header value for CSS preload hints.
+ *
+ * Cloudflare CDN automatically converts Link headers with rel=preload
+ * into 103 Early Hints responses. This avoids platform-specific 103
+ * sending code.
+ *
+ * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
+ */
+export function buildLinkHeaders(cssUrls: string[]): string {
+  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
+}
+// ─── Font utilities ──────────────────────────────────────────────────────
+/**
+ * Collect all font entries needed for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting fonts for each layout and page.
+ * Deduplicates by href while preserving order.
+ */
+export function collectRouteFonts(
+  segments: SegmentWithFiles[],
+  manifest: BuildManifest
+): ManifestFontEntry[] {
+  const seen = new Set<string>();
+  const result: ManifestFontEntry[] = [];
+  for (const segment of segments) {
+    for (const file of [segment.layout, segment.page]) {
+      if (!file) continue;
+      const fonts = manifest.fonts[file.filePath];
+      if (!fonts) continue;
+      for (const entry of fonts) {
+        if (!seen.has(entry.href)) {
+          seen.add(entry.href);
+          result.push(entry);
+        }
+      }
+    }
+  }
+  return result;
+}
+/**
+ * Generate <link rel="preload"> tags for font assets.
+ *
+ * Font preloads use `as=font` and always include `crossorigin` (required
+ * for font preloads even for same-origin resources per the spec).
+ */
+export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
+  return fonts
+    .map(
+      (f) =>
+        `<link rel="preload" href="${f.href}" as="font" type="font/${f.format}" crossorigin="${f.crossOrigin}">`
+    )
+    .join('');
+}
+/**
+ * Generate Link header values for font preload hints.
+ *
+ * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
+ *
+ * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ */
+export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
+  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
+}
+// ─── JS chunk utilities ──────────────────────────────────────────────────
+/**
+ * Collect JS chunk URLs for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting the JS chunk for each layout
+ * and page. Deduplicates while preserving order.
+ */
+export function collectRouteJs(segments: SegmentWithFiles[], manifest: BuildManifest): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const segment of segments) {
+    for (const file of [segment.layout, segment.page]) {
+      if (!file) continue;
+      const jsUrl = manifest.js[file.filePath];
+      if (!jsUrl) continue;
+      if (!seen.has(jsUrl)) {
+        seen.add(jsUrl);
+        result.push(jsUrl);
+      }
+    }
+  }
+  return result;
+}
+/**
+ * Collect modulepreload URLs for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting transitive JS dependencies
+ * for each layout and page. Deduplicates across segments.
+ */
+export function collectRouteModulepreloads(
+  segments: SegmentWithFiles[],
+  manifest: BuildManifest
+): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const segment of segments) {
+    for (const file of [segment.layout, segment.page]) {
+      if (!file) continue;
+      const preloads = manifest.modulepreload[file.filePath];
+      if (!preloads) continue;
+      for (const url of preloads) {
+        if (!seen.has(url)) {
+          seen.add(url);
+          result.push(url);
+        }
+      }
+    }
+  }
+  return result;
+}
+/**
+ * Generate <link rel="modulepreload"> tags for JS dependency URLs.
+ *
+ * Modulepreload hints tell the browser to fetch and parse JS modules
+ * before they're needed, reducing waterfall latency for dynamic imports.
+ */
+export function buildModulepreloadTags(urls: string[]): string {
+  return urls.map((url) => `<link rel="modulepreload" href="${url}">`).join('');
+}
+/**
+ * Generate a <script type="module"> tag for a JS entry point.
+ */
+export function buildEntryScriptTag(url: string): string {
+  return `<script type="module" src="${url}"></script>`;
+}

package/src/server/canonicalize.ts ADDED Viewed

@@ -0,0 +1,90 @@
+/**
+ * URL canonicalization — runs once at the request boundary.
+ *
+ * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same
+ * canonical path. No re-decoding occurs at any later stage.
+ *
+ * See design/07-routing.md §"URL Canonicalization & Security"
+ */
+/** Result of canonicalization — either a clean path or a rejection. */
+export type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; status: 400 };
+/**
+ * Encoded separators that produce a 400 rejection.
+ * %2f (/) and %5c (\) cause path-confusion attacks.
+ */
+const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
+/** Null byte — rejected. */
+const NULL_BYTE_RE = /%00/i;
+/**
+ * Canonicalize a URL pathname.
+ *
+ * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)
+ * 2. Single percent-decode
+ * 3. Collapse // → /
+ * 4. Resolve .. segments (reject if escaping root)
+ * 5. Strip trailing slash (except root "/")
+ *
+ * @param rawPathname - The raw pathname from the request URL (percent-encoded)
+ * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.
+ */
+export function canonicalize(rawPathname: string, stripTrailingSlash = true): CanonicalizeResult {
+  // Step 1: Reject dangerous encoded sequences BEFORE decoding.
+  // This must happen on the raw input so %252f doesn't bypass after a single decode.
+  if (ENCODED_SEPARATOR_RE.test(rawPathname)) {
+    return { ok: false, status: 400 };
+  }
+  if (NULL_BYTE_RE.test(rawPathname)) {
+    return { ok: false, status: 400 };
+  }
+  // Step 2: Single percent-decode.
+  // Double-encoded input (%2561 → %61) stays as %61 — not decoded again.
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(rawPathname);
+  } catch {
+    // Malformed percent-encoding → 400
+    return { ok: false, status: 400 };
+  }
+  // Reject null bytes that appeared after decoding (from valid %00-like sequences
+  // that weren't caught above — belt and suspenders).
+  if (decoded.includes('\0')) {
+    return { ok: false, status: 400 };
+  }
+  // Backslash is NOT a path separator — keep as literal character.
+  // But reject if it would create // after normalization (e.g., /\evil.com).
+  // We do NOT convert \ to / — it stays as a literal.
+  // Step 3: Collapse consecutive slashes.
+  let pathname = decoded.replace(/\/\/+/g, '/');
+  // Step 4: Resolve .. and . segments.
+  const segments = pathname.split('/');
+  const resolved: string[] = [];
+  for (const seg of segments) {
+    if (seg === '..') {
+      if (resolved.length <= 1) {
+        // Trying to escape root — 400
+        return { ok: false, status: 400 };
+      }
+      resolved.pop();
+    } else if (seg !== '.') {
+      resolved.push(seg);
+    }
+  }
+  pathname = resolved.join('/') || '/';
+  // Step 5: Strip trailing slash (except root "/").
+  if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith('/')) {
+    pathname = pathname.slice(0, -1);
+  }
+  return { ok: true, pathname };
+}

package/src/server/client-module-map.ts ADDED Viewed

@@ -0,0 +1,58 @@
+/**
+ * Client module map — maps client reference IDs to their SSR module loaders.
+ *
+ * When the RSC stream contains a client component reference (from a
+ * "use client" module), the SSR environment needs to resolve it to the
+ * actual component module so it can render the component to HTML.
+ *
+ * The @vitejs/plugin-rsc SSR runtime handles this internally via its
+ * setRequireModule hook — it imports client reference modules from the
+ * SSR environment's module graph. This module provides the configuration
+ * bridge between timber's entry system and the RSC plugin's runtime.
+ *
+ * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
+ */
+/**
+ * Client reference metadata used during SSR to resolve client components.
+ *
+ * The RSC plugin tracks these internally via `clientReferenceMetaMap`.
+ * At SSR time, when `createFromReadableStream` encounters a client
+ * reference in the RSC payload, it uses the module map to import the
+ * actual component for server-side HTML rendering.
+ */
+export interface ClientModuleEntry {
+  /** The module ID (Vite-resolved file path) */
+  id: string;
+  /** The export name (e.g., 'default', 'Counter') */
+  name: string;
+  /** Async module loader */
+  load: () => Promise<Record<string, unknown>>;
+}
+/**
+ * Create a client module map for SSR resolution.
+ *
+ * In dev mode, the RSC plugin's SSR runtime (`@vitejs/plugin-rsc/ssr`)
+ * handles client reference resolution automatically via its initialize()
+ * function which sets up `setRequireModule` with dynamic imports through
+ * Vite's dev server. No explicit module map is needed.
+ *
+ * In production builds, the RSC plugin generates a `virtual:vite-rsc/client-references`
+ * module that maps client reference IDs to their chunk imports. The SSR
+ * runtime reads this at startup.
+ *
+ * This function returns an empty map as a placeholder — the actual
+ * resolution is handled by the RSC plugin's runtime internals.
+ */
+export function createClientModuleMap(): Record<string, ClientModuleEntry> {
+  // The @vitejs/plugin-rsc SSR runtime handles client reference
+  // resolution internally. In dev mode, it uses Vite's module runner
+  // to dynamically import client modules. In production, it reads
+  // from the virtual:vite-rsc/client-references manifest.
+  //
+  // This empty map serves as the timber-side type contract. Framework
+  // code that needs to interact with client references at a higher
+  // level (e.g., collecting CSS deps, prefetch hints) can extend this.
+  return {};
+}

package/src/server/csrf.ts ADDED Viewed

@@ -0,0 +1,79 @@
+/**
+ * CSRF protection — Origin header validation.
+ *
+ * Auto-derived from the Host header for single-origin deployments.
+ * Configurable via allowedOrigins for multi-origin setups.
+ * Disable with csrf: false (not recommended outside local dev).
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection"
+ * See design/13-security.md §"Security Testing Checklist" #6
+ */
+// ─── Types ────────────────────────────────────────────────────────────────
+export interface CsrfConfig {
+  /** Explicit list of allowed origins. Replaces Host-based auto-derivation. */
+  allowedOrigins?: string[];
+  /** Set to false to disable CSRF validation entirely. */
+  csrf?: boolean;
+}
+export type CsrfResult = { ok: true } | { ok: false; status: 403 };
+// ─── Constants ────────────────────────────────────────────────────────────
+/** HTTP methods that are considered safe (no mutation). */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+// ─── Implementation ───────────────────────────────────────────────────────
+/**
+ * Validate the Origin header against the request's Host.
+ *
+ * For mutation methods (POST, PUT, PATCH, DELETE):
+ * - If `csrf: false`, skip validation.
+ * - If `allowedOrigins` is set, Origin must match one exactly (no wildcards).
+ * - Otherwise, Origin's host must match the request's Host header.
+ *
+ * Safe methods (GET, HEAD, OPTIONS) always pass.
+ */
+export function validateCsrf(req: Request, config: CsrfConfig): CsrfResult {
+  // Safe methods don't need CSRF protection
+  if (SAFE_METHODS.has(req.method)) {
+    return { ok: true };
+  }
+  // Explicitly disabled
+  if (config.csrf === false) {
+    return { ok: true };
+  }
+  const origin = req.headers.get('Origin');
+  // No Origin header on a mutation → reject
+  if (!origin) {
+    return { ok: false, status: 403 };
+  }
+  // If allowedOrigins is configured, use that instead of Host-based derivation
+  if (config.allowedOrigins) {
+    const allowed = config.allowedOrigins.includes(origin);
+    return allowed ? { ok: true } : { ok: false, status: 403 };
+  }
+  // Auto-derive from Host header
+  const host = req.headers.get('Host');
+  if (!host) {
+    return { ok: false, status: 403 };
+  }
+  // Extract hostname from Origin URL and compare to Host header
+  let originHost: string;
+  try {
+    originHost = new URL(origin).host;
+  } catch {
+    return { ok: false, status: 403 };
+  }
+  return originHost === host ? { ok: true } : { ok: false, status: 403 };
+}