lambder 14.1.1 → 15.0.1

package/dist/api/LambderApiRateLimits.js

@@ -1,5 +1,4 @@
 import { joinKeyFields } from "../shared/util/joinKeyFields.js";
-import { boundKeyField } from "../shared/util/boundKeyField.js";
 import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 import { LambderApiRefusal, LAMBDER_REFUSAL_CODES } from "../shared/wire/LambderApiRefusal.js";
 import { parsePreflightSlice } from "./LambderApiValidationRefusal.js";
@@ -7,29 +6,43 @@ import { assertNonNegativeInteger } from "../shared/util/LambderOptionChecks.js"
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import { DEFAULT_IPV6_RATE_LIMIT_PREFIX, rateLimitSubjectOf } from "../shared/util/LambderClientIp.js";
 const RATE_LIMIT_WINDOW_KEYS = RATE_LIMIT_WINDOWS.map((window) => window.key);
-/** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
-export const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", code: LAMBDER_REFUSAL_CODES.rateLimited, content: "Too many requests. Please try again later." };
+/** The words a rate-limited call answers with unless the policy or the API's override writes its own (the `refusal` option of each). */
+export const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", content: "Too many requests. Please try again later." };
 /**
  * The refusal a rate-limited call answers with: a 429 envelope carrying the
- * framework code, whatever message a policy or an API wrote, and a
- * Retry-After header. The engine throws it; the mock runtime's failure
- * injection throws the same one, so an injected rate limit is
- * indistinguishable from a real one.
+ * framework code, the words a policy or an API wrote, the policy's name and
+ * the seconds to wait as its data, and a Retry-After header of those same
+ * seconds. The engine throws it; the mock runtime's failure injection throws
+ * the same one, so an injected rate limit is indistinguishable from a real
+ * one.
  *
- * The code goes on after the message, so a message that carries one anyway
- * (a plain-JS caller, a cast) cannot replace it: a rate limit is never a code
- * an endpoint declares, and the pipeline would refuse to send one it did not.
+ * Only the words are read off the message, so one that carries a code or
+ * data anyway (a plain-JS caller, a cast) cannot replace them: a rate limit
+ * is never a code an endpoint declares, and the pipeline sends one only with
+ * the data a client narrows it by.
  */
