@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/action-handler.ts

@@ -18,19 +18,27 @@ import {
   decodeReply,
   decodeAction,
   renderToReadableStream,
-} from '#/rsc-runtime/rsc.js';
+} from '../rsc-runtime/rsc.js';
 
 import { validateCsrf, type CsrfConfig } from './csrf.js';
+import { DenySignal, RedirectSignal } from './primitives.js';
 import { executeAction, type RevalidateRenderer } from './actions.js';
-import {
-  runWithRequestContext,
-  setMutableCookieContext,
-  getSetCookieHeaders,
-} from './request-context.js';
+import { runWithRequestContext, setMutableCookieContext } from './request-context.js';
+import { getSetCookieHeaders, getCookiesForSsr } from './cookie-context.js';
 import { handleActionError } from './action-client.js';
 import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.js';
 import { parseFormData } from './form-data.js';
+import {
+  stripSensitiveFields,
+  resolveSensitivePredicate,
+  getGlobalSensitiveFieldsConfig,
+  type SensitiveFieldsOption,
+} from './sensitive-fields.js';
 import type { FormFlashData } from './form-flash.js';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { logActionError } from './logger.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -42,12 +50,14 @@ export interface ActionDispatchConfig {
   revalidateRenderer?: RevalidateRenderer;
   /** Body size limits (from timber.config.ts). */
   bodyLimits?: BodyLimitsConfig;
+  /**
+   * Override the sensitive-field deny-list for the no-JS form POST path.
+   * Defaults to the global `forms.stripSensitiveFields` from `timber.config.ts`.
+   * See `SensitiveFieldsOption` in `./sensitive-fields.ts` and TIM-816.
+   */
+  sensitiveFields?: SensitiveFieldsOption;
 }
 
