lambder 3.7.1 → 4.0.1

package/Readme.md

@@ -1,8 +1,18 @@
-# Lambder - Serverless NodeJS Web Framework (v3)
+# Lambder - Serverless NodeJS Web Framework (v4)
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
-**New in v3:** Public file serving with `servePublicFiles()` + `serveIndexHtml()`, unified `addAction()` for non-HTTP triggers, automatic gzip + ETag, thrown responses with a real `die`, the comment-based `LambderTemplatingEngine`, type-safe `html`/`xml` tagged templates, API Gateway HTTP API (payload v2) / Lambda Function URL support, the `LambderDdbCache` DynamoDB cache (3.1), typed translations with `createLambderI18n` (3.2), and in 3.5: typed API refusals with `LambderApiError`, caller outcomes/timeouts with `apiOutcome()`, plus declarative per-API rate limits, guards, and idempotency; 3.7 makes guards and custom rate-limit keys payload-sliced ({ input, handler }): the slice is validated pre-run, typed in the handler, and force-merged into the contract input.
+**New in v4:**
+
+- **Declarative auth as guards**: guards take per-API params (`guards: { orgPermission: "SOME.PERMISSION" }`), can require a session (`session: true`, compile-checked), and RETURN typed values that land on the handler's `ctx.guardData[name]`. Together with the apiInput/guardInput input modes, permission checks and device auth become registration-time declarations instead of per-handler boilerplate.
+- **Hardened policy layer**: rate-limit policies can share one counter across APIs (`scope: "policy"`); idempotency replays answer before rate limits, survive client IP changes (key-scoped for public APIs, 16-char minimum keys), store full response headers, refuse to store Set-Cookie responses, and Brotli-compress stored bodies of 1KB+ so the ~350KB replay budget applies to compressed bytes.
+- **Secrets hashed at rest**: session records store only sha256 hashes of the bearer secrets, so a session-table read yields no usable cookies; `LambderSessionReadError` keeps a DynamoDB blip from reading as a logout.
+- **Three package entry points**: `lambder` (server), `lambder/client` (browser-safe by construction: no AWS SDK, no Node built-ins), `lambder/testing` (`LambderMSW`); sources organized into core/policies/session/stores/client/shared.
+- **Quality of life**: the `LambderApp` alias for annotating api modules, `LambderCaller.createIdempotencyKeyScope()` for one self-rotating key per logical operation, fail-open rate limiting logs its passes.
+
+**Breaking in v4** (from 3.x): session records are reshaped (hashes at rest; live sessions invalidate once on upgrade, clients just re-login) and the manager-level `createSession`/`regenerateSession` return `LambderCreatedSession` (`{ session, sessionToken, csrfToken }`; the controller API is unchanged); `LambderMSW` moved from the root entry to `lambder/testing`; `LambderCaller.apiRaw()` is removed (use `apiOutcome()`, whose failure outcomes carry the envelope on `response`); the `multiValueHeaders` alias on `res.raw()` is removed (use `headers`); `LambderDdbIdempotency.complete()` answers `"stored" | "too-large" | "lost"`; idempotency keys must be 16-200 chars.
+
+v3 (public file serving, `addAction()`, gzip + ETag, thrown responses, `LambderTemplatingEngine`, `html`/`xml` tags, payload v2 support, `LambderDdbCache`, `createLambderI18n`, `LambderApiError`/`refuse()`, `apiOutcome()`, the declarative policy foundations) is documented in the git history.
 
 ## Features
 
