lambder 3.7.1 → 4.0.1

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,14 +193,15 @@ export default class Lambder {
     }
     /**
      * 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(guards) {
         this.getOrCreatePolicyEngine().addGuards(guards);
@@ -256,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);
@@ -281,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

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

@@ -1,7 +1,9 @@
 import type { LambderRenderContext } from "./LambderContext.js";
 import { LambderResponse, type HttpStatusCode, type LambderHeadersInput } from "./LambderResponse.js";
-import { LambderSafeHtml } from "./LambderHtml.js";
+import { LambderSafeHtml } from "../shared/LambderHtml.js";
 import { type LambderTemplateData } from "./LambderTemplatingEngine.js";
+import type { LambderApiResponseConfig } from "../shared/LambderApiContract.js";
+export type { LambderApiResponse, LambderApiResponseConfig } from "../shared/LambderApiContract.js";
 export type LambderResponseOptions = {
     statusCode?: HttpStatusCode;
     headers?: LambderHeadersInput;
@@ -12,23 +14,9 @@ export type LambderResponseOptions = {
     /** "auto" (default): ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
 };
-export type LambderApiResponseConfig = {
-    versionExpired?: boolean;
-    sessionExpired?: boolean;
-    notAuthorized?: boolean;
-    message?: any;
-    errorMessage?: any;
-    logList?: any[];
-};
-export type LambderApiResponse<T> = LambderApiResponseConfig & {
-    apiVersion?: string | null;
-    payload?: T | null;
-};
 export type LambderRawResponseInit = {
     statusCode: HttpStatusCode;
     headers?: LambderHeadersInput;
-    /** Legacy alias for headers (API Gateway naming). */
-    multiValueHeaders?: Record<string, string[]>;
     body: string | Buffer | null;
     /** True when body is already a base64-encoded string. */
     isBase64Encoded?: boolean;

