@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/segment-params/define.ts

@@ -0,0 +1,279 @@
+/**
+ * defineSegmentParams — factory for typed route param coercion.
+ *
+ * Creates a ParamsDefinition that coerces raw string params from the
+ * URL into typed values. Used by exporting from params.ts (segment-level)
+ * convention file.
+ *
+ * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,
+ * same pattern as defineSearchParams. Runtime constraints are stricter:
+ * - serialize must return string (not null — path segments can't be omitted)
+ * - parse throwing → 404 (invalid param value)
+ *
+ * Design doc: design/07a-route-params-triage.md
+ */
+
+import type { Codec } from '../codec.js';
+import {
+  type StandardSchemaV1,
+  validateSync,
+  isStandardSchema,
+  isCodec,
+} from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// Server-only ALS reference for .load()
+// ---------------------------------------------------------------------------
+
+// Same pattern as search-params: eagerly registered at server startup
+// to avoid dynamic imports that lose ALS context. See TIM-523.
+let _rawSegmentParams: (() => Promise<Record<string, string | string[]>>) | undefined;
+
+/**
+ * Register the rawSegmentParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setRawSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void {
+  _rawSegmentParams = fn;
+}
+
+function getRawSegmentParams(): Promise<Record<string, string | string[]>> {
+  if (!_rawSegmentParams) {
+    throw new Error(
+      '[timber] segmentParams.load() is only available on the server. ' +
+        'Use useSegmentParams() on the client.'
+    );
+  }
+  return _rawSegmentParams();
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Infer the output type from a Codec or StandardSchemaV1. */
+export type InferParamField<V> =
+  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+
+/** Acceptable field value for defineParams: a Codec or a Standard Schema. */
+export type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;
+
+export type { StandardSchemaV1 };
+
+/**
+ * A typed route params definition.
+ *
+ * Returned by defineParams(). Provides parse (string → typed) and
+ * serialize (typed → string) for each declared param.
+ */
+export interface ParamsDefinition<T extends Record<string, unknown>> {
+  /** Parse raw string params into typed values. Throws on invalid values. */
+  parse(raw: Record<string, string | string[]>): T;
+
+  /** Serialize typed values back to strings for URL construction. */
+  serialize(values: T): Record<string, string>;
+
+  /**
+   * Load typed segment params from the current request context (ALS).
+   *
+   * Server-only. Reads rawSegmentParams() from ALS and coerces through
+   * this definition's codecs, returning fully typed params.
+   *
+   * ```ts
+   * // app/products/[id]/params.ts
+   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })
+   *
+   * // app/products/[id]/page.tsx
+   * import { segmentParams } from './params'
+   * export default async function Page() {
+   *   const { id } = await segmentParams.load() // id: number
+   * }
+   * ```
+   */
+  load(): Promise<T>;
+
+  /** Read-only codec map. */
+  codecs: { [K in keyof T]: Codec<T[K]> };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a Standard Schema into a Codec for route params.
+ *
+ * Unlike fromSchema for search params:
+ * - Parse throws on failure (no fallback to default)
+ * - Serialize returns string (not null)
+ */
+function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      // Route params are always strings (single segment) or string[] (catch-all)
+      const input = Array.isArray(value) ? value : value;
+
+      const result = validateSync(schema, input);
+      if (!result.issues) {
+        return result.value;
+      }
+
+      // For route params, parse failure means the param is invalid → throw
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      // Catch-all segments produce arrays — join with '/' for path reconstruction
+      if (Array.isArray(value)) {
+        return value.join('/');
+      }
+      return String(value);
+    },
+  };
+}
+
+/**
+ * Resolve a field value to a Codec. Auto-detects Standard Schema objects.
+ */
+function resolveField(fieldName: string, value: ParamField): Codec<unknown> {
+  if (isCodec(value)) {
+    return value;
+  }
+
+  if (isStandardSchema(value)) {
+    return fromParamSchema(fieldName, value);
+  }
+
+  throw new Error(
+    `[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +
+      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +
+      `(Zod, Valibot, ArkType).`
+  );
+}
+
+/**
+ * Validate that no codec's serialize returns null.
+ * Route params are structural — they must produce a valid path segment.
+ */
+function validateSerialize(codecMap: Record<string, Codec<unknown>>): void {
+  for (const [key, codec] of Object.entries(codecMap)) {
+    // Test serialize with a sample parsed value to check for null
+    // We can't exhaustively test, but we can check that serialize(parse("test"))
+    // doesn't return null for a basic input.
+    try {
+      const testValue = codec.parse('test');
+      const serialized = codec.serialize(testValue);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\n` +
+            `  Route params are path segments — they cannot be omitted.\n` +
+            `  Ensure serialize() always returns a string.`
+        );
+      }
+    } catch (e) {
+      // parse('test') may throw for strict codecs (e.g., number-only).
+      // That's fine — it means the codec validates. We only care about
+      // serialize returning null, which we can't test without a valid value.
+      if (e instanceof Error && e.message.includes('returned null')) {
+        throw e;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.
+ *
+ * ```ts
+ * // app/products/[id]/layout.tsx
+ * import { defineSegmentParams } from '@timber-js/app/segment-params'
+ * import { z } from 'zod/v4'
+ *
+ * export const segmentParams = defineSegmentParams({
+ *   id: z.coerce.number().int().positive(),
+ * })
+ * ```
+ */
+export function defineSegmentParams<C extends Record<string, ParamField>>(
+  codecs: C
+): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {
+  type T = { [K in keyof C]: InferParamField<C[K]> };
+
+  const resolvedCodecs: Record<string, Codec<unknown>> = {};
+
+  for (const [key, value] of Object.entries(codecs)) {
+    resolvedCodecs[key] = resolveField(key, value as ParamField);
+  }
+
+  // Validate that serialize doesn't return null
+  validateSerialize(resolvedCodecs);
+
+  // ---- parse ----
+  function parse(raw: Record<string, string | string[]>): T {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const rawValue = raw[key];
+      // Route params are always present (the route matched)
+      result[key] = codec.parse(rawValue);
+    }
+
+    return result as T;
+  }
+
+  // ---- serialize ----
+  function serialize(values: T): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const serialized = codec.serialize(values[key as keyof T] as unknown);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] params.serialize: field '${key}' serialized to null. ` +
+            `Route params must produce a valid path segment.`
+        );
+      }
+      result[key] = serialized;
+    }
+
+    return result;
+  }
+
+  // ---- load ----
+  // ALS-backed: reads segment params from the current request context.
+  // Server-only — throws on client.
+  //
+  // The pipeline already coerces params via coerceSegmentParams() which
+  // calls parse() and stores typed values in ALS via setSegmentParams().
+  // We return those directly instead of re-parsing, because codecs may
+  // not be idempotent (e.g., a codec that only accepts raw strings would
+  // throw if given an already-parsed value). See TIM-574.
+  async function load(): Promise<T> {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] segmentParams.load() is server-only. ' + 'Use useSegmentParams() on the client.'
+      );
+    }
+    const params = await getRawSegmentParams();
+    // params are already coerced by the pipeline — return as-is.
+    return params as unknown as T;
+  }
+
+  const definition: ParamsDefinition<T> = {
+    parse,
+    serialize,
+    load,
+    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
+  };
+
+  return definition;
+}

package/src/segment-params/index.ts

@@ -0,0 +1,28 @@
+// @timber-js/app/segment-params — Typed route param coercion and search param definitions
+//
+// This is the primary import path for both segmentParams and searchParams.
+// params.ts convention files import from here.
+//
+// See design/07-routing.md §"params.ts Convention File"
+
+// --- Segment params (route path param coercion) ---
+export type { ParamsDefinition, InferParamField, ParamField } from './define.js';
+export { defineSegmentParams } from './define.js';
+
+// --- Search params (re-exported from search-params for convenience) ---
+// This lets params.ts import both from a single path:
+//   import { defineSegmentParams, defineSearchParams } from '@timber-js/app/segment-params'
+export { defineSearchParams } from '../search-params/define.js';
+
+// Codec bridges moved to @timber-js/app/codec
+// Import fromSchema / fromArraySchema from '@timber-js/app/codec' instead.
+export { withDefault, withUrlKey } from '../search-params/wrappers.js';
+export type { Codec } from '../codec.js';
+export type {
+  SearchParamCodec,
+  SearchParamsDefinition,
+  SetParams,
+  SetParamsOptions,
+  QueryStatesOptions,
+  CodecMap,
+} from '../search-params/define.js';

package/src/server/access-gate.tsx

@@ -17,6 +17,8 @@ import { DenySignal, RedirectSignal } from './primitives.js';
 import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
+import type { DenyPageEntry } from './deny-page-resolver.js';
+import { renderMatchingDenyPage, setDenyStatus } from './deny-page-resolver.js';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -35,24 +37,20 @@ import { isDebug } from './debug.js';
  * gets the same data by calling the same cached functions (React.cache dedup).
  */
 export function AccessGate(props: AccessGateProps): ReactElement | Promise<ReactElement> {
-  const { accessFn, params, searchParams, segmentName, verdict, children } = props;
+  const { accessFn, segmentName, verdict, denyPages, children } = props;
 
   // Fast path: replay pre-computed verdict from the pre-render pass.
-  // This is synchronous — Suspense boundaries cannot interfere with the
-  // status code because the signal throws before any async work.
   if (verdict !== undefined) {
     if (verdict === 'pass') {
       return children;
     }
-    // Throw the stored DenySignal or RedirectSignal synchronously.
-    // React catches this as a render-phase throw — the flush controller
-    // produces the correct HTTP status code.
     throw verdict;
   }
 
-  // Fallback: call accessFn directly (used by tree-builder.ts which
-  // doesn't run a pre-render pass, and for backward compat).
-  return accessGateFallback(accessFn, params, searchParams, segmentName, children);
+  // Primary path: call accessFn directly during render.
+  // If denyPages is provided, catch DenySignal and render the deny page
+  // in-tree — no throw reaches React Flight, no second render pass.
+  return accessGateFallback(accessFn, segmentName, denyPages, children);
 }
 
 /**
@@ -61,28 +59,41 @@ export function AccessGate(props: AccessGateProps): ReactElement | Promise<React
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
-  params: AccessGateProps['params'],
-  searchParams: AccessGateProps['searchParams'],
   segmentName: AccessGateProps['segmentName'],
+  denyPages: DenyPageEntry[] | undefined,
   children: ReactElement
 ): Promise<ReactElement> {
-  await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
-    try {
-      await accessFn({ params, searchParams });
-      await setSpanAttribute('timber.result', 'pass');
-    } catch (error: unknown) {
-      if (error instanceof DenySignal) {
-        await setSpanAttribute('timber.result', 'deny');
-        await setSpanAttribute('timber.deny_status', error.status);
-        if (error.sourceFile) {
-          await setSpanAttribute('timber.deny_file', error.sourceFile);
+  try {
+    await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
+      try {
+        await accessFn();
+        await setSpanAttribute('timber.result', 'pass');
+      } catch (error: unknown) {
+        if (error instanceof DenySignal) {
+          await setSpanAttribute('timber.result', 'deny');
+          await setSpanAttribute('timber.deny_status', error.status);
+          if (error.sourceFile) {
+            await setSpanAttribute('timber.deny_file', error.sourceFile);
+          }
+        } else if (error instanceof RedirectSignal) {
+          await setSpanAttribute('timber.result', 'redirect');
         }
-      } else if (error instanceof RedirectSignal) {
-        await setSpanAttribute('timber.result', 'redirect');
+        throw error;
+      }
+    });
+  } catch (error: unknown) {
+    // Catch DenySignal and render the deny page in-tree.
+    // No throw reaches React Flight — clean stream, single render pass.
+    // RedirectSignal and other errors propagate normally.
+    if (error instanceof DenySignal && denyPages) {
+      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
+      if (denyElement) {
+        setDenyStatus(error.status);
+        return denyElement;
       }
-      throw error;
     }
-  });
+    throw error;
+  }
 
   return children;
 }
@@ -96,18 +107,27 @@ async function accessGateFallback(
  * The HTTP status code is unaffected — slot denial is a UI concern, not
  * a protocol concern. The parent layout and sibling slots still render.
  *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * DenySignal.data can be forwarded as the dangerouslyPassData prop
+ * and the slot name can be passed as the slot prop. See TIM-488.
+ *
  * redirect() in slot access.ts is a dev-mode error — redirecting from a
  * slot doesn't make architectural sense.
  */
 export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactElement> {
-  const { accessFn, params, searchParams, deniedFallback, defaultFallback, children } = props;
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
   try {
-    await accessFn({ params, searchParams });
+    await accessFn();
   } catch (error: unknown) {
     // DenySignal → graceful degradation (denied.tsx → default.tsx → null)
+    // Build the denied element dynamically so DenySignal.data is forwarded.
     if (error instanceof DenySignal) {
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, error.data, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // RedirectSignal in slot access → dev-mode error.
@@ -123,7 +143,11 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
         );
       }
       // In production, treat as a deny — render fallback rather than crash.
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // Unhandled error — re-throw so error boundaries can catch it.
@@ -141,3 +165,20 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
   // Access passed — render slot content.
   return children;
 }
+
+/**
+ * Build the denied fallback element dynamically with DenySignal data.
+ * Returns null if no DeniedComponent is available.
+ */
+function buildDeniedFallback(
+  DeniedComponent: SlotAccessGateProps['DeniedComponent'],
+  slotName: string,
+  data: unknown,
+  createElement: SlotAccessGateProps['createElement']
+): ReactElement | null {
+  if (!DeniedComponent) return null;
+  return createElement(DeniedComponent, {
+    slot: slotName,
+    dangerouslyPassData: data,
+  });
+}

package/src/server/action-client.ts

@@ -148,12 +148,23 @@ export interface ActionBuilderWithSchema<TCtx, 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.
  */
 export type ActionFn<TData> = {
+  /** <form action={fn}> compatibility — React discards the return value. */
+  (formData: FormData): void;
+  /** Direct call: action(input) */
   (input?: unknown): Promise<ActionResult<TData>>;
+  /** React useActionState: action(prevState, formData) */
   (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;
 };
 
@@ -183,8 +194,9 @@ 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';
 
 /**
  * Extract validation errors from a schema error.
@@ -295,8 +307,14 @@ export function createActionClient<TCtx = Record<string, never>>(
         // Determine input — either FormData (from useActionState) or direct arg
         let rawInput: unknown;
         if (args.length === 2 && args[1] instanceof FormData) {
-          // Called as (prevState, formData) by React useActionState
+          // Called as (prevState, formData) by React useActionState (with-JS path)
           rawInput = schema ? parseFormData(args[1]) : args[1];
+        } else if (args.length === 1 && args[0] instanceof FormData) {
+          // No-JS path: React's decodeAction binds FormData as the sole argument.
+          // The form POSTs without JavaScript, decodeAction resolves the server
+          // reference and binds the FormData, then executeAction calls fn() with
+          // no additional args — so the bound FormData arrives as args[0].
+          rawInput = schema ? parseFormData(args[0]) : args[0];
         } else {
           // Direct call: action(input)
           rawInput = args[0];
@@ -360,6 +378,13 @@ 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);
       }
     }

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'))"`
+    );
+  }
+}