@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

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,7 +18,7 @@ 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';
@@ -31,6 +31,8 @@ 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';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { logActionError } from './logger.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -90,6 +92,21 @@ 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.
   const csrfResult = validateCsrf(req, config.csrf);
   if (!csrfResult.ok) {
@@ -106,7 +123,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);
@@ -177,7 +194,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' }
@@ -293,7 +310,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

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;
 }
@@ -112,8 +110,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 +170,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)

package/src/server/als-registry.ts

@@ -21,9 +21,10 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
 // ─── Request Context ──────────────────────────────────────────────────────
-// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())
 // Design doc: design/04-authorization.md
 
 /** @internal — import via request-context.ts public API */
@@ -39,17 +40,44 @@ export interface RequestContextStore {
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
   /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
+   * Promise resolving to the raw URLSearchParams for the current request.
+   * To get typed parsed params, import a search params definition and
+   * call `.parse(searchParams())`.
    */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  searchParamsPromise: Promise<URLSearchParams>;
+  /**
+   * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+   * Available synchronously for use in `redirect()` with `preserveSearchParams`.
+   */
+  searchString: string;
+  /**
+   * Promise resolving to the coerced segment params for the current request.
+   * Set by the pipeline after route matching and param coercion, before
+   * middleware and rendering. Pages and layouts read params via
+   * `getSegmentParams()` instead of receiving them as a prop.
+   *
+   * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+   */
+  segmentParamsPromise?: Promise<Record<string, string | string[]>>;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
+   * server-side (inside the React tree, before React Flight sees it).
+   * The pipeline reads this after render to set the HTTP status code.
+   * See TIM-666.
+   */
+  denyStatus?: number;
+  /**
+   * Dev-only: getter for the current request's RSC debug components.
+   * Set by renderRoute() so onPipelineError can include component tree
+   * context for render-phase errors without module-level shared state.
+   */
+  debugComponentsGetter?: () => DebugComponentEntry[];
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
@@ -60,7 +88,7 @@ export interface CookieEntry {
 }
 
 // ─── Tracing ──────────────────────────────────────────────────────────────
-// Used by: tracing.ts (traceId(), spanId())
+// Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
 export interface TraceStore {

package/src/server/build-manifest.ts

@@ -85,6 +85,12 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
+  // Emit <link rel="stylesheet"> tags as a fallback for platforms where
+  // React's Float system (via @vitejs/plugin-rsc preinit with
+  // data-precedence) doesn't handle CSS injection. In practice, Float
+  // deduplicates and these may be dropped. No preload hints — Float
+  // already starts the fetch via preinit(), and redundant preloads
+  // cause "ignored due to unknown as/type" browser warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
@@ -95,10 +101,10 @@ export function buildCssLinkTags(cssUrls: string[]): string {
  * into 103 Early Hints responses. This avoids platform-specific 103
  * sending code.
  *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
+ * Example output: `</assets/root.css>; as=style; rel=preload, </assets/page.css>; as=style; rel=preload`
  */
 export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
+  return cssUrls.map((url) => `<${url}>; as=style; rel=preload`).join(', ');
 }
 
 // ─── Font utilities ──────────────────────────────────────────────────────
@@ -153,10 +159,10 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
  *
  * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
  *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ * Example: `</fonts/inter.woff2>; as=font; rel=preload; crossorigin`
  */
 export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
+  return fonts.map((f) => `<${f.href}>; as=font; rel=preload; crossorigin`).join(', ');
 }
 
 // ─── JS chunk utilities ──────────────────────────────────────────────────

package/src/server/compress.ts

@@ -160,15 +160,33 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const compressionStream = new CompressionStream('gzip');
-  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
-  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
-  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+  nodeInput.pipe(gzip);
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }

package/src/server/debug.ts

@@ -48,7 +48,7 @@
  *
  * This is the ONLY function that should gate client-visible dev behavior:
  * - Dev error pages with stack traces
- * - Detailed Server-Timing response headers
+ * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
  * - Error messages in action `INTERNAL_ERROR` payloads
  * - Pipeline error handler wiring (Vite overlay)
  *

package/src/server/default-logger.ts

@@ -0,0 +1,99 @@
+/**
+ * DefaultLogger — human-readable stderr logging when no custom logger is configured.
+ *
+ * Ships as the fallback so production deployments always have error visibility,
+ * even without an `instrumentation.ts` logger export. Output is one line per
+ * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+ *
+ * Format:
+ *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+ *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+ *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+ *
+ * Behavior:
+ * - Suppressed entirely in dev mode (dev logging handles all output)
+ * - `debug` suppressed unless TIMBER_DEBUG is set
+ * - Replaced entirely when a custom logger is set via `setLogger()`
+ *
+ * See design/17-logging.md §"DefaultLogger"
+ */
+
+import { isDevMode, isDebug } from './debug.js';
+import { formatSsrError } from './error-formatter.js';
+import type { TimberLogger } from './logger.js';
+
+/**
+ * Format data fields as `key=value` pairs for human-readable output.
+ * - `error` key is serialized via formatSsrError for stack trace cleanup
+ * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+ * - Other values are stringified inline
+ */
+function formatDataFields(data?: Record<string, unknown>): string {
+  if (!data) return '';
+
+  const parts: string[] = [];
+  let traceId: string | undefined;
+
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'trace_id') {
+      // Defer trace_id to the end
+      traceId = typeof value === 'string' ? value : String(value);
+      continue;
+    }
+    if (key === 'error') {
+      // Serialize errors with formatSsrError for clean output
+      parts.push(`error=${formatSsrError(value)}`);
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+    parts.push(`${key}=${value}`);
+  }
+
+  // trace_id always last, truncated to 8 chars for readability
+  if (traceId) {
+    parts.push(`trace_id=${traceId.slice(0, 8)}`);
+  }
+
+  return parts.length > 0 ? '  ' + parts.join('  ') : '';
+}
+
+/** Pad level string to fixed width for alignment. */
+function padLevel(level: string): string {
+  return level.padEnd(5);
+}
+
+export function createDefaultLogger(): TimberLogger {
+  return {
+    error(msg: string, data?: Record<string, unknown>): void {
+      // Errors are ALWAYS logged, including dev mode. Suppressing errors
+      // in dev causes silent 500s with no stack trace, making route.ts
+      // and render errors impossible to debug. See TIM-555.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\n`);
+    },
+
+    warn(msg: string, data?: Record<string, unknown>): void {
+      // Warnings are always logged — same rationale as errors.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\n`);
+    },
+
+    info(msg: string, data?: Record<string, unknown>): void {
+      // info is suppressed by default — per-request lines are too noisy
+      // without a custom logger. Enable with TIMBER_DEBUG.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\n`);
+    },
+
+    debug(msg: string, data?: Record<string, unknown>): void {
+      // debug is suppressed in dev (dev logger handles it) and in
+      // production unless TIMBER_DEBUG is explicitly set.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\n`);
+    },
+  };
+}