@@ -35,6 +45,20 @@ npm install lambder zod
 yarn add lambder zod
 ```
 
+## Package Entry Points
+
+The package ships three entry points; pick by where the code runs:
+
+| Entry | Runs in | Carries |
+|-------|---------|---------|
+| `lambder` | Server (Lambda) | The full framework: pipeline, sessions, DDB stores, policies, plus everything from `lambder/client` |
+| `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiError`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
+| `lambder/testing` | Dev and test tooling | `LambderMSW`, the MSW adapter that serves your typed contract from mock handlers |
+
+Frontends and shared isomorphic packages should import from `lambder/client` only; the entry's module graph contains no AWS SDK, Node built-ins, or server pipeline, so the browser boundary is structural rather than left to tree-shaking.
+
+Source layout mirrors this: `src/core/` (request pipeline), `src/policies/` (declarative rate limits, guards, idempotency), `src/session/`, `src/stores/` (DynamoDB primitives), `src/client/`, and `src/shared/` (isomorphic modules both entries re-export).
+
 ## Backend Usage
 
 ### Basic Setup
@@ -275,6 +299,10 @@ lambder
 
 See [docs/DYNAMODB_SETUP.md](docs/DYNAMODB_SETUP.md) for detailed setup instructions.
 
+#### How the secrets are stored
+
+The session cookie is `pkHash:secret`: `pkHash = sha256(sessionKey + sessionSalt)` and `secret` is 256 random bits. At rest the record stores only HASHES of the bearer secrets: the range key is `sha256(secret)` (so the lookup itself proves possession of the raw secret) and the CSRF token is stored as `csrfTokenHash`. The raw values exist only in the client's cookies and, transiently, on the `LambderCreatedSession` result the manager returns at creation; a read of the session table (backup leak, over-broad IAM, insider) therefore yields no usable cookies. Fast sha256 is the correct construction here rather than a password KDF: the secrets are 256-bit random, so there is nothing to brute-force, while `sessionSalt` peppers the identity-to-partition-key mapping so partition keys and cookie prefixes cannot be derived from (or linked to) known user ids.
+
 #### Keeping session data fresh (`dataRefresh`)
 
 Session data often caches values derived from external state: roles, permissions, feature flags. Opt in to `dataRefresh` to give that data a shelf life. Every session read checks it, and once `ttlSeconds` have passed your `refresh` callback rebuilds the data, which is persisted onto the same session record: same tokens, same cookies, the session itself is untouched. Changes to the source of truth then reach every live session within `ttlSeconds`, with no mass session invalidation.
@@ -300,6 +328,7 @@ Semantics:
 - The callback must be a pure derivation of external state: concurrent reads may run it in parallel, last write wins.
 - Returning `null` deletes the session; the request is answered as session-expired.
 - Thrown errors fail the request as a `LambderSessionDataRefreshError` and leave the session untouched (they are never mistaken for a logout). Catch inside and return `session.data` to explicitly serve stale instead.
+- Similarly, a DynamoDB failure while READING a session fails the request as a `LambderSessionReadError` instead of reading as "no session": answering session-expired there would make LambderCaller clear the client's cookies, turning an infra blip into a forced logout.
 - The renewal write and the sliding-expiration write share a single DynamoDB put when both are due.
 - Records created before `dataRefresh` was enabled renew on their first read.
 - `updateSessionData()` marks data fresh (it was just written deliberately); `regenerateSession()` carries the old freshness stamp over.
@@ -478,11 +507,15 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
             writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
             codePerEmail: {
                 perMin: 3,
-                // The key declares the payload slice it needs: validated before
-                // it runs, handed to the handler typed, and merged into the
-                // contract input of every API referencing this policy.
+                // scope "policy": ONE combined budget across every API that
+                // references this policy (send + register + reset share the
+                // 3/min). Default scope "api" gives each API its own counter.
+                scope: "policy",
+                // apiInput key: derives from the API's OWN payload. Validated
+                // before it runs, typed in the handler, and the policy is only
+                // referable from APIs whose input schema carries `email`.
                 per: lambderRateLimitKey({
-                    input: z.object({ email: z.string() }),
+                    apiInput: z.object({ email: z.string() }),
                     handler: (_ctx, { email }) => email.trim().toLowerCase(),
                 }),
                 errorMessage: { type: "warning", content: "Too many attempts for this address." },
@@ -496,41 +529,75 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
         defaultTtlSeconds: 24 * 3600,
         failOpen: true,   // DynamoDB down => execute without dedupe instead of failing
     })
-    // 3. Named guards: { input?, handler } definitions run before input
-    //    validation and refuse by throwing. A guard's `input` slice is
-    //    validated against the raw payload, handed to the handler typed, and
-    //    merged into the contract input of every API declaring the guard, so
-    //    forgetting to send captchaToken is a compile error at the call site.
+    // 3. Named guards. Input modes: apiInput checks a slice of the API's own
+    //    payload (the schema keeps the field; the guard is declarable only
+    //    where the payload type passes both); guardInput is the guard's OWN
+    //    value, sent separately by the caller via options.guardInputs and
+    //    made mandatory by the contract, so forgetting it is a compile error
+    //    at the call site; or neither. Both are validated pre-run and typed
+    //    in the handler. On top of that a guard may require a session
+    //    (session: true, declarable only on addSessionApi), take a per-API
+    //    PARAM (annotate a 4th handler argument), and RETURN a value that
+    //    lands typed on the API handler's ctx.guardData[name].
     .defineApiGuards({
         captcha: lambderGuard({
-            input: z.object({ captchaToken: z.string() }),
+            guardInput: z.object({ captchaToken: z.string() }),
             handler: async (ctx, { captchaToken }) => {
                 if (!await verifyCaptcha(captchaToken, ctx.ip)) refuse("Verification failed, please retry.");
             },
         }),
+        deviceAuth: lambderGuard({
+            apiInput: z.object({ deviceToken: z.string() }),
+            // Returns a value: the API handler reads ctx.guardData.deviceAuth.
+            handler: async (_ctx, { deviceToken }) => await resolveDeviceOrRefuse(deviceToken),
+        }),
+        orgPermission: lambderGuard({
+            session: true,
+            // Parameterized: APIs declare guards: { orgPermission: "SOME.PERMISSION" }.
+            handler: (ctx, _payload, _res, permission: PermissionString) =>
+                requirePermissionOrRefuse(ctx.session, permission),   // return value → ctx.guardData.orgPermission
+        }),
     });
 
 lambder.addApi("public.resetPassword", {
-    // captchaToken is NOT declared here: the guard contributes it to the
-    // contract, the guard validates and consumes it, and the handler never
-    // sees it.
+    // captchaToken is NOT declared here: it travels in the separate
+    // guardInputs channel, so the guard validates and consumes it and the
+    // handler never sees it. `email` IS declared: the codePerEmail key runs
+    // in apiInput mode against the API's own payload.
     input: z.object({ email: z.string().email() }),
     output: z.object({ ok: z.boolean() }),
     rateLimit: ["authPerIp", "codePerEmail"],   // stacked: checked in order, first exceeded refuses (429 envelope)
-    guards: "captcha",
+    guards: "captcha",                          // one name, a list of names, or a { name: param } map
 }, handler);
 
 lambder.addSessionApi("secure.order.create", {
     input: OrderSchema,
     output: OrderResultSchema,
     rateLimit: "writePerUser",
+    guards: { orgPermission: "ORDERS.CREATE" }, // param typed per guard; entries run in insertion order
     idempotency: true,                          // or { ttlSeconds: 3600 }; type error until enableApiIdempotency()
-}, handler);
+}, async (ctx, res) => {
+    const { organizationId } = ctx.guardData.orgPermission;  // typed guard output
+    // ...
+});
+```
+
+Guard results are typed end to end: the handler's `ctx.guardData` carries exactly the declared guards that return a value, a session guard on a public API is a compile error (and a startup assert), an apiInput guard is declarable only where the API's schema carries its fields, and a parameterized guard's param is typechecked in the declaration.
+
+For api modules split across files, annotate their `lambder` parameter with the `LambderApp` alias instead of hand-writing the instance generics:
+
+```typescript
+export type AppLambder = LambderApp<SessionData, {
+    policies: typeof apiRateLimitPolicies;   // what enableApiRateLimits({ policies }) receives
+    guards: typeof apiGuards;                // what defineApiGuards(...) receives
+    idempotency: true;                       // enableApiIdempotency(...) is called
+}>;
+export const orderApi = (lambder: AppLambder) => lambder.addSessionApi(...);
 ```
 
