@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.35

package/dist/search-params/index.js

@@ -1,474 +1,3 @@
-import { i as registerSearchParams, n as useQueryStates, r as getSearchParams } from "../_chunks/use-query-states-D5KaffOK.js";
-//#region src/search-params/create.ts
-/**
-* createSearchParams — factory for SearchParamsDefinition<T>.
-*
-* Creates a typed, composable definition for a route's search parameters.
-* Supports codec protocol, URL key aliasing, default-omission serialization,
-* and composition via .extend() / .pick().
-*
-* Design doc: design/09-typescript.md §"Typed searchParams — search-params.ts"
-*/
-/**
-* Convert URLSearchParams or a plain record to a normalized record
-* where repeated keys produce arrays.
-*/
-function normalizeRaw(raw) {
-	if (raw instanceof URLSearchParams) {
-		const result = {};
-		for (const key of new Set(raw.keys())) {
-			const values = raw.getAll(key);
-			result[key] = values.length === 1 ? values[0] : values;
-		}
-		return result;
-	}
-	return raw;
-}
-/**
-* Compute the serialized default value for a codec. Used for
-* default-omission: when serialize(value) === serialize(parse(undefined)),
-* the field is omitted from the URL.
-*/
-function getDefaultSerialized(codec) {
-	return codec.serialize(codec.parse(void 0));
-}
-/**
-* Create a SearchParamsDefinition from a codec map and optional URL key aliases.
-*
-* ```ts
-* import { createSearchParams, fromSchema } from '@timber-js/app/search-params'
-* import { z } from 'zod/v4'
-*
-* export default createSearchParams({
-*   page: fromSchema(z.coerce.number().int().min(1).default(1)),
-*   q: { parse: (v) => v ?? null, serialize: (v) => v },
-* }, {
-*   urlKeys: { q: 'search' },
-* })
-* ```
-*/
-function createSearchParams(codecs, options) {
-	const urlKeys = {};
-	if (options?.urlKeys) {
-		for (const [k, v] of Object.entries(options.urlKeys)) if (v !== void 0) urlKeys[k] = v;
-	}
-	return buildDefinition(codecs, urlKeys);
-}
-/**
-* Internal: build a SearchParamsDefinition from a typed codec map and url keys.
-*/
-function buildDefinition(codecMap, urlKeys) {
-	const defaultSerialized = {};
-	for (const key of Object.keys(codecMap)) defaultSerialized[key] = getDefaultSerialized(codecMap[key]);
-	function getUrlKey(prop) {
-		return urlKeys[prop] ?? prop;
-	}
-	function parse(raw) {
-		const normalized = normalizeRaw(raw);
-		const result = {};
-		for (const prop of Object.keys(codecMap)) {
-			const rawValue = normalized[getUrlKey(prop)];
-			result[prop] = codecMap[prop].parse(rawValue);
-		}
-		return result;
-	}
-	function serialize(values) {
-		const parts = [];
-		for (const prop of Object.keys(codecMap)) {
-			if (!(prop in values)) continue;
-			const serialized = codecMap[prop].serialize(values[prop]);
-			if (serialized === defaultSerialized[prop]) continue;
-			if (serialized === null) continue;
-			parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
-		}
-		return parts.join("&");
-	}
-	function href(pathname, values) {
-		const qs = serialize(values);
-		return qs ? `${pathname}?${qs}` : pathname;
-	}
-	function toSearchParams(values) {
-		const usp = new URLSearchParams();
-		for (const prop of Object.keys(codecMap)) {
-			if (!(prop in values)) continue;
-			const serialized = codecMap[prop].serialize(values[prop]);
-			if (serialized === defaultSerialized[prop]) continue;
-			if (serialized === null) continue;
-			usp.set(getUrlKey(prop), serialized);
-		}
-		return usp;
-	}
-	function extend(newCodecs, extendOptions) {
-		const combinedCodecs = {
-			...codecMap,
-			...newCodecs
-		};
-		const combinedUrlKeys = { ...urlKeys };
-		if (extendOptions?.urlKeys) {
-			for (const [k, v] of Object.entries(extendOptions.urlKeys)) if (v !== void 0) combinedUrlKeys[k] = v;
-		}
-		return buildDefinition(combinedCodecs, combinedUrlKeys);
-	}
-	function pick(...keys) {
-		const pickedCodecs = {};
-		const pickedUrlKeys = {};
-		for (const key of keys) {
-			pickedCodecs[key] = codecMap[key];
-			if (key in urlKeys) pickedUrlKeys[key] = urlKeys[key];
-		}
-		return buildDefinition(pickedCodecs, pickedUrlKeys);
-	}
-	function useQueryStates$1(options) {
-		return useQueryStates(codecMap, options, Object.freeze({ ...urlKeys }));
-	}
-	return {
-		parse,
-		useQueryStates: useQueryStates$1,
-		extend,
-		pick,
-		serialize,
-		href,
-		toSearchParams,
-		codecs: codecMap,
-		urlKeys: Object.freeze({ ...urlKeys })
-	};
-}
-//#endregion
-//#region src/search-params/codecs.ts
-/**
-* Zod v4's ~standard.validate() signature includes Promise in the return union
-* to satisfy the Standard Schema spec, but in practice Zod always validates
-* synchronously for the schema types we use. We assert the result is sync and
-* throw if it isn't — search params parsing must be synchronous.
-*/
-function validateSync(schema, value) {
-	const result = schema["~standard"].validate(value);
-	if (result instanceof Promise) throw new Error("[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.");
-	return result;
-}
-/**
-* Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
-* SearchParamCodec.
-*
-* Parse: coerces the raw URL string through the schema. On validation failure,
-* parses `undefined` to get the schema's default value (the schema should have
-* a `.default()` call). If that also fails, returns `undefined`.
-*
-* Serialize: uses `String()` for primitives, `null` for null/undefined.
-*
-* ```ts
-* import { fromSchema } from '@timber-js/app/search-params'
-* import { z } from 'zod/v4'
-*
-* const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
-* ```
-*/
-function fromSchema(schema) {
-	return {
-		parse(value) {
-			const result = validateSync(schema, Array.isArray(value) ? value[value.length - 1] : value);
-			if (!result.issues) return result.value;
-			const defaultResult = validateSync(schema, void 0);
-			if (!defaultResult.issues) return defaultResult.value;
-		},
-		serialize(value) {
-			if (value === null || value === void 0) return null;
-			return String(value);
-		}
-	};
-}
-/**
-* Bridge a Standard Schema for array values. Handles both single strings
-* and repeated query keys (`?tag=a&tag=b`).
-*
-* ```ts
-* import { fromArraySchema } from '@timber-js/app/search-params'
-* import { z } from 'zod/v4'
-*
-* const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
-* ```
-*/
-function fromArraySchema(schema) {
-	return {
-		parse(value) {
-			let input = value;
-			if (typeof value === "string") input = [value];
-			else if (value === void 0) input = void 0;
-			const result = validateSync(schema, input);
-			if (!result.issues) return result.value;
-			const defaultResult = validateSync(schema, void 0);
-			if (!defaultResult.issues) return defaultResult.value;
-		},
-		serialize(value) {
-			if (value === null || value === void 0) return null;
-			if (Array.isArray(value)) return value.length === 0 ? null : value.join(",");
-			return String(value);
-		}
-	};
-}
-//#endregion
-//#region src/search-params/builtin-codecs.ts
-/**
-* Normalize array inputs to a single string (last value wins, matching
-* URLSearchParams.get() semantics). Returns undefined if absent or empty.
-*/
-function normalizeInput(value) {
-	if (Array.isArray(value)) return value.length > 0 ? value[value.length - 1] : void 0;
-	return value;
-}
-/**
-* String codec. Returns the raw string value, or null if absent.
-*
-* ```ts
-* import { parseAsString } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ q: parseAsString })
-* // ?q=shoes → { q: 'shoes' }
-* // (absent) → { q: null }
-* ```
-*/
-var parseAsString = {
-	parse(value) {
-		const v = normalizeInput(value);
-		return v !== void 0 ? v : null;
-	},
-	serialize(value) {
-		return value;
-	}
-};
-/**
-* Integer codec. Parses a base-10 integer, or returns null if absent or
-* not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.
-*
-* ```ts
-* import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })
-* // ?page=2 → { page: 2 }
-* // ?page=abc → { page: 1 }
-* // (absent) → { page: 1 }
-* ```
-*/
-var parseAsInteger = {
-	parse(value) {
-		const v = normalizeInput(value);
-		if (v === void 0 || v === "") return null;
-		const n = Number(v);
-		if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
-		return n;
-	},
-	serialize(value) {
-		return value === null ? null : String(value);
-	}
-};
-/**
-* Float codec. Parses a finite number, or returns null if absent or invalid.
-* Rejects NaN and Infinity.
-*
-* ```ts
-* import { parseAsFloat, withDefault } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })
-* ```
-*/
-var parseAsFloat = {
-	parse(value) {
-		const v = normalizeInput(value);
-		if (v === void 0 || v === "") return null;
-		const n = Number(v);
-		if (!Number.isFinite(n)) return null;
-		return n;
-	},
-	serialize(value) {
-		return value === null ? null : String(value);
-	}
-};
-/**
-* Boolean codec. Accepts "true"/"1" as true, "false"/"0" as false.
-* Returns null for absent or unrecognized values.
-*
-* ```ts
-* import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'
-*
-* const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })
-* // ?debug=true → { debug: true }
-* // ?debug=0 → { debug: false }
-* ```
-*/
-var parseAsBoolean = {
-	parse(value) {
-		const v = normalizeInput(value);
-		if (v === void 0) return null;
-		if (v === "true" || v === "1") return true;
-		if (v === "false" || v === "0") return false;
-		return null;
-	},
-	serialize(value) {
-		return value === null ? null : String(value);
-	}
-};
-/**
-* String enum codec. Accepts only values in the provided list.
-* Returns null for absent or invalid values.
-*
-* ```ts
-* import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'
-*
-* const sortCodec = withDefault(
-*   parseAsStringEnum(['price', 'name', 'date']),
-*   'date'
-* )
-* ```
-*/
-function parseAsStringEnum(values) {
-	const allowed = new Set(values);
-	return {
-		parse(value) {
-			const v = normalizeInput(value);
-			if (v === void 0) return null;
-			return allowed.has(v) ? v : null;
-		},
-		serialize(value) {
-			return value;
-		}
-	};
-}
-/**
-* String literal codec. Functionally identical to parseAsStringEnum but
-* accepts `as const` tuples for narrower type inference.
-*
-* ```ts
-* import { parseAsStringLiteral } from '@timber-js/app/search-params'
-*
-* const sizes = ['sm', 'md', 'lg', 'xl'] as const
-* const codec = parseAsStringLiteral(sizes)
-* // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>
-* ```
-*/
-function parseAsStringLiteral(values) {
-	return parseAsStringEnum(values);
-}
-/**
-* Wrap a nullable codec with a default value. When the inner codec returns
-* null, the default is used instead. The output type becomes non-nullable.
-*
-* ```ts
-* import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
-*
-* const page = withDefault(parseAsInteger, 1)
-* // page.parse(undefined) → 1 (not null)
-* // page.parse('5') → 5
-* ```
-*/
-function withDefault(codec, defaultValue) {
-	return {
-		parse(value) {
-			const result = codec.parse(value);
-			return result === null ? defaultValue : result;
-		},
-		serialize(value) {
-			return codec.serialize(value);
-		}
-	};
-}
-//#endregion
-//#region src/search-params/analyze.ts
-/**
-* Patterns that indicate a valid default export:
-*
-* 1. `export default createSearchParams(...)`
-* 2. `export default someVar.extend(...)`
-* 3. `export default someVar.pick(...)`
-* 4. `export default someVar.extend(...).extend(...)`  (chained)
-* 5. `export default someVar.extend(...).pick(...)`    (chained)
-* 6. `export default createSearchParams(...).extend(...)`
-*
-* Invalid patterns:
-* - `export default someFunction(...)` (arbitrary factory)
-* - `export default condition ? a : b` (runtime conditional)
-* - `export default variable` (opaque reference without call)
-*/
-/**
-* Analyze a search-params.ts file source for static analyzability.
-*
-* @param source - The file content as a string
-* @param filePath - Absolute path to the file (for diagnostics)
-*/
-function analyzeSearchParams(source, filePath) {
-	const defaultExport = extractDefaultExport(stripComments(source));
-	if (!defaultExport) return {
-		valid: false,
-		error: {
-			filePath,
-			expression: "(no default export found)",
-			suggestion: "search-params.ts must have a default export. Use: export default createSearchParams({ ... })"
-		}
-	};
-	if (isValidExpression(defaultExport.trim())) return { valid: true };
-	return {
-		valid: false,
-		error: {
-			filePath,
-			expression: defaultExport.trim(),
-			suggestion: "The default export must be a createSearchParams() call, or a chain of .extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory functions and runtime conditionals are not supported."
-		}
-	};
-}
-/** Strip single-line and multi-line comments from source. */
-function stripComments(source) {
-	let result = source.replace(/\/\*[\s\S]*?\*\//g, "");
-	result = result.replace(/\/\/.*$/gm, "");
-	return result;
-}
-/**
-* Extract the expression from `export default <expr>`.
-*
-* Handles both:
-*   export default createSearchParams(...)
-*   export default expr\n (terminated by newline or semicolon before next statement)
-*/
-function extractDefaultExport(source) {
-	const match = source.match(/export\s+default\s+([\s\S]+?)(?:;|\n(?=export|import|const|let|var|function|class|type|interface|declare))/);
-	if (match) return match[1];
-	const fallback = source.match(/export\s+default\s+([\s\S]+)$/);
-	if (fallback) return fallback[1].replace(/;\s*$/, "");
-}
-/**
-* Check if an expression is a valid statically-analyzable pattern.
-*
-* Valid patterns:
-* - Starts with `createSearchParams(`
-* - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)
-* - A variable identifier followed by chaining
-*/
-function isValidExpression(expr) {
-	const normalized = expr.replace(/\s+/g, " ").trim();
-	if (normalized.startsWith("createSearchParams(")) return true;
-	if (/\.(extend|pick)\s*\(/.test(normalized)) {
-		if (/\?/.test(normalized) && /:/.test(normalized)) return false;
-		if (/^\s*(function|=>|\()/.test(normalized)) return false;
-		return true;
-	}
-	return false;
-}
-/**
-* Format an AnalyzeError into a human-readable build error message.
-*/
-function formatAnalyzeError(error) {
-	return [
-		`[timber] Non-analyzable search-params.ts`,
-		``,
-		`  File: ${error.filePath}`,
-		`  Expression: ${error.expression}`,
-		``,
-		`  ${error.suggestion}`,
-		``,
-		`  The framework must be able to statically extract the type from your`,
-		`  search-params.ts at build time. Dynamic values, conditionals, and`,
-		`  arbitrary factory functions prevent this analysis.`
-	].join("\n");
-}
-//#endregion
-export { analyzeSearchParams, createSearchParams, formatAnalyzeError, fromArraySchema, fromSchema, getSearchParams, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsString, parseAsStringEnum, parseAsStringLiteral, registerSearchParams, withDefault };
-
-//# sourceMappingURL=index.js.map
+import { i as registerSearchParams, r as getSearchParams } from "../_chunks/use-query-states-BvW0TKDn.js";
+import { a as fromSchema, i as fromArraySchema, n as withUrlKey, r as defineSearchParams, t as withDefault } from "../_chunks/wrappers-C1SN725w.js";
+export { defineSearchParams, fromArraySchema, fromSchema, getSearchParams, registerSearchParams, withDefault, withUrlKey };

package/dist/search-params/registry.d.ts

@@ -6,7 +6,7 @@
  *
  * Design doc: design/23-search-params.md §"Runtime: Registration at Route Load"
  */
-import type { SearchParamsDefinition } from './create.js';
+import type { SearchParamsDefinition } from './define.js';
 /**
  * Register a route's search params definition.
  * Called by the generated route manifest loader when a route's modules load.

package/dist/search-params/wrappers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Codec wrappers — withDefault and withUrlKey.
+ *
+ * These are timber-specific utilities that work with any SearchParamCodec.
+ * For actual codecs (string, integer, boolean, etc.), use nuqs parsers
+ * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.
+ *
+ * Design doc: design/23-search-params.md
+ */
+import type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';
+/**
+ * Wrap a nullable codec with a default value. When the inner codec returns
+ * null, the default is used instead. The output type becomes non-nullable.
+ *
+ * Works with any codec — nuqs parsers, custom codecs, fromSchema results.
+ *
+ * ```ts
+ * import { parseAsInteger } from 'nuqs'
+ * import { withDefault } from '@timber-js/app/search-params'
+ *
+ * const page = withDefault(parseAsInteger, 1)
+ * // page.parse(undefined) → 1 (not null)
+ * // page.parse('5') → 5
+ * ```
+ */
+export declare function withDefault<T>(codec: SearchParamCodec<T | null>, defaultValue: T): SearchParamCodec<T>;
+/**
+ * Attach a URL key alias to a codec. The alias determines what query
+ * parameter key is used in the URL, while the TypeScript property name
+ * stays descriptive.
+ *
+ * Aliases travel with codecs through object spread composition — when
+ * you spread a bundle containing aliased codecs into defineSearchParams,
+ * the aliases come along automatically.
+ *
+ * ```ts
+ * import { parseAsString } from 'nuqs'
+ * import { withUrlKey } from '@timber-js/app/search-params'
+ *
+ * export const searchable = {
+ *   q: withUrlKey(parseAsString, 'search'),
+ *   // ?search=shoes → { q: 'shoes' }
+ * }
+ * ```
+ *
+ * Composes with withDefault:
+ * ```ts
+ * import { parseAsInteger } from 'nuqs'
+ * withUrlKey(withDefault(parseAsInteger, 1), 'p')
+ * ```
+ */
+export declare function withUrlKey<T>(codec: SearchParamCodec<T>, urlKey: string): SearchParamCodecWithUrlKey<T>;
+//# sourceMappingURL=wrappers.d.ts.map

package/dist/search-params/wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers.d.ts","sourceRoot":"","sources":["../../src/search-params/wrappers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAMhF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,gBAAgB,CAAC,CAAC,GAAG,IAAI,CAAC,EACjC,YAAY,EAAE,CAAC,GACd,gBAAgB,CAAC,CAAC,CAAC,CAUrB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,0BAA0B,CAAC,CAAC,CAAC,CAM/B"}

package/dist/server/access-gate.d.ts

@@ -35,6 +35,10 @@ export declare function AccessGate(props: AccessGateProps): ReactElement | Promi
  * 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.
  */

package/dist/server/access-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-gate.d.ts","sourceRoot":"","sources":["../../src/server/access-gate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAM5F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBvF;AAoCD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAyCtF"}
+{"version":3,"file":"access-gate.d.ts","sourceRoot":"","sources":["../../src/server/access-gate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAM5F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBvF;AAmCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmDtF"}

package/dist/server/action-encryption.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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
+ */
+/** 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;
+}
+/**
+ * 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 declare function resolveEncryptionKeyExpression(): string | 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 declare function shouldEnableEncryption(isDev: boolean, config?: ActionEncryptionConfig): boolean;
+/**
+ * Validate that a key string is a valid base64-encoded 256-bit key.
+ * Throws a descriptive error if the key is malformed.
+ */
+export declare function validateKeyFormat(key: string): void;
+//# sourceMappingURL=action-encryption.d.ts.map

package/dist/server/action-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-encryption.d.ts","sourceRoot":"","sources":["../../src/server/action-encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAwBnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAI/F;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBnD"}

package/dist/server/action-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-handler.d.ts","sourceRoot":"","sources":["../../src/server/action-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,gDAAgD;IAChD,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAQD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAarD;AAID,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC,CAwCzC"}
+{"version":3,"file":"action-handler.d.ts","sourceRoot":"","sources":["../../src/server/action-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKrD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,gDAAgD;IAChD,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAQD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAarD;AAID,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC,CAuDzC"}

package/dist/server/als-registry.d.ts

@@ -32,11 +32,11 @@ 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>;
     /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
     cookieJar: Map<string, CookieEntry>;
     /** Whether the response has flushed (headers committed). */

package/dist/server/als-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"als-registry.d.ts","sourceRoot":"","sources":["../../src/server/als-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAMrD,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,wCAA+C,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAC,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxE,wFAAwF;IACxF,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAC;CACvD;AAMD,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,+BAAsC,CAAC;AAM5D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,oBAAoB,EAAE,WAAW,EAAE,CAAC;CACrD;AAED,yDAAyD;AACzD,eAAO,MAAM,SAAS,gCAAuC,CAAC;AAM9D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,mDAAmD;AACnD,eAAO,MAAM,eAAe,sCAA6C,CAAC;AAM1E,sDAAsD;AACtD,eAAO,MAAM,YAAY,4DAAmE,CAAC;AAM7F,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAE3D,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,uCAA8C,CAAC;AAM/E,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,YAAY,gCAAuC,CAAC"}
+{"version":3,"file":"als-registry.d.ts","sourceRoot":"","sources":["../../src/server/als-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAMrD,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,wCAA+C,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C,wFAAwF;IACxF,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAC;CACvD;AAMD,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,+BAAsC,CAAC;AAM5D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,oBAAoB,EAAE,WAAW,EAAE,CAAC;CACrD;AAED,yDAAyD;AACzD,eAAO,MAAM,SAAS,gCAAuC,CAAC;AAM9D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,mDAAmD;AACnD,eAAO,MAAM,eAAe,sCAA6C,CAAC;AAM1E,sDAAsD;AACtD,eAAO,MAAM,YAAY,4DAAmE,CAAC;AAM7F,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAE3D,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,uCAA8C,CAAC;AAM/E,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,YAAY,gCAAuC,CAAC"}