-// ─── Constants ────────────────────────────────────────────────────────────
-
-const RSC_CONTENT_TYPE = 'text/x-component';
-
 // ─── Detection ────────────────────────────────────────────────────────────
 
 /**
@@ -57,6 +67,12 @@ const RSC_CONTENT_TYPE = 'text/x-component';
  * - With JS: POST with `x-rsc-action` header (client callServer dispatch)
  * - Without JS: POST with form data containing `$ACTION_REF` or `$ACTION_KEY`
  *   (React's progressive enhancement hidden fields)
+ *
+ * **Important:** This function returns true for ANY POST with a form
+ * Content-Type, including non-action POSTs to route.ts API handlers.
+ * The caller (wrap-action-dispatch.ts) MUST check the matched route type
+ * before entering the action path — route.ts matches skip action detection
+ * entirely so their body is not pre-parsed. See TIM-870.
  */
 export function isActionRequest(req: Request): boolean {
   if (req.method !== 'POST') return false;
@@ -75,9 +91,30 @@ export function isActionRequest(req: Request): boolean {
 
 // ─── Handler ──────────────────────────────────────────────────────────────
 
-/** Signal from handleFormAction to re-render the page with flash data instead of redirecting. */
+/**
+ * Signal from handleFormAction to re-render the page with flash data instead of redirecting.
+ *
+ * Carries two cookie-related snapshots taken before the action's ALS scope
+ * exits, so the rerender pipeline (which establishes its own fresh cookie
+ * jar from the original request) doesn't lose the action's mutations:
+ *
+ *   - `setCookieHeaders`: serialized Set-Cookie headers to append to the
+ *     final HTML response. Without this, cookies set inside the action are
+ *     silently dropped from the response. See TIM-836 (LOCAL-740).
+ *
+ *   - `cookies`: the post-action read-your-own-writes view of the cookie
+ *     jar, as the same `Map<string, string>` shape used by the request
+ *     context's `parsedCookies`. The rerender dispatcher seeds this map
+ *     directly into the rerender request context via `seedRequestCookies`,
+ *     bypassing any string round-trip through a `Cookie:` header. The
+ *     direct-Map seed eliminates the value-smuggling primitive that the
+ *     previous `cookieHeader: string` shape carried — see
+ *     ONGOING_SECURITY.md H-3 (TIM-868) and TIM-837.
+ */
 export interface FormRerender {
   rerender: FormFlashData;
+  setCookieHeaders: string[];
+  cookies: Map<string, string>;
 }
 
 /**
@@ -90,7 +127,28 @@ export async function handleActionRequest(
   req: Request,
   config: ActionDispatchConfig
 ): Promise<Response | FormRerender | null> {
+  // Version skew detection — reject actions from stale clients (TIM-446).
+  // On mismatch, return a structured RSC error response that the client
+  // handles by showing a brief "App updated" message and reloading.
+  const skewCheck = checkVersionSkew(req);
+  if (!skewCheck.ok) {
+    const reloadHeaders = new Headers({
+      'Content-Type': RSC_CONTENT_TYPE,
+    });
+    applyReloadHeaders(reloadHeaders);
+    // Return the reload signal as an RSC stream so createFromFetch can
+    // decode it. The client checks X-Timber-Reload before processing.
+    const rscStream = renderToReadableStream({ _versionSkew: true });
+    return new Response(rscStream, { status: 200, headers: reloadHeaders });
+  }
+
   // CSRF validation — reject cross-origin mutation requests.
+  //
+  // Defense-in-depth: the pipeline boundary in rsc-entry/index.ts already
+  // validates Origin on every unsafe-method request before dispatch reaches
+  // here, so this call is a no-op on the happy path. It is intentionally
+  // retained so that handleActionRequest remains safe to call from any
+  // future entry point that bypasses the wrapper. See LOCAL-773.
   const csrfResult = validateCsrf(req, config.csrf);
   if (!csrfResult.ok) {
     return new Response(null, { status: csrfResult.status });
@@ -106,7 +164,7 @@ export async function handleActionRequest(
     return new Response(null, { status: limitsResult.status });
   }
 
-  // Run inside request context so headers(), cookies() work in actions.
+  // Run inside request context so getHeaders(), getCookies() work in actions.
   // Actions are a mutable context — they can set cookies (design/29-cookies.md).
   return runWithRequestContext(req, async () => {
     setMutableCookieContext(true);
@@ -121,11 +179,27 @@ export async function handleActionRequest(
       result = await handleFormAction(req, config);
     }
 
-    // Apply cookie jar to action responses
+    // Apply cookie jar to action responses.
+    //
+    // For Response results we append Set-Cookie directly. For FormRerender
+    // signals we snapshot the headers here, before this ALS scope exits, so
+    // the caller can apply them to the rerender pipeline's response (which
+    // runs in its own request-context scope with a fresh cookie jar).
+    // See LOCAL-740 — without this snapshot, cookies set inside a no-JS
+    // form action that returns validation errors are silently dropped.
     if (result instanceof Response) {
       for (const value of getSetCookieHeaders()) {
         result.headers.append('Set-Cookie', value);
       }
+    } else if (result && 'rerender' in result) {
+      result.setCookieHeaders = getSetCookieHeaders();
+      // Snapshot the post-action RYW cookie state as a Map so the rerender
+      // dispatcher can seed it directly into the rerender request context
+      // via `seedRequestCookies`, with no string round-trip. See TIM-837
+      // and ONGOING_SECURITY.md H-3 (TIM-868). `getCookiesForSsr` already
+      // returns a defensive copy, so the rerender scope cannot mutate the
+      // snapshot through this reference.
+      result.cookies = getCookiesForSsr();
     }
     return result;
   });
@@ -177,7 +251,7 @@ async function handleRscAction(
     });
   } catch (error) {
     // Log full error server-side for debugging
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return structured error response — ActionError gets its code/data,
     // unexpected errors get sanitized { code: 'INTERNAL_ERROR' }
@@ -215,24 +289,107 @@ async function handleRscAction(
     'Content-Type': RSC_CONTENT_TYPE,
   };
 
-  let payload: unknown;
   if (result.revalidation) {
     // Wrapper object — Next.js-style pattern: action result + element tree
     // serialized together so React Flight handles both in one stream.
-    payload = {
+    const revalidationPayload = {
       _action: result.actionResult,
-      _tree: result.revalidation.element,
+      // The payload root, not a bare tree: it carries the revalidated
+      // route's params too, and the client publishes them (TIM-1297).
+      _tree: result.revalidation.payload,
     };
-    headers['X-Timber-Revalidation'] = '1';
-    // Forward head elements as JSON so the client can update <head>.
-    if (result.revalidation.headElements.length > 0) {
-      headers['X-Timber-Head'] = JSON.stringify(result.revalidation.headElements);
+
+    // TIM-1366: access.ts deny signals fire during serialization (inside
+    // AccessGate during renderToReadableStream), not during buildRouteElement.
+    // Buffer the stream and track errors so we can drop the revalidation
+    // cleanly instead of shipping a broken flight stream. Access runs
+    // exactly once — during the real render — preserving TIM-1363.
+    let serializationSignal:
+      | { kind: 'deny'; status: number }
+      | { kind: 'redirect'; location: string; status: number }
+      | { kind: 'error' }
+      | undefined;
+    const rscStream = renderToReadableStream(revalidationPayload, {
+      signal: req.signal,
+      onError(error: unknown) {
+        // ??= keeps the first signal (shallowest AccessGate in top-down render).
+        if (error instanceof DenySignal) {
+          serializationSignal ??= { kind: 'deny', status: error.status };
+        } else if (error instanceof RedirectSignal) {
+          serializationSignal ??= {
+            kind: 'redirect',
+            location: error.location,
+            status: error.status,
+          };
+        } else {
+          console.error('[timber] revalidation serialization error:', error);
+          serializationSignal ??= { kind: 'error' };
+        }
+      },
+    });
+
+    // Drain the stream to detect any signals before committing the response.
+    // Timeout-guarded: the element tree may contain async server components
+    // with stalled fetches. 30s matches the default renderTimeoutMs.
+    const reader = rscStream.getReader();
+    const chunks: Uint8Array[] = [];
+    const drainTimeoutMs = 30_000;
+    try {
+      for (;;) {
+        const { done, value } = await withTimeout(
+          reader.read(),
+          drainTimeoutMs,
+          'revalidation stream drain timed out'
+        );
+        if (done) break;
+        chunks.push(value);
+        if (serializationSignal) {
+          reader.cancel().catch(() => {});
+          break;
+        }
+      }
+    } catch (drainError) {
+      reader.cancel().catch(() => {});
+      if (drainError instanceof RenderTimeoutError) {
+        console.error('[timber] revalidatePath dropped — stream drain timed out');
+        const fallbackStream = renderToReadableStream(result.actionResult);
+        return new Response(fallbackStream, { status: 200, headers });
+      }
+      throw drainError;
     }
-  } else {
-    payload = result.actionResult;
+
+    if (serializationSignal) {
+      if (serializationSignal.kind === 'redirect') {
+        const redirectPayload = {
+          _redirect: serializationSignal.location,
+          _status: serializationSignal.status,
+        };
+        const redirectStream = renderToReadableStream(redirectPayload);
+        return new Response(redirectStream, {
+          status: 200,
+          headers: {
+            'Content-Type': RSC_CONTENT_TYPE,
+            'X-Timber-Redirect': serializationSignal.location,
+          },
+        });
+      }
+      // Deny or render error: drop the revalidation tree, ship the action result alone.
+      if (serializationSignal.kind === 'deny') {
+        console.error(
+          `[timber] revalidatePath dropped — access denied during render (status ${serializationSignal.status})`
+        );
+      }
+      const fallbackStream = renderToReadableStream(result.actionResult);
+      return new Response(fallbackStream, { status: 200, headers });
+    }
+
+    // Clean serialization — return the buffered bytes with revalidation header.
+    headers['X-Timber-Revalidation'] = '1';
+    const buffered = concatUint8Arrays(chunks);
+    return new Response(buffered.buffer as ArrayBuffer, { status: 200, headers });
   }
 
-  const rscStream = renderToReadableStream(payload);
+  const rscStream = renderToReadableStream(result.actionResult);
 
   return new Response(rscStream, {
     status: 200,
@@ -240,6 +397,20 @@ async function handleRscAction(
   });
 }
 
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function concatUint8Arrays(chunks: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const c of chunks) total += c.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
 // ─── No-JS Form Action ───────────────────────────────────────────────────
 
 /**
@@ -264,26 +435,25 @@ async function handleFormAction(
     return new Response(null, { status: fieldResult.status });
   }
 
-  // Check if this is actually a React server action form.
-  // If there's no $ACTION_REF_* or $ACTION_KEY, it's a regular form POST
-  // that should be handled by the route's route handler, not here.
-  // React uses `$ACTION_REF_` + identifierPrefix — since we don't set one,
-  // the suffix is empty. Check for any key starting with $ACTION_REF_ or $ACTION_ID_.
-  const allKeys = [...formData.keys()];
-  const hasActionField = allKeys.some(
-    (k) => k.startsWith('$ACTION_REF_') || k.startsWith('$ACTION_ID_')
-  );
-  if (!hasActionField && !formData.has('$ACTION_KEY')) {
-    return null;
-  }
-
   // Capture submitted values for re-render on validation failure.
-  // Parse before decodeAction consumes the FormData.
-  const submittedValues = parseFormData(formData);
+  // Parse before decodeAction consumes the FormData, then strip sensitive
+  // fields (passwords, tokens, CVV, etc.) so they are never rendered back
+  // into the HTML as `defaultValue` attributes. See TIM-816.
+  const sensitivePredicate = resolveSensitivePredicate(
+    config.sensitiveFields,
+    getGlobalSensitiveFieldsConfig()
+  );
+  const submittedValues = stripSensitiveFields(parseFormData(formData), sensitivePredicate);
 
   // decodeAction resolves the action function from the form data's hidden fields.
-  // It returns a bound function with the form data already applied.
-  const actionFn = (await decodeAction(formData)) as (...args: unknown[]) => Promise<unknown>;
+  // Returns null when no $ACTION_REF_/$ACTION_ID_ fields are present — meaning
+  // this is a regular form POST, not a React server action.
+  const actionFn = (await decodeAction(formData)) as
+    | ((...args: unknown[]) => Promise<unknown>)
+    | null;
+  if (!actionFn) {
+    return null;
+  }
 
   // Execute the action — no additional args needed (form data is already bound).
   // Errors are caught to prevent stack traces from leaking in the response.
@@ -293,7 +463,7 @@ async function handleFormAction(
       renderer: config.revalidateRenderer,
     });
   } catch (error) {
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return the error as flash data for re-render.
     // handleActionError produces { serverError } for ActionErrors
@@ -304,6 +474,9 @@ async function handleFormAction(
         ...errorResult,
         submittedValues,
       },
+      // Filled in by handleActionRequest before the ALS scope exits.
+      setCookieHeaders: [],
+      cookies: new Map(),
     };
   }
 
@@ -321,5 +494,19 @@ async function handleFormAction(
   // This handles both success ({ data }) and validation failure
   // ({ validationErrors, submittedValues }) — the form is the single source of truth.
   const actionResult = result.actionResult as FormFlashData;
-  return { rerender: actionResult };
+
+  // Defense-in-depth: strip sensitive fields from `actionResult.submittedValues`
+  // even if the action already built it. `createActionClient` strips internally,
+  // but raw `'use server'` functions that manually return `{ submittedValues }`
+  // are not covered by the inner strip. See TIM-816.
+  if (actionResult && actionResult.submittedValues) {
+    actionResult.submittedValues = stripSensitiveFields(
+      actionResult.submittedValues,
+      sensitivePredicate
+    );
+  }
+
+  // setCookieHeaders + cookies are filled in by handleActionRequest before
+  // the ALS scope exits.
+  return { rerender: actionResult, setCookieHeaders: [], cookies: new Map() };
 }

package/src/server/actions.ts

@@ -3,7 +3,7 @@
  *
  * - revalidatePath(path) re-renders the route at that path and returns the RSC
  *   flight payload for inline reconciliation.
- * - revalidateTag(tag) invalidates cached shells and 'use cache' entries by tag.
+ * - revalidateTag(tag) invalidates timber.cache entries by tag.
  *
  * Both are callable from anywhere on the server — actions, API routes, handlers.
  *
@@ -14,19 +14,19 @@
  * See design/08-forms-and-actions.md
  */
 
-import type { CacheHandler } from '#/cache/index';
-import { RedirectSignal } from './primitives';
+import { cache } from '../cache/cache-api';
+import { DenySignal, RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
-
 // ─── Types ───────────────────────────────────────────────────────────────
 
-/** Result of rendering a revalidation — element tree before RSC serialization. */
+/** Result of rendering a revalidation — payload root before RSC serialization. */
 export interface RevalidationResult {
-  /** React element tree (pre-serialization — passed to renderToReadableStream). */
-  element: unknown;
-  /** Resolved head elements for metadata. */
-  headElements: unknown[];
+  /**
+   * The payload root — tree plus the params it rendered with, exactly as an
+   * ordinary route payload. The client splits it in `applyRevalidation`.
+   */
+  payload: unknown;
 }
 
 /** Renderer function that builds a React element tree for a given path. */
@@ -37,8 +37,6 @@ export type { RevalidationState } from './als-registry.js';
 
 /** Options for creating the action handler. */
 export interface ActionHandlerConfig {
-  /** Cache handler for tag invalidation. */
-  cacheHandler?: CacheHandler;
   /** Renderer for producing RSC payloads during revalidation. */
   renderer?: RevalidateRenderer;
 }
@@ -62,21 +60,11 @@ export interface ActionHandlerResult {
 // (the previous module-level global was vulnerable to cross-request pollution).
 
 /**
- * Set the revalidation state for the current action execution.
- * @internal — kept for test compatibility; prefer executeAction() which uses ALS.
- */
-export function _setRevalidationState(state: RevalidationState): void {
-  // Enter ALS scope — this is only used by tests that call revalidatePath/Tag
-  // directly without going through executeAction().
-  revalidationAls.enterWith(state);
-}
-
-/**
- * Clear the revalidation state after action execution.
- * @internal — kept for test compatibility.
+ * Run `fn` inside a revalidation ALS scope.
+ * @internal — for tests that call revalidatePath/Tag directly without executeAction().
  */
-export function _clearRevalidationState(): void {
-  revalidationAls.enterWith(undefined as unknown as RevalidationState);
+export function _runWithRevalidationState<T>(state: RevalidationState, fn: () => T): T {
+  return revalidationAls.run(state, fn);
 }
 
 /**
@@ -112,8 +100,8 @@ export function revalidatePath(path: string): void {
 }
 
 /**
- * Invalidate all pre-rendered shells and 'use cache' entries tagged with `tag`.
- * Does not return a payload — the next request for an invalidated route re-renders fresh.
+ * Invalidate all timber.cache entries tagged with `tag`.
+ * Does not return a payload — the next request for an invalidated entry re-executes.
  *
  * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
  */
@@ -172,9 +160,26 @@ export async function executeAction(
     }
   });
 
-  // Process tag invalidation
-  if (state.tags.length > 0 && config.cacheHandler) {
-    await Promise.all(state.tags.map((tag) => config.cacheHandler!.invalidate({ tag })));
+  // Process tag invalidation through cache.invalidate so it records the
+  // invalidation epoch — an in-flight cached fn must not re-store data this
+  // mutation just invalidated (TIM-1028). cache.invalidate resolves the
+  // module-level handler singleton: setCacheHandler() is called at boot from
+  // rsc-entry when timber.config.ts provides a cacheHandler; otherwise falls
+  // back to in-memory LRU (TIM-599).
+  if (state.tags.length > 0) {
+    // cache.invalidate handles both data-cache clearing AND component-seed
+    // tombstone writes (design/45 §ISR mechanics) — no separate tombstone
+    // step needed here.
+    // Best-effort: the action body already executed and its mutation committed.
+    // Use allSettled so all tags settle before proceeding — Promise.all would
+    // short-circuit on the first rejection, leaving other invalidations (including
+    // component-seed tombstone writes) in-flight during revalidatePath rendering.
+    const results = await Promise.allSettled(state.tags.map((tag) => cache.invalidate({ tag })));
+    for (const r of results) {
+      if (r.status === 'rejected') {
+        console.error('[timber] revalidateTag invalidation failed:', r.reason);
+      }
+    }
   }
 
   // Process path revalidation — build element tree (not yet serialized)
@@ -187,11 +192,28 @@ export async function executeAction(
       revalidation = await config.renderer(path);
     } catch (renderError) {
       if (renderError instanceof RedirectSignal) {
-        // Revalidation triggered a redirect (e.g., session expired)
+        // Revalidation triggered a redirect (e.g., session expired,
+        // middleware on the target path called `redirect()`).
         redirectTo = renderError.location;
         redirectStatus = renderError.status;
+      } else if (renderError instanceof DenySignal) {
+        // Target path's middleware/access denied this user.
+        //
+        // Dropping the revalidation here is the security boundary added
+        // in TIM-996: without this branch, a DenySignal would fall into
+        // the `console.error` path AND the element tree would have
+        // already been built and serialized — leaking a privileged RSC
+        // payload to the action submitter. By the time the signal
+        // surfaces, the renderer has thrown BEFORE building the tree,
+        // so we simply drop `revalidation` and ship the action result
+        // alone. The action itself still succeeded.
+        console.error(
+          `[timber] revalidatePath dropped — target middleware denied (status ${renderError.status})`
+        );
       } else {
-        // Log but don't fail the action — revalidation is best-effort
+        // Log but don't fail the action — revalidation is best-effort.
+        // Includes input-validation rejections from the renderer
+        // (e.g., revalidatePath('//evil.com/admin')).
         console.error('[timber] revalidatePath render failed:', renderError);
       }
     }
@@ -203,28 +225,3 @@ export async function executeAction(
     ...(redirectTo ? { redirectTo, redirectStatus } : {}),
   };
 }
-
-/**
- * Build an HTTP Response for a no-JS form submission.
- * Standard POST → 302 redirect pattern.
- *
- * @param redirectPath - Where to redirect after the action executes.
- */
-export function buildNoJsResponse(redirectPath: string, status: number = 302): Response {
-  return new Response(null, {
-    status,
-    headers: { Location: redirectPath },
-  });
-}
-
-/**
- * Detect whether the incoming request is an RSC action request (with JS)
- * or a plain HTML form POST (no JS).
- *
- * RSC action requests use Accept: text/x-component or Content-Type: text/x-component.
- */
-export function isRscActionRequest(req: Request): boolean {
-  const accept = req.headers.get('Accept') ?? '';
-  const contentType = req.headers.get('Content-Type') ?? '';
-  return accept.includes('text/x-component') || contentType.includes('text/x-component');
-}