-Request flow per API: session (session APIs) → rate limits → guards → zod validation → idempotency claim → handler → idempotency store. Refusals ride the envelope via `LambderApiError` (429 rate limited, 409 duplicate in flight), so the caller's `errorMessageHandler` surfaces them with zero client code.
+Request flow per API: session (session APIs) → idempotency replay lookup → rate limits → guards → zod validation → idempotency claim → handler → idempotency store. The replay lookup runs first on purpose: a completed idempotent request answers its stored response without burning rate-limit quota or re-running guards (the original already passed them, and no handler executes either way). Refusals ride the envelope via `LambderApiError` (429 rate limited, 409 duplicate in flight), so the caller's `errorMessageHandler` surfaces them with zero client code.
 
-**Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation and reuse it on retries. The scope is identity (session key, or IP for public APIs) + API name + key: concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL, and a crashed original releases its claim so a retry actually retries. A response delivered by throwing (`res.die.*`, `throw res.api(...)`) counts as a completion and is stored like a returned one; thrown `LambderApiError` refusals release the claim instead. Responses with status ≥ 500 are never stored. Claims are owner-checked, so an original that stalls past the pending window can no longer overwrite or delete the claim a retry has since taken. Requests without a key execute normally.
+**Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation with `LambderCaller.createIdempotencyKey()` and reuse it on retries. Keys must be 16-200 characters and UNGUESSABLE random (shorter keys refuse with 400): on session APIs the scope is session + API name + key, and on public APIs it is the key itself + API name, deliberately NOT the client IP, because the retry idempotency exists for (a timeout followed by a network switch) frequently arrives from a new IP. Concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL (response headers included, so headers set via `res.setHeader`/`res.addHeader` replay too), and a crashed original releases its claim so a retry actually retries. The replay rule for failures: RESPONSES are stored and replayed, refusals returned as envelopes (`res.api(null, { errorMessage })`) and thrown responses (`res.die.*`) included; EXCEPTIONS are not, so a thrown `LambderApiError`/`refuse()` releases the claim and a retry re-executes and decides afresh. Stored bodies of 1KB or more are Brotli-compressed (the same scheme as LambderDdbCache; `compressionQuality` on the store, default 5): JSON envelopes typically shrink 5-10x, which cuts DynamoDB write cost, and the ~350KB item budget applies to the COMPRESSED bytes, so even large responses usually stay replayable. Responses with status ≥ 500, bodies over the budget even compressed, and responses that set cookies are never stored (replaying one request's Set-Cookie, e.g. session tokens, into another would be wrong; such APIs still get in-flight 409 dedupe, just not replays). Claims are owner-checked, so an original that stalls past the pending window can no longer overwrite or delete the claim a retry has since taken. Requests without a key execute normally.
 
 Also enforced at registration: **duplicate API names throw** (dispatch is first-match, so a second registration of the same name would be silently dead code).
 
@@ -581,12 +648,12 @@ cI18n.forLanguage("tr")("compute"); // explicit (per-request backend use)
 
 ## Frontend Usage with LambderCaller
 
-LambderCaller is a frontend companion library for Lambder (only 2kb compressed) designed to simplify making type-safe API requests to your Lambder backend.
+LambderCaller is a frontend companion library for Lambder (only 2kb compressed) designed to simplify making type-safe API requests to your Lambder backend. Import it from the `lambder/client` entry: everything reachable from there is browser-safe by construction (no AWS SDK, no Node built-ins, no server pipeline), so your bundle can never pick up server code.
 
 ### Basic Setup with Type Safety
 
 ```typescript
-import { LambderCaller } from "lambder";
+import { LambderCaller } from "lambder/client";
 import type { ApiContractType } from "./backend/handler"; // Import the inferred contract type
 
 const lambderCaller = new LambderCaller<ApiContractType>({
@@ -635,8 +702,9 @@ Every configured handler still fires on the matching failure, so global UX (toas
 Also available:
 
 - **Timeouts**: pass `timeoutMs` in the constructor for a default (API Gateway caps around 29s, so ~30000 is sensible) and/or per call; timed-out calls abort the fetch and report `reason: 'timeout'`. A per-call `signal` combines with the timeout.
-- **Per-call handler overrides**: every constructor handler (`errorHandler`, `sessionExpiredHandler`, `errorMessageHandler`, ...) can be overridden in the options of a single `api`/`apiRaw`/`apiOutcome` call.
-- **Idempotency keys**: pass `idempotencyKey` per call for APIs declared idempotent on the server (see Declarative API Policies). Generate it once per logical operation with `LambderCaller.createIdempotencyKey()` (safe in insecure contexts where `crypto.randomUUID` is missing) and send the same key on retries; rotate after a confirmed success.
+- **Per-call handler overrides**: every constructor handler (`errorHandler`, `sessionExpiredHandler`, `errorMessageHandler`, ...) can be overridden in the options of a single `api`/`apiOutcome` call.
+- **Guard inputs**: for APIs whose guards run in guardInput mode, pass their values per call as `guardInputs: { <guardName>: value }`; the typed contract makes the options argument (and the correct value shape) mandatory for those APIs.
+- **Idempotency keys**: pass `idempotencyKey` per call for APIs declared idempotent on the server (see Declarative API Policies). Generate it once per logical operation with `LambderCaller.createIdempotencyKey()` (safe in insecure contexts where `crypto.randomUUID` is missing) and send the same key on retries; rotate after a confirmed success. `LambderCaller.createIdempotencyKeyScope()` packages that pattern for a component performing one operation repeatedly: read `scope.current` on every attempt, call `scope.rotate()` after a confirmed success. Keys must be unguessable random and 16-200 characters (they scope the replay record for logged-out clients); the server refuses shorter keys with a 400.
 
 ### Benefits
 
@@ -654,7 +722,7 @@ Also available:
 LambderMSW provides seamless integration with [MSW (Mock Service Worker)](https://mswjs.io/) for testing your APIs with full type safety.
 
 ```typescript
-import { LambderMSW } from 'lambder';
+import { LambderMSW } from 'lambder/testing';
 import { setupServer } from 'msw/node';
 import type { ApiContractType } from './backend/handler';
 

package/dist/{LambderCaller.d.ts → client/LambderCaller.d.ts}

@@ -1,6 +1,18 @@
-import { LambderApiResponse } from './LambderResponseBuilder';
-import type { ApiContractShape } from './LambderApiContract';
+import type { LambderApiResponse } from '../shared/LambderApiContract.js';
+import type { ApiContractShape } from '../shared/LambderApiContract.js';
 import type { z } from "zod";
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+type GuardInputsOf<TEntry> = TEntry extends {
+    guardInputs: infer G;
+} ? G : never;
+/**
+ * The options argument: optional normally, REQUIRED (with guardInputs) when
+ * the API's contract declares guardInput-mode guards, so forgetting to send
+ * a guard's value is a compile error at the call site.
+ */
+type CallOptionsArg<TContract, TApiName> = IsAny<TContract> extends true ? [options?: LambderCallOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: LambderCallOptions] : [options: LambderCallOptions & {
+    guardInputs: GuardInputsOf<TContract[TApiName]>;
+}] : [options?: LambderCallOptions];
 type VoidFunction = () => void | Promise<void>;
 type FetchTracker = {
     apiName: string;
@@ -24,6 +36,13 @@ type FetchEndEventHandler = (params: {
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type ValidationErrorHandler = (zodError: z.ZodError) => (void | false) | Promise<(void | false)>;
 type MessageHandler = (message: any) => void | Promise<void>;
+/** One logical operation's rotating idempotency key: see LambderCaller.createIdempotencyKeyScope(). */
+export type LambderIdempotencyKeyScope = {
+    /** The key for the operation currently in progress. */
+    readonly current: string;
+    /** Call after a confirmed success: the next operation is a new intent. Returns the new key. */
+    rotate(): string;
+};
 export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
 /**
  * Discriminated result of an API call: `ok: true` carries the payload, every
@@ -55,12 +74,20 @@ export type LambderCallOptions = {
     timeoutMs?: number;
     /** External abort signal, combined with the timeout when both are set. */
     signal?: AbortSignal;
+    /**
+     * Values for the API's guardInput-mode guards, keyed by guard name; sent
+     * beside the payload and consumed by the guards before validation. The
+     * typed contract makes this REQUIRED for APIs that declare such guards.
+     */
+    guardInputs?: Record<string, unknown>;
     /**
      * Replay-protection key for APIs declared idempotent on the server.
-     * Generate once per logical operation (e.g. crypto.randomUUID() when the
-     * form opens) and send the same key on retries: duplicates of an
-     * in-flight request refuse, and repeats of a completed one replay its
-     * stored response instead of re-executing.
+     * Generate once per logical operation with createIdempotencyKey() and
+     * send the same key on retries: duplicates of an in-flight request
+     * refuse, and repeats of a completed one replay its stored response
+     * instead of re-executing. Must be UNGUESSABLE random (it scopes the
+     * replay record for logged-out clients) and at least 16 characters; the
+     * server refuses shorter keys with a 400.
      */
     idempotencyKey?: string;
     versionExpiredHandler?: VoidFunction;
@@ -111,6 +138,21 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
         sessionCookieDomain?: string | ((hostname: string) => string | undefined | null);
     });
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
+    /**
+     * A self-rotating idempotency key for a component or form that performs
+     * the same logical operation repeatedly. `current` is the key for the
+     * operation in progress: send it with every attempt (first try, retry
+     * after a failure, double-tap) so the server collapses them. Call
+     * `rotate()` after a confirmed success so the next operation is a new
+     * intent with its own key.
+     *
+     * ```typescript
+     * const submitKey = LambderCaller.createIdempotencyKeyScope();
+     * await caller.api("order.create", payload, { idempotencyKey: submitKey.current });
+     * submitKey.rotate();
+     * ```
+     */
+    static createIdempotencyKeyScope(): LambderIdempotencyKeyScope;
     /**
      * Generate an idempotency key for one logical operation. Create it when
      * the operation begins (a form opens, a draft starts), send the same key
@@ -127,14 +169,8 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to null. Never throws.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: LambderCallOptions): Promise<LambderApiOutcome<TOutput>>;
-    /**
-     * Legacy shape: the parsed envelope on success (and on structured
-     * errorMessage refusals, which carry an envelope), null on every other
-     * failure. Prefer apiOutcome() when the call site needs to know why.
-     */
-    apiRaw<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: LambderCallOptions): Promise<LambderApiResponse<TOutput> | null | undefined>;
+    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiOutcome<TOutput>>;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: LambderCallOptions): Promise<TOutput | null | undefined>;
+    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<TOutput | null | undefined>;
 }
 export {};