package/dist/{LambderResponseBuilder.js → core/LambderResponseBuilder.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";
 import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
 // Compiled templates survive across requests (builder instances are per-request).
@@ -72,7 +72,7 @@ export default class LambderResponseBuilder {
     raw(init) {
         return new LambderResponse({
             statusCode: init.statusCode,
-            headers: init.headers ?? init.multiValueHeaders,
+            headers: init.headers,
             body: init.body,
             isBodyBase64: init.isBase64Encoded ?? false,
             compress: init.compress ?? (init.isBase64Encoded ? false : "auto"),

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

@@ -1,4 +1,4 @@
-import { type LambderHtmlValue } from "./LambderHtml.js";
+import { type LambderHtmlValue } from "../shared/LambderHtml.js";
 /**
  * LambderTemplatingEngine: a comment-only HTML template engine.
  *

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

@@ -1,5 +1,5 @@
-import { getFS } from "./node-polyfills.js";
-import { renderHtmlValue } from "./LambderHtml.js";
+import { getFS } from "../shared/node-polyfills.js";
+import { renderHtmlValue } from "../shared/LambderHtml.js";
 const TOKEN_PATTERN = /<!--\s*(?:(slot:([\w-]+)\s*\/)|(slot:([\w-]+))|(\/slot:([\w-]+))|(if:(!?)([\w-]+))|(else)|(\/if:(!?)([\w-]+)))\s*-->/g;
 /**
  * Fail loudly on slot positions where HTML escaping cannot protect against

package/dist/index.d.ts

@@ -1,36 +1,37 @@
-import Lambder from './Lambder.js';
+import Lambder from './core/Lambder.js';
 export default Lambder;
-export { default as LambderCaller } from "./LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions } from "./LambderCaller.js";
-export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
-export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./LambderApiError.js";
-export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
-export { default as LambderResolver } from "./LambderResolver.js";
-export { default as LambderSessionManager } from "./LambderSessionManager.js";
-export { default as LambderSessionController } from "./LambderSessionController.js";
-export { default as LambderMSW } from "./LambderMSW.js";
-export type { LambderMswModule } from "./LambderMSW.js";
-export { LambderResponse, finalizeResponse, acceptsEncoding, type HttpStatusCode, type LambderHttpResponse, type LambderHttpEventFormat, type LambderHeadersInput, type LambderFinalizeOptions, } from "./LambderResponse.js";
-export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./LambderHtml.js";
-export { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
-export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./LambderTemplatingEngine.js";
-export type { LambderResponseOptions, LambderApiResponse, LambderApiResponseConfig, LambderRawResponseInit, } from "./LambderResponseBuilder.js";
-export type { LambderRouteMatcher, LambderCorsConfig, LambderConstructorOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./Lambder.js";
-export { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-export type { LambderPublicFilesOptions } from "./LambderPublicFiles.js";
-export type { LambderSessionCookieOptions } from "./LambderSessionController.js";
-export type { LambderSessionContext, LambderSessionDataRefreshConfig } from "./LambderSessionManager.js";
-export { LambderSessionDataRefreshError } from "./LambderSessionManager.js";
-export { LambderDdbCache } from "./LambderDdbCache.js";
-export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./LambderDdbCache.js";
-export { LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
-export type { LambderDdbRateLimiterOptions, LambderRateLimitPolicy, LambderRateLimitExceededMap, LambderRateLimitResult, } from "./LambderDdbRateLimiter.js";
-export { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
-export type { LambderDdbIdempotencyOptions, LambderIdempotencyBeginResult, } from "./LambderDdbIdempotency.js";
-export { lambderGuard, lambderRateLimitKey } from "./LambderApiPolicies.js";
-export type { LambderApiGuard, LambderRateLimitKeyFn, LambderRateLimitPer, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderApiIdempotencyConfig, LambderPublicRateLimitNames, LambderGuardPayload, LambderGuardPayloadMap, LambderPolicyPayload, LambderGuardsRequirement, LambderPoliciesRequirement, LambderMergedInput, } from "./LambderApiPolicies.js";
-export { createLambderI18n } from "./LambderI18n.js";
-export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./LambderI18n.js";
-export { type ApiContractShape, } from "./LambderApiContract.js";
-export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./LambderContext.js";
-export { createContext, isV2HttpEvent } from "./LambderContext.js";
+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 { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
+export { default as LambderResolver } from "./core/LambderResolver.js";
+export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
+export { default as LambderSessionController } from "./session/LambderSessionController.js";
+export { LambderResponse, finalizeResponse, acceptsEncoding, type HttpStatusCode, type LambderHttpResponse, type LambderHttpEventFormat, type LambderHeadersInput, type LambderFinalizeOptions, } from "./core/LambderResponse.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
+export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
+export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
+export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
+export type { LambderRouteMatcher, LambderCorsConfig, LambderConstructorOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, LambderApp, } from "./core/Lambder.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
+export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
+export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
+export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
+export { LambderDdbCache } from "./stores/LambderDdbCache.js";
+export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
+export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
+export type { LambderDdbRateLimiterOptions, LambderRateLimitPolicy, LambderRateLimitExceededMap, LambderRateLimitResult, } from "./stores/LambderDdbRateLimiter.js";
+export { LambderDdbIdempotency } from "./stores/LambderDdbIdempotency.js";
+export type { LambderDdbIdempotencyOptions, LambderIdempotencyBeginResult, LambderIdempotencyDoneRecord, } from "./stores/LambderDdbIdempotency.js";
+export { lambderGuard } from "./policies/LambderApiGuards.js";
+export type { LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardsOptionValue, LambderGuardDataOf, LambderGuardInputsOf, } from "./policies/LambderApiGuards.js";
+export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
+export type { LambderRateLimitKeyFn, LambderRateLimitPer, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, } from "./policies/LambderApiRateLimits.js";
+export type { LambderApiIdempotencyConfig } from "./policies/LambderApiIdempotency.js";
+export { createLambderI18n } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
+export { type ApiContractShape, type LambderApiResponse, type LambderApiResponseConfig, } from "./shared/LambderApiContract.js";
+export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./core/LambderContext.js";
+export { createContext, isV2HttpEvent } from "./core/LambderContext.js";

package/dist/index.js

@@ -1,30 +1,31 @@
-import Lambder from './Lambder.js';
+import Lambder from './core/Lambder.js';
 export default Lambder;
-export { default as LambderCaller } from "./LambderCaller.js";
+export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiError, isLambderApiError, refuse } from "./LambderApiError.js";
-export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
-export { default as LambderResolver } from "./LambderResolver.js";
-export { default as LambderSessionManager } from "./LambderSessionManager.js";
-export { default as LambderSessionController } from "./LambderSessionController.js";
-export { default as LambderMSW } from "./LambderMSW.js";
+export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
+export { default as LambderResolver } from "./core/LambderResolver.js";
+export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
+export { default as LambderSessionController } from "./session/LambderSessionController.js";
 // Response model
-export { LambderResponse, finalizeResponse, acceptsEncoding, } from "./LambderResponse.js";
+export { LambderResponse, finalizeResponse, acceptsEncoding, } from "./core/LambderResponse.js";
 // Type-safe templating (tagged templates with auto-escaping)
-export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./LambderHtml.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Comment-based HTML templating engine (build-pipeline-safe slots and conditionals, standalone)
-export { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 // Public file serving
-export { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-export { LambderSessionDataRefreshError } from "./LambderSessionManager.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 // DynamoDB-backed compressed cache (standalone, server-only)
-export { LambderDdbCache } from "./LambderDdbCache.js";
+export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 // DynamoDB-backed fixed-window rate limiter (standalone, server-only)
-export { LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
+export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
 // DynamoDB-backed idempotency records (standalone, server-only)
-export { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
-// Declarative per-API policies (rate limits, guards, idempotency)
-export { lambderGuard, lambderRateLimitKey } from "./LambderApiPolicies.js";
+export { LambderDdbIdempotency } from "./stores/LambderDdbIdempotency.js";
+// Declarative per-API policies: guards
+export { lambderGuard } from "./policies/LambderApiGuards.js";
+// Declarative per-API policies: rate limits
+export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
 // Typed translations (standalone, isomorphic)
-export { createLambderI18n } from "./LambderI18n.js";
-export { createContext, isV2HttpEvent } from "./LambderContext.js";
+export { createLambderI18n } from "./shared/LambderI18n.js";
+export { createContext, isV2HttpEvent } from "./core/LambderContext.js";

package/dist/policies/LambderApiGuards.d.ts

@@ -0,0 +1,221 @@
+import type { z } from "zod";
+import type { LambderRenderContext, LambderSessionRenderContext } from "../core/LambderContext.js";
+import type LambderResolver from "../core/LambderResolver.js";
+/**
+ * A named guard, run before the API's own input validation. Three input
+ * modes:
+ *
+ * - `apiInput`: the guard checks fields of the API's OWN payload. The slice
+ *   is validated against the raw payload before `handler` runs and handed to
+ *   it typed. The API's input schema stays the owner of those fields:
+ *   declaring the guard on an API whose schema does not carry them is a
+ *   compile error.
+ * - `guardInput`: the guard has its own value the client sends SEPARATELY,
+ *   outside the API payload, via the caller's options.guardInputs[name].
+ *   The requirement lands on the API's contract (`guardInputs`), so the
+ *   typed caller refuses to compile a call that does not send it. The API
+ *   payload and handler never see the value.
+ * - neither: the guard reads only the context.
+ *
+ * Orthogonally, a guard may also:
+ *
+ * - declare `session: true`: the guard needs ctx.session, so it is only
+ *   declarable on addSessionApi (compile error and startup assert on public
+ *   APIs) and its handler receives the session-typed context.
+ * - take a PARAMETER: annotate a 4th handler argument
+ *   (`(ctx, payload, res, param: YourType) => ...`) and APIs pass the value
+ *   in their declaration: `guards: { yourGuard: paramValue }`. The value is
+ *   trusted registration-time code (never client data), typed per guard.
+ * - RETURN a value: whatever the handler returns (awaited) is attached to
+ *   the API handler's context as `ctx.guardData[guardName]`, fully typed.
+ *   Guards that return nothing never appear in guardData.
+ *
+ * A validation failure answers the standard 422 shape, and the handler
+ * refuses by throwing (typically refuse()/LambderApiError). Build with
+ * lambderGuard() so the handler's payload/ctx/param types line up.
+ */
+export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny, TParam = any, TOutput = any> = {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session?: boolean;
+    handler: (ctx: any, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+} | {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session?: boolean;
+    handler: (ctx: any, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+} | {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session?: boolean;
+    handler: (ctx: any, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+type GuardCtx = LambderRenderContext;
+type GuardSessionCtx = LambderSessionRenderContext<any, any>;
+/**
+ * Builder that ties the handler's payload, context, param, and output types
+ * together inside one literal. Returns the exact shape so type extraction
+ * (mode, session, param, output) works downstream. The param type is
+ * inferred from the handler's 4th argument annotation; the output from its
+ * return type.
+ */
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    apiInput: TInput;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    apiInput: TInput;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput: TInput;
+    guardInput?: undefined;
+    session?: undefined;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    guardInput: TInput;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TInput extends z.ZodTypeAny, TParam = undefined, TOutput = void>(guard: {
+    guardInput: TInput;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    guardInput: TInput;
+    apiInput?: undefined;
+    session?: undefined;
+    handler: (ctx: GuardCtx, payload: z.output<TInput>, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TParam = undefined, TOutput = void>(guard: {
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session: true;
+    handler: (ctx: GuardSessionCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+export declare function lambderGuard<TParam = undefined, TOutput = void>(guard: {
+    handler: (ctx: GuardCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+}): {
+    apiInput?: undefined;
+    guardInput?: undefined;
+    session?: undefined;
+    handler: (ctx: GuardCtx, payload: undefined, res: LambderResolver, param: TParam) => TOutput | Promise<TOutput>;
+};
+/** The param type a guard's handler declares as its 4th argument; undefined for paramless guards. */
+type LambderGuardParamOf<G> = G extends {
+    handler: (...args: infer A) => any;
+} ? (A extends [any, any, any, infer P, ...any[]] ? P : undefined) : undefined;
+/** What a guard's handler returns (awaited); void for check-only guards. */
+type LambderGuardOutputOf<G> = G extends {
+    handler: (...args: any[]) => infer R;
+} ? Awaited<R> : never;
+/** Per-guard metadata carried on the Lambder instance: input mode, session requirement, param type, output type. */
+export type LambderGuardMeta<G> = (G extends {
+    apiInput: infer S extends z.ZodTypeAny;
+} ? {
+    apiInput: z.output<S>;
+} : G extends {
+    guardInput: infer S extends z.ZodTypeAny;
+} ? {
+    guardInput: z.output<S>;
+} : {}) & (G extends {
+    session: true;
+} ? {
+    session: true;
+} : {}) & {
+    param: LambderGuardParamOf<G>;
+    output: LambderGuardOutputOf<G>;
+};
+export type LambderGuardMetaMap<TGuards> = {
+    [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
+};
+/** Guard names referenced by a guards option, whichever of its three forms is used. */
+type NamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;
+type LambderGuardNameIfPayloadOk<TGuards, K extends keyof TGuards, TPayload> = TGuards[K] extends {
+    apiInput: infer R;
+} ? (TPayload extends R ? K : never) : K;
+/**
+ * Guard names an API may declare: apiInput-mode guards only when the API's
+ * payload carries their fields, session guards only on session APIs.
+ */
+export type LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession extends boolean = true> = {
+    [K in keyof TGuards]: TGuards[K] extends {
+        session: true;
+    } ? (TIncludeSession extends true ? LambderGuardNameIfPayloadOk<TGuards, K, TPayload> : never) : LambderGuardNameIfPayloadOk<TGuards, K, TPayload>;
+}[keyof TGuards] & string;
+/** The allowed guard names whose handler takes no param (usable in the string/array forms). */
+export type LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession extends boolean> = {
+    [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
+        param: undefined;
+    } ? K & string : never;
+}[LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards];
+/**
+ * The per-API `guards` option: one paramless guard name, an ordered list of
+ * paramless names, or an object map that can carry each guard's param
+ * (`true` enables a paramless guard). Map entries run in insertion order.
+ */
+export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[] | {
+    readonly [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
+        param: undefined;
+    } ? true : TGuards[K] extends {
+        param: infer P;
+    } ? P : true;
+};
+/**
+ * The typed ctx.guardData an API's handler sees: declared guards that return
+ * a value, keyed by name. Check-only (void) guards never appear.
+ */
+export type LambderGuardDataOf<TGuards, TOpt> = {
+    [K in NamesIn<TOpt> & keyof TGuards as [
+        TGuards[K] extends {
+            output: infer O;
+        } ? O : never
+    ] extends [void] ? never : K & string]: TGuards[K] extends {
+        output: infer O;
+    } ? O : never;
+};
+type GuardInputsEntries<TGuards, TOpt> = {
+    [K in Extract<NamesIn<TOpt>, keyof TGuards> as TGuards[K] extends {
+        guardInput: any;
+    } ? K : never]: TGuards[K] extends {
+        guardInput: infer V;
+    } ? V : never;
+};
+/** The guardInputs map an API's contract requires clients to send; never when no declared guard uses guardInput mode. */
+export type LambderGuardInputsOf<TGuards, TOpt> = keyof GuardInputsEntries<TGuards, TOpt> extends never ? never : GuardInputsEntries<TGuards, TOpt>;
+/** The guards option's runtime shape: a name, ordered names, or a name-to-param map. */
+export type LambderGuardsOptionValue = string | readonly string[] | Readonly<Record<string, unknown>>;
+/**
+ * Validate a preflight input slice (an apiInput slice of the raw payload, or
+ * a guardInput value from the raw guardInputs map). Runs before the API's
+ * own validation; failures answer the same 422 shape as regular input
+ * validation. Shared with the rate-limit engine's apiInput-keyed policies.
+ */
+export declare const parsePreflightSlice: (input: z.ZodTypeAny, value: unknown, resolver: LambderResolver) => unknown;
+/**
+ * Runtime side of the guards subsystem: holds the defined guards, asserts
+ * API registrations against them at startup, and executes an API's declared
+ * guards during preflight. Composed into LambderApiPolicyEngine.
+ */
+export declare class LambderApiGuardsEngine {
+    private guards;
+    addGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
+    /** Startup validation of one API registration's guards option. */
+    assertRegistration(apiName: string, mode: "public" | "session", guardsOption?: LambderGuardsOptionValue): void;
+    /** Run the API's guards in declared order. Refusals throw; outputs land on ctx.guardData. */
+    run(ctx: LambderRenderContext, resolver: LambderResolver, guardsOption?: LambderGuardsOptionValue): Promise<void>;
+}
+export {};

package/dist/policies/LambderApiGuards.js

@@ -0,0 +1,79 @@
+export function lambderGuard(guard) { return guard; }
+/** Normalize the three guards-option forms into ordered { name, param } entries. */
+const toGuardEntries = (value) => {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return [{ name: value, param: undefined }];
+    if (Array.isArray(value))
+        return value.map((name) => ({ name: String(name), param: undefined }));
+    // Object form: insertion order, params passed verbatim (paramless guards
+    // are declared with `true` and their handlers take no param argument).
+    return Object.entries(value).map(([name, param]) => ({ name, param }));
+};
+/**
+ * Validate a preflight input slice (an apiInput slice of the raw payload, or
+ * a guardInput value from the raw guardInputs map). Runs before the API's
+ * own validation; failures answer the same 422 shape as regular input
+ * validation. Shared with the rate-limit engine's apiInput-keyed policies.
+ */
+export const parsePreflightSlice = (input, value, resolver) => {
+    const parsed = input.safeParse(value);
+    if (!parsed.success) {
+        throw resolver.json({ error: "Input validation failed", zodError: parsed.error }, { statusCode: 422 });
+    }
+    return parsed.data;
+};
+/**
+ * Runtime side of the guards subsystem: holds the defined guards, asserts
+ * API registrations against them at startup, and executes an API's declared
+ * guards during preflight. Composed into LambderApiPolicyEngine.
+ */
+export class LambderApiGuardsEngine {
+    guards = {};
+    addGuards(guards) {
+        for (const [name, guardDef] of Object.entries(guards)) {
+            if (this.guards[name])
+                throw new Error(`Lambder: guard "${name}" is already defined.`);
+            if (typeof guardDef?.handler !== "function")
+                throw new Error(`Lambder: guard "${name}" has no handler function.`);
+            if (guardDef.apiInput && guardDef.guardInput)
+                throw new Error(`Lambder: guard "${name}" declares both apiInput and guardInput; pick one.`);
+            this.guards[name] = guardDef;
+        }
+    }
+    /** Startup validation of one API registration's guards option. */
+    assertRegistration(apiName, mode, guardsOption) {
+        for (const { name } of toGuardEntries(guardsOption)) {
+            const guardDef = this.guards[name];
+            if (!guardDef) {
+                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Define it via defineApiGuards() before registering the API.`);
+            }
+            if (guardDef.session && mode !== "session") {
+                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);
+            }
+        }
+    }
+    /** Run the API's guards in declared order. Refusals throw; outputs land on ctx.guardData. */
+    async run(ctx, resolver, guardsOption) {
+        for (const { name, param } of toGuardEntries(guardsOption)) {
+            const guardDef = this.guards[name];
+            if (!guardDef)
+                throw new Error(`Lambder: guard "${name}" is not configured.`);
+            const post = ctx.post;
+            let payload;
+            if (guardDef.apiInput) {
+                payload = parsePreflightSlice(guardDef.apiInput, post?.payload, resolver);
+            }
+            else if (guardDef.guardInput) {
+                payload = parsePreflightSlice(guardDef.guardInput, post?.guardInputs?.[name], resolver);
+            }
+            // A guard's return value becomes the handler's typed
+            // ctx.guardData[name]; check-only guards return undefined.
+            const output = await guardDef.handler(ctx, payload, resolver, param);
+            if (output !== undefined) {
+                ctx.guardData[name] = output;
+            }
+        }
+    }
+}