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

package/src/server/action-handler.ts

@@ -18,19 +18,28 @@ import {
   decodeReply,
   decodeAction,
   renderToReadableStream,
-} from '#/rsc-runtime/rsc.js';
-
-import { validateCsrf, type CsrfConfig } from './csrf.js';
-import { executeAction, type RevalidateRenderer } from './actions.js';
+} from '../rsc-runtime/rsc.ts';
+
+import { validateCsrf, type CsrfConfig } from './csrf.ts';
+import { isDenySignal, isRedirectSignal } from './primitives.ts';
+import { executeAction, type RevalidateRenderer } from './actions.ts';
+import { runWithRequestContext, setMutableCookieContext } from './request-context.ts';
+import { getSetCookieHeaders, getCookiesForSsr } from './cookie-context.ts';
+import { handleActionError } from './action-client.ts';
+import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.ts';
+import { parseFormData } from './form-data.ts';
 import {
-  runWithRequestContext,
-  setMutableCookieContext,
-  getSetCookieHeaders,
-} from './request-context.js';
-import { handleActionError } from './action-client.js';
-import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.js';
-import { parseFormData } from './form-data.js';
-import type { FormFlashData } from './form-flash.js';
+  stripSensitiveFields,
+  resolveSensitivePredicate,
+  getGlobalSensitiveFieldsConfig,
+  type SensitiveFieldsOption,
+} from './sensitive-fields.ts';
+import type { FormFlashData } from './form-flash.ts';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.ts';
+import { logActionError } from './logger.ts';
+import { withTimeout, RenderTimeoutError } from './render-timeout.ts';
+import { canonicalize } from './canonicalize.ts';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -42,12 +51,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 +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;
   });
@@ -172,12 +247,18 @@ async function handleRscAction(
   // of leaking stack traces as 500s.
   let result;
   try {
+    const requestUrl = new URL(req.url);
+    // Canonicalize the request pathname so it matches the decoded form
+    // that revalidationPathMatches uses on the target side.
+    const canonical = canonicalize(requestUrl.pathname, true);
     result = await executeAction(actionFn, args, {
       renderer: config.revalidateRenderer,
+      requestPathname: canonical.ok ? canonical.pathname : requestUrl.pathname,
+      requestSearch: requestUrl.search,
     });
   } 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' }
@@ -198,13 +279,14 @@ async function handleRscAction(
       _status: result.redirectStatus ?? 302,
     };
     const rscStream = renderToReadableStream(redirectPayload);
-    return new Response(rscStream, {
-      status: 200,
-      headers: {
-        'Content-Type': RSC_CONTENT_TYPE,
-        'X-Timber-Redirect': result.redirectTo,
-      },
-    });
+    const redirectHeaders: Record<string, string> = {
+      'Content-Type': RSC_CONTENT_TYPE,
+      'X-Timber-Redirect': result.redirectTo,
+    };
+    if (result.invalidatedPaths && result.invalidatedPaths.length > 0) {
+      redirectHeaders['X-Timber-Revalidation-Path'] = result.invalidatedPaths.join(' ');
+    }
+    return new Response(rscStream, { status: 200, headers: redirectHeaders });
   }
 
   // Render the action result as an RSC stream.
@@ -215,24 +297,112 @@ async function handleRscAction(
     'Content-Type': RSC_CONTENT_TYPE,
   };
 
-  let payload: unknown;
+  // TIM-1454: Tell the client which paths were invalidated (non-matching).
+  if (result.invalidatedPaths && result.invalidatedPaths.length > 0) {
+    headers['X-Timber-Revalidation-Path'] = result.invalidatedPaths.join(' ');
+  }
+
   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 (isDenySignal(error)) {
+          serializationSignal ??= { kind: 'deny', status: error.status };
+        } else if (isRedirectSignal(error)) {
+          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 +410,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 +448,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 +476,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 +487,9 @@ async function handleFormAction(
         ...errorResult,
         submittedValues,
       },
+      // Filled in by handleActionRequest before the ALS scope exits.
+      setCookieHeaders: [],
+      cookies: new Map(),
     };
   }
 
@@ -321,5 +507,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() };
 }