@timber-js/app 0.2.0-alpha.209 → 0.2.0-alpha.210

package/dist/server/internal.js

@@ -1,19 +1,19 @@
 import { r as RenderTimeoutError, t as DEFAULT_RENDER_TIMEOUT_MS } from "../_chunks/render-timeout-DOf_BBcO.js";
 import { n as isRscContentType, r as isRscRequest } from "../_chunks/rsc-media-type-DDc7duTD.js";
-import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-DSDjM_hJ.js";
-import { r as canonicalize } from "../_chunks/canonicalize-CgHoscYO.js";
 import { n as classifyUrlSegment, r as effectiveUrlSegment } from "../_chunks/segment-classify-C539Pa2O.js";
 import { t as computeSegmentTreePaths } from "../_chunks/segment-keys-D5hu1hz4.js";
+import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-DSDjM_hJ.js";
+import { r as canonicalize } from "../_chunks/canonicalize-CgHoscYO.js";
 import { a as requestContextAls, r as prebuiltCaptureAls, s as timingAls, t as earlyHintsSenderAls } from "../_chunks/als-registry-DaxkVjt5.js";
-import { A as getTraceId, C as isDebug, D as generateTraceId, M as runWithTraceId, N as setSpanAttribute, O as getOtelTraceId, P as withSpan, S as isRedirectSignal, _ as swallow, a as logMiddlewareShortCircuit, b as isControlFlowSignal, c as logRequestCompleted, d as logRouteSetupError, f as logSlowRequest, g as setLogger, h as logWaitUntilUnsupported, i as logMiddlewareError, j as replaceTraceId, l as logRequestReceived, m as logWaitUntilRejected, n as logCacheMiss, o as logProxyError, p as logSwrRefetchFailed, s as logRenderError, t as getLogger, u as logRouteError, x as isDenySignal } from "../_chunks/logger-DiDt5ppH.js";
+import { C as isRedirectSignal, F as withSpan, M as replaceTraceId, N as runWithTraceId, O as generateTraceId, P as setSpanAttribute, S as isDenySignal, _ as setLogger, a as logMiddlewareError, c as logRenderError, d as logRouteError, f as logRouteSetupError, g as logWaitUntilUnsupported, h as logWaitUntilRejected, j as getTraceId, k as getOtelTraceId, l as logRequestCompleted, m as logSwrRefetchFailed, n as logCacheMiss, o as logMiddlewareShortCircuit, p as logSlowRequest, r as logCsrfRejected, s as logProxyError, t as getLogger, u as logRequestReceived, v as swallow, w as isDebug, x as isControlFlowSignal } from "../_chunks/logger-BP0LN6vP.js";
 import { i as collectRouteModulepreloads, n as collectRouteCss, r as collectRouteFonts } from "../_chunks/build-manifest-DWppEdLB.js";
 import { i as isRscCacheKeyShape, n as RSC_KEY_PARAM, s as rscCacheKey, t as RSC_KEY_HEADERS } from "../_chunks/rsc-cache-key-ClUiXQnK.js";