-export const rateLimitRefusal = (detail, retryAfterSeconds, message) => new LambderApiRefusal(detail, {
-    refusal: message ? { type: message.type, ...(message.title !== undefined ? { title: message.title } : {}), content: message.content, code: LAMBDER_REFUSAL_CODES.rateLimited } : DEFAULT_RATE_LIMIT_REFUSAL,
-    statusCode: 429,
-    headers: { "Retry-After": String(Math.max(1, Math.floor(retryAfterSeconds))) },
-});
+export const rateLimitRefusal = (detail, data, message = DEFAULT_RATE_LIMIT_REFUSAL) => {
+    // The header carries whole seconds of at least one, and the data says the
+    // same number: a client reading either waits as long.
+    if (!Number.isFinite(data.retryAfterSeconds))
+        throw new Error(`Lambder: a rate-limit refusal waits a finite number of seconds, got ${String(data.retryAfterSeconds)}.`);
+    const retryAfterSeconds = Math.max(1, Math.floor(data.retryAfterSeconds));
+    return new LambderApiRefusal(detail, {
+        refusal: {
+            type: message.type,
+            ...(message.title !== undefined ? { title: message.title } : {}),
+            content: message.content,
+            code: LAMBDER_REFUSAL_CODES.rateLimited,
+            data: { policy: data.policy, retryAfterSeconds },
+        },
+        statusCode: 429,
+        headers: { "Retry-After": String(retryAfterSeconds) },
+    });
+};
 /**
- * A rate-limit message carries no code of its own and no data: its code is
- * always the framework's, which rateLimitRefusal sets, and a code there would
- * read as one the app chose for clients to branch on when it never reaches
- * them.
+ * A rate-limit message carries no code of its own and no data: both are the
+ * framework's, which rateLimitRefusal sets, and a code there would read as
+ * one the app chose for clients to branch on when it never reaches them.
  */
 const assertRateLimitMessage = (where, message) => {
     if (message === undefined)
@@ -39,7 +52,7 @@ const assertRateLimitMessage = (where, message) => {
         throw new Error(`Lambder: ${where} sets a refusal code. A rate-limit refusal is always "${LAMBDER_REFUSAL_CODES.rateLimited}", so an endpoint never has to declare it; write the type, title and content only.`);
     }
     if (data !== undefined) {
-        throw new Error(`Lambder: ${where} sets refusal data. A rate-limit refusal carries none.`);
+        throw new Error(`Lambder: ${where} sets refusal data. A rate-limit refusal carries the framework's: the policy that refused and the seconds to wait.`);
     }
 };
 /**
@@ -118,8 +131,13 @@ const trackerKeyOf = (name, policy, apiName, key) => policy.budget === "perPolic
  * slice) and hands the context to a custom key's handler, reading nothing
  * of the context itself but its session, so it runs unchanged under the
  * server and the mock runtime.
+ *
+ * The caller's half of every tracker key (the address, the session key, a
+ * custom key) reaches the limiter as a digest (LambderKeyFieldDigest), so a
+ * table read names the API and the policy and never who was counted.
  */
 export class LambderApiRateLimitsEngine {
+    keyFieldDigest;
     limiter = null;
     failOpen = true;
     ipv6PrefixLength = DEFAULT_IPV6_RATE_LIMIT_PREFIX;
@@ -134,6 +152,9 @@ export class LambderApiRateLimitsEngine {
      * second would otherwise be as many identical log lines.
      */
     loggedFailures = new WeakSet();
+    constructor(keyFieldDigest) {
+        this.keyFieldDigest = keyFieldDigest;
+    }
     /** True once rateLimits were configured. */
     get isConfigured() { return this.limiter !== null; }
     configure(config) {
@@ -249,14 +270,14 @@ export class LambderApiRateLimitsEngine {
             const limits = windowsOf(policy, override);
             const exceeded = await this.countAttempt(name, trackerKeyOf(name, policy, apiName, key), limits, `API "${apiName}"`);
             if (exceeded) {
-                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, this.retryAfterOf(exceeded), override?.refusal ?? policy.refusal);
+                throw rateLimitRefusal(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, { policy: name, retryAfterSeconds: this.retryAfterOf(exceeded) }, override?.refusal ?? policy.refusal);
             }
         }
     }
     /**
      * One policy charged by code rather than by a declaration, for
      * `ctx.rateLimit` and `ctx.isRateLimited`. Counters, failOpen, key
-     * bounding and refusal are those of a declared limit; only who knows the
+     * digests and refusal are those of a declared limit; only who knows the
      * key differs. A policy without `per` takes the key the code passes, a
      * `per: "ip"` or `per: "session"` one reads it off the request, and one
      * keyed by an API payload is refused, since only its APIs know the key.
@@ -276,7 +297,7 @@ export class LambderApiRateLimitsEngine {
         const retryAfterSeconds = this.retryAfterOf(exceeded);
         return {
             checkResult: { ...exceeded, retryAfterSeconds },
-            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, retryAfterSeconds, policy.refusal),
+            refusal: rateLimitRefusal(`Rate limited: ${where} exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, { policy: name, retryAfterSeconds }, policy.refusal),
         };
     }
     /**
@@ -292,10 +313,10 @@ export class LambderApiRateLimitsEngine {
     /**
      * Counts one attempt, or lets it through when the limiter itself fails
      * and failOpen is on. The log line names the policy and its windows,
-     * never the tracker key: the key carries whatever a custom handler
-     * returned, which the docs' own example makes an email address. A
-     * failure the limiter throws again (see loggedFailures) is not logged
-     * again.
+     * never the tracker key: digested as its caller's half is, the key is
+     * still the same for every attempt of one caller, and a log is read by
+     * more people than the table. A failure the limiter throws again (see
+     * loggedFailures) is not logged again.
      */
     async countAttempt(name, trackerKey, limits, where) {
         try {
@@ -319,7 +340,7 @@ export class LambderApiRateLimitsEngine {
         if (per === undefined) {
             if (subject.key === undefined)
                 throw new Error(`Lambder: rate-limit policy "${name}" declares no per, so the code charging it passes the key: ctx.rateLimit("${name}", key).`);
-            return await boundKeyField("custom", subject.key);
+            return await this.keyFieldDigest.digestOf("custom", subject.key);
         }
         if (per !== "ip" && per !== "session") {
             throw new Error(`Lambder: rate-limit policy "${name}" derives its key from an API's payload, so only the APIs declaring it can charge it.`);
@@ -332,21 +353,20 @@ export class LambderApiRateLimitsEngine {
         if (per === "ip" || per === "session")
             return await this.requestKeyOf(name, per, request.ip, ctx.session);
         const payload = per.apiInput ? await parsePreflightSlice(per.apiInput, request.payload) : undefined;
-        return await boundKeyField("custom", await per.handler(ctx, payload));
+        return await this.keyFieldDigest.digestOf("custom", await per.handler(ctx, payload));
     }
     /**
      * The key a `per: "ip"` or `per: "session"` policy counts under: what the
-     * request carries, however the policy is charged. A session key is
-     * bounded like a custom one (see boundKeyField); an address needs no
-     * bound, since normalizeClientIp caps it at 45 characters whichever
-     * header or gateway field named it.
+     * request carries, however the policy is charged, digested as a custom
+     * key is. The address is the subject rateLimitSubjectOf counts (an IPv6
+     * caller's /64), so the digest of one subscriber's every address is one.
      */
     async requestKeyOf(name, per, ip, session) {
         if (per === "ip")
-            return `ip:${rateLimitSubjectOf(ip, this.ipv6PrefixLength)}`;
+            return await this.keyFieldDigest.digestOf("ip", rateLimitSubjectOf(ip, this.ipv6PrefixLength));
         const sessionKey = session?.sessionKey;
         if (!sessionKey)
             throw new Error(`Lambder: rate-limit policy "${name}" is keyed per "session", and the request charging it has no session.`);
-        return await boundKeyField("session", sessionKey);
+        return await this.keyFieldDigest.digestOf("session", sessionKey);
     }
 }

package/dist/api/LambderApiRefusals.d.ts

@@ -130,6 +130,8 @@ type LambderRefusalViolation = {
     thrown: unknown;
 } | {
     notObject: string;
+} | {
+    notRateLimitData: true;
 };
 /**
  * A refusal an endpoint is not allowed to send, so it was not sent and the
@@ -137,8 +139,10 @@ type LambderRefusalViolation = {
  * the endpoint does not declare (neither
  * in its own `refusals` option nor through a guard), data on a refusal whose
  * code declares none, no data on one whose code carries data, data its code's
- * schema rejects or that is not an object or an array, or a declared code
- * raised with a status or flag of its own, which its declaration owns.
+ * schema rejects or that is not an object or an array, a framework code
+ * without the data it carries (`lambder/rate-limited`'s policy and wait), or
+ * a declared code raised with a status or flag of its own, which its
+ * declaration owns.
  *
  * What makes a client's refusal type exact: a reader narrows `code` to the
  * endpoint's declared codes and the framework's own, and relies on this to
@@ -162,8 +166,10 @@ export declare class LambderApiRefusalValidationError extends Error {
  * here first.
  *
  * - An uncoded refusal, or one carrying a framework code, goes out as it is,
- *   provided it carries no data. Where the app requires codes, an uncoded
- *   refusal is refused too; a framework code still passes.
+ *   provided it carries the data its code does: the policy and the seconds
+ *   to wait for `lambder/rate-limited`, none for every other. Where the app
+ *   requires codes, an uncoded refusal is refused too; a framework code
+ *   still passes.
  * - A declared code leaves with its declaration's status and flags, and
  *   with data exactly when the code carries data, parsed through
  *   the code's schema as an output is: undeclared fields stripped, defaults

package/dist/api/LambderApiRefusals.js

@@ -1,4 +1,4 @@
-import { LambderApiRefusal, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
+import { LambderApiRefusal, LAMBDER_REFUSAL_CODES, isLambderRefusalCode } from "../shared/wire/LambderApiRefusal.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { mergeNamedMaps } from "../shared/util/LambderNamedMaps.js";
 /**
@@ -22,14 +22,27 @@ export const allowedRefusalOf = (declaration) => {
     };
     return declaration.data === undefined ? { ...leaves, data: false } : { ...leaves, data: true, schema: declaration.data };
 };
+/**
+ * Whether a `lambder/rate-limited` refusal's data is the shape a client
+ * narrows it to: the policy's name, and the whole seconds of at least one
+ * that the Retry-After header carries.
+ */
+const isRateLimitRefusalData = (data) => {
+    if (data === null || typeof data !== "object")
+        return false;
+    const { policy, retryAfterSeconds } = data;
+    return typeof policy === "string" && Number.isInteger(retryAfterSeconds) && retryAfterSeconds >= 1;
+};
 /**
  * A refusal an endpoint is not allowed to send, so it was not sent and the
  * call is answered as a crash: no code where the app requires one, a code
  * the endpoint does not declare (neither
  * in its own `refusals` option nor through a guard), data on a refusal whose
  * code declares none, no data on one whose code carries data, data its code's
- * schema rejects or that is not an object or an array, or a declared code
- * raised with a status or flag of its own, which its declaration owns.
+ * schema rejects or that is not an object or an array, a framework code
+ * without the data it carries (`lambder/rate-limited`'s policy and wait), or
+ * a declared code raised with a status or flag of its own, which its
+ * declaration owns.
  *
  * What makes a client's refusal type exact: a reader narrows `code` to the
  * endpoint's declared codes and the framework's own, and relies on this to
@@ -76,6 +89,10 @@ export class LambderApiRefusalValidationError extends Error {
             message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data its schema threw on while parsing it (a transform that threw, `
                 + "or an async step: a refusal's data is parsed synchronously), so the refusal was not sent.";
         }
+        else if ("notRateLimitData" in violation) {
+            message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data that is not { policy, retryAfterSeconds }, so the refusal was not sent. `
+                + "Refuse a rate limit through ctx.rateLimit, or throw rateLimitRefusal(), which writes the data a client narrows it by.";
+        }
         else {
             message = `Lambder: API "${apiName}" refused with the code "${String(code)}" and data that is ${violation.notObject}, and a refusal's data is an object or an array, so the refusal was not sent.`;
         }
@@ -94,8 +111,10 @@ export class LambderApiRefusalValidationError extends Error {
  * here first.
  *
  * - An uncoded refusal, or one carrying a framework code, goes out as it is,
- *   provided it carries no data. Where the app requires codes, an uncoded
- *   refusal is refused too; a framework code still passes.
+ *   provided it carries the data its code does: the policy and the seconds
+ *   to wait for `lambder/rate-limited`, none for every other. Where the app
+ *   requires codes, an uncoded refusal is refused too; a framework code
+ *   still passes.
  * - A declared code leaves with its declaration's status and flags, and
  *   with data exactly when the code carries data, parsed through
  *   the code's schema as an output is: undeclared fields stripped, defaults
@@ -111,6 +130,13 @@ export const checkedRefusal = (apiName, endpoint, thrown) => {
     if (endpoint === undefined)
         return thrown;
     const { code, data } = thrown.refusal;
+    if (code === LAMBDER_REFUSAL_CODES.rateLimited) {
+        if (data === undefined)
+            throw new LambderApiRefusalValidationError(apiName, thrown, { missingData: code });
+        if (!isRateLimitRefusalData(data))
+            throw new LambderApiRefusalValidationError(apiName, thrown, { notRateLimitData: true });
+        return thrown;
+    }
     if (code === undefined || isLambderRefusalCode(code)) {
         if (code === undefined && endpoint.codeRequired)
             throw new LambderApiRefusalValidationError(apiName, thrown, { uncoded: true });

package/dist/api/LambderApiRequest.d.ts

@@ -27,6 +27,13 @@ export type LambderApiRequest = {
      * expired, which reloads it.
      */
     retiredPath?: true;
+    /**
+     * Set when the call's body is no envelope: not a JSON object (a number,
+     * a string, a boolean, null, an array) or not JSON at all. The
+     * client-facing reason, which the pipeline answers with the
+     * invalid-payload refusal (prepare) before anything reads the call.
+     */
+    invalidEnvelope?: string;
     /** The caller's apiVersion, informational; null when it sent none. */
     version: string | null;
     /** The signature the caller carries for this endpoint (see LambderApiSignatureMap), for the signature gate; null when it sent none. */
@@ -91,10 +98,23 @@ export declare const isApiCallContentType: (lowercasedHeaders: Record<string, st
  * comes from where the call was posted, never from the body. Everything is
  * taken as posted: a malformed idempotencyKey or guardInputs value is the
  * engines' to refuse, with the client-facing message they already give.
+ *
+ * `posted` is the body as JSON parsed it; undefined (no body) reads as an
+ * empty envelope. A body that is not a JSON object, or one the adapter could
+ * not parse (`bodyNotJson`), is flagged on the request as invalidEnvelope
+ * and read as an empty envelope, so every adapter refuses it alike, in the
+ * pipeline, rather than each deciding what such a body means.
  */
-export declare const readApiEnvelope: (post: Record<string, unknown> | null | undefined, info: LambderApiRequestInfo, apiName: string, flags?: {
+export declare const readApiEnvelope: (posted: unknown, info: LambderApiRequestInfo, apiName: string, flags?: {
     retiredPath?: true;
+    bodyNotJson?: true;
 }) => LambderApiRequest;
+/**
+ * readApiEnvelope over a body's text, for an adapter that holds the text and
+ * nothing parsed from it: an empty body reads as an empty envelope, and text
+ * that is not JSON is flagged as no envelope, as the server flags it.
+ */
+export declare const readApiEnvelopeText: (text: string, info: LambderApiRequestInfo, apiName: string) => LambderApiRequest;
 /** Outcome of restoring a compressed request payload; the message is client-facing. */
 export type LambderRestorePayloadResult = {
     ok: true;

package/dist/api/LambderApiRequest.js

@@ -42,20 +42,34 @@ export const lowercaseHeaderNames = (headers) => {
  * read the same rule here.
  */
 export const isApiCallContentType = (lowercasedHeaders) => (lowercasedHeaders["content-type"] ?? "").split(";")[0].trim().toLowerCase() === "application/json";
+/** The one shape an API call's body may take: a JSON object, the envelope every Lambder caller posts. */
+const isEnvelopeObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Why a body that did parse is no envelope, client-facing: its kind, never its value. */
+const notAnEnvelopeMessage = (posted) => `Request body must be a JSON object, got ${Array.isArray(posted) ? "an array" : posted === null ? "null" : `a ${typeof posted}`}.`;
 /**
  * Reads the posted envelope of a call to `apiName` into a request; the name
  * comes from where the call was posted, never from the body. Everything is
  * taken as posted: a malformed idempotencyKey or guardInputs value is the
  * engines' to refuse, with the client-facing message they already give.
+ *
+ * `posted` is the body as JSON parsed it; undefined (no body) reads as an
+ * empty envelope. A body that is not a JSON object, or one the adapter could
+ * not parse (`bodyNotJson`), is flagged on the request as invalidEnvelope
+ * and read as an empty envelope, so every adapter refuses it alike, in the
+ * pipeline, rather than each deciding what such a body means.
  */
-export const readApiEnvelope = (post, info, apiName, flags = {}) => {
-    post ??= {};
+export const readApiEnvelope = (posted, info, apiName, flags = {}) => {
+    const invalidEnvelope = flags.bodyNotJson ? "Request body must be a JSON object, and it is not valid JSON."
+        : posted === undefined || isEnvelopeObject(posted) ? null
+            : notAnEnvelopeMessage(posted);
+    const post = isEnvelopeObject(posted) ? posted : {};
     const hasGzip = post[COMPRESSED_PAYLOAD_GZ_FIELD] !== undefined;
     const hasBrotli = post[COMPRESSED_PAYLOAD_BR_FIELD] !== undefined;
     const guardInputs = post.guardInputs;
     return {
         apiName,
         ...(flags.retiredPath ? { retiredPath: true } : {}),
+        ...(invalidEnvelope !== null ? { invalidEnvelope } : {}),
         version: typeof post.version === "string" ? post.version : null,
         signature: typeof post.signature === "string" ? post.signature : null,
         token: typeof post.token === "string" ? post.token : "",
@@ -76,6 +90,21 @@ export const readApiEnvelope = (post, info, apiName, flags = {}) => {
         ...(info.signal ? { signal: info.signal } : {}),
     };
 };
+/**
+ * readApiEnvelope over a body's text, for an adapter that holds the text and
+ * nothing parsed from it: an empty body reads as an empty envelope, and text
+ * that is not JSON is flagged as no envelope, as the server flags it.
+ */
+export const readApiEnvelopeText = (text, info, apiName) => {
+    let posted;
+    try {
+        posted = JSON.parse(text || "{}");
+    }
+    catch {
+        return readApiEnvelope(undefined, info, apiName, { bodyNotJson: true });
+    }
+    return readApiEnvelope(posted, info, apiName);
+};
 /**
  * Restores a payload the caller sent compressed (`payloadGz` or `payloadBr`,
  * beside `payloadBytes`) onto request.payload, so every later stage

package/dist/build/checkApiRefusals.d.ts

@@ -5,6 +5,8 @@ export type LambderApiRefusalCheckOptions = {
     files?: string[];
     /** Whether a refusal with no code is a finding, as it is a crash in an app whose vocabulary requires codes (declareRefusals's requireCodes). Default: true. */
     requireCodes?: boolean;
+    /** Whether a handler handed no typed refuse is a finding, since nothing it reaches could be checked. Default: true; false lists such handlers without failing. */
+    requireTypedRefuse?: boolean;
 };
 /** What one handler's check found. */
 export type LambderRefusalCheckFinding = {
@@ -20,15 +22,18 @@ export type LambderRefusalCheckFinding = {
      * - `untraced`: a handler handed a typed refuse whose function cannot be
      *   found (a parameter, a dependency's value), so nothing it reaches was
      *   checked.
+     * - `unchecked`: a handler handed no typed refuse, built by an init that
+     *   declared no refusal vocabulary, so there is nothing to hold what it
+     *   reaches to. Not a finding with `requireTypedRefuse: false`.
      */
-    problem: "undeclared" | "unused" | "uncoded" | "unreadable" | "untraced";
+    problem: "undeclared" | "unused" | "uncoded" | "unreadable" | "untraced" | "unchecked";
     /** The code, for `undeclared` and `unused`. */
     code?: string;
     /** Where the refusal is raised, as `file:line`, for `undeclared`, `uncoded` and `unreadable`. */
     raisedAt?: string;
 };
 export type LambderApiRefusalCheckResult = {
-    /** False when the project could not be read, no handler in it could be checked, or any handler has a finding. */
+    /** False when the project could not be read, no handler in it could be checked, or any handler has a finding, an unchecked one included unless `requireTypedRefuse` is false. */
     ok: boolean;
     /** How many handlers were checked. */
     handlers: number;

package/dist/build/checkApiRefusals.js

@@ -27,6 +27,7 @@ const HANDLER_REGISTRATIONS = {
 export const checkApiRefusals = async (options) => {
     const ts = await loadTypeScriptCompiler("checkApiRefusals reads the project");
     const requireCodes = options.requireCodes ?? true;
+    const requireTypedRefuse = options.requireTypedRefuse ?? true;
     const configPath = resolve(options.tsconfig);
     const read = ts.readConfigFile(configPath, ts.sys.readFile);
     if (read.error)
@@ -106,27 +107,42 @@ export const checkApiRefusals = async (options) => {
             return [{ at, unreadable: true }];
         return values.map((value) => ({ at, code: value }));
     };
+    /**
+     * Whether a signature's declaration (one of Lambder's) is a refuse
+     * function: a function type in LambderDeclaredRefuse, which types every
+     * context's, guard's and init's refuse, or the type of something Lambder
+     * declares as `refuse`, the free refuse() and the members an emitted
+     * declaration file spells out in place of the alias. Read off the
+     * declaration rather than off the call, so a refuse the app reaches under
+     * a name of its own (an import renamed, a context's refuse held in a
+     * variable or destructured under another name, a parameter typed as one)
+     * is a raise all the same.
+     */
+    const isRefuseDeclaration = (declaration) => {
+        let node = declaration;
+        while (ts.isTypeNode(node.parent))
+            node = node.parent;
+        const holder = node.parent;
+        if (ts.isTypeAliasDeclaration(holder))
+            return holder.name.text === "LambderDeclaredRefuse";
+        return (ts.isVariableDeclaration(holder) || ts.isPropertySignature(holder) || ts.isPropertyDeclaration(holder))
+            && holder.type === node && ts.isIdentifier(holder.name) && holder.name.text === "refuse";
+    };
     /**
      * The refusal a call or construction raises, when it is one of Lambder's
-     * refuse functions or its refusal class's constructor. The constructor is
-     * told by the signature the call resolves to rather than by the name
-     * written, so it counts constructed as itself, as a class of the app's
-     * own that declares no constructor and inherits it, or as the super() of
-     * one that declares its own, which is then raised wherever that class is
-     * constructed.
+     * refuse functions or its refusal class's constructor. Both are told by
+     * the signature the call resolves to rather than by the name written, so
+     * a refuse counts however the app names it, and the constructor counts
+     * constructed as itself, as a class of the app's own that declares no
+     * constructor and inherits it, or as the super() of one that declares
+     * its own, which is then raised wherever that class is constructed.
      */
     const raiseSitesOf = (node) => {
-        const callee = node.expression;
-        const constructs = ts.isNewExpression(node) || callee.kind === ts.SyntaxKind.SuperKeyword;
-        if (!constructs) {
-            const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : null;
-            if (name !== "refuse")
-                return [];
-        }
+        const constructs = ts.isNewExpression(node) || node.expression.kind === ts.SyntaxKind.SuperKeyword;
         const declaration = checker.getResolvedSignature(node)?.declaration;
-        if (!isLambderDeclaration(declaration))
+        if (!declaration || !isLambderDeclaration(declaration))
             return [];
-        if (constructs && !(declaration && ts.isConstructorDeclaration(declaration) && declaration.parent.name?.text === "LambderApiRefusal"))
+        if (constructs ? !(ts.isConstructorDeclaration(declaration) && declaration.parent.name?.text === "LambderApiRefusal") : !isRefuseDeclaration(declaration))
             return [];
         const args = node.arguments ?? ts.factory.createNodeArray();
         return constructs ? codeOfOptions(args[1], "refusal", where(node)) : codeOfOptions(args[1], "code", where(node));
@@ -269,14 +285,20 @@ export const checkApiRefusals = async (options) => {
         }
         return [...codes];
     };
-    /** The codes an options object's `refusals` property names: one code or a list, each a literal or a constant typed as one. */
+    /**
+     * The codes an options object's `refusals` property names: one code or a
+     * list, each a literal or a constant typed as one. Null where it has no
+     * such property, which for a guard built without the vocabulary is the
+     * difference between declaring no codes (`refusals: []`) and saying
+     * nothing of what it may send.
+     */
     const ownRefusalsOf = (optionsNode) => {
         const options = optionsNode && unwrap(optionsNode);
         if (!options || !ts.isObjectLiteralExpression(options))
-            return [];
+            return null;
         const property = options.properties.find((candidate) => ts.isPropertyAssignment(candidate) && ts.isIdentifier(candidate.name) && candidate.name.text === "refusals");
         if (!property || !ts.isPropertyAssignment(property))
-            return [];
+            return null;
         const value = unwrap(property.initializer);
         const entries = ts.isArrayLiteralExpression(value) ? [...value.elements] : [value];
         return entries.flatMap((entry) => ts.isStringLiteralLike(entry) ? [entry.text] : literalsOf(checker.getTypeAtLocation(entry)) ?? []);
@@ -334,9 +356,11 @@ export const checkApiRefusals = async (options) => {
             return;
         const name = handlerNameOf(call, registration);
         const at = where(call);
-        const allowed = allowedCodesOf(handler) ?? (registration === "guard" || registration === "lambderGuard" ? ownRefusalsOfOrNull(optionsNode) : null);
+        // A guard built without the vocabulary may send the codes its own
+        // refusals option names, which is what the server checks it against.
+        const allowed = allowedCodesOf(handler) ?? (registration === "guard" || registration === "lambderGuard" ? ownRefusalsOf(optionsNode) : null);
         if (allowed === null) {
-            unchecked.push(`${name} (${at})`);
+            unchecked.push({ handler: name, at, problem: "unchecked" });
             return;
         }
         handlers += 1;
@@ -366,16 +390,11 @@ export const checkApiRefusals = async (options) => {
                 findings.push({ handler: name, at, problem: "unreadable", raisedAt: raise.at });
             }
         }
-        for (const code of ownRefusalsOf(optionsNode)) {
+        for (const code of ownRefusalsOf(optionsNode) ?? []) {
             if (!reached.has(code))
                 findings.push({ handler: name, at, problem: "unused", code });
         }
     };
-    /** A guard's `refusals` option, or null when it has none: what a guard built without the vocabulary may send. */
-    const ownRefusalsOfOrNull = (optionsNode) => {
-        const own = ownRefusalsOf(optionsNode);
-        return own.length ? own : null;
-    };
     for (const sourceFile of program.getSourceFiles()) {
         if (!isOwnFile(sourceFile))
             continue;
@@ -386,16 +405,23 @@ export const checkApiRefusals = async (options) => {
         };
         visit(sourceFile);
     }
-    const uncheckedLine = unchecked.length ? [`  ${unchecked.length} ${unchecked.length === 1 ? "handler has" : "handlers have"} no typed refuse to check against: ${unchecked.join(", ")}`] : [];
+    // Found, or only listed where the caller lets them stand unchecked.
+    if (requireTypedRefuse)
+        findings.push(...unchecked);
+    const uncheckedLine = !requireTypedRefuse && unchecked.length
+        ? [`  ${unchecked.length} ${unchecked.length === 1 ? "handler has" : "handlers have"} no typed refuse to check against: ${unchecked.map(({ handler, at }) => `${handler} (${at})`).join(", ")}`]
+        : [];
     if (handlers === 0) {
-        return failed(`✗ ${options.tsconfig}: no handler Lambder hands a typed refuse was found, so nothing was checked. Do its APIs come from an init that declares its refusals (declareRefusals), and do its files resolve lambder?`, uncheckedLine);
+        const nothingChecked = `✗ ${options.tsconfig}: no handler Lambder hands a typed refuse was found, so nothing was checked. Do its APIs come from an init that declares its refusals (declareRefusals), and do its files resolve lambder?`;
+        return { ...failed(nothingChecked, [...findings.map(describeFinding), ...uncheckedLine]), findings };
     }
     // Duplicate uncoded or unreadable findings of one site through two paths say the same thing once.
     const unique = [...new Map(findings.map((finding) => [JSON.stringify(finding), finding])).values()];
     const lines = [
         unique.length === 0
             ? `✓ ${handlers} handlers reach only the refusals they may send`
-            : `✗ ${unique.length} refusal ${unique.length === 1 ? "finding" : "findings"} in ${new Set(unique.map((finding) => finding.handler)).size} of ${handlers} handlers`,
+            // Out of every handler found, the unchecked ones among them, which are never counted as checked.
+            : `✗ ${unique.length} refusal ${unique.length === 1 ? "finding" : "findings"} in ${new Set(unique.map((finding) => finding.handler)).size} of ${handlers + unchecked.length} handlers`,
         ...unique.map(describeFinding),
         ...uncheckedLine,
     ];
@@ -408,6 +434,7 @@ const describeFinding = (finding) => {
         case "uncoded": return `  ${finding.handler} (${finding.at}) can reach a refusal with no code (${finding.raisedAt})`;
         case "unreadable": return `  ${finding.handler} (${finding.at}) can reach a refusal whose code is not a string literal (${finding.raisedAt}), so which code it sends cannot be told`;
         case "untraced": return `  ${finding.handler} (${finding.at}) is handed a typed refuse, but its function cannot be found (a parameter, a dependency's value), so nothing it reaches was checked`;
+        case "unchecked": return `  ${finding.handler} (${finding.at}) is handed no typed refuse, so nothing it reaches could be checked: build it from an init that declares the refusal vocabulary (declareRefusals, on initLambderMock() as on initLambder()), or give a guard a refusals option naming the codes it may send`;
     }
 };
 const failed = (line, details = []) => ({ ok: false, handlers: 0, findings: [], lines: [line, ...details] });

package/dist/build/contractPrinterProcess.d.ts

@@ -0,0 +1,11 @@
+import { type LambderApiContractFileOptions, type LambderApiContractFileResult } from "./writeApiContract.js";
+/** writeApiContract's options as they cross the process boundary: the module as a string, a URL by its href. */
+export type ContractPrinterRequest = Omit<LambderApiContractFileOptions, "module"> & {
+    module: string;
+};
+/** The result, or the messages of what was thrown, outermost first, down its chain of causes. */
+export type ContractPrinterReport = {
+    result: LambderApiContractFileResult;
+} | {
+    thrown: string[];
+};

package/dist/build/contractPrinterProcess.js

@@ -0,0 +1,17 @@
+import { CONTRACT_REPORT_PREFIX } from "./generateApiFiles.js";
+import { writeApiContract } from "./writeApiContract.js";
+const request = JSON.parse(process.argv[2] ?? "null");
+let report;
+try {
+    report = { result: await writeApiContract(request) };
+}
+catch (err) {
+    const thrown = err instanceof Error ? [] : [String(err)];
+    for (let cause = err; cause instanceof Error && thrown.length < 8; cause = cause.cause)
+        thrown.push(cause.message);
+    report = { thrown };
+}
+// Waited for: a write to a pipe can still be pending when the process exits,
+// and the parent reads the pipe.
+await new Promise((resolveWrite) => process.stdout.write(`\n${CONTRACT_REPORT_PREFIX}${JSON.stringify(report)}\n`, () => resolveWrite()));
+process.exit(0);