lambder 9.0.2 → 10.0.1

package/dist/core/Lambder.js

@@ -13,17 +13,23 @@ import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
+import { checkedRefusal, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { refuse } from "../shared/wire/LambderApiRefusal.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignatureMap.js";
 import { assertPlainData } from "../shared/util/assertPlainData.js";
-import { apiNotFoundAnswer, buildApiEnvelope, envelopeAnswer, refusalAnswer, sessionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { apiNotFoundAnswer, envelopeAnswer, refusalAnswer, sessionExpiredAnswer, successEnvelope, } from "../api/LambderApiEnvelope.js";
+import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
+import { toGuardEntries } from "../api/LambderApiGuards.js";
 import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
 import { LambderCrashHandling } from "./LambderCrashHandling.js";
 import { policyBuildersFor } from "./LambderPolicyBuilders.js";
 import { assertCreateOptions, } from "./LambderCreateOptions.js";
+/** The refusals of a name no API is registered under: no code, and none required. */
+const NO_DECLARED_REFUSALS = { codes: new Map(), codeRequired: false };
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -38,6 +44,8 @@ import { assertCreateOptions, } from "./LambderCreateOptions.js";
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
  * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
  * @typeParam _TSessionsEnabled - @internal True when create() received the session option (do not pass manually). Defaults to true, unlike its siblings, so a plugin annotating its parameter as the bare Lambder<SessionData> can still register session APIs. create() knows the option and supplies the false; `new Lambder(...)` relies on the registration-time throw alone.
+ * @typeParam _TRefusals - @internal The refusal vocabulary declareRefusals() gave the init (do not pass manually)
+ * @typeParam _TRefusalCodesRequired - @internal True when declareRefusals() received requireCodes (do not pass manually)
  *
  * @example
  * ```typescript
@@ -84,6 +92,10 @@ export default class Lambder {
     guards;
     /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
     rateLimitPolicies;
+    /** The refusal vocabulary given at creation: what each API's and each guard's refusal codes resolve against. Null without the option. */
+    refusalVocabulary;
+    /** Every API's refusals option as written, for apiOptionEntries(); its definition holds the resolved set. */
+    refusalOptions = new Map();
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
     initPromise = null;
@@ -98,6 +110,8 @@ export default class Lambder {
     corsConfig = null;
     finalizeOptions;
     requireSessionApiGuards;
+    /** Whether every refusal an API answers with has to name a code (declareRefusals's requireCodes). */
+    requireRefusalCodes;
     /** Told what a request threw, beside whatever answers it; null outside a test. See LAMBDER_CRASH_WATCH. */
     crashWatcher = null;
     /** The crashes option applied: reporting, and the framework's own 500. */
@@ -127,6 +141,7 @@ export default class Lambder {
         const session = options.session;
         this.guards = options.guards;
         this.rateLimitPolicies = options.rateLimits?.policies;
+        this.refusalVocabulary = readRefusalVocabulary(options.refusals);
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
             minApiVersion: options.minApiVersion,
@@ -157,12 +172,13 @@ export default class Lambder {
         this.trustedClientIpHeaders = options.trustedClientIpHeaders ?? [];
         this.trustedHostHeaders = options.trustedHostHeaders ?? [];
         this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
+        this.requireRefusalCodes = options.requireRefusalCodes ?? false;
         this.requirePublicApiGuards = options.requirePublicApiGuards ?? false;
         this.crashHandling = new LambderCrashHandling(options.crashes ?? {}, this.apiVersion);
         this.contextTools = {
             sessionControllerFor: (ctx) => this.getSessionController(ctx),
             chargeRateLimit: async (ctx, policy, key, refuse) => {
-                const { checkResult, refusal } = await this.pipeline.chargeRateLimit(policy, {
+                const { checkResult, refusal: refusalToThrow } = await this.pipeline.chargeRateLimit(policy, {
                     // A per-API budget counts per registered API. The posted
                     // name of a call no API matched (a hook or the fallback
                     // charging it) is the caller's choice, and a fresh name
@@ -172,13 +188,13 @@ export default class Lambder {
                     session: ctx.session,
                     key,
                 });
-                if (refuse && refusal) {
+                if (refuse && refusalToThrow) {
                     if (ctx.api)
-                        throw refusal;
+                        throw refusalToThrow;
                     // A route has no envelope to carry a refusal, so it
                     // answers the same 429 as text, with the same Retry-After
                     // and the policy's own words.
-                    throw this.getResolver(ctx).text(refusal.errorMessage.content, { statusCode: 429, headers: refusal.headers });
+                    throw this.getResolver(ctx).text(refusalToThrow.refusal.content, { statusCode: 429, headers: refusalToThrow.headers });
                 }
                 return checkResult;
             },
@@ -265,14 +281,14 @@ export default class Lambder {
     }
     // Typed API with Zod
     addApi(name, schema, 
-    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with refuse(). */
+    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
     handler) {
         this.registerApi(name, "public", schema, handler);
         return this;
     }
     // Typed Session API with Zod
     addSessionApi(name, schema, 
-    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with refuse(). */
+    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
     handler) {
         this.registerApi(name, "session", schema, handler);
         return this;
@@ -303,9 +319,22 @@ export default class Lambder {
             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 definition = { name, mode, guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output };
+        // The option, like guards and rateLimit, is a declaration or absent:
+        // an empty list would read as declaring codes while declaring none.
+        const ownRefusals = toRefusalCodes(schema.refusals);
+        if (schema.refusals !== undefined && ownRefusals.length === 0) {
+            throw new Error(`Lambder: API "${name}" declares an empty refusals option, which declares no code. Name the codes it refuses with, or omit the option entirely.`);
+        }
+        const allowedCodes = resolveAllowedRefusals(name, this.refusalVocabulary, ownRefusals, toGuardEntries(schema.guards).map(({ name: guard }) => ({
+            guard,
+            codes: (this.guards && Object.prototype.hasOwnProperty.call(this.guards, guard) ? this.guards[guard]?.refusals : undefined) ?? [],
+        })));
+        const refusals = { codes: allowedCodes, codeRequired: this.requireRefusalCodes };
+        const definition = { name, mode, guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output, refusals };
         this.pipeline.assertRegistration(definition);
         this.apiDefinitions.set(name, definition);
+        if (schema.refusals !== undefined)
+            this.refusalOptions.set(name, schema.refusals);
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
             actionFn: (ctx) => this.runApi(ctx, definition, schema.output, schema.compress ?? "auto", handler),
@@ -436,13 +465,16 @@ export default class Lambder {
      * and guard name. A policy's key handler is never written: its `per`
      * says "custom" and no more. A guard's input schema is never written
      * either; its declaration says only which of the three input modes it
-     * has. Every table is sorted by name, so the module diffs by endpoint
-     * and never moves when registrations are reordered.
+     * has. The refusal vocabulary is not written at all: it is shared code
+     * (codes, zod schemas, statuses and flags), and the mock declares the
+     * same object. Every table is sorted by name, so the module diffs by
+     * endpoint and never moves when registrations are reordered.
      */
     apiOptionEntries() {
         const apis = {};
         for (const name of [...this.apiDefinitions.keys()].sort()) {
             const { mode, guards, rateLimit, idempotency } = this.apiDefinitions.get(name);
+            const refusals = this.refusalOptions.get(name);
             const entry = { mode };
             if (guards !== undefined) {
                 assertPlainData(guards, `the guards option of API "${name}"`);
@@ -454,11 +486,13 @@ export default class Lambder {
             }
             if (idempotency !== undefined)
                 entry.idempotency = idempotency;
+            if (refusals !== undefined)
+                entry.refusals = refusals;
             apis[name] = entry;
         }
         const rateLimitPolicies = {};
         for (const name of Object.keys(this.rateLimitPolicies ?? {}).sort()) {
-            const { per, budget, chargeAt, errorMessage, ...windows } = this.rateLimitPolicies[name];
+            const { per, budget, chargeAt, refusal, ...windows } = this.rateLimitPolicies[name];
             const entry = {};
             for (const [window, limit] of Object.entries(windows)) {
                 if (limit !== undefined)
@@ -470,9 +504,9 @@ export default class Lambder {
                 entry.budget = budget;
             if (chargeAt !== undefined)
                 entry.chargeAt = chargeAt;
-            if (errorMessage !== undefined) {
-                assertPlainData(errorMessage, `the errorMessage of rate-limit policy "${name}"`);
-                entry.errorMessage = errorMessage;
+            if (refusal !== undefined) {
+                assertPlainData(refusal, `the refusal of rate-limit policy "${name}"`);
+                entry.refusal = refusal;
             }
             rateLimitPolicies[name] = entry;
         }
@@ -483,6 +517,7 @@ export default class Lambder {
                 input: guard.apiInput ? "apiInput" : guard.guardInput ? "guardInput" : "none",
                 session: guard.session === true,
                 runAt: guard.runAt ?? "beforeInputValidation",
+                ...(guard.refusals?.length ? { refusals: guard.refusals } : {}),
             };
         }
         return { apis, rateLimitPolicies, guards };
@@ -902,7 +937,9 @@ export default class Lambder {
      * see the declared shape. The handler returns the schema's input form, so
      * a transform runs exactly once.
      *
-     * An output the schema rejects is the handler breaking its contract,
+     * An output the schema rejects, or one that is not an object or an array
+     * (isObjectPayload: what makes a caller's success never falsy), is the
+     * handler breaking its contract,
      * answered as a crash rather than sent (LambderApiOutputValidationError,
      * which an idempotency key records as its answer, since the handler has
      * already run). The parse is synchronous, so an output schema cannot be
@@ -929,52 +966,69 @@ export default class Lambder {
             }
             if (!parsed.success)
                 throw new LambderApiOutputValidationError(definition.name, { zodError: parsed.error });
-            return envelopeAnswer(buildApiEnvelope(this.apiVersion, parsed.data, { logList: ctx.logList }));
+            if (!isObjectPayload(parsed.data))
+                throw new LambderApiOutputValidationError(definition.name, { notObject: describePayloadKind(parsed.data) });
+            return envelopeAnswer(successEnvelope(this.apiVersion, parsed.data, ctx.logList));
         });
         // The API's compress option, on whatever answer the call ended with:
         // a replayed one comes back from its store without the hint.
         return responseFromAnswer({ ...answer, compress });
     }
-    /** A thrown LambderApiRefusal (from a hook, say) as the structured API envelope: the core's one mapping. */
+    /**
+     * A thrown LambderApiRefusal (from a hook, say) as the structured API
+     * envelope: the core's one mapping, after the same check the pipeline
+     * applies, against the endpoint the call names. A name no API is
+     * registered under declares no code, so only an uncoded or a framework
+     * refusal goes out for it.
+     */
     apiErrorResponse(err, ctx) {
-        return responseFromAnswer(refusalAnswer(err, this.apiVersion, ctx.logList));
+        const apiName = ctx.apiName ?? "";
+        const refusal = checkedRefusal(apiName, this.apiDefinitions.get(apiName)?.refusals ?? NO_DECLARED_REFUSALS, err);
+        return responseFromAnswer(refusalAnswer(refusal, this.apiVersion, ctx.logList));
     }
 }
+/** The init bound to one vocabulary (or none): the policy builders, refuse and create() that share it. */
+const lambderInitOf = (declared) => ({
+    ...policyBuildersFor(declared?.vocabulary ?? null),
+    /**
+     * refuse() typed to the app's whole vocabulary, for a shared helper or a
+     * hook that raises a declared code with no endpoint in hand: `code` is
+     * one of the vocabulary's and `data` follows it. Which endpoint may send
+     * the code is checked where the refusal is rendered, as for the free
+     * refuse(). Inside an API handler ctx.refuse is narrower, that
+     * endpoint's codes alone.
+     */
+    refuse: refuse,
+    create(options) {
+        const withRefusals = { ...options, refusals: declared?.refusals, requireRefusalCodes: declared?.requireCodes ?? false };
+        return new Lambder(withRefusals);
+    },
+});
 /**
- * The canonical way to create an instance: fix the session data type first,
- * then create with the full configuration in one declaration. The policy,
- * guard and idempotency types are inferred from the options, so the instance
- * is born fully typed and `typeof lambderApp` is the annotation type for api
- * modules. There are no ordering rules, and nothing can be half-configured.
- *
- * ```typescript
- * // app.ts (imports no api modules, so modules can import the type back)
- * export const lambderApp = initLambder<SessionData>().create({
- *     apiPath: "/api",
- *     session: { store: new LambderDdbSessionStore({ tableName: "app-session", region: "us-east-1" }), sessionSalt: "..." },
- *     rateLimits: { limiter, policies },
- *     guards,
- *     idempotency: { store },
- * });
- * export type AppLambder = typeof lambderApp;
- *
- * // orders.ts
- * export const orderApi = (lambder: AppLambder) => lambder.addSessionApi(...);
- *
- * // index.ts: registration only
- * const lambder = lambderApp.addHook(...).use(orderApi)...;
- * export const handler = lambder.getHandler();
- * ```
- *
- * Curried because TypeScript type arguments are all-or-nothing per call:
- * passing the session data type to `new Lambder<S>(...)` would silently
- * widen the inferred policy and guard types to their {} defaults. Fixing the
- * session type in the first call lets the second infer everything else.
- * `new Lambder(options)` serves untyped or session-data-free instances.
+ * The entry point of an app: binds the session data type, and hands out the
+ * builders and create() that share it. `declareRefusals()` binds the app's
+ * refusal vocabulary too, so a guard's ctx.refuse and the init's own refuse
+ * are typed to it before any instance exists, and create() gives it to the
+ * instance for every API's refusals option to name codes from.
  */
 export const initLambder = () => ({
-    ...policyBuildersFor(),
-    create(options) {
-        return new Lambder(options);
+    ...lambderInitOf(null),
+    /**
+     * Declares the app's refusal vocabulary: every code once, with the schema
+     * of its data (`{ data: schema }`) or none (`{}`), the status every
+     * refusal with it leaves with (`status`, 200 by default) and whether it
+     * sets the notAuthorized flag (`notAuthorized: true`). Returns the init
+     * bound to it: its guard() types ctx.refuse to a guard's refusals and
+     * refuses a guard naming a code outside the vocabulary, its refuse is
+     * typed to the whole vocabulary, and its create() hands the vocabulary to
+     * the instance. With `requireCodes`, an uncoded refusal from an API
+     * handler, a guard or a helper is a crash rather than an answer, so every
+     * "no" a client reads names a code.
+     */
+    declareRefusals(refusals, options = {}) {
+        const vocabulary = readRefusalVocabulary(refusals);
+        if (!vocabulary)
+            throw new Error("Lambder: declareRefusals() takes the vocabulary, an object of codes.");
+        return lambderInitOf({ refusals, vocabulary, requireCodes: (options.requireCodes ?? false) });
     },
 });

package/dist/core/LambderContext.d.ts

@@ -120,7 +120,7 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     /**
      * Counts one attempt against a named rate-limit policy and refuses the
      * request when it is over: a 429 envelope on an API call, a plain 429 on
-     * a route, with Retry-After and the policy's errorMessage either way. A
+     * a route, with Retry-After and the policy's refusal either way. A
      * policy without `per` takes the key as the second argument; a `per:
      * "ip"` or `per: "session"` one reads it off the request. The instance's
      * limiter, failOpen and key bounding apply, as for a declared limit.

package/dist/core/LambderContext.js

@@ -6,6 +6,7 @@ import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
 import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID } from "../shared/wire/LambderInvokeApiId.js";
 import { bindCallTools, responseToolsOf } from "../api/LambderApiCallContext.js";
 import { decodeRequestPath } from "./LambderRequestPath.js";
+import { refuse } from "../shared/wire/LambderApiRefusal.js";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export const isV2HttpEvent = (event) => !!event && typeof event === "object"
     && event.version === "2.0"
@@ -23,6 +24,10 @@ export const bindContextTools = (ctx, tools) => {
         methods: {
             rateLimit: async (policy, key) => { await tools.chargeRateLimit(bound, policy, key, true); },
             isRateLimited: (policy, key) => tools.chargeRateLimit(bound, policy, key, false),
+            // refuse() itself: what an API handler's context types as the
+            // endpoint's declared codes (LambderDeclaredRefuse). The check
+            // against the declaration happens where the refusal is rendered.
+            refuse,
             ...responseToolsOf(bound, bound.host),
         },
     });

package/dist/core/LambderCreateOptions.d.ts

@@ -14,6 +14,10 @@ import type { LambderSessionCrypto } from "../session/LambderSessionCrypto.js";
 import type { LambderApiGuard } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "../api/LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "../api/LambderApiIdempotency.js";
+import { type LambderRefusalVocabulary } from "../api/LambderApiRefusals.js";
+import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderJsonOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderRateLimitMessage } from "../shared/wire/LambderApiOptionValues.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
 export type LambderRouteHandler = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
 export type LambderSessionRouteHandler<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => MaybePromise<LambderResponse>;
@@ -250,6 +254,29 @@ export type LambderCreateOptions<TSessionData = any> = {
      * rejected here rather than reading fields that are not on its context.
      */
     guards?: Record<string, LambderApiGuard<any, any, any, LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>>>;
+    /**
+     * The app's refusal vocabulary: every code an API or a guard may refuse
+     * with, each declared once with the schema of its data (`{ data: schema }`
+     * or none), the status every refusal with it leaves with and whether it
+     * sets the notAuthorized flag. An API names the codes it may refuse with
+     * in its own `refusals` option, a guard in its own, and a refusal
+     * carrying any other code is a crash rather than an answer
+     * (LambderApiRefusalValidationError). The codes are what goes on the
+     * wire, so they may not start with the framework's `lambder/`; a code's
+     * data is an object or an array, as an output is.
+     *
+     * An app declares it with `initLambder().declareRefusals()`, which hands
+     * it here and types the init's guard() and refuse to it; it is written
+     * here only when the class is constructed directly.
+     */
+    refusals?: LambderRefusalVocabulary;
+    /**
+     * Whether every refusal an API answers with has to name a declared code
+     * (or a framework code): an uncoded refuse() is then a crash rather than
+     * an answer, and ctx.refuse requires a code. Set through
+     * declareRefusals()'s `requireCodes`, as `refusals` is. Default false.
+     */
+    requireRefusalCodes?: boolean;
     /**
      * Make an authorization declaration part of registering a session API:
      * every addSessionApi must declare `guards`, at the type level (a missing
@@ -305,6 +332,19 @@ type LambderSessionOptionRequired = {
  * away to nothing.
  */
 export type LambderSessionEnabledInstance<TSessionsEnabled extends boolean> = TSessionsEnabled extends true ? unknown : LambderSessionOptionRequired;
+/**
+ * An API answers with an object or an array (see isObjectPayload), so a
+ * caller's success is never null, false, 0 or "". Intersected onto an API's
+ * options: an output schema whose wire form is anything else (z.void(),
+ * z.boolean(), a nullable or an optional object, a Date) is refused where it
+ * is written, and the property name is the message.
+ */
+export type LambderObjectOutputCheck<TOutput extends z.ZodType> = 0 extends 1 & z.output<TOutput> ? unknown : undefined extends z.output<TOutput> ? LambderObjectOutputRefusal : [LambderJsonOf<z.output<TOutput>>] extends [never] ? LambderObjectOutputRefusal : [LambderJsonOf<z.output<TOutput>>] extends [object] ? unknown : LambderObjectOutputRefusal;
+type LambderObjectOutputRefusal = {
+    output: {
+        readonly "lambder: an API answers with an object or an array. One with nothing to answer declares output: z.object({}) and returns {}.": never;
+    };
+};
 /**
  * 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
@@ -320,17 +360,7 @@ export type LambderRequirableGuardsField<TRequired extends boolean, TGuardsOpt>
     /** Named guards, run in declared order before input validation (after it for a guard declared runAt: "afterInputValidation"): 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;
 };
-/**
- * Rejects a key the options type does not have, which `const TOptions` would
- * otherwise wave through: inferring a generic from an object literal switches
- * excess-property checking off for the whole literal, so
- * `requireSessionApiGuard` (no trailing "s") or `maxResponseByte` would
- * compile, be dropped in silence, and leave the app on the default. That is
- * worst for the two require*ApiGuards flags, which exist to make a missing
- * authorization declaration a compile error. Mapping every surplus key to
- * `never` puts the error back on the key itself.
- */
-export type LambderNoExtraKeys<TOptions, TShape> = TOptions & Record<Exclude<keyof TOptions, keyof TShape>, never>;
+export type { LambderNoExtraKeys };
 /**
  * What create() was actually given for one option, or undefined when the
  * literal does not carry the key at all.
@@ -346,6 +376,16 @@ export type LambderGivenOption<TOptions, TKey extends PropertyKey> = TKey extend
  * option they check.
  */
 type LambderOptionShape<TSessionData, TKey extends keyof LambderCreateOptions<TSessionData>> = NonNullable<LambderCreateOptions<TSessionData>[TKey]>;
+/**
+ * A guard's `refusals` against the vocabulary given beside it: the guard is
+ * built before the instance, so a code it names that the vocabulary does not
+ * hold is caught here, on the guard's entry in the guards option.
+ */
+type LambderGuardRefusalsKnown<TGuard, TRefusals> = TGuard extends {
+    refusals?: infer TNamed;
+} ? NonNullable<TNamed> extends readonly (infer TCode extends string)[] ? string extends TCode ? unknown : [Exclude<TCode, keyof NonNullable<TRefusals> & string>] extends [never] ? unknown : {
+    refusals: readonly (keyof NonNullable<TRefusals> & string)[];
+} : unknown : unknown;
 /**
  * The surplus-key rule one level down, over the option objects a typo is
  * worst on. Excess-property checking is off for the WHOLE literal under
@@ -358,7 +398,7 @@ type LambderOptionShape<TSessionData, TKey extends keyof LambderCreateOptions<TS
  * checked against its own option's shape, so the error lands on the
  * misspelled key.
  */
-export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCreateOptions<TSessionData>> = {
+export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCreateOptions<TSessionData>, TRefusals = TOptions["refusals"]> = {
     session?: LambderNoExtraKeys<NonNullable<TOptions["session"]>, LambderOptionShape<TSessionData, "session">> & {
         cookie?: LambderNoExtraKeys<NonNullable<NonNullable<TOptions["session"]>["cookie"]>, LambderSessionCookieOptions>;
     };
@@ -366,11 +406,15 @@ export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCrea
     crashes?: LambderNoExtraKeys<NonNullable<TOptions["crashes"]>, LambderOptionShape<TSessionData, "crashes">>;
     rateLimits?: LambderNoExtraKeys<NonNullable<TOptions["rateLimits"]>, LambderOptionShape<TSessionData, "rateLimits">> & {
         policies?: {
-            [TPolicy in keyof NonNullable<TOptions["rateLimits"]>["policies"]]: LambderNoExtraKeys<NonNullable<TOptions["rateLimits"]>["policies"][TPolicy], LambderApiRateLimitPolicyConfig<LambderRenderContext>>;
+            [TPolicy in keyof NonNullable<TOptions["rateLimits"]>["policies"]]: LambderNoExtraKeys<NonNullable<TOptions["rateLimits"]>["policies"][TPolicy], LambderApiRateLimitPolicyConfig<LambderRenderContext>> & (NonNullable<TOptions["rateLimits"]>["policies"][TPolicy] extends {
+                refusal: infer TMessage;
+            } ? {
+                refusal?: LambderNoExtraKeys<TMessage, LambderRateLimitMessage>;
+            } : unknown);
         };
     };
     guards?: {
-        [TGuard in keyof NonNullable<TOptions["guards"]>]: LambderNoExtraKeys<NonNullable<TOptions["guards"]>[TGuard], LambderOptionShape<TSessionData, "guards">[string]>;
+        [TGuard in keyof NonNullable<TOptions["guards"]>]: LambderNoExtraKeys<NonNullable<TOptions["guards"]>[TGuard], LambderOptionShape<TSessionData, "guards">[string]> & LambderGuardRefusalsKnown<NonNullable<TOptions["guards"]>[TGuard], TRefusals>;
     };
     files?: TOptions["files"] extends {
         source: unknown;
@@ -387,4 +431,3 @@ export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCrea
  * response (maxResponseBytes: 0) that an app discovers in production.
  */
 export declare const assertCreateOptions: (options: LambderCreateOptions<any>) => void;
-export {};

package/dist/core/LambderCreateOptions.js

@@ -1,3 +1,4 @@
+import { assertRefusalCodesDeclared, readRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 /**
  * Everything create() refuses before an instance exists, in one place: a
@@ -25,6 +26,15 @@ export const assertCreateOptions = (options) => {
     if (typeof cors === "object" && cors.credentials && (cors.origins === undefined || cors.origins === "*")) {
         throw new Error('Lambder: cors.credentials needs cors.origins to be an allowlist or a predicate. With every origin allowed, any website could make credentialed calls and read the answers.');
     }
+    // The vocabulary, and every code a guard names against it: a guard built
+    // by the standalone lambderGuard() meets the vocabulary here first.
+    const vocabulary = readRefusalVocabulary(options.refusals);
+    for (const [name, guard] of Object.entries(options.guards ?? {})) {
+        assertRefusalCodesDeclared(`guard "${name}"`, (guard?.refusals ?? []), vocabulary);
+    }
+    if (options.requireRefusalCodes && !vocabulary) {
+        throw new Error("Lambder: requireRefusalCodes needs a refusals vocabulary to name codes from; declare one with initLambder().declareRefusals().");
+    }
     if ((options.requireSessionApiGuards || options.requirePublicApiGuards) && !options.guards) {
         const requireFlag = options.requireSessionApiGuards ? "requireSessionApiGuards" : "requirePublicApiGuards";
         throw new Error(`Lambder: ${requireFlag} needs a guards map at creation for APIs to declare from.`);

package/dist/core/LambderPolicyBuilders.d.ts

@@ -9,21 +9,24 @@
  */
 import type { LambderRenderContext, LambderSessionRenderContext } from "./LambderContext.js";
 import { type LambderGuardBuilder } from "../api/LambderApiGuards.js";
+import type { LambderRefusalDeclaration, LambderRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import { type LambderRateLimitKeyBuilder } from "../api/LambderApiRateLimits.js";
 /** Builder for the server's guards: the handler sees the render context (session-typed when `session: true`). */
 export declare const lambderGuard: LambderGuardBuilder<LambderRenderContext, LambderSessionRenderContext<any, any>>;
 /** Builder for the server's rate-limit keys: the handler sees the render context. */
 export declare const lambderRateLimitKey: LambderRateLimitKeyBuilder<LambderRenderContext>;
 /**
- * The same two builders bound to one app's session data, which is what
- * initLambder<SessionData>() hands out beside create(): a guard's
- * `ctx.session.data` and `ctx.sessionController` are SessionData where the standalone
- * lambderGuard() leaves them `any`. The server's counterpart of the mock's
- * `guard` and `rateLimitKey`.
+ * The same two builders bound to one app's session data and refusal
+ * vocabulary, which is what initLambder<SessionData>() hands out beside
+ * create(): a guard's `ctx.session.data` and `ctx.sessionController` are
+ * SessionData where the standalone lambderGuard() leaves them `any`, and its
+ * `ctx.refuse` is typed to the guard's refusals from the vocabulary
+ * declareRefusals() gave (null: none declared, so a guard names no code).
+ * The server's counterpart of the mock's `guard` and `rateLimitKey`.
  */
-export declare const policyBuildersFor: <TSessionData>() => {
-    /** Builds a guard whose handler sees this app's session type. */
-    guard: LambderGuardBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>>;
+export declare const policyBuildersFor: <TSessionData, TRefusals extends LambderRefusalVocabulary = {}, TCodesRequired extends boolean = false>(vocabulary: ReadonlyMap<string, LambderRefusalDeclaration> | null) => {
+    /** Builds a guard whose handler sees this app's session type and, on ctx.refuse, the guard's own refusal codes. */
+    guard: LambderGuardBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>, TRefusals, TCodesRequired>;
     /** Builds a rate-limit key whose handler sees this app's session type; the counterpart of `guard`. */
     rateLimitKey: LambderRateLimitKeyBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>>;
 };

package/dist/core/LambderPolicyBuilders.js

@@ -14,15 +14,17 @@ export const lambderGuard = lambderGuardBuilder();
 /** Builder for the server's rate-limit keys: the handler sees the render context. */
 export const lambderRateLimitKey = lambderRateLimitKeyBuilder();
 /**
- * The same two builders bound to one app's session data, which is what
- * initLambder<SessionData>() hands out beside create(): a guard's
- * `ctx.session.data` and `ctx.sessionController` are SessionData where the standalone
- * lambderGuard() leaves them `any`. The server's counterpart of the mock's
- * `guard` and `rateLimitKey`.
+ * The same two builders bound to one app's session data and refusal
+ * vocabulary, which is what initLambder<SessionData>() hands out beside
+ * create(): a guard's `ctx.session.data` and `ctx.sessionController` are
+ * SessionData where the standalone lambderGuard() leaves them `any`, and its
+ * `ctx.refuse` is typed to the guard's refusals from the vocabulary
+ * declareRefusals() gave (null: none declared, so a guard names no code).
+ * The server's counterpart of the mock's `guard` and `rateLimitKey`.
  */
-export const policyBuildersFor = () => ({
-    /** Builds a guard whose handler sees this app's session type. */
-    guard: lambderGuardBuilder(),
+export const policyBuildersFor = (vocabulary) => ({
+    /** Builds a guard whose handler sees this app's session type and, on ctx.refuse, the guard's own refusal codes. */
+    guard: lambderGuardBuilder(vocabulary),
     /** Builds a rate-limit key whose handler sees this app's session type; the counterpart of `guard`. */
     rateLimitKey: lambderRateLimitKeyBuilder(),
 });

package/dist/core/LambderResolver.d.ts

@@ -14,7 +14,7 @@ interface DieResolverMethods {
     redirect: SyncDie<LambderResponseBuilder["redirect"]>;
     versionExpired: SyncDie<LambderResponseBuilder["versionExpired"]>;
     fileBase64: SyncDie<LambderResponseBuilder["fileBase64"]>;
-    api: SyncDie<LambderResponseBuilder["api"]>;
+    apiRefusal: SyncDie<LambderResponseBuilder["apiRefusal"]>;
     file: AsyncDie<LambderResponseBuilder["file"]>;
     templateFile: AsyncDie<LambderResponseBuilder["templateFile"]>;
 }

package/dist/core/LambderResolver.js

@@ -22,7 +22,7 @@ export default class LambderResolver extends LambderResponseBuilder {
             redirect: (...a) => { throw this.redirect(...a); },
             versionExpired: (...a) => { throw this.versionExpired(...a); },
             fileBase64: (...a) => { throw this.fileBase64(...a); },
-            api: (...a) => { throw this.api(...a); },
+            apiRefusal: (...a) => { throw this.apiRefusal(...a); },
             file: async (...a) => { throw await this.file(...a); },
             templateFile: async (...a) => { throw await this.templateFile(...a); },
         };

package/dist/core/LambderResponseBuilder.d.ts

@@ -4,8 +4,8 @@ import { LambderResponse, type LambderHeadersInput } from "./LambderResponse.js"
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import { LambderSafeHtml } from "../shared/LambderHtml.js";
 import type { LambderTemplateData } from "./LambderTemplatingEngine.js";
-import type { LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
-export type { LambderApiEnvelopeBody, LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiRefusalConfig } from "../shared/wire/LambderApiContract.js";
+export type { LambderApiEnvelopeBody, LambderApiRefusalConfig } from "../shared/wire/LambderApiContract.js";
 export type LambderResponseOptions = {
     statusCode?: LambderHttpStatusCode;
     headers?: LambderHeadersInput;
@@ -79,12 +79,14 @@ export default class LambderResponseBuilder {
         htmlVirtualSlots?: boolean;
     }): Promise<LambderResponse>;
     /**
-     * An API envelope written by hand: what a hook, an input validation
-     * handler or a global error handler answers an API call with (a refusal
-     * flag, an errorMessage, a crash). The payload goes out as given; an API
-     * handler's own output is parsed through its schema by the instance
-     * instead. The logList channel is what the request accumulated unless the
-     * config names its own.
+     * An API call answered from outside its handler: what a hook, a fallback,
+     * the input validation handler or the global error handler answers with.
+     * It is always a refusal (a refusal message, or one of the versionExpired,
+     * sessionExpired and notAuthorized flags) with a null payload, so a
+     * caller's success is only ever the handler's parsed output. Its message
+     * carries a framework code or none, and no data, since it answers outside
+     * any one endpoint's declared refusals. The logList channel is what the
+     * request accumulated unless the config names its own.
      */
-    api(payload: unknown, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    apiRefusal(config: LambderApiRefusalConfig, options?: LambderResponseOptions): LambderResponse;
 }