-import { C as setMutableCookieContext, S as setMatchedSegmentPath, T as runOutsideReactCacheScope, b as markResponseFlushed, f as getCookie, g as getHeader, h as applyRequestHeaderOverlay, i as coerce, m as getSetCookieHeaders, o as DenySignal, s as RedirectSignal, t as executeAction, v as getSearchParams, w as setSegmentParams, x as runWithRequestContext, y as getSegmentParams } from "../_chunks/actions-BerlqoXA.js";
-import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPayload, d as checkVersionSkew, i as storeOverlayEntry, l as setPrebuiltPayloadSource, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as isParamIndependent, u as applyReloadHeaders, v as currentInvalidationEpoch, x as getWaitUntil, y as lastInvalidationEpochFor } from "../_chunks/cache-api-CR23J_NC.js";
+import { C as setMutableCookieContext, S as setMatchedSegmentPath, T as runOutsideReactCacheScope, b as markResponseFlushed, f as getCookie, g as getHeader, h as applyRequestHeaderOverlay, i as coerce, m as getSetCookieHeaders, o as DenySignal, s as RedirectSignal, t as executeAction, v as getSearchParams, w as setSegmentParams, x as runWithRequestContext, y as getSegmentParams } from "../_chunks/actions-Rjk4htmA.js";
+import { a as getManifestEntry, b as wasInvalidatedSince, c as lookupPrebuiltPayload, d as checkVersionSkew, i as storeOverlayEntry, l as setPrebuiltPayloadSource, n as lookupOverlay, o as hasPrebuiltPayloadSource, r as overlayKey, s as isParamIndependent, u as applyReloadHeaders, v as currentInvalidationEpoch, x as getWaitUntil, y as lastInvalidationEpochFor } from "../_chunks/cache-api-DGdYfNJn.js";
 import { n as createSingleflight } from "../_chunks/singleflight-BeVMMKi0.js";
 import { n as toBracketKey } from "../_chunks/resolve-schema-CBR6Lm4i.js";
 import { t as normalizeParamValue } from "../_chunks/param-value-C8TNYchQ.js";
