@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/server/rsc-entry/wrap-action-dispatch.ts

@@ -0,0 +1,186 @@
+/**
+ * Action-dispatch wrapper around the route pipeline.
+ *
+ * Extracted from rsc-entry/index.ts so the wiring can be unit-tested in
+ * isolation from Vite's virtual modules.
+ *
+ * ## Architecture (TIM-1213)
+ *
+ * The wrapper is responsible for ONE thing:
+ *
+ *   **Pipeline-boundary CSRF validation** — runs on EVERY unsafe-method
+ *   request, before any dispatch decision. This is the only line of
+ *   defense for `route.ts` API handlers and server actions. See LOCAL-773.
+ *
+ * Server action dispatch has moved INTO the pipeline (`PipelineConfig.
+ * dispatchAction`) so that `proxy.ts` runs on action POSTs — matching the
+ * design doc contract: "proxy.ts runs on every request, no exclusions."
+ *
+ * The `buildActionDispatcher` function constructs the `dispatchAction`
+ * callback that `createPipeline` calls after proxy.ts runs. It
+ * encapsulates action detection, route-type check, action handler
+ * dispatch, and the no-JS validation rerender path.
+ *
+ * Per-segment `middleware.ts` does NOT run on action POSTs (TIM-1134).
+ * Actions are dispatched by action ID, not by route segment. CSRF
+ * validation runs at the pipeline boundary. Per-action auth/validation
+ * belongs in `createActionClient({ middleware })`.
+ */
+
+import type { FormRerender } from '../action-handler.ts';
+import { handleActionRequest, isActionRequest } from '../action-handler.ts';
+import type { BodyLimitsConfig } from '../body-limits.ts';
+import { validateCsrf, type CsrfConfig } from '../csrf.ts';
+import { runWithFormFlash } from '../form-flash.ts';
+import { seedRequestCookies } from '../cookie-context.ts';
+import type { RouteMatcher } from '../pipeline.ts';
+import type { SensitiveFieldsOption } from '../sensitive-fields.ts';
+import type { RevalidateRenderer } from '../actions.ts';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a `RevalidateRenderer` for a specific request.
+ *
+ * The renderer needs to forward cookies/headers from the originating
+ * request when fetching the revalidated route. We pass the request in
+ * via a builder so the wrapper doesn't need to know about route matching,
+ * segment param coercion, or element building — those concerns stay in
+ * `rsc-entry/index.ts`.
+ */
+export type RevalidateRendererFactory = (req: Request) => RevalidateRenderer;
+
+/** Dependencies for the CSRF wrapper. */
+export interface ActionDispatchDeps {
+  /** CSRF configuration (Origin allow-list, on/off switch). */
+  csrfConfig: CsrfConfig;
+}
+
+/** Dependencies for the action dispatcher (used inside the pipeline). */
+export interface ActionDispatcherDeps {
+  /** CSRF configuration — defense-in-depth check inside the action handler. */
+  csrfConfig: CsrfConfig;
+  /** Body size limits forwarded to `handleActionRequest`. */
+  bodyLimits?: BodyLimitsConfig['limits'];
+  /** Sensitive-field deny-list forwarded to `handleActionRequest`. */
+  sensitiveFields?: SensitiveFieldsOption;
+  /** Per-request factory that builds a `RevalidateRenderer`. */
+  buildRevalidateRenderer: RevalidateRendererFactory;
+  /**
+   * Route matcher — used for the route-type check that skips action
+   * detection on `route.ts` API handlers (TIM-870).
+   */
+  matchRoute?: RouteMatcher;
+}
+
+// ─── CSRF Wrapper ─────────────────────────────────────────────────────────
+
+/**
+ * Wrap a pipeline function with pipeline-boundary CSRF validation.
+ *
+ * The returned handler is the framework's outermost request entry point.
+ * It validates the `Origin` header on every unsafe-method request before
+ * any dispatch decision — this is the ONLY line of defense for `route.ts`
+ * API handlers, which never see the action handler.
+ *
+ * Action dispatch has moved inside the pipeline (TIM-1213) so proxy.ts
+ * runs on every request. This wrapper now only handles CSRF.
+ */
+export function wrapPipelineWithActionDispatch(
+  pipeline: (req: Request) => Promise<Response>,
+  deps: ActionDispatchDeps
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    // Pipeline-boundary CSRF validation (LOCAL-773).
+    // Runs on EVERY unsafe-method request, before any dispatch decision.
+    const csrfResult = validateCsrf(req, deps.csrfConfig);
+    if (!csrfResult.ok) {
+      return new Response(null, { status: csrfResult.status });
+    }
+
+    return pipeline(req);
+  };
+}
+
+// ─── Action Dispatcher ────────────────────────────────────────────────────
+
+/**
+ * Build the `dispatchAction` callback for `PipelineConfig`.
+ *
+ * Called after proxy.ts runs (inside the pipeline) for every request.
+ * Checks if the request is a server action POST, handles the route-type
+ * check (TIM-870), dispatches to the action handler, and handles the
+ * no-JS validation rerender path.
+ *
+ * Returns `Response` if the request was handled as an action, `null` to
+ * fall through to normal routing.
+ */
+export function buildActionDispatcher(
+  deps: ActionDispatcherDeps
+): (
+  req: Request,
+  canonicalPath: string,
+  reenter: (req: Request) => Promise<Response>
+) => Promise<Response | null> {
+  return async (
+    req: Request,
+    canonicalPath: string,
+    reenter: (req: Request) => Promise<Response>
+  ): Promise<Response | null> => {
+    if (!isActionRequest(req)) return null;
+
+    // Route-type check (TIM-870): match the route BEFORE any body parsing.
+    // If the matched route is an API route (route.ts), skip action detection
+    // entirely — server actions only live on page routes; POSTs to route.ts
+    // are API requests whose body must reach the handler untouched.
+    //
+    // Use `canonicalPath` from the pipeline — NOT `new URL(req.url).pathname`,
+    // which re-encodes the path. The matcher expects the decoded canonical form.
+    if (deps.matchRoute) {
+      const match = deps.matchRoute(canonicalPath);
+      if (match) {
+        const leaf = match.segments[match.segments.length - 1];
+        if (leaf?.route) {
+          return null;
+        }
+      }
+    }
+
+    // Action handler dispatch
+    const actionResponse = await handleActionRequest(req, {
+      csrf: deps.csrfConfig,
+      bodyLimits: { limits: deps.bodyLimits },
+      sensitiveFields: deps.sensitiveFields,
+      revalidateRenderer: deps.buildRevalidateRenderer(req),
+    });
+
+    if (actionResponse) {
+      // No-JS validation rerender
+      if ('rerender' in actionResponse) {
+        const formRerender = actionResponse as FormRerender;
+        // Build a synthetic GET request for the rerender pipeline:
+        //   - Same URL (so route matching lands on the same page)
+        //   - Cookie header DROPPED entirely. The post-action RYW state
+        //     is threaded into the rerender request context as a parsed
+        //     `Map<string, string>` via `seedRequestCookies` below.
+        //   - Method GET because the rerender is conceptually a page render.
+        const rerenderHeaders = new Headers(req.headers);
+        rerenderHeaders.delete('cookie');
+        const rerenderReq = new Request(req.url, {
+          method: 'GET',
+          headers: rerenderHeaders,
+        });
+        seedRequestCookies(rerenderReq, formRerender.cookies);
+        const response = await runWithFormFlash(formRerender.rerender, () => reenter(rerenderReq));
+        // Apply Set-Cookie headers snapshotted from the action's ALS scope.
+        for (const value of formRerender.setCookieHeaders) {
+          response.headers.append('Set-Cookie', value);
+        }
+        return response;
+      }
+      return actionResponse;
+    }
+
+    return null;
+  };
+}

