lambder 3.8.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.8 gives guards and custom rate-limit keys two typed modes: apiInput (checks a slice of the API's own payload; declarable only where the schema carries those fields) and guardInput (a separate client-sent guardInputs channel the contract makes mandatory at the call site).
+**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,6 +507,10 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
             writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
             codePerEmail: {
                 perMin: 3,
+                // 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`.
@@ -496,12 +529,16 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
         defaultTtlSeconds: 24 * 3600,
         failOpen: true,   // DynamoDB down => execute without dedupe instead of failing
     })
-    // 3. Named guards, two modes. apiInput checks a slice of the API's own
+    // 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
+    //    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. Both are validated pre-run and typed in the handler.
+    //    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({
             guardInput: z.object({ captchaToken: z.string() }),
@@ -509,6 +546,17 @@ const lambder = new Lambder<SessionData>({ apiPath: "/api" })
                 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", {
@@ -519,20 +567,37 @@ lambder.addApi("public.resetPassword", {
     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).
 
@@ -583,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>({
@@ -637,9 +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.
+- **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.
+- **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
 
@@ -657,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,5 +1,5 @@
-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 {
@@ -36,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
@@ -75,10 +82,12 @@ export type LambderCallOptions = {
     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;
@@ -129,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
@@ -146,12 +170,6 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
      * 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, ...rest: CallOptionsArg<TContract, TApiName>): 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, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiResponse<TOutput> | null | undefined>;
     /** 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, ...rest: CallOptionsArg<TContract, TApiName>): Promise<TOutput | null | undefined>;
 }

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
@@ -285,18 +306,6 @@ export default class LambderCaller {
         return await this.dispatch(apiName, payload, rest[0]);
     }
     ;
-    /**
-     * 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, ...rest) {
-        const outcome = await this.dispatch(apiName, payload, rest[0]);
-        if (outcome.ok)
-            return outcome.response;
-        return outcome.reason === 'errorMessage' ? outcome.response : null;
-    }
-    ;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
     async api(apiName, payload, ...rest) {
         const outcome = await this.dispatch(apiName, payload, rest[0]);

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 LambderGuardMetaMap, type LambderAllowedGuardNames, type LambderAllowedPolicyNames, type LambderGuardInputsOf } 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,17 +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 built with lambderGuard() in one of two modes:
-     * apiInput (checks a slice of the API's own payload; declarable only on
-     * APIs whose input schema carries those fields, so the payload type
-     * passes both the API input and the guard's apiInput) or guardInput (the
-     * client sends the guard's value separately via options.guardInputs, and
-     * the contract forces it at the call site). 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 & LambderGuardMetaMap<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;
@@ -220,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 LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false> | readonly LambderAllowedPolicyNames<_TRateLimitPolicies, z.infer<TInput>, false>[] = never, const TGuardsOpt extends LambderAllowedGuardNames<_TGuards, z.infer<TInput>> | readonly LambderAllowedGuardNames<_TGuards, z.infer<TInput>>[] = 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, 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 LambderAllowedGuardNames<_TGuards, z.infer<TInput>> | readonly LambderAllowedGuardNames<_TGuards, z.infer<TInput>>[] = 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, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _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),
@@ -290,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>;

package/dist/{Lambder.js → core/Lambder.js}

@@ -3,11 +3,11 @@ import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, finalizeResponse, DEFAULT_FINALIZE_OPTIONS, } from "./LambderResponse.js";
 import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
-import LambderSessionManager from "./LambderSessionManager.js";
-import LambderSessionController from "./LambderSessionController.js";
+import LambderSessionManager from "../session/LambderSessionManager.js";
+import LambderSessionController from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-import { isLambderApiError } from "./LambderApiError.js";
-import { LambderApiPolicyEngine, } from "./LambderApiPolicies.js";
+import { isLambderApiError } from "../shared/LambderApiError.js";
+import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 /**
  * Main Lambder class for building type-safe serverless APIs
@@ -193,15 +193,15 @@ export default class Lambder {
     }
     /**
      * Define named guards that APIs reference (typed) via the `guards`
-     * option. Each guard is built with lambderGuard() in one of two modes:
-     * apiInput (checks a slice of the API's own payload; declarable only on
-     * APIs whose input schema carries those fields, so the payload type
-     * passes both the API input and the guard's apiInput) or guardInput (the
-     * client sends the guard's value separately via options.guardInputs, and
-     * the contract forces it at the call site). 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(guards) {
         this.getOrCreatePolicyEngine().addGuards(guards);
@@ -257,6 +257,14 @@ export default class Lambder {
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: async (ctx, resolver) => {
+                // Replay fast path first: a completed idempotent request must
+                // answer its stored response without burning rate-limit quota
+                // or re-running guards (no handler executes either way).
+                if (this.apiPolicyEngine && schema.idempotency) {
+                    const replay = await this.apiPolicyEngine.findReplay(name, ctx);
+                    if (replay)
+                        return replay;
+                }
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);
@@ -282,6 +290,13 @@ export default class Lambder {
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: async (ctx, resolver) => {
                 await this.requireSession(ctx, resolver);
+                // Replay fast path (after the session fetch: the replay scope
+                // is keyed per session): see addApi.
+                if (this.apiPolicyEngine && schema.idempotency) {
+                    const replay = await this.apiPolicyEngine.findReplay(name, ctx);
+                    if (replay)
+                        return replay;
+                }
                 if (this.apiPolicyEngine)
                     await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
                 const inputResult = schema.input.safeParse(ctx.apiPayload);

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

@@ -1,10 +1,10 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, APIGatewayProxyEventHeaders, Context } from "aws-lambda";
-import type { LambderSessionContext } from "./LambderSessionManager.js";
+import type { LambderSessionContext } from "../session/LambderSessionManager.js";
 import type { LambderHttpEventFormat } from "./LambderResponse.js";
 export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxyEventV2;
-export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<string, string> = Record<string, string>> = {
+export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}> = {
     host: string;
     path: string;
     pathParams: TPathParams;
@@ -15,6 +15,12 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     session: null;
     apiName: string | null;
     apiPayload: TApiPayload;
+    /**
+     * Outputs of this API's guards, keyed by guard name. Only guards the API
+     * declares AND that return a value appear (typed via the declarative
+     * guards option); void guards never do.
+     */
+    guardData: TGuardData;
     headers: APIGatewayProxyEventHeaders;
     /** Decoded request body, exactly as received (e.g. for webhook signature verification). */
     rawBody: string;
@@ -39,7 +45,7 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
         logToApiResponseAccumulator: any[];
     };
 };
-export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>> = Omit<LambderRenderContext<TApiPayload, TPathParams>, 'session'> & {
+export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}> = Omit<LambderRenderContext<TApiPayload, TPathParams, TGuardData>, 'session'> & {
     session: LambderSessionContext<SessionData>;
 };
 export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, apiPath: string) => LambderRenderContext;

package/dist/{LambderContext.js → core/LambderContext.js}

@@ -77,6 +77,7 @@ export const createContext = (event, lambdaContext, apiPath) => {
         get, post, cookie, event,
         session: null,
         apiName, apiPayload,
+        guardData: {},
         headers, rawBody, ip, header,
         lambdaContext,
         _otherInternal: {

package/dist/{LambderPublicFiles.js → core/LambderPublicFiles.js}

@@ -1,5 +1,5 @@
 import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "./node-polyfills.js";
+import { getFS, getPath } from "../shared/node-polyfills.js";
 import { LambderResponse } from "./LambderResponse.js";
 // Content-hashed build outputs (Vite/webpack/Rollup): a [-.] separated run of
 // 8+ hash chars containing at least one digit, before the extension.

package/dist/{LambderResponse.js → core/LambderResponse.js}

@@ -1,4 +1,4 @@
-import { getZlib, getCrypto } from "./node-polyfills.js";
+import { getZlib, getCrypto } from "../shared/node-polyfills.js";
 export const normalizeHeaders = (headers) => Object.fromEntries(Object.entries(headers ?? {}).map(([k, v]) => [k, Array.isArray(v) ? [...v] : [v]]));
 /**
  * Intermediate response object returned by all response builder methods and by