package/dist/{LambderCaller.js → client/LambderCaller.js}

@@ -39,6 +39,27 @@ export default class LambderCaller {
         this.sessionTokenCookieKey = sessionTokenCookieKey;
         this.sessionCsrfCookieKey = sessionCsrfCookieKey;
     }
+    /**
+     * A self-rotating idempotency key for a component or form that performs
+     * the same logical operation repeatedly. `current` is the key for the
+     * operation in progress: send it with every attempt (first try, retry
+     * after a failure, double-tap) so the server collapses them. Call
+     * `rotate()` after a confirmed success so the next operation is a new
+     * intent with its own key.
+     *
+     * ```typescript
+     * const submitKey = LambderCaller.createIdempotencyKeyScope();
+     * await caller.api("order.create", payload, { idempotencyKey: submitKey.current });
+     * submitKey.rotate();
+     * ```
+     */
+    static createIdempotencyKeyScope() {
+        let key = LambderCaller.createIdempotencyKey();
+        return {
+            get current() { return key; },
+            rotate() { key = LambderCaller.createIdempotencyKey(); return key; },
+        };
+    }
     /**
      * Generate an idempotency key for one logical operation. Create it when
      * the operation begins (a form opens, a draft starts), send the same key
@@ -149,6 +170,7 @@ export default class LambderCaller {
                     headers: { 'Content-Type': 'application/json', ...(headers || {}) },
                     body: JSON.stringify({
                         apiName, version, token, siteHost, payload,
+                        ...(options?.guardInputs !== undefined ? { guardInputs: options.guardInputs } : {}),
                         ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
                     }),
                     ...(signal ? { signal } : {}),
@@ -280,25 +302,15 @@ export default class LambderCaller {
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to null. Never throws.
      */