package/src/server/rsc-error-envelope.ts

@@ -0,0 +1,18 @@
+import { TIMBER_ERROR_HEADER } from '../shared/rsc-error-envelope.ts';
+import { errorResponseHeaders } from './error-response-headers.ts';
+
+/**
+ * Build the hard-navigate envelope for a status code.
+ *
+ * Preserve middleware's request-wide headers and cookies, but discard the
+ * abandoned body's framing, validators, and cache policy. Every producer,
+ * including errors returned normally during render, gets this cleanup here.
+ * The input header bag is left intact. The body deliberately carries no message —
+ * only the status already on the wire (design/13-security.md principle 4).
+ */
+export function rscErrorEnvelope(status: number, responseHeaders?: Headers): Response {
+  const headers = errorResponseHeaders(responseHeaders);
+  headers.set(TIMBER_ERROR_HEADER, '1');
+  headers.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify({ error: true, status }), { status, headers });
+}

package/src/server/rsc-prop-warnings.ts

@@ -16,7 +16,7 @@
  * Task: TIM-358
  */
 
-import { isDebug } from './debug.js';
+import { isDebug } from './debug.ts';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 

package/src/server/safe-load.ts

@@ -0,0 +1,60 @@
+/**
+ * loadModule — enriched error context for route manifest .load() failures.
+ *
+ * Wraps the lazy `load()` functions from the route manifest with a
+ * try/catch that re-throws with the file path and original cause.
+ *
+ * Callers that need fallthrough behavior (error renderers) can use
+ * `.catch(() => null)` or try/catch — the decision stays at the call site.
+ *
+ * See design/spike-TIM-551-dynamic-import-audit.md §"Proposed Wrapping Strategy"
+ */
+
+/** A manifest file reference with a lazy import function and file path. */
+export interface ManifestLoader {
+  load: () => Promise<unknown>;
+  filePath: string;
+}
+
+/**
+ * Custom error class for module load failures.
+ *
+ * Preserves the original error as `cause` while providing a
+ * human-readable message with the file path.
+ */
+export class ModuleLoadError extends Error {
+  /** The file path that failed to load. */
+  readonly filePath: string;
+
+  constructor(filePath: string, cause: unknown) {
+    const originalMessage = cause instanceof Error ? cause.message : String(cause);
+    super(`[timber] Failed to load module ${filePath}\n  ${originalMessage}`, { cause });
+    this.name = 'ModuleLoadError';
+    this.filePath = filePath;
+  }
+}
+
+/**
+ * Load a route manifest module with enriched error context.
+ *
+ * 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);
+ * ```
+ */
+export async function loadModule<T = Record<string, unknown>>(loader: ManifestLoader): Promise<T> {
+  try {
+    return (await loader.load()) as T;
+  } catch (error) {
+    throw new ModuleLoadError(loader.filePath, error);
+  }
+}