-import { l as TIMBER_ERROR_HEADER, t as StatusPageMarker } from "../_chunks/status-page-marker-gaihi0KZ.js";
+import { l as TIMBER_ERROR_HEADER, t as StatusPageMarker } from "../_chunks/status-page-marker-BRX9Ib-d.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import React, { createElement, useContext } from "react";
@@ -317,16 +317,7 @@ var ModuleLoadError = class extends Error {
 * On success: returns the module object (same as `loader.load()`).
 * On failure: throws `ModuleLoadError` with file path and original cause.
 *
-* For error rendering paths that need fallthrough instead of throwing,
-* callers should catch at the call site:
-*
-* ```ts
-* // Throwing (default) — route-element-builder, api-handler, etc.
-* const mod = await loadModule(segment.page);
-*
-* // Fallthrough — error-renderer, error-boundary-wrapper
-* const mod = await loadModule(segment.error).catch(() => null);
-* ```
+* Error rendering paths that need fallthrough use `loadFallbackModule()`.
 */
 async function loadModule(loader) {
 	try {
@@ -347,12 +338,248 @@ function isApiRouteChain(segments) {
 	const leaf = segments[segments.length - 1];
 	return !!leaf?.route && !leaf.page;
 }
+/**
+* Whether a matched chain is a route.ts handler that opted out of the CSRF
+* check with `export const csrf = false`. Keyed on the same leaf
+* `isApiRouteChain` dispatches on, so the exemption can only ever apply to
+* the route.ts that will actually run — never to a page, and so never to a
+* server action. See design/08-forms-and-actions.md §"Per-route exemption".
+*/
+function isCsrfExemptRoute(segments) {
+	return isApiRouteChain(segments) && segments[segments.length - 1]?.csrfExempt === true;
+}
 var SERVE_PATH_TO_CONVENTION = /* @__PURE__ */ new Map();
 for (const [baseName, convention] of Object.entries(METADATA_ROUTE_CONVENTIONS)) if (convention.serveExtension) for (const ext of [...convention.staticExtensions, convention.serveExtension]) SERVE_PATH_TO_CONVENTION.set(`${convention.servePath}.${ext}`, baseName);
 else SERVE_PATH_TO_CONVENTION.set(convention.servePath, baseName);
 //#endregion
+//#region src/shared/csrf-reject.ts
+/**
+* Marker header on CSRF rejections.
+*
+* A CSRF rejection is a 403, the same status as an access-control denial.
+* The server stamps this header on every CSRF 403 so callers — the browser
+* action runtime, a same-origin `fetch` in user code, a curl session — can
+* tell the two apart without parsing the body. A cross-origin `fetch` cannot
+* read it: the rejection returns before proxy.ts, so no CORS headers are set
+* and the browser reports a network error instead. Shared so the server writer and the client
+* reader cannot drift.
+*
+* See design/08-forms-and-actions.md §"CSRF Protection" (TIM-1459).
+*/
+var CSRF_REJECT_HEADER = "X-Timber-Reject";
+var CSRF_REJECT_VALUE = "csrf";
+//#endregion
+//#region src/server/csrf.ts
+/**
+* CSRF protection — Fetch Metadata first, Origin as the fallback.
+*
+* CSRF needs a victim's browser to attach cookies, and browsers mark the
+* requests they send: `Sec-Fetch-Site` on HTTPS (and localhost) pages in
+* every current browser, `Origin` on cross-site POSTs everywhere else. So
+* the check trusts those two headers in that order, and lets a request
+* carrying neither through — a webhook, curl, or a server-to-server
+* `fetch`. The residual risk is browsers old enough to send neither on a
+* form POST (Firefox < 70, IE11); SameSite cookies are the defense there.
+* See design/08-forms-and-actions.md §"CSRF Protection".
+*
+* Prior art: Go's `net/http.CrossOriginProtection` (Go 1.25) and the OWASP
+* CSRF cheat sheet (Fetch Metadata as a primary defense).
+*
+* The per-route exemption (`export const csrf = false` in route.ts) is not
+* decided here: the caller owns route matching and applies it to a
+* rejection. Disable globally with csrf: false (not recommended).
+*
+* See design/08-forms-and-actions.md §"CSRF Protection"
+* See design/13-security.md §"Security Testing Checklist" #6
+*/
+/** HTTP methods that are considered safe (no mutation). */
+var SAFE_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+/**
+* `Sec-Fetch-Site` values that mean the browser itself vouches for the
+* request: `same-origin`, or `none` (user-initiated — typed URL, bookmark).
+* Every other value, including ones no browser sends, is not same-origin.
+* The header is forbidden to page scripts, so a page cannot forge it.
+*/
+var TRUSTED_FETCH_SITES = /* @__PURE__ */ new Set(["same-origin", "none"]);
+/**
+* Derive the request's scheme from trusted sources.
+*
+* Priority:
+* 1. X-Forwarded-Proto (set by reverse proxies / load balancers)
+* 2. Request URL protocol
+*
+* Falls back to 'https' (fail closed) if neither is available.
+*/
+function deriveRequestScheme(req) {
+	const forwarded = req.headers.get("X-Forwarded-Proto");
+	if (forwarded) {
+		const proto = forwarded.split(",")[0].trim().toLowerCase();
+		if (proto === "http" || proto === "https") return proto;
+	}
+	try {
+		return new URL(req.url).protocol.replace(":", "");
+	} catch {
+		return "https";
+	}
+}
+/**
+* Decide whether an unsafe-method request may proceed.
+*
+* In order:
+* 1. `Sec-Fetch-Site` is `same-origin` or `none` → allow.
+* 2. `Sec-Fetch-Site` has any other value → allow only if `Origin` is in
+*    `allowedOrigins`.
+* 3. No `Sec-Fetch-Site`, `Origin` present (a plain-HTTP page, or an
+*    older browser) → `Origin` must be in `allowedOrigins` or equal the
+*    origin derived from the scheme and `Host`.
+* 4. Neither header → allow: not a browser, so no ambient cookies to abuse.
+*
+* Safe methods (GET, HEAD, OPTIONS) and `csrf: false` always pass.
+*/
+function validateCsrf(req, config) {
+	if (SAFE_METHODS.has(req.method)) return { ok: true };
+	if (config.csrf === false) return { ok: true };
+	const fetchSite = req.headers.get("Sec-Fetch-Site");
+	const origin = req.headers.get("Origin");
+	const rejection = (reason, expected) => ({
+		ok: false,
+		status: 403,
+		reason,
+		origin,
+		fetchSite,
+		expected
+	});
+	if (fetchSite !== null) {
+		if (TRUSTED_FETCH_SITES.has(fetchSite)) return { ok: true };
+		if (origin !== null && config.allowedOrigins?.includes(origin)) return { ok: true };
+		return rejection("cross-origin", config.allowedOrigins ?? []);
+	}
+	if (origin === null) return { ok: true };
+	const allowed = config.allowedOrigins ?? [];
+	if (allowed.includes(origin)) return { ok: true };
+	const host = req.headers.get("Host");
+	if (!host) return rejection("missing-host", allowed);
+	let originOrigin;
+	try {
+		originOrigin = new URL(origin).origin;
+	} catch {
+		return rejection("invalid-origin", allowed);
+	}
+	let expectedOrigin;
+	try {
+		expectedOrigin = new URL(`${deriveRequestScheme(req)}://${host}`).origin;
+	} catch {
+		return rejection("invalid-host", allowed);
+	}
+	return originOrigin === expectedOrigin ? { ok: true } : rejection("origin-mismatch", [expectedOrigin, ...allowed]);
+}
+/**
+* Longest request-derived value echoed into the server log. Origin, Host,
+* Sec-Fetch-Site, and the path are attacker-controlled; a request can carry
+* kilobytes in each, and every rejection writes a log line. Real values are
+* far shorter.
+*/
+var MAX_LOGGED_VALUE = 200;
+function clip(value) {
+	return value.length > MAX_LOGGED_VALUE ? `${value.slice(0, MAX_LOGGED_VALUE)}…` : value;
+}
+/**
+* Clip and quote a request-derived value for the log. JSON quoting escapes
+* quotes and control characters, so a crafted header cannot close the quote
+* and forge `key=value` fields or a second line.
+*/
+function quote(value) {
+	return JSON.stringify(clip(value));
+}
+var PROXY_HINT = "If the app runs behind a proxy that rewrites Host or terminates TLS, forward the original Host and X-Forwarded-Proto, or list the public origin in allowedOrigins in timber.config.ts.";
+var EXEMPTION_HINT = "If this route.ts must accept cross-site browser requests (OIDC form_post, SAML, 3-D Secure returns), add `export const csrf = false` to it.";
+/**
+* Browsers send `Origin: null` from opaque contexts: sandboxed iframes, a POST
+* redirected across origins, file: pages. Every such context shares the one
+* value — an attacker's `<iframe sandbox>` included — so config validation
+* refuses it in `allowedOrigins` and the hint points at the exemption instead.
+*/
+var OPAQUE_ORIGIN_DETAIL = `origin "null" is an opaque origin (sandboxed iframe, a POST redirected across origins, or a file: page). allowedOrigins cannot admit it: every opaque context sends "null", including an attacker's sandboxed iframe. ${EXEMPTION_HINT}`;
+/** One sentence per rejection path: what was observed, and what to change. */
+function describeRejection(r, host) {
+	const opaque = r.origin === "null";
+	const origin = quote(r.origin ?? "");
+	const expected = r.expected.map(quote).join(", ");
+	switch (r.reason) {
+		case "cross-origin": {
+			if (opaque) return OPAQUE_ORIGIN_DETAIL;
+			const from = r.origin === null ? "with no Origin header" : `from origin ${origin}`;
+			const allowed = r.expected.length > 0 ? ` and is not in allowedOrigins [${expected}]` : "";
+			return `Sec-Fetch-Site ${quote(r.fetchSite ?? "")} request ${from}: the browser reports it is not same-origin${allowed}. If this origin is legitimate, add it to allowedOrigins in timber.config.ts. ${EXEMPTION_HINT}`;
+		}
+		case "missing-host": return `origin ${origin} could not be checked: request has no Host header. ${PROXY_HINT}`;
+		case "invalid-host": return `origin ${origin} could not be checked: Host header ${quote(host ?? "")} is not a valid host. ${PROXY_HINT}`;
+		case "invalid-origin":
+			if (opaque) return OPAQUE_ORIGIN_DETAIL;
+			return `Origin header ${origin} is not a valid origin.`;
+		case "origin-mismatch": {
+			const [own, ...listed] = r.expected.map(quote);
+			return `origin ${origin} does not match the request origin ${own}${listed.length > 0 ? ` or allowedOrigins [${listed.join(", ")}]` : ""}. ${PROXY_HINT}`;
+		}
+	}
+}
+/**
+* Turn a failed check into the response the client sees, and log why.
+*
+* The response is a 403 marked as a CSRF rejection (header + plain-text
+* body) so it cannot be mistaken for an access-control 403. It never
+* carries the observed or expected origins — `allowedOrigins` is server
+* configuration, and a Host-derived origin can be an internal hostname
+* behind a proxy. The server log gets the full diagnosis.
+*/
+function csrfRejectionResponse(req, rejection) {
+	logCsrfRejected(describeRejection(rejection, req.headers.get("Host")), {
+		method: req.method,
+		path: clip(new URL(req.url).pathname),
+		reason: rejection.reason
+	});
+	return new Response("Forbidden: CSRF origin check failed\n", {
+		status: rejection.status,
+		headers: {
+			"Content-Type": "text/plain; charset=utf-8",
+			[CSRF_REJECT_HEADER]: CSRF_REJECT_VALUE
+		}
+	});
+}
+//#endregion
 //#region src/server/pipeline-helpers.ts
 /**
+* The pipeline-boundary CSRF gate: the 403 to answer with, or null to go on.
+*
+* Runs on every request after canonicalization and before proxy.ts, so it
+* covers route.ts handlers and server actions alike, and no user code has
+* run when it decides. The per-route exemption is looked up only for a
+* request the check would reject — the common accepted request never pays
+* for a match. The lookup uses the pipeline's own matcher on the canonical
+* path, the same match `handleRequest` dispatches on, and reads a flag the
+* scanner took from route.ts source, so deciding it loads no module.
+*
+* A matcher that throws leaves the request unexempted: fail closed.
+*
+* See design/08-forms-and-actions.md §"CSRF Protection".
+*/
+function csrfGate(req, canonicalPath, csrf, matchRoute) {
+	const result = validateCsrf(req, csrf);
+	if (result.ok) return null;
+	let exempt = false;
+	try {
+		const match = matchRoute(canonicalPath);
+		exempt = match !== null && isCsrfExemptRoute(match.segments);
+	} catch (err) {
+		swallow(err, "csrf gate: route match for exemption lookup threw");
+	}
+	return exempt ? null : csrfRejectionResponse(req, result);
+}
+/**
 * Build a proxy resolver closure from the declared source. Called exactly
 * once at `createPipeline` setup time, so the hot path sees only the branch
 * that corresponds to this pipeline's configured variant.
@@ -1784,6 +2011,7 @@ function createPipeline(config) {
 							const canonResult = canonicalize(url.pathname, stripTrailingSlash);
 							if (!canonResult.ok) {
 								if (isDebug()) console.warn(`[timber] URL canonicalization rejected ${method} ${url.pathname} — responding with ${canonResult.status}\n  This usually means the URL contains encoded separators (%2f, %5c),\n  null bytes (%00), path traversal (..), or malformed percent-encoding.`);
+								await setSpanAttribute("http.response.status_code", canonResult.status);
 								return new Response(null, { status: canonResult.status });
 							}
 							const canonicalPath = canonResult.pathname;
@@ -1793,6 +2021,11 @@ function createPipeline(config) {
 								canonicalUrl.pathname = canonicalPath;
 								canonicalReq = new Request(canonicalUrl.toString(), req);
 							}
+							const csrfRejection = csrfGate(canonicalReq, canonicalPath, config.csrf ?? {}, config.matchRoute);
+							if (csrfRejection) {
+								await setSpanAttribute("http.response.status_code", csrfRejection.status);
+								return csrfRejection;
+							}
 							const innerHandler = async () => {
 								if (config.dispatchAction) {
 									const actionResult = await config.dispatchAction(canonicalReq, canonicalPath, pipelineFn);