-    async apiOutcome(apiName, payload, options) {
-        return await this.dispatch(apiName, payload, options);
-    }
-    ;
-    /**
-     * Legacy shape: the parsed envelope on success (and on structured
-     * errorMessage refusals, which carry an envelope), null on every other
-     * failure. Prefer apiOutcome() when the call site needs to know why.
-     */
-    async apiRaw(apiName, payload, options) {
-        const outcome = await this.dispatch(apiName, payload, options);
-        if (outcome.ok)
-            return outcome.response;
-        return outcome.reason === 'errorMessage' ? outcome.response : null;
+    async apiOutcome(apiName, payload, ...rest) {
+        return await this.dispatch(apiName, payload, rest[0]);
     }
     ;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    async api(apiName, payload, options) {
-        const result = await this.apiRaw(apiName, payload, options);
-        return result?.payload;
+    async api(apiName, payload, ...rest) {
+        const outcome = await this.dispatch(apiName, payload, rest[0]);
+        if (outcome.ok)
+            return outcome.response?.payload;
+        return outcome.reason === 'errorMessage' ? outcome.response?.payload : undefined;
     }
 }

package/dist/{LambderMSW.d.ts → client/LambderMSW.d.ts}

@@ -1,4 +1,4 @@
-import type { ApiContractShape } from './LambderApiContract';
+import type { ApiContractShape } from '../shared/LambderApiContract.js';
 type RequestHandler = any;
 /** The parts of the msw module LambderMSW uses: `import { http, HttpResponse } from "msw"`. */
 export type LambderMswModule = {

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Browser entry point (`import ... from "lambder/client"`).
+ *
+ * Everything reachable from here is browser-safe: no AWS SDK, no Node
+ * built-ins, no server pipeline. Frontends and isomorphic shared packages
+ * import from this entry so their bundles can never pick up server code;
+ * the root entry (`"lambder"`) is the server surface.
+ */
+export { default as LambderCaller } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope, } from "./client/LambderCaller.js";
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./shared/LambderApiError.js";
+export type { ApiContractShape, LambderApiResponse, LambderApiResponseConfig } from "./shared/LambderApiContract.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
+export { createLambderI18n } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";

package/dist/client.js

@@ -0,0 +1,17 @@
+/**
+ * Browser entry point (`import ... from "lambder/client"`).
+ *
+ * Everything reachable from here is browser-safe: no AWS SDK, no Node
+ * built-ins, no server pipeline. Frontends and isomorphic shared packages
+ * import from this entry so their bundles can never pick up server code;
+ * the root entry (`"lambder"`) is the server surface.
+ */
+// The typed API caller.
+export { default as LambderCaller } from "./client/LambderCaller.js";
+// Typed API refusals (isomorphic: shared code may throw them from anywhere;
+// in the browser they are plain Errors).
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+// Type-safe templating (tagged templates with auto-escaping)
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
+// Typed translations (standalone, isomorphic)
+export { createLambderI18n } from "./shared/LambderI18n.js";

package/dist/{Lambder.d.ts → core/Lambder.d.ts}

@@ -5,11 +5,13 @@ import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, type LambderHttpResponse } from "./LambderResponse.js";
 import { type ConditionFunction, type LambderRouteMatcher, type PathParamsOf } from "./LambderRouting.js";
 import { type LambderCorsConfig } from "./LambderCors.js";
