lambder 4.8.1 → 4.9.1

package/Readme.md

@@ -2,6 +2,11 @@
 
 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 4.9:**
+
+- **Mandatory authorization on public APIs**: `requirePublicApiGuards: true` at creation makes `guards` a required field of every `addApi`, the same way `requireSessionApiGuards` does for session APIs, at the type level and at registration. Public APIs are open by default and that stays the default; what turning it on buys 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 (`guards: { open: "Static strings already in the bundle." }`), the ones that authorize their caller some other way (a signature, a device secret, a one-shot token) name where that happens, and one grep over the guard names then lists every public door and why it is open. The two flags are independent, so an app can require either or both.
+- **An empty guards option is refused**: `guards: {}` and `guards: []` were inhabited by the option type and passed the require\*ApiGuards field check while normalizing to zero entries, so a declaration that authorized nothing satisfied a requirement that exists to make authorization explicit. Both are now compile errors (every form of the option is non-empty by construction) and a registration error for a plain-JS caller, whichever flag is on or off. Requiring the chosen key also rejects `guards: { theGuard: undefined }`, which an optional property accepted and which reached the guard's handler with an undefined param.
+
 **New in 4.8:**
 
 - **Grouped cache keys**: `LambderDdbCache` keys may be a `{ pk, sk }` pair instead of a string, which stores related entries in one partition: `{ pk: "division:ist-34", sk: "1700:1800" }` keeps every cached window of one division together. `deletePartition(pk)` then drops the whole group without knowing which sort keys exist, and `listSortKeys(pk, { prefix, limit })` reads back what is currently cached under it. The group invalidation a cache of derived, per-entity values needs, in place of remembering every key ever written or waiting out the TTL. Reads stay one request, and the memory layer, single-flight and fill lease stay per entry. Only the `pk` part is hashed, so the sort key is queryable; a caller's `#` is escaped rather than refused (`~`→`~0`, `#`→`~1`). Plain string keys keep their exact item layout, so a live table needs no migration and both forms can share a partition.
@@ -729,7 +734,7 @@ 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 + Retry-After)
-    guards: "captcha",                          // one name, a list of names, or a { name: param } map
+    guards: "captcha",                          // one name, a non-empty list of names, or a non-empty { name: param } map
 }, handler);
 
 lambder.addSessionApi("secure.order.create", {
@@ -766,6 +771,28 @@ const lambder = initLambder<SessionData>().create({
 lambder.addSessionApi("secure.order.create", { input, output, guards: { orgPermission: "ORDERS.CREATE" } }, handler);
 lambder.addSessionApi("secure.me.logOut", { input, output, guards: "sessionOnly" }, handler);
 lambder.addSessionApi("secure.report.list", { input, output }, handler);   // compile error: which guard?
+lambder.addSessionApi("secure.report.list", { input, output, guards: {} }, handler);   // compile error: {} declares no guard
+```
+
+**The same for public APIs (`requirePublicApiGuards`)**: public APIs are open by default, and that remains the default. An app whose public surface has grown past a handful of endpoints can turn `requirePublicApiGuards: true` on to make each one's openness a written decision instead of an omission. Not every public endpoint has a control that can be hoisted into a guard (an endpoint that checks a password *is* the check), so the vocabulary an app declares here is usually a real guard for what is a genuine precondition, plus named no-op guards for the rest. The two flags are independent; either or both may be on.
+
+```typescript
+const lambder = initLambder<SessionData>().create({
+    apiPath: "/api",
+    guards: {
+        deviceToken: lambderGuard({ apiInput: z.object({ deviceToken: z.string().min(20) }), handler: (_c, { deviceToken }) => requireDevice(deviceToken) }),
+        // Anyone may call, and the param records why: `grep "open:"` lists every public door.
+        open: lambderGuard({ handler: (_c, _p, _r, _reason: string) => {} }),
+        // This endpoint establishes identity; the proof is the handler's own work.
+        credentialFlow: lambderGuard({ handler: () => {} }),
+    },
+    requirePublicApiGuards: true,
+});
+
+lambder.addApi("public.device.report", { input, output, guards: "deviceToken" }, handler);
+lambder.addApi("public.translations", { input, output, guards: { open: "Static strings already in the bundle." } }, handler);
+lambder.addApi("public.login", { input, output, guards: "credentialFlow" }, handler);
+lambder.addApi("public.search", { input, output }, handler);   // compile error: open to anyone, or authorized how?
 ```
 
 For api modules split across files, DERIVE the annotation type from the real instance instead of writing it by hand: create the instance next to the policy declarations and export `typeof` it. The type can never drift from what actually runs, and modules import it without a cycle (the app file imports no modules):

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "4.8.1",
+  "version": "4.9.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",