lambder 4.8.1 → 5.0.0

package/README.md

@@ -0,0 +1,158 @@
+# Lambder
+
+A highly opinionated serverless web framework for TypeScript on AWS Lambda.
+Lambder handles HTTP requests, routes, type-safe APIs, sessions and the
+declarative policy layer around them (rate limits, authorization guards,
+idempotency), so an application is a set of declarations rather than a pile of
+per-handler boilerplate.
+
+```typescript
+import { initLambder, LambderLocalFileSource } from "lambder";
+import { z } from "zod";
+
+const lambder = initLambder<SessionData>().create({
+    apiPath: "/api",
+    files: new LambderLocalFileSource({ root: "./public" }),
+    session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: process.env.SESSION_SALT! },
+});
+
+lambder.addApi("getCompany", {
+    input: z.object({ slug: z.string() }),
+    output: z.object({ id: z.string(), name: z.string() }),
+}, async ({ apiPayload }, res) => res.api(await loadCompany(apiPayload.slug)));
+
+export type ApiContractType = typeof lambder.ApiContract;
+export const handler = lambder.getHandler();
+```
+
+The frontend imports that contract type and gets autocomplete, typed payloads
+and typed results with no hand-written client:
+
+```typescript
+import { LambderCaller } from "lambder/client";
+import type { ApiContractType } from "./backend/handler";
+
+const caller = new LambderCaller<ApiContractType>({ apiPath: "/api", isCorsEnabled: false });
+const company = await caller.api("getCompany", { slug: "acme" });
+```
+
+## Features
+
+- **Type-safe APIs with Zod.** Define inputs and outputs with Zod schemas; get
+  runtime validation and compile-time inference on both sides of the wire.
+- **One inferred contract.** The API contract is derived from the backend code
+  and consumed by the frontend as a type-only import.
+- **Simple route and API declaration.** Paths, regexes, predicates and
+  structured matchers, chained fluently.
+- **Sessions.** DynamoDB-backed, with secrets hashed at rest, sliding
+  expiration, data refresh and cross-subdomain cookies.
+- **Declarative policies.** Named rate-limit policies, authorization guards and
+  idempotency, referenced by name from an API declaration and checked at
+  compile time.
+- **A real response pipeline.** Automatic Brotli/gzip, ETag and 304 handling,
+  cookies, and a guard against Lambda's response size cap.
+- **Hooks and actions.** Lifecycle hooks, plus `addAction()` for the non-HTTP
+  invocations (EventBridge, SQS, custom events) the same function receives.
+- **Frontend hosting.** Serve a build from a folder, S3 or R2, with an app
+  shell rendered through a build-pipeline-safe template engine.
+- **Runs anywhere Lambda does.** API Gateway REST APIs (payload v1), HTTP APIs
+  (payload v2) and Lambda Function URLs; the payload format is detected per
+  event.
+
+## Installation
+
+```bash
+npm install lambder zod
+```
+
+`zod` and the AWS SDK clients are optional peer dependencies, so installing
+lambder never drags them into your tree. Add whatever the code you actually
+import needs:
+
+| What you import | What to install alongside |
+| --- | --- |
+| `lambder/client` (browser, shared isomorphic code) | `zod` |
+| `lambder` on AWS Lambda (`nodejs18.x` and later) | `zod`. The runtime already provides the AWS SDK v3, so mark the SDK packages as dev dependencies and keep them out of the deployment package |
+| `lambder` anywhere else (a long-running server, a container, local tests) | `zod`, `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+| `LambderS3FileSource` | `@aws-sdk/client-s3`, loaded on first read |
+| `lambder/testing` | `msw` |
+
+The SDK and its `@smithy` tree are roughly 21MB installed, which is why they are
+peers rather than dependencies: a frontend importing only `lambder/client` has
+no use for any of it, and a Lambda deployment package should not ship a second
+copy of what the runtime already loads. The runtime pins its own SDK version,
+so if you need a specific one, install it and bundle it yourself.
+
+## 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).
+
+## Documentation
+
+Start with [Getting started](./docs/getting-started.md), then reach for the
+guide that matches what you are building. The full index lives in
+[docs/](./docs/README.md).
+
+| Guide | Covers |
+| --- | --- |
+| [Getting started](./docs/getting-started.md) | The three-step path from a first API to a typed frontend call |
+| [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
+| [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, and non-HTTP invocations |
+| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiError` |
+| [Responses](./docs/responses.md) | The render context, resolver methods, cookies, compression, ETag and the size cap |
+| [Sessions](./docs/sessions.md) | DynamoDB sessions, cookie scope, secrets at rest, `dataRefresh`, the controller API |
+| [API policies](./docs/api-policies.md) | Declarative rate limits, guards and idempotency, and mandatory authorization declarations |
+| [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression |
+| [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |
+| [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |
+| [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, runtime dictionaries |
+| [Testing](./docs/testing.md) | `LambderMSW`: typed MSW mocking of the API contract |
+| [DynamoDB tables](./docs/dynamodb-tables.md) | Table shapes, TTL and IAM for sessions, cache, rate limits and idempotency |
+| [Exports reference](./docs/exports.md) | Every name the three entry points export, grouped by purpose |
+
+## Standalone modules
+
+Self-contained tools that ship with the package and work with or without the
+framework:
+
+| Module | Guide | Description |
+| --- | --- | --- |
+| `html` / `xml` tags + `LambderTemplatingEngine` | [Templating](./docs/templating.md) | Type-safe tagged templates and a comment-only HTML template engine (build-pipeline-safe) |
+| `createLambderI18n` | [Translations](./docs/i18n.md) | Typed translations with enforced/optional languages, component-level extension and auto language detection (isomorphic) |
+| `LambderDdbCache` | [DynamoDB cache](./docs/ddb-cache.md) | DynamoDB-backed compressed JSON cache with lease-based single-fill and grouped keys (server-only) |
+| `LambderDdbRateLimiter` | [Rate limiter](./docs/ddb-rate-limiter.md) | DynamoDB fixed-window rate limiter, atomic per window (server-only) |
+| `LambderDdbIdempotency` | [Idempotency store](./docs/ddb-idempotency.md) | DynamoDB idempotency records with owner-checked claims and compressed replays (server-only) |
+| `LambderMSW` | [Testing](./docs/testing.md) | Typed MSW mocking of the API contract for frontend development |
+
+## Versioning and changes
+
+Released versions and what each one changed are in
+[CHANGELOG.md](./CHANGELOG.md). The current major is v5, which is v4's API
+plus this documentation set: upgrading from 4.x needs no code changes.
+Upgrading from 3.x is covered by the breaking-changes section of the 4.0.1
+entry.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to
+run the tests and what a good change looks like.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/core/Lambder.d.ts

@@ -21,7 +21,7 @@ type MaybePromise<T> = T | Promise<T>;
 type Path = `/${string}`;
 type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
 type SessionActionFunction<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => MaybePromise<LambderResponse>;
-type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any, any>) => void | Promise<void>;
+type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any, any, any>) => void | Promise<void>;
 /** Return the (possibly replaced) ctx to continue, a LambderResponse to short-circuit, or an Error to fail. */
 type HookBeforeRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderRenderContext | LambderResponse | Error>;
 type HookAfterRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResponse) => MaybePromise<LambderResponse | Error>;
@@ -157,19 +157,38 @@ export type LambderCreateOptions<TSessionData = any> = {
      * from. Default: false.
      */
     requireSessionApiGuards?: boolean;
+    /**
+     * The same for public APIs: every addApi must declare `guards`, at the
+     * type level and at registration.
+     *
+     * Public APIs are open by default and that is the right default, so this
+     * is off unless an app decides otherwise. What it buys an app that turns
+     * it on is that a public endpoint's openness becomes a written decision
+     * rather than an omission: the ones anybody may call declare a named no-op
+     * guard carrying the reason, and the ones that authorize their caller some
+     * other way (a signature, a device secret, a one-shot token) name where
+     * that happens. One grep over the guard names then lists every public
+     * door and why it is open, which is the review question a growing public
+     * surface makes expensive to answer any other way. Needs a guards map to
+     * pick from. Default: false.
+     */
+    requirePublicApiGuards?: boolean;
     /** Declarative idempotency: your store plus replay defaults; APIs opt in via `idempotency: true | { ttlSeconds }`. */
     idempotency?: LambderApiIdempotencyConfig;
 };
 /**
- * The `guards` field of a session API's options: optional by default,
- * required once create() received requireSessionApiGuards, so that an
- * authorization declaration cannot be forgotten at the type level.
+ * The `guards` field of an API's options: optional by default, required once
+ * create() received the require*ApiGuards flag for that kind of API, so that
+ * an authorization declaration cannot be forgotten at the type level.
+ *
+ * One type for both kinds: the requirement is the same shape either way, and
+ * only which flag switches it on differs.
  */
-type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
-    /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Required on this instance (requireSessionApiGuards): an API the session alone authorizes declares the named no-op session guard. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
+type LambderRequirableGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
+    /** Named guards, run in declared order before input validation: a name, a non-empty list of names, or a non-empty { name: param } map for parameterized guards. Required on this instance: an API that needs no authorization declares a named no-op guard, so every opt-out is explicit and one grep lists them all. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
     guards: TGuardsOpt;
 } : {
-    /** 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. */
+    /** Named guards, run in declared order before input validation: a name, a non-empty list of names, or a non-empty { 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;
 };
 /**
@@ -184,6 +203,7 @@ type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequire
  * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
+ * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
  *
  * @example
  * ```typescript
@@ -194,7 +214,7 @@ type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequire
  *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
  * ```
  */
-export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false> {
+export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false, _TPublicGuardsRequired extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
     /** The instance's file reader (source + caches), or null without the files option. */
@@ -228,6 +248,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private finalizeOptions;
     private maxRequestPayloadBytes;
     private requireSessionApiGuards;
+    private requirePublicApiGuards;
     private lambderSessionManager?;
     private sessionCookieOptions;
     private sessionTokenCookieKey;
@@ -275,20 +296,18 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: ActionFunction): this;
     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, any>) => Lambder<TSessionData, _TNewContract, any, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