-import { type LambderSessionDataRefreshConfig } from "./LambderSessionManager.js";
-import LambderSessionController, { type LambderSessionCookieOptions } from "./LambderSessionController.js";
+import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
+import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderApiIdempotencyConfig, type LambderApiGuard, type LambderGuardPayloadMap, type LambderGuardsRequirement, type LambderPoliciesRequirement, type LambderMergedInput, type LambderPublicRateLimitNames } from "./LambderApiPolicies.js";
-import type { MergeContract } from "./LambderApiContract.js";
+import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../policies/LambderApiGuards.js";
+import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames } from "../policies/LambderApiRateLimits.js";
+import type { LambderApiIdempotencyConfig } from "../policies/LambderApiIdempotency.js";
+import type { MergeContract } from "../shared/LambderApiContract.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
 export type { PathParamsOf, RouteCondition, ConditionFunction, LambderRouteMatcher } from "./LambderRouting.js";
 export type { LambderCorsConfig } from "./LambderCors.js";
@@ -201,16 +203,17 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     enableApiIdempotency(config: LambderApiIdempotencyConfig): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards, true>;
     /**
      * Define named guards that APIs reference (typed) via the `guards`
-     * option. Each guard is a { input?, handler } definition (build with
-     * lambderGuard()): the input slice is validated against the raw payload
-     * before the handler runs, the handler receives it typed, and the
-     * requirement merges into the contract input of every API declaring the
-     * guard. Guards run before input validation, in the order the API
-     * declares them; a handler refuses by throwing (typically refuse()).
-     * Callable multiple times so domain modules can contribute their own;
-     * names must not collide.
+     * option. Each guard is built with lambderGuard(): its input mode
+     * (apiInput slice of the API's own payload, a separate client-sent
+     * guardInput, or none), an optional `session: true` requirement, an
+     * optional parameter APIs pass in their declaration (`guards: { name:
+     * param }`), and an optional return value that lands typed on the
+     * handler's ctx.guardData[name]. Guards run before input validation, in
+     * the order the API declares them; a handler refuses by throwing
+     * (typically refuse()). Callable multiple times so domain modules can
+     * contribute their own; names must not collide.
      */
