@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/action-client.ts

@@ -8,7 +8,7 @@
  *   1. Direct call: action(input) → Promise<ActionResult>
  *   2. React useActionState: (prevState, formData) => Promise<ActionResult>
  *
- * See design/08-forms-and-actions.md §"Middleware for Server Actions"
+ * See design/08-forms-and-actions.md §"Middleware and Server Actions"
  */
 
 // ─── ActionError ─────────────────────────────────────────────────────────
@@ -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>>;
 };
 
@@ -182,8 +220,16 @@ 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 { parseFormData } from './form-data.ts';
+import { formatSize } from '../utils/format.ts';
+import { isDebug, isDevMode } from './debug.ts';
+import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import {
+  stripSensitiveFields,
+  resolveSensitivePredicate,
+  getGlobalSensitiveFieldsConfig,
+  type SensitiveFieldsOption,
+} from './sensitive-fields.ts';
 
 /**
  * Extract validation errors from a schema error.
@@ -246,12 +292,15 @@ export function handleActionError(error: unknown): ActionResult<never> {
     };
   }
 
-  // In dev, include the message for debugging
-  const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  // In dev, include the message for debugging.
+  // Uses isDevMode() — NOT isDebug() — because this data is sent to the
+  // browser. TIMBER_DEBUG must never cause error messages to leak to clients.
+  // See design/13-security.md principle 4: "Errors don't leak."
+  const devMode = isDevMode();
   return {
     serverError: {
       code: 'INTERNAL_ERROR',
-      ...(isDev && error instanceof Error ? { data: { message: error.message } } : {}),
+      ...(devMode && error instanceof Error ? { data: { message: error.message } } : {}),
     },
   };
 }
@@ -282,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
@@ -291,13 +340,38 @@ 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];
         }
 
+        // 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(
@@ -305,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;
@@ -356,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 (isRedirectSignal(error) || isDenySignal(error)) {
+          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>);
     },
   };
@@ -400,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));
@@ -413,7 +496,7 @@ export function validated<TInput, TData>(
  * In production, validation errors are only returned to the client.
  */
 function logValidationFailure(errors: ValidationErrors): void {
-  const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  const isDev = isDebug();
   if (!isDev) return;
 
   const fields = Object.entries(errors)
@@ -427,26 +510,38 @@ function logValidationFailure(errors: ValidationErrors): void {
  * Returns validation errors keyed by field name, or null if all files are ok.
  */
 function validateFileSizes(input: Record<string, unknown>, limit: number): ValidationErrors | null {
-  const errors: ValidationErrors = {};
   const limitKb = Math.round(limit / 1024);
   const limitLabel =
     limit >= 1024 * 1024 ? `${Math.round(limit / (1024 * 1024))}MB` : `${limitKb}KB`;
 
-  for (const [key, value] of Object.entries(input)) {
-    if (value instanceof File && value.size > limit) {
-      errors[key] = [
-        `File "${value.name}" (${formatSize(value.size)}) exceeds the ${limitLabel} limit`,
-      ];
-    } else if (Array.isArray(value)) {
-      const oversized = value.filter((item) => item instanceof File && item.size > limit);
-      if (oversized.length > 0) {
-        errors[key] = oversized.map(
-          (f: File) => `File "${f.name}" (${formatSize(f.size)}) exceeds the ${limitLabel} limit`
-        );
+  const errors: ValidationErrors = {};
+
+  function walk(obj: Record<string, unknown>, prefix: string): void {
+    for (const [key, value] of Object.entries(obj)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (value instanceof File && value.size > limit) {
+        errors[path] = [
+          `File "${value.name}" (${formatSize(value.size)}) exceeds the ${limitLabel} limit`,
+        ];
+      } else if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+          const item = value[i];
+          const itemPath = `${path}[${i}]`;
+          if (item instanceof File && item.size > limit) {
+            (errors[itemPath] ??= []).push(
+              `File "${item.name}" (${formatSize(item.size)}) exceeds the ${limitLabel} limit`
+            );
+          } else if (typeof item === 'object' && item !== null && !(item instanceof File)) {
+            walk(item as Record<string, unknown>, itemPath);
+          }
+        }
+      } else if (typeof value === 'object' && value !== null && !(value instanceof File)) {
+        walk(value as Record<string, unknown>, path);
       }
     }
   }
 
+  walk(input, '');
   return Object.keys(errors).length > 0 ? errors : null;
 }
 
@@ -462,7 +557,13 @@ function stripFiles(value: unknown): Record<string, unknown> | undefined {
   for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
     if (v instanceof File) continue;
     if (Array.isArray(v)) {
-      result[k] = v.filter((item) => !(item instanceof File));
+      result[k] = v
+        .filter((item) => !(item instanceof File))
+        .map((item) =>
+          typeof item === 'object' && item !== null && !(item instanceof File)
+            ? (stripFiles(item) ?? {})
+            : item
+        );
     } else if (typeof v === 'object' && v !== null && !(v instanceof File)) {
       result[k] = stripFiles(v) ?? {};
     } else {

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