@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.132

package/src/server/action-client.ts

@@ -131,6 +131,13 @@ interface ActionClientConfig<TCtx> {
   middleware?: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[];
   /** Max file size in bytes. Files exceeding this are rejected with validation errors. */
   fileSizeLimit?: number;
+  /**
+   * Override the sensitive-field deny-list for this action client.
+   * See `SensitiveFieldsOption` in `./sensitive-fields.ts`. Per-action config
+   * takes precedence over the global `forms.stripSensitiveFields` option in
+   * `timber.config.ts`. See design/08-forms-and-actions.md and TIM-816.
+   */
+  stripSensitiveFields?: SensitiveFieldsOption;
 }
 
 /** Intermediate builder returned by createActionClient(). */
@@ -138,22 +145,53 @@ export interface ActionBuilder<TCtx> {
   /** Declare the input schema. Validation errors are returned typed. */
   schema<TInput>(schema: ActionSchema<TInput>): ActionBuilderWithSchema<TCtx, TInput>;
   /** Define the action body without input validation. */
-  action<TData>(fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>): ActionFn<TData>;
+  action<TData>(
+    fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>
+  ): ActionFn<TData, undefined>;
 }
 
 /** Builder after .schema() has been called. */
 export interface ActionBuilderWithSchema<TCtx, TInput> {
   /** Define the action body with validated input. */
-  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData>;
+  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData, TInput>;
 }
 
 /**
- * The final action function. Callable two ways:
+ * The final action function. Callable three ways:
  * - Direct: action(input) → Promise<ActionResult<TData>>
  * - React useActionState: action(prevState, formData) → Promise<ActionResult<TData>>
+ * - React <form action={fn}>: action(formData) → void  (return value ignored by React)
+ *
+ * The third overload exists purely for type compatibility with React's
+ * `<form action>` prop, which expects `(formData: FormData) => void`.
+ * At runtime the function still returns Promise<ActionResult>, but React
+ * discards it. This lets validated actions be passed directly to forms
+ * without casts.
+ */
+/**
+ * Map schema output keys to `string | undefined` for form-facing APIs.
+ * HTML form values are always strings, and fields can be absent.
+ * Gives autocomplete for field names without lying about value types.
  */