package/src/server/sensitive-fields.ts

@@ -0,0 +1,230 @@
+/**
+ * Sensitive field stripping — removes password/token/CVV-style fields
+ * from form values before they are echoed back to the client as
+ * `submittedValues` for form repopulation.
+ *
+ * Applied to both action paths:
+ *  - With-JS action path: `createActionClient()` in `action-client.ts`
+ *  - No-JS form POST path: `handleFormAction()` in `action-handler.ts`
+ *
+ * Why: on a validation failure, timber echoes submitted form values back so
+ * the user doesn't have to re-type everything. Without filtering, plaintext
+ * passwords / credit-card numbers / TOTP codes would travel through the RSC
+ * stream (with-JS) or land in the HTML as `defaultValue` attributes (no-JS)
+ * — ending up in browser history, proxy logs, disk caches, and the
+ * back-forward cache.
+ *
+ * Safe by default: the built-in deny-list is applied unconditionally unless
+ * the user explicitly opts out via `forms.stripSensitiveFields: false` in
+ * `timber.config.ts` or per-action via `createActionClient({ stripSensitiveFields: false })`.
+ *
+ * See design/08-forms-and-actions.md §"Validation errors"
+ * See design/13-security.md §"Sensitive field stripping"
+ * See TIM-816
+ */
+
+import { isDebug } from './debug.ts';
+
+// ─── Public types ────────────────────────────────────────────────────────
+
+/**
+ * How to strip sensitive fields from `submittedValues`.
+ *
+ * - `true` / `undefined` — use the built-in deny-list (default, safe).
+ * - `false` — do not strip anything (dev convenience; never do this in prod).
+ * - `string[]` — additional field names to strip, merged with the built-in list.
+ * - `(name) => boolean` — custom predicate, fully replaces the built-in list.
+ *   Return `true` to strip, `false` to keep. The `name` argument is the raw
+ *   (un-normalized) field name as it appeared in the submitted form.
+ */
+export type SensitiveFieldsOption = boolean | readonly string[] | ((name: string) => boolean);
+
+// ─── Built-in deny-list ──────────────────────────────────────────────────
+
+/**
+ * Substring patterns matched against the normalized field name.
+ * Normalization = lowercase + strip `_` and `-`.
+ *
+ * Any field whose normalized name *contains* one of these strings is
+ * considered sensitive. Entries like `currentPassword`, `passwordConfirmation`,
+ * and `user.password` all match via the `password` substring.
+ */
+const BUILTIN_SUBSTRING_PATTERNS: readonly string[] = [
+  'password',
+  'passwd',
+  'pwd',
+  'secret',
+  'apikey',
+  'accesstoken',
+  'refreshtoken',
+  'cvv',
+  'cvc',
+  'cardnumber',
+  'cardcvc',
+  'ssn',
+  'socialsecuritynumber',
+  'otp',
+  'totp',
+  'mfacode',
+  'twofactorcode',
+  'privatekey',
+];
+
+/**
+ * Exact matches against the normalized field name. These are field names that
+ * are too short or too common to substring-match safely. e.g. `token` alone
+ * would match `csrfToken`, which is not sensitive — so `token` is exact-only,
+ * while legitimate token fields are covered by `accesstoken` / `refreshtoken`.
+ */
+const BUILTIN_EXACT_PATTERNS: readonly string[] = ['token'];
+
+/**
+ * Normalize a field name for deny-list comparison.
+ * Lowercases the string and strips `_` and `-` so camelCase, snake_case, and
+ * kebab-case variants all compare equal (`api_key` / `apiKey` / `api-key` →
+ * `apikey`).
+ */
+function normalize(name: string): string {
+  let out = '';
+  for (let i = 0; i < name.length; i++) {
+    const ch = name.charCodeAt(i);
+    if (ch === 0x5f /* _ */ || ch === 0x2d /* - */) continue;
+    // A-Z → a-z
+    if (ch >= 0x41 && ch <= 0x5a) {
+      out += String.fromCharCode(ch + 32);
+    } else {
+      out += name[i];
+    }
+  }
+  return out;
+}
+
+/**
+ * Check whether a name matches the built-in deny-list (with optional extras).
+ * Extras are merged into the substring pattern list after normalization.
+ */
+function isBuiltinSensitive(name: string, extras?: readonly string[]): boolean {
+  const normalized = normalize(name);
+  if (BUILTIN_EXACT_PATTERNS.includes(normalized)) return true;
+  for (const pattern of BUILTIN_SUBSTRING_PATTERNS) {
+    if (normalized.includes(pattern)) return true;
+  }
+  if (extras && extras.length > 0) {
+    for (const extra of extras) {
+      const normExtra = normalize(extra);
+      if (normExtra.length === 0) continue;
+      if (normalized.includes(normExtra)) return true;
+    }
+  }
+  return false;
+}
+
+// ─── Predicate resolution ────────────────────────────────────────────────
+
+/**
+ * A resolved predicate: `null` means "don't strip anything" (the option was
+ * explicitly `false`). Otherwise a function from raw field name → boolean.
+ */
+export type ResolvedSensitivePredicate = ((name: string) => boolean) | null;
+
+/**
+ * Resolve a `SensitiveFieldsOption` into a concrete predicate.
+ * Precedence: per-action > global > built-in default.
+ *
+ * - Per-action `undefined` → fall back to global.
+ * - Global `undefined` → use built-in list.
+ * - Either level set to `false` → disable stripping entirely (returns `null`).
+ * - `true` → built-in list.
+ * - `string[]` → built-in ∪ extras.
+ * - function → custom, replaces the built-in list entirely.
+ */
+export function resolveSensitivePredicate(
+  perAction: SensitiveFieldsOption | undefined,
+  global: SensitiveFieldsOption | undefined
+): ResolvedSensitivePredicate {
+  const chosen = perAction !== undefined ? perAction : global;
+
+  if (chosen === false) return null;
+  if (chosen === undefined || chosen === true) {
+    return (name) => isBuiltinSensitive(name);
+  }
+  if (typeof chosen === 'function') {
+    return chosen;
+  }
+  // Array of extra names merged with the built-in list.
+  const extras = chosen;
+  return (name) => isBuiltinSensitive(name, extras);
+}
+
+// ─── Module-level global config ──────────────────────────────────────────
+
+let globalConfig: SensitiveFieldsOption | undefined;
+
+/**
+ * Set the global `forms.stripSensitiveFields` config from `timber.config.ts`.
+ * Called once at startup from `rsc-entry`.
+ */
+export function setGlobalSensitiveFieldsConfig(option: SensitiveFieldsOption | undefined): void {
+  globalConfig = option;
+}
+
+/** Read the global `forms.stripSensitiveFields` config. */
+export function getGlobalSensitiveFieldsConfig(): SensitiveFieldsOption | undefined {
+  return globalConfig;
+}
+
+// ─── Stripping ───────────────────────────────────────────────────────────
+
+// One warning per field name per process — prevents log spam when a form is
+// submitted many times in dev mode.
+const warnedFields = new Set<string>();
+
+function warnStripped(name: string): void {
+  if (!isDebug()) return;
+  if (warnedFields.has(name)) return;
+  warnedFields.add(name);
+  console.warn(
+    `[timber] stripped sensitive field "${name}" from submittedValues. ` +
+      `Override via forms.stripSensitiveFields in timber.config.ts.`
+  );
+}
+
+/**
+ * Walk an object (recursively) and return a copy with every key matching
+ * `predicate` removed. Nested objects like `{ user: { password: '...' } }`
+ * are handled — `user.password` is stripped while other `user.*` fields remain.
+ *
+ * - Arrays are walked element-wise (object entries inside arrays are cleaned).
+ * - Non-plain values (strings, numbers, Files, Dates, etc.) are returned as-is.
+ * - When a stripped key is encountered, it is omitted from the result entirely
+ *   — we do NOT set it to an empty string, because that would overwrite a
+ *   valid `defaultValue` the form author might have set.
+ */
+export function stripSensitiveFields<T>(value: T, predicate: ResolvedSensitivePredicate): T {
+  // Null predicate = stripping disabled entirely.
+  if (predicate === null) return value;
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+  if (value instanceof File || value instanceof Date) return value;
+
+  if (Array.isArray(value)) {
+    return value.map((item) => stripSensitiveFields(item, predicate)) as unknown as T;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+    if (predicate(key)) {
+      warnStripped(key);
+      continue;
+    }
+    result[key] = stripSensitiveFields(nested, predicate);
+  }
+  return result as unknown as T;
+}
+
+// ─── Test helpers ────────────────────────────────────────────────────────
+
+/** Reset the "warned once" cache. Exposed for tests. */
+export function __resetSensitiveFieldsWarnings(): void {
+  warnedFields.clear();
+}

package/src/server/server-only-guard-noop.js

@@ -0,0 +1,3 @@
+// No-op module for Node.js and vitest resolution of #server-only-guard.
+// The shims plugin intercepts this specifier in the client environment
+// and returns the server-only poison pill instead.

package/src/server/server-timing.ts

@@ -11,7 +11,7 @@
  * Task: LOCAL-290
  */
 
-import { timingAls } from './als-registry.js';
+import { timingAls } from './als-registry.ts';
 
 // ─── Types ────────────────────────────────────────────────────────────────