-    defineApiGuards<TGuards extends Record<string, LambderApiGuard<any>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardPayloadMap<TGuards>, _TIdempotencyEnabled>;
+    defineApiGuards<TGuards extends Record<string, LambderApiGuard<any, any, any>>>(guards: TGuards): Lambder<TSessionData, _TContract, _TRateLimitPolicies, _TGuards & LambderGuardMetaMap<TGuards>, _TIdempotencyEnabled>;
     private getOrCreatePolicyEngine;
     /** Registration-time checks shared by addApi/addSessionApi. */
     private assertApiRegistration;
@@ -219,32 +222,32 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addSessionRoute<TPath extends Path>(condition: TPath, actionFn: (ctx: LambderSessionRenderContext<any, TSessionData, PathParamsOf<TPath>>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
     addSessionRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: SessionActionFunction<TSessionData>): this;
     use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
-    addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderPublicRateLimitNames<_TRateLimitPolicies> | readonly LambderPublicRateLimitNames<_TRateLimitPolicies>[] = never, const TGuardsOpt extends Extract<keyof _TGuards, string> | readonly Extract<keyof _TGuards, string>[] = never>(name: TName, schema: {
+    addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false> | readonly LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false>[] = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
         /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
         rateLimit?: TRateOpt;
-        /** Named guards, run in declared order before input validation; their input requirements merge into this API's contract input. */
+        /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
         guards?: TGuardsOpt;
         /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    }, handler: (ctx: LambderRenderContext<z.infer<TInput>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, LambderMergedInput<z.infer<TInput>, LambderPoliciesRequirement<_TRateLimitPolicies, TRateOpt>, LambderGuardsRequirement<_TGuards, TGuardsOpt>>, z.infer<TOutput>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
-    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends Extract<keyof _TRateLimitPolicies, string> | readonly Extract<keyof _TRateLimitPolicies, string>[] = never, const TGuardsOpt extends Extract<keyof _TGuards, string> | readonly Extract<keyof _TGuards, string>[] = never>(name: TName, schema: {
+    }, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, true> | readonly LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, true>[] = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
         /** Named rate limits, checked in declared order before guards and validation; the first exceeded one refuses (429 envelope). */
         rateLimit?: TRateOpt;
-        /** Named guards, run in declared order before input validation; their input requirements merge into this API's contract input. */
+        /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
         guards?: TGuardsOpt;
         /** Replay-protect this API per client idempotencyKey. Requires enableApiIdempotency() first. */
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    }, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, LambderMergedInput<z.infer<TInput>, LambderPoliciesRequirement<_TRateLimitPolicies, TRateOpt>, LambderGuardsRequirement<_TGuards, TGuardsOpt>>, z.infer<TOutput>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
+    }, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),
@@ -289,3 +292,26 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private resolveRequest;
     render(event: LambderHttpEvent, lambdaContext: Context): Promise<LambderHttpResponse>;
 }
+/**
+ * The app's configured Lambder instance type, for annotating the parameter
+ * of api modules used via lambder.use(...). Name the pieces you wired in
+ * index.ts and the guard metadata mapping happens for you:
+ *
+ * ```typescript
+ * export type AppLambder = LambderApp<SessionData, {
+ *     policies: typeof apiRateLimitPolicies;   // enableApiRateLimits({ policies })
+ *     guards: typeof apiGuards;                // defineApiGuards(apiGuards)
+ *     idempotency: true;                       // enableApiIdempotency(...) was called
+ * }>;
+ * ```
+ *
+ * Every field is optional; omit what the app does not wire. The declaration
+ * is still an assertion about index.ts (registration-time asserts backstop a
+ * mismatch at cold start), but derive the fields from the same exported
+ * consts the enable calls receive and the types cannot drift.
+ */
+export type LambderApp<TSessionData, TConfig extends {
+    policies?: Record<string, LambderApiRateLimitPolicyConfig>;
+    guards?: Record<string, LambderApiGuard<any, any, any>>;
+    idempotency?: boolean;
+} = {}> = Lambder<TSessionData, {}, TConfig["policies"] extends Record<string, LambderApiRateLimitPolicyConfig> ? TConfig["policies"] : {}, TConfig["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TConfig["guards"]> : {}, TConfig["idempotency"] extends true ? true : false>;