-export type ActionFn<TData> = {
-  (input?: unknown): Promise<ActionResult<TData>>;
+export type InputHint<T> =
+  T extends Record<string, unknown> ? { [K in keyof T]: string | undefined } : T;
+
+/**
+ * ActionFn — the callable returned by `createActionClient().action()`.
+ *
+ * Generic order: `<TData, TInput>` — TData first for backward compatibility.
+ * Previously ActionFn had a single `<TData>` generic, so existing code like
+ * `ActionFn<MyResult>` must still work with TData in the first position.
+ * See TIM-797.
+ */
+export type ActionFn<TData = unknown, TInput = unknown> = {
+  /** <form action={fn}> compatibility — React discards the return value. */
+  (formData: FormData): void;
+  /** Direct call: action(input) — optional when TInput is undefined/unknown (no-schema actions). */
+  (
+    ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]
+  ): Promise<ActionResult<TData>>;
+  /** React useActionState: action(prevState, formData) */
   (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;
 };
 
@@ -183,8 +221,15 @@ async function runActionMiddleware<TCtx>(
 
 // Re-export parseFormData for use throughout the framework
 import { parseFormData } from './form-data.js';
-import { formatSize } from '#/utils/format.js';
+import { formatSize } from '../utils/format.js';
 import { isDebug, isDevMode } from './debug.js';
+import { RedirectSignal, DenySignal } from './primitives.js';
+import {
+  stripSensitiveFields,
+  resolveSensitivePredicate,
+  getGlobalSensitiveFieldsConfig,
+  type SensitiveFieldsOption,
+} from './sensitive-fields.js';
 
 /**
  * Extract validation errors from a schema error.
@@ -286,7 +331,7 @@ export function createActionClient<TCtx = Record<string, never>>(
   function buildAction<TInput, TData>(
     schema: ActionSchema<TInput> | undefined,
     fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
-  ): ActionFn<TData> {
+  ): ActionFn<TData, TInput> {
     async function actionHandler(...args: unknown[]): Promise<ActionResult<TData>> {
       try {
         // Run middleware
@@ -308,6 +353,25 @@ export function createActionClient<TCtx = Record<string, never>>(
           rawInput = args[0];
         }
 
+        // Resolve the sensitive-field stripping predicate once per invocation.
+        // Precedence: per-action (config.stripSensitiveFields) > global
+        // (forms.stripSensitiveFields from timber.config.ts) > built-in deny-list.
+        // See TIM-816.
+        const sensitivePredicate = resolveSensitivePredicate(
+          config.stripSensitiveFields,
+          getGlobalSensitiveFieldsConfig()
+        );
+
+        // Capture a "safe-to-echo" snapshot of the raw input once. Files are
+        // stripped (can't serialize, shouldn't echo back) and sensitive fields
+        // (passwords, tokens, CVV, etc.) are removed before they would land
+        // in the RSC payload → client form `defaultValue` → DOM.
+        const buildSubmittedValues = (): Record<string, unknown> | undefined => {
+          const withoutFiles = stripFiles(rawInput);
+          if (withoutFiles === undefined) return undefined;
+          return stripSensitiveFields(withoutFiles, sensitivePredicate);
+        };
+
         // Validate file sizes before schema validation.
         if (config.fileSizeLimit !== undefined && rawInput && typeof rawInput === 'object') {
           const fileSizeErrors = validateFileSizes(
@@ -315,14 +379,12 @@ export function createActionClient<TCtx = Record<string, never>>(
             config.fileSizeLimit
           );
           if (fileSizeErrors) {
-            const submittedValues = stripFiles(rawInput);
-            return { validationErrors: fileSizeErrors, submittedValues };
+            return { validationErrors: fileSizeErrors, submittedValues: buildSubmittedValues() };
           }
         }
 
         // Capture submitted values for repopulation on validation failure.
-        // Exclude File objects (can't serialize, shouldn't echo back).
-        const submittedValues = schema ? stripFiles(rawInput) : undefined;
+        const submittedValues = schema ? buildSubmittedValues() : undefined;
 
         // Validate with schema if provided
         let input: TInput;
@@ -366,22 +428,33 @@ export function createActionClient<TCtx = Record<string, never>>(
         const data = await fn({ ctx, input });
         return { data };
       } catch (error) {
+        // Re-throw redirect/deny signals — these are control flow, not errors.
+        // They must propagate to executeAction() which converts them to proper
+        // HTTP responses (302 redirect, 4xx deny). Catching them here would
+        // wrap them as INTERNAL_ERROR and break redirect()/redirectExternal()/deny().
+        if (error instanceof RedirectSignal || error instanceof DenySignal) {
+          throw error;
+        }
         return handleActionError(error);
       }
     }
 
-    return actionHandler as ActionFn<TData>;
+    return actionHandler as ActionFn<TData, TInput>;
   }
 
   return {
     schema<TInput>(schema: ActionSchema<TInput>) {
       return {
-        action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData> {
+        action<TData>(
+          fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
+        ): ActionFn<TData, TInput> {
           return buildAction(schema, fn);
         },
       };
     },
-    action<TData>(fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>): ActionFn<TData> {
+    action<TData>(
+      fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>
+    ): ActionFn<TData, undefined> {
       return buildAction(undefined, fn as (ctx: ActionContext<TCtx, unknown>) => Promise<TData>);
     },
   };
@@ -410,7 +483,7 @@ export function createActionClient<TCtx = Record<string, never>>(
 export function validated<TInput, TData>(
   schema: ActionSchema<TInput>,
   handler: (input: TInput) => Promise<TData>
-): ActionFn<TData> {
+): ActionFn<TData, TInput> {
   return createActionClient()
     .schema(schema)
     .action(async ({ input }) => handler(input));

package/src/server/action-encryption.ts

@@ -0,0 +1,144 @@
+/**
+ * Server action bound args encryption utilities.
+ *
+ * Provides key management for the RSC plugin's built-in bound args encryption.
+ * The RSC plugin (@vitejs/plugin-rsc) handles the actual encrypt/decrypt via
+ * AES-256-GCM — this module handles:
+ *
+ * 1. Key sourcing: auto-generated at build time (embedded in bundle), overridable
+ *    via env var for cross-build key sharing (rolling/blue-green deployments)
+ * 2. Build-time key expression generation for the RSC plugin's `defineEncryptionKey`
+ *
+ * Encryption is always on in production. In dev mode, it's on by default
+ * (matching the RSC plugin's behavior) but can be disabled for debugging.
+ *
+ * ## Known Security Considerations
+ *
+ * 1. **defineEncryptionKey is a raw JS expression.** The RSC plugin inlines it
+ *    verbatim into generated code. We only emit the hardcoded string
+ *    `process.env.TIMBER_ACTIONS_ENCRYPTION_KEY` — never user-controlled input.
+ *    If this function is ever extended to accept configurable env var names,
+ *    the expression MUST be validated against a safe pattern.
+ *
+ * 2. **Key material lives in GC-visible JS strings.** `atob()` decodes the key
+ *    into a regular JavaScript string on the V8 heap. JavaScript has no
+ *    `SecureString` or memory-zeroing primitive — this is an inherent platform
+ *    limitation. Acceptable for web server use; would need review for FIPS.
+ *
+ * 3. **TIMBER_ACTIONS_ENCRYPTION_KEY must be set at both build time and runtime.**
+ *    At build time, we validate the key format and emit a runtime expression.
+ *    If the env var is present at build time but missing at runtime, the server
+ *    will crash on first action invocation with an opaque `atob(undefined)` error.
+ *    If the env var is present at runtime but was absent at build time, the RSC
+ *    plugin will have generated its own key and the env var is silently ignored.
+ *
+ * See design/08-forms-and-actions.md §"Security"
+ * See design/13-security.md
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** User-facing configuration for action bound args encryption. */
+export interface ActionEncryptionConfig {
+  /**
+   * Disable encryption in dev mode for easier debugging.
+   * Has no effect in production — encryption is always enabled.
+   * Default: false (encryption is on in dev too).
+   */
+  disableInDev?: boolean;
+}
+
+// ─── Key Resolution ───────────────────────────────────────────────────────
+
+/**
+ * Regex for safe `defineEncryptionKey` expressions.
+ *
+ * The RSC plugin inlines this expression verbatim into generated JavaScript.
+ * We restrict it to `process.env.<UPPER_SNAKE_CASE>` to prevent code injection.
+ * See "Known Security Considerations" at the top of this file.
+ */
+const SAFE_KEY_EXPR = /^process\.env\.[A-Z_][A-Z0-9_]*$/;
+
+/**
+ * Build the `defineEncryptionKey` expression for the RSC plugin.
+ *
+ * The RSC plugin accepts a JavaScript expression string that will be
+ * inlined into the encryption runtime module. At runtime, this expression
+ * must evaluate to the base64-encoded encryption key.
+ *
+ * Priority:
+ * 1. `TIMBER_ACTIONS_ENCRYPTION_KEY` env var (for cross-build key sharing
+ *    in rolling/blue-green deployments)
+ * 2. Auto-generated at build time (RSC plugin default — embedded in bundle,
+ *    consistent across all instances of the same build)
+ *
+ * For env var keys, we generate a runtime expression that reads the env var.
+ * For auto-generated keys, we return undefined and let the RSC plugin handle it.
+ */
+export function resolveEncryptionKeyExpression(): string | undefined {
+  // Check for env var override — used for cross-build key sharing where
+  // multiple builds must agree on the same encryption key.
+  const envKey = process.env.TIMBER_ACTIONS_ENCRYPTION_KEY;
+  if (envKey) {
+    // Validate the key format (must be base64-encoded 32-byte key)
+    validateKeyFormat(envKey);
+
+    // Return a runtime expression that reads the env var at startup.
+    // This ensures the key is read at runtime, not embedded in the build.
+    const expr = 'process.env.TIMBER_ACTIONS_ENCRYPTION_KEY';
+
+    // Defense-in-depth: validate the expression matches our safe pattern.
+    // This is redundant today (hardcoded string), but protects against
+    // future refactors that might make the expression configurable.
+    if (!SAFE_KEY_EXPR.test(expr)) {
+      throw new Error(`Unsafe encryption key expression: ${expr}`);
+    }
+
+    return expr;
+  }
+
+  // No override — let the RSC plugin auto-generate a per-build key
+  return undefined;
+}
+
+/**
+ * Determine whether action encryption should be enabled.
+ *
+ * Encryption is always enabled in production. In dev mode, it's enabled
+ * by default but can be disabled via config for debugging.
+ */
+export function shouldEnableEncryption(isDev: boolean, config?: ActionEncryptionConfig): boolean {
+  if (!isDev) return true; // Always on in production
+  if (config?.disableInDev) return false; // Opt-out in dev
+  return true; // On by default in dev too
+}
+
+// ─── Key Validation ───────────────────────────────────────────────────────
+
+/**
+ * Validate that a key string is a valid base64-encoded 256-bit key.
+ * Throws a descriptive error if the key is malformed.
+ */
+export function validateKeyFormat(key: string): void {
+  // Decode base64 and check length (32 bytes = 256 bits)
+  try {
+    const decoded = atob(key);
+    const bytes = decoded.length;
+    if (bytes !== 32) {
+      throw new Error(
+        `TIMBER_ACTIONS_ENCRYPTION_KEY must be a base64-encoded 256-bit (32-byte) key. ` +
+          `Got ${bytes} bytes. Generate one with: ` +
+          `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+      );
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('TIMBER_ACTIONS_ENCRYPTION_KEY')) {
+      throw error;
+    }
+    throw new Error(
+      `TIMBER_ACTIONS_ENCRYPTION_KEY is not valid base64. ` +
+        `Generate a key with: ` +
+        `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+    );
+  }
+}

package/src/server/action-handler.ts

@@ -18,19 +18,24 @@ import {
   decodeReply,
   decodeAction,
   renderToReadableStream,
-} from '#/rsc-runtime/rsc.js';
+} from '../rsc-runtime/rsc.js';
 
 import { validateCsrf, type CsrfConfig } from './csrf.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';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -42,6 +47,12 @@ 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 ────────────────────────────────────────────────────────────
@@ -57,6 +68,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 +92,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 +128,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 +165,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 +180,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 +252,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' }
@@ -278,8 +353,14 @@ async function handleFormAction(
   }
 
   // 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.
@@ -293,7 +374,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 +385,9 @@ async function handleFormAction(
         ...errorResult,
         submittedValues,
       },
+      // Filled in by handleActionRequest before the ALS scope exits.
+      setCookieHeaders: [],
+      cookies: new Map(),
     };
   }
 
@@ -321,5 +405,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,7 +14,7 @@
  * See design/08-forms-and-actions.md
  */
 
-import type { CacheHandler } from '#/cache/index';
+import { getCacheHandler } from '../cache/handler-store';
 import { RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
@@ -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.
+ * Run `fn` inside a revalidation ALS scope.
+ * @internal — for tests that call revalidatePath/Tag directly without executeAction().
  */
-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.
- */
-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,12 @@ 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 via the module-level cache 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) {
+    const handler = getCacheHandler();
+    await Promise.all(state.tags.map((tag) => handler.invalidate({ tag })));
   }
 
   // Process path revalidation — build element tree (not yet serialized)