+    use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired>;
     addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_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: a name, a list of names, or a { name: true | override } map (windows overridable on perApi budgets, errorMessage on any). The first exceeded one refuses (429 envelope + Retry-After); attempts count on every counter checked before it. */
         rateLimit?: TRateOpt;
-        /** 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 the idempotency option at creation. */
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    }, 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>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
+    } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt>, 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>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired>;
     addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
@@ -299,7 +318,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    } & LambderSessionGuardsField<_TSessionGuardsRequired, TGuardsOpt>, 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>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
+    } & LambderRequirableGuardsField<_TSessionGuardsRequired, TGuardsOpt>, 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>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),
@@ -382,5 +401,5 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
 export declare const initLambder: <TSessionData = any>() => {
     create<const TOptions extends LambderCreateOptions<TSessionData>>(options: TOptions): Lambder<TSessionData, {}, TOptions["rateLimits"] extends {
         policies: infer TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>;
-    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false, TOptions["requireSessionApiGuards"] extends true ? true : false>;
+    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false, TOptions["requireSessionApiGuards"] extends true ? true : false, TOptions["requirePublicApiGuards"] extends true ? true : false>;
 };

package/dist/core/Lambder.js

@@ -24,6 +24,7 @@ import { DEFAULT_MAX_REQUEST_PAYLOAD_BYTES } from "../shared/LambderRequestPaylo
  * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
+ * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
  *
  * @example
  * ```typescript
@@ -68,6 +69,7 @@ export default class Lambder {
     finalizeOptions;
     maxRequestPayloadBytes;
     requireSessionApiGuards;
+    requirePublicApiGuards;
     lambderSessionManager;
     sessionCookieOptions = {};
     sessionTokenCookieKey = "LMDRSESSIONTKID";
@@ -116,8 +118,10 @@ export default class Lambder {
         if (options.idempotency)
             this.getOrCreatePolicyEngine().setIdempotency(options.idempotency);
         this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
-        if (this.requireSessionApiGuards && !options.guards) {
-            throw new Error("Lambder: requireSessionApiGuards needs a guards map at creation for session APIs to declare from.");
+        this.requirePublicApiGuards = options.requirePublicApiGuards ?? false;
+        const requireFlag = this.requireSessionApiGuards ? "requireSessionApiGuards" : "requirePublicApiGuards";
+        if ((this.requireSessionApiGuards || this.requirePublicApiGuards) && !options.guards) {
+            throw new Error(`Lambder: ${requireFlag} needs a guards map at creation for APIs to declare from.`);
         }
     }
     setRouteFallbackHandler(routeFallbackHandler) {
@@ -215,9 +219,13 @@ export default class Lambder {
             throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
         }
         this.registeredApiNames.add(name);
-        if (mode === "session" && this.requireSessionApiGuards && options.guards === undefined) {
-            throw new Error(`Lambder: session API "${name}" declares no guards, and requireSessionApiGuards is on. ` +
-                `Declare the guard that authorizes it, or the named no-op guard that marks the session itself as the whole authorization.`);
+        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
+        if (guardsRequired && options.guards === undefined) {
+            const optOut = mode === "session"
+                ? "the named no-op guard that marks the session itself as the whole authorization"
+                : "the named no-op guard that records why anyone may call it";
+            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
+                `Declare the guard that authorizes it, or ${optOut}.`);
         }
         const usesPolicies = options.rateLimit !== undefined || options.guards !== undefined || options.idempotency !== undefined;
         if (!usesPolicies)

package/dist/policies/LambderApiGuards.d.ts

@@ -164,18 +164,42 @@ export type LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession extend
         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>[] | {
+/** The map form's full shape: every declarable guard name, each carrying its own param type. */
+type LambderGuardsMap<TGuards, TPayload, TIncludeSession extends boolean> = {
     readonly [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
         param: undefined;
     } ? true : TGuards[K] extends {
         param: infer P;
     } ? P : true;
 };
+/**
+ * The map form with AT LEAST ONE entry: the union, over every declarable
+ * name, of "this one required and the rest optional".
+ *
+ * An all-optional map is inhabited by `{}`, which would let `guards: {}`
+ * satisfy requireSessionApiGuards / requirePublicApiGuards at the type level
+ * while declaring no guard at all: the option is present, so the required-field
+ * check passes, and it normalizes to zero entries, so nothing runs. Requiring
+ * the chosen key also rejects `{ theGuard: undefined }`, which an optional
+ * property accepts and which would otherwise reach the guard's handler with an
+ * undefined param.
+ */
+type LambderNonEmptyGuardsMap<TGuards, TPayload, TIncludeSession extends boolean, TMap = LambderGuardsMap<TGuards, TPayload, TIncludeSession>> = {
+    [K in keyof TMap]-?: Required<Pick<TMap, K>> & Omit<TMap, K>;
+}[keyof TMap];
+/**
+ * The per-API `guards` option: one paramless guard name, a non-empty ordered
+ * list of paramless names, or a non-empty object map that can carry each
+ * guard's param (`true` enables a paramless guard). Map entries run in
+ * insertion order.
+ *
+ * Every form is non-empty by construction, so declaring the option is always
+ * declaring a guard. See LambderNonEmptyGuardsMap.
+ */
+export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly [
+    LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>,
+    ...LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[]
+] | LambderNonEmptyGuardsMap<TGuards, TPayload, TIncludeSession>;
 /**
  * The typed ctx.guardData an API's handler sees: declared guards that return
  * a value, keyed by name. Check-only (void) guards never appear.

package/dist/policies/LambderApiGuards.js

@@ -48,7 +48,18 @@ export class LambderApiGuardsEngine {
     }
     /** Startup validation of one API registration's guards option. */
     assertRegistration(apiName, mode, guardsOption) {
-        for (const { name } of toGuardEntries(guardsOption)) {
+        const entries = toGuardEntries(guardsOption);
+        // The runtime half of LambderNonEmptyGuardsMap. `guards: {}` and
+        // `guards: []` are present-but-empty: they satisfy the require*ApiGuards
+        // field check while running nothing, which is the one shape that turns a
+        // mandatory authorization declaration back into an optional one. The type
+        // rejects both; a plain-JS caller, a cast, or a spread that happened to
+        // produce an empty object lands here instead.
+        if (guardsOption !== undefined && entries.length === 0) {
+            throw new Error(`Lambder: API "${apiName}" declares an empty guards option, which authorizes nothing. ` +
+                `Name the guard that authorizes it, or omit the option entirely.`);
+        }
+        for (const { name } of entries) {
             const guardDef = this.guards[name];
             if (!guardDef) {
                 throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);

package/dist/shared/LambderI18n.d.ts

@@ -4,7 +4,7 @@
  * Zero dependencies, no Node/DOM requirements (browser detection is feature-gated),
  * safe to import in both lambda backends and frontend bundles.
  *
- * See docs/I18N.md for the full guide.
+ * See docs/i18n.md for the full guide.
  */
 export interface LambderLanguageMeta {
     /** Native language name (shown in language switchers). */

package/dist/shared/LambderI18n.js

@@ -4,7 +4,7 @@
  * Zero dependencies, no Node/DOM requirements (browser detection is feature-gated),
  * safe to import in both lambda backends and frontend bundles.
  *
- * See docs/I18N.md for the full guide.
+ * See docs/i18n.md for the full guide.
  */
 // ---------------------------------------------------------------------------
 // Implementation

package/package.json

@@ -1,10 +1,40 @@
 {
   "name": "lambder",
-  "version": "4.8.1",
-  "description": "",
+  "version": "5.0.0",
+  "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
+  "keywords": [
+    "lambda",
+    "aws-lambda",
+    "serverless",
+    "framework",
+    "typescript",
+    "api",
+    "zod",
+    "type-safe",
+    "rest",
+    "api-gateway",
+    "dynamodb",
+    "session",
+    "rate-limit",
+    "idempotency",
+    "guards",
+    "msw",
+    "i18n",
+    "templating"
+  ],
+  "homepage": "https://github.com/nesovera/lambder#readme",
+  "bugs": {
+    "url": "https://github.com/nesovera/lambder/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nesovera/lambder.git"
+  },
+  "license": "MIT",
+  "author": "NesoVera",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,6 +68,9 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "typecheck": "tsc -p tsconfig.tests.json",
     "test": "npm run typecheck && vitest run",
@@ -45,12 +78,6 @@
     "build": "tsc",
     "lint": "eslint . --ext .ts,.tsx --fix"
   },
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nesovera/lambder.git"
-  },
   "dependencies": {
     "cookie": "^1.0.2",
     "js-cookie": "^3.0.5",