lambder 8.1.2 → 8.3.1

package/dist/shared/util/LambderSignedClaims.d.ts

@@ -0,0 +1,78 @@
+import type { z } from "zod";
+export type LambderSignedClaimsOptions<TClaims> = {
+    /** The HMAC key. Server side, and every runtime that verifies; never a browser. */
+    secret: string;
+    /**
+     * Names this kind of token, as the first segment of every one it signs;
+     * a token of another version does not verify. Any text without a dot.
+     */
+    version: string;
+    /** The claims' shape, parsed on the way out and on the way back, so a token never carries a shape the app did not declare. */
+    schema: z.ZodType<TClaims>;
+    /** The clock `exp` is judged against, in epoch milliseconds. Default: Date.now. */
+    now?: () => number;
+};
+/**
+ * Refuses a claims type whose `exp` is not a number, at the constructor: the
+ * class would judge it as an expiry, find no number, and let the token live
+ * for ever. The property name is the message.
+ */
+type LambderExpIsSeconds<TClaims> = TClaims extends {
+    exp: infer E;
+} ? ([E] extends [number] ? unknown : {
+    readonly "lambder: the exp claim is an expiry in epoch seconds, so the schema must declare it as a number.": never;
+}) : unknown;
+/**
+ * One kind of signed token: constructed once with its secret, version and
+ * claims schema, it keeps the imported HMAC key and answers `sign` and
+ * `verify`. An app declares one instance per kind of token it hands out.
+ *
+ * The one claim with a meaning here is `exp`, an expiry in epoch seconds,
+ * the unit sessions, DynamoDB's TTL and JWTs use. A schema that declares it
+ * gets it checked on every verify; a schema without it declares a token that
+ * does not expire on its own, which is right where the thing the token names
+ * (a request, a message) decides what it may still do.
+ *
+ * `verify` answers null for every failure alike: a forged signature, another
+ * version, malformed text, claims the schema refuses, an `exp` in the past.
+ * A caller cannot tell them apart, and so cannot tell a client apart either.
+ */
+export declare class LambderSignedClaims<TClaims extends object> {
+    private readonly secret;
+    private readonly version;
+    private readonly schema;
+    private readonly now;
+    /** Imported on first use and kept: signing and verifying share one key object for the life of the instance. */
+    private keyPromise;
+    constructor(options: LambderSignedClaimsOptions<TClaims> & LambderExpIsSeconds<TClaims>);
+    /** The token for these claims, which the schema parses first. `exp`, when the schema has it, is epoch seconds. */
+    sign(claims: TClaims): Promise<string>;
+    /**
+     * The claims, when the token is this version, signed under this secret,
+     * well formed, accepted by the schema and not past its `exp`; null
+     * otherwise, for every reason alike. `now`, in epoch milliseconds, is the
+     * moment `exp` is judged against for this call; default: the clock's.
+     */
+    verify(token: string, options?: {
+        now?: number;
+    }): Promise<TClaims | null>;
+    private key;
+}
+/**
+ * The keyed digest of a secret an app stores and later looks up or compares
+ * by value: a device's secret, a code sent by email, a pairing code. Keyed
+ * under the app's secret rather than a plain hash, so a copied table alone
+ * cannot be attacked offline, and deterministic, so a lookup is one indexed
+ * read. HMAC-SHA256 as 43 characters of base64url; compare two with
+ * constantTimeEquals.
+ */
+export declare const keyedDigest: (secret: string, value: string) => Promise<string>;
+/**
+ * A fresh secret from the runtime's cryptographic random source, as base64url
+ * (43 characters for the default 32 bytes): the credential a paired device
+ * keeps, the token in a link that must not be guessable. Synchronous, since
+ * getRandomValues is, on every runtime with a WebCrypto global; a runtime
+ * without one is told so.
+ */
+export declare const randomSecret: (bytes?: number) => string;
+export {};

package/dist/shared/util/LambderSignedClaims.js

@@ -0,0 +1,109 @@
+import { base64UrlToBytes, bytesToBase64Url, isBase64Url } from "./LambderBase64.js";
+import { hmacSha256Of, importHmacKey, resolveWebCrypto } from "./LambderTextDigest.js";
+/**
+ * One kind of signed token: constructed once with its secret, version and
+ * claims schema, it keeps the imported HMAC key and answers `sign` and
+ * `verify`. An app declares one instance per kind of token it hands out.
+ *
+ * The one claim with a meaning here is `exp`, an expiry in epoch seconds,
+ * the unit sessions, DynamoDB's TTL and JWTs use. A schema that declares it
+ * gets it checked on every verify; a schema without it declares a token that
+ * does not expire on its own, which is right where the thing the token names
+ * (a request, a message) decides what it may still do.
+ *
+ * `verify` answers null for every failure alike: a forged signature, another
+ * version, malformed text, claims the schema refuses, an `exp` in the past.
+ * A caller cannot tell them apart, and so cannot tell a client apart either.
+ */
+export class LambderSignedClaims {
+    secret;
+    version;
+    schema;
+    now;
+    /** Imported on first use and kept: signing and verifying share one key object for the life of the instance. */
+    keyPromise;
+    constructor(options) {
+        if (typeof options.secret !== "string" || options.secret.length === 0) {
+            throw new Error("Lambder: LambderSignedClaims needs a secret to sign with.");
+        }
+        if (typeof options.version !== "string" || options.version.length === 0 || options.version.includes(".")) {
+            throw new Error(`Lambder: LambderSignedClaims version must be text without a dot, got ${JSON.stringify(options.version)}: it is the first of the token's three dot-separated segments.`);
+        }
+        this.secret = options.secret;
+        this.version = options.version;
+        this.schema = options.schema;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** The token for these claims, which the schema parses first. `exp`, when the schema has it, is epoch seconds. */
+    async sign(claims) {
+        const body = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(this.schema.parse(claims))));
+        const message = `${this.version}.${body}`;
+        const webCrypto = await resolveWebCrypto();
+        const mac = await webCrypto.subtle.sign("HMAC", await this.key(webCrypto), new TextEncoder().encode(message));
+        return `${message}.${bytesToBase64Url(new Uint8Array(mac))}`;
+    }
+    /**
+     * The claims, when the token is this version, signed under this secret,
+     * well formed, accepted by the schema and not past its `exp`; null
+     * otherwise, for every reason alike. `now`, in epoch milliseconds, is the
+     * moment `exp` is judged against for this call; default: the clock's.
+     */
+    async verify(token, options = {}) {
+        const parts = token.split(".");
+        if (parts.length !== 3 || parts[0] !== this.version)
+            return null;
+        const [, body, mac] = parts;
+        if (!isBase64Url(body) || !isBase64Url(mac))
+            return null;
+        // The last character of a MAC carries bits decoding ignores, so four
+        // spellings decode to the same bytes. Only the one sign() writes is a
+        // token: an app that keys anything on the token string (a list of
+        // spent tokens, a rate limit) must not meet the same token again
+        // under another spelling.
+        const macBytes = base64UrlToBytes(mac);
+        if (bytesToBase64Url(macBytes) !== mac)
+            return null;
+        const webCrypto = await resolveWebCrypto();
+        const valid = await webCrypto.subtle.verify("HMAC", await this.key(webCrypto), macBytes, new TextEncoder().encode(`${this.version}.${body}`));
+        if (!valid)
+            return null;
+        let claims;
+        try {
+            claims = this.schema.parse(JSON.parse(new TextDecoder().decode(base64UrlToBytes(body))));
+        }
+        catch {
+            return null;
+        }
+        const exp = claims.exp;
+        if (typeof exp === "number" && exp * 1000 <= (options.now ?? this.now()))
+            return null;
+        return claims;
+    }
+    key(webCrypto) {
+        this.keyPromise ??= importHmacKey(webCrypto, this.secret, ["sign", "verify"]);
+        return this.keyPromise;
+    }
+}
+/**
+ * The keyed digest of a secret an app stores and later looks up or compares
+ * by value: a device's secret, a code sent by email, a pairing code. Keyed
+ * under the app's secret rather than a plain hash, so a copied table alone
+ * cannot be attacked offline, and deterministic, so a lookup is one indexed
+ * read. HMAC-SHA256 as 43 characters of base64url; compare two with
+ * constantTimeEquals.
+ */
+export const keyedDigest = async (secret, value) => bytesToBase64Url(await hmacSha256Of(secret, value));
+/**
+ * A fresh secret from the runtime's cryptographic random source, as base64url
+ * (43 characters for the default 32 bytes): the credential a paired device
+ * keeps, the token in a link that must not be guessable. Synchronous, since
+ * getRandomValues is, on every runtime with a WebCrypto global; a runtime
+ * without one is told so.
+ */
+export const randomSecret = (bytes = 32) => {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues !== "function") {
+        throw new Error("Lambder needs crypto.getRandomValues in this runtime to mint a secret. Every browser provides it; Node 20+ provides it as globalThis.crypto.");
+    }
+    return bytesToBase64Url(webCrypto.getRandomValues(new Uint8Array(bytes)));
+};

package/dist/shared/util/LambderTextDigest.d.ts

@@ -1,9 +1,11 @@
 /**
- * SHA-256 through WebCrypto: the one digest every layer shares. The session
- * crypto hashes bearer secrets with it and the rate-limit engine folds an
- * over-long tracker key with it, so both key spaces are built from the same
- * primitive on every runtime (browsers on a secure context, Node 20+, edge
- * runtimes); an upload's checksum is the same digest over the file's bytes.
+ * SHA-256 and HMAC-SHA256 through WebCrypto: the digests every layer shares.
+ * The session crypto hashes bearer secrets with the first and partitions
+ * session keys with the second, the rate-limit engine folds an over-long
+ * tracker key, signed claims and keyed digests are HMACs under an app's
+ * secret, so every key space is built from the same primitives on every
+ * runtime (browsers on a secure context, Node 20+, edge runtimes); an
+ * upload's checksum is the same digest over the file's bytes.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export declare const bytesToHexString: (bytes: Uint8Array) => string;
@@ -17,3 +19,15 @@ export declare const resolveWebCrypto: () => Promise<Crypto>;
 export declare const sha256HexOf: (text: string) => Promise<string>;
 /** The SHA-256 digest of `bytes`, as base64: the form object storage checks an upload's checksum in. */
 export declare const sha256Base64Of: (bytes: Uint8Array) => Promise<string>;
+/** An HMAC-SHA256 key over `secret` (UTF-8), for `usages`; a holder that signs often keeps the key rather than importing it per call. */
+export declare const importHmacKey: (webCrypto: Crypto, secret: string, usages?: KeyUsage[]) => Promise<CryptoKey>;
+/** HMAC-SHA256 of `text` under `secret` (both UTF-8), as bytes. */
+export declare const hmacSha256Of: (secret: string, text: string) => Promise<Uint8Array>;
+/**
+ * Length-aware, timing-neutral string comparison: no early exit on the first
+ * differing character, so how long it takes says nothing about where two
+ * digests part. For comparing a stored digest with the digest of a candidate;
+ * a signature is verified by WebCrypto, which compares in constant time
+ * itself.
+ */
+export declare const constantTimeEquals: (a: string, b: string) => boolean;

package/dist/shared/util/LambderTextDigest.js

@@ -1,11 +1,13 @@
 import { bytesToBase64 } from "./LambderBase64.js";
 import { getCrypto } from "./LambderNodeModules.js";
 /**
- * SHA-256 through WebCrypto: the one digest every layer shares. The session
- * crypto hashes bearer secrets with it and the rate-limit engine folds an
- * over-long tracker key with it, so both key spaces are built from the same
- * primitive on every runtime (browsers on a secure context, Node 20+, edge
- * runtimes); an upload's checksum is the same digest over the file's bytes.
+ * SHA-256 and HMAC-SHA256 through WebCrypto: the digests every layer shares.
+ * The session crypto hashes bearer secrets with the first and partitions
+ * session keys with the second, the rate-limit engine folds an over-long
+ * tracker key, signed claims and keyed digests are HMACs under an app's
+ * secret, so every key space is built from the same primitives on every
+ * runtime (browsers on a secure context, Node 20+, edge runtimes); an
+ * upload's checksum is the same digest over the file's bytes.
  */
 /** Lowercase hex of a byte array, two characters per byte. */
 export const bytesToHexString = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -38,3 +40,26 @@ export const sha256Base64Of = async (bytes) => {
     const webCrypto = await resolveWebCrypto();
     return bytesToBase64(new Uint8Array(await webCrypto.subtle.digest("SHA-256", bytes)));
 };
+/** An HMAC-SHA256 key over `secret` (UTF-8), for `usages`; a holder that signs often keeps the key rather than importing it per call. */
+export const importHmacKey = async (webCrypto, secret, usages = ["sign"]) => await webCrypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, usages);
+/** HMAC-SHA256 of `text` under `secret` (both UTF-8), as bytes. */
+export const hmacSha256Of = async (secret, text) => {
+    const webCrypto = await resolveWebCrypto();
+    const key = await importHmacKey(webCrypto, secret);
+    return new Uint8Array(await webCrypto.subtle.sign("HMAC", key, new TextEncoder().encode(text)));
+};
+/**
+ * Length-aware, timing-neutral string comparison: no early exit on the first
+ * differing character, so how long it takes says nothing about where two
+ * digests part. For comparing a stored digest with the digest of a candidate;
+ * a signature is verified by WebCrypto, which compares in constant time
+ * itself.
+ */
+export const constantTimeEquals = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let difference = 0;
+    for (let i = 0; i < a.length; i += 1)
+        difference |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return difference === 0;
+};

package/dist/shared/util/assertPlainData.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a value survives JSON unchanged, and so can be written into a
+ * generated module as the data it is: strings, finite numbers, booleans,
+ * null, and arrays and plain objects of them. Anything else (a function, a
+ * class instance such as a zod schema, a symbol, a bigint, NaN, undefined
+ * inside a container) is code or a shape JSON would silently rewrite, and
+ * the caller is told where it sits.
+ */
+export declare const assertPlainData: (value: unknown, subject: string) => void;

package/dist/shared/util/assertPlainData.js

@@ -0,0 +1,41 @@
+/**
+ * Whether a value survives JSON unchanged, and so can be written into a
+ * generated module as the data it is: strings, finite numbers, booleans,
+ * null, and arrays and plain objects of them. Anything else (a function, a
+ * class instance such as a zod schema, a symbol, a bigint, NaN, undefined
+ * inside a container) is code or a shape JSON would silently rewrite, and
+ * the caller is told where it sits.
+ */
+export const assertPlainData = (value, subject) => {
+    const offence = findNonPlain(value, "");
+    if (offence === null)
+        return;
+    throw new Error(`Lambder: ${subject} must be plain data (strings, finite numbers, booleans, null, and arrays and plain objects of them) to be written as a value, but ${offence.path || "it"} is ${offence.kind}.`);
+};
+const findNonPlain = (value, path) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return null;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? null : { path, kind: String(value) };
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const offence = findNonPlain(value[index], `${path}[${index}]`);
+            if (offence)
+                return offence;
+        }
+        return null;
+    }
+    if (typeof value === "object") {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return { path, kind: `an instance of ${value.constructor?.name || "a class"}` };
+        }
+        for (const [key, member] of Object.entries(value)) {
+            const offence = findNonPlain(member, path ? `${path}.${key}` : key);
+            if (offence)
+                return offence;
+        }
+        return null;
+    }
+    return { path, kind: typeof value === "function" ? "a function" : `a ${typeof value}` };
+};

package/dist/shared/wire/LambderApiOptionEntries.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The declared options of an app's APIs as plain data: what
+ * `lambder.apiOptionEntries()` reports and `writeApiOptions` (lambder/build)
+ * writes to a module a mock or a test imports instead of the server. The
+ * contract carries the same options as types; this is the same fact as a
+ * value, for the code that has to decide something at runtime with it (which
+ * declarations a mock restates, which APIs a test walks). A screen reads one
+ * guard's parameters instead (writeApiGuardParams), since this table names
+ * every endpoint.
+ *
+ * Declared here, below the contract and the engines, for the reason
+ * LambderApiOptionValues is: the generated module names these types through
+ * `lambder/client`, the instance method fills them, and neither may reach
+ * into `api/`. The three vocabularies the engines share with the entries
+ * (when a guard runs, what a budget spans, when a custom key is charged) are
+ * declared here too and re-exported by the engines that read them.
+ */
+import type { LambderApiMode, LambderGuardNamesIn } from "./LambderApiContract.js";
+import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
+import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
+import type { LambderRateLimitPolicy } from "../contracts/LambderRateLimiter.js";
+/**
+ * When a guard runs, relative to the API's input validation.
+ *
+ * - "beforeInputValidation" (default): an unauthorized caller learns nothing
+ *   about the input, and no async refinement in the schema runs for it.
+ * - "afterInputValidation": for a guard that spends something on the
+ *   request, such as a single-use captcha token, which a request refused for
+ *   a mistyped field would otherwise waste. The API's input schema then runs
+ *   for callers this guard would refuse, so keep lookups (an "email is free"
+ *   refinement) out of it, in the handler.
+ *
+ * Guards run in their declared order within each, and the limits keyed by
+ * caller data are charged after both unless their policy says otherwise
+ * (LambderRateLimitChargeAt).
+ */
+export type LambderGuardRunAt = "beforeInputValidation" | "afterInputValidation";
+/**
+ * What one rate-limit budget spans:
+ *
+ * - "perApi" (default): every API referencing the policy gets its own
+ *   counter, so the windows are a per-API ceiling (three APIs referencing a
+ *   60/min policy allow one subject 180/min in total). An API may tune the
+ *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
+ * - "perPolicy": every API referencing the policy shares ONE counter, so the
+ *   windows are one combined budget (e.g. one per-email allowance across
+ *   send, register, and reset). The policy IS the group: to give user APIs
+ *   and report APIs separate shared budgets, declare two policies.
+ */
+export type LambderRateLimitBudget = "perApi" | "perPolicy";
+/**
+ * When a custom-keyed policy is charged, relative to the guards and the input
+ * schema.
+ *
+ * - "afterGuards" (default): after every guard and the input schema passed.
+ *   The key is a value the caller chose (an email in the payload), so a
+ *   caller who never passes a captcha guard cannot spend a victim's budget
+ *   and lock them out of reset, register and send-code.
+ * - "beforeGuards": before the guards and the input schema, so an attempt
+ *   they refuse is counted too. For a limit on guessing a secret a guard or
+ *   the schema checks (a one-time code checked by a guard, keyed per email):
+ *   charged after them, a wrong guess is refused before it is ever counted.
+ *   Pair it with an IP limit, since anyone may spend this budget.
+ */
+export type LambderRateLimitChargeAt = "beforeGuards" | "afterGuards";
+/**
+ * One API as the generated module records it: its mode and its three
+ * declarative options exactly as written at registration. A guard's
+ * parameter is written as the JSON it is (a permission string, a list of
+ * them, a reason), which is what makes the module plain data: a parameter
+ * that is code or a class instance fails the write and names the API.
+ */
+export type LambderApiOptionEntry = {
+    mode: LambderApiMode;
+    guards?: LambderGuardsOptionValue;
+    rateLimit?: LambderRateLimitOptionValue;
+    idempotency?: LambderApiIdempotencyOption;
+};
+/**
+ * One rate-limit policy as the generated module records it: its windows,
+ * budget, charge point and message as declared, and its key reduced to what
+ * it counts. A policy keyed by a handler of the app's is `per: "custom"` and
+ * nothing more: the handler is code, and never written. A policy with no
+ * `per` is charged by code with a key of its own and has none here either.
+ */
+export type LambderRateLimitPolicyEntry = LambderRateLimitPolicy & {
+    per?: "ip" | "session" | "custom";
+    budget?: LambderRateLimitBudget;
+    chargeAt?: LambderRateLimitChargeAt;
+    errorMessage?: LambderAppRefusalMessage;
+};
+/**
+ * One guard as the generated module records it: how it is fed (a slice of
+ * the API's own payload, a value the client sends separately, or nothing),
+ * whether it needs a session, and when it runs. The schema behind an input
+ * mode is never written; the mode alone is what a mock guard standing in for
+ * it has to match.
+ */
+export type LambderGuardDeclarationEntry = {
+    input: "apiInput" | "guardInput" | "none";
+    session: boolean;
+    runAt: LambderGuardRunAt;
+};
+/** Everything `lambder.apiOptionEntries()` reports, and the three tables the generated module exports. */
+export type LambderApiOptionEntries = {
+    apis: Record<string, LambderApiOptionEntry>;
+    rateLimitPolicies: Record<string, LambderRateLimitPolicyEntry>;
+    guards: Record<string, LambderGuardDeclarationEntry>;
+};
+/** The names of the APIs in a generated `apiOptions` table whose guards option names guard N, in any of its three forms and whatever else it declares beside it. */
+export type LambderApisWithGuard<TOptions, N extends string> = {
+    [K in keyof TOptions]: TOptions[K] extends {
+        guards: infer G;
+    } ? (N extends LambderGuardNamesIn<G> ? K : never) : never;
+}[keyof TOptions] & string;
+/**
+ * The names of the APIs whose guards option is exactly TGuards: the APIs
+ * behind `"platformAdmin"` alone, say, and not those that declare it beside
+ * another guard. For a list a test loops over, checked against the table in
+ * both directions.
+ */
+export type LambderApisGuardedBy<TOptions, TGuards> = {
+    [K in keyof TOptions]: TOptions[K] extends {
+        guards: infer G;
+    } ? ([G] extends [TGuards] ? K : never) : never;
+}[keyof TOptions] & string;
+/** The names of the APIs of one mode in a generated `apiOptions` table. */
+export type LambderApisWithMode<TOptions, M extends LambderApiMode> = {
+    [K in keyof TOptions]: TOptions[K] extends {
+        mode: M;
+    } ? K : never;
+}[keyof TOptions] & string;
+/**
+ * The parameter an API's guards option gives guard N: the value in the map
+ * form, `true` for a guard named without one (the string and list forms, or
+ * `true` in the map), and `undefined` for an API that does not declare it.
+ */
+export type LambderGuardParamOf<TEntry, N extends string> = TEntry extends {
+    guards: infer G;
+} ? G extends string ? (N extends G ? true : undefined) : G extends readonly string[] ? (N extends G[number] ? true : undefined) : N extends keyof G ? G[N] : undefined : undefined;
+/**
+ * The parameter an API's guards option gives guard N, read off a generated
+ * `apiOptions` table with the type the table pins: the literal a permission
+ * was declared as, `true` for a guard named without a parameter, and
+ * `undefined` when the API does not declare the guard. What a test or a mock
+ * reads instead of the source.
+ */
+export declare const apiGuardParam: <TOptions extends Record<string, LambderApiOptionEntry>, K extends keyof TOptions & string, N extends string>(options: TOptions, name: K, guard: N) => LambderGuardParamOf<TOptions[K], N>;

package/dist/shared/wire/LambderApiOptionEntries.js

@@ -0,0 +1,35 @@
+/**
+ * The declared options of an app's APIs as plain data: what
+ * `lambder.apiOptionEntries()` reports and `writeApiOptions` (lambder/build)
+ * writes to a module a mock or a test imports instead of the server. The
+ * contract carries the same options as types; this is the same fact as a
+ * value, for the code that has to decide something at runtime with it (which
+ * declarations a mock restates, which APIs a test walks). A screen reads one
+ * guard's parameters instead (writeApiGuardParams), since this table names
+ * every endpoint.
+ *
+ * Declared here, below the contract and the engines, for the reason
+ * LambderApiOptionValues is: the generated module names these types through
+ * `lambder/client`, the instance method fills them, and neither may reach
+ * into `api/`. The three vocabularies the engines share with the entries
+ * (when a guard runs, what a budget spans, when a custom key is charged) are
+ * declared here too and re-exported by the engines that read them.
+ */
+/**
+ * The parameter an API's guards option gives guard N, read off a generated
+ * `apiOptions` table with the type the table pins: the literal a permission
+ * was declared as, `true` for a guard named without a parameter, and
+ * `undefined` when the API does not declare the guard. What a test or a mock
+ * reads instead of the source.
+ */
+export const apiGuardParam = (options, name, guard) => {
+    const guards = options[name]?.guards;
+    let param;
+    if (typeof guards === "string")
+        param = guards === guard ? true : undefined;
+    else if (Array.isArray(guards))
+        param = guards.includes(guard) ? true : undefined;
+    else if (guards !== undefined && Object.prototype.hasOwnProperty.call(guards, guard))
+        param = guards[guard];
+    return param;
+};

package/dist/stores/LambderDdbOneShotSecretStore.d.ts

@@ -0,0 +1,64 @@
+import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { LambderOneShotIssueOutcome, LambderOneShotSecretDraft, LambderOneShotSecretRecord, LambderOneShotSecretStore } from "../shared/contracts/LambderOneShotSecretStore.js";
+export interface LambderDdbOneShotSecretStoreOptions {
+    tableName: string;
+    /** Region the client is created for on first use; the SDK's default chain otherwise. */
+    region?: string;
+    /** Partition key prefix, keeps secrets separated from other systems in a shared table. Default: "OTS". */
+    keyPrefix?: string;
+    client?: DynamoDBClient;
+}
+/**
+ * One-shot secrets in DynamoDB, under the store's prefix, so the table can be
+ * shared with LambderDdbRateLimiter (`RL#`) and LambderDdbIdempotencyStore
+ * (`IDEM#`):
+ *
+ * - `<prefix>#scope#<scope>` / `secret`: the scope's current record. Issuing
+ *   writes it over whatever was there, which is how the older secret is
+ *   retired in the same act; a cooldown is a condition on that write
+ *   (`issuedAt <= :threshold`), so of two callers racing past it exactly one
+ *   is issued and the other reads when the winner was.
+ * - `<prefix>#digest#<digest>` / `secret`, for a token alone: the scope the
+ *   digest belongs to, which is how a token is found by its value. A code is
+ *   found through its scope and has none. A token's two items are written in
+ *   one transaction, the digest item conditioned on being free or already the
+ *   scope's (`attribute_not_exists(pk) OR #scope = :scope`), so no two scopes
+ *   share a digest and no issue leaves a record without its digest. A digest
+ *   of a secret the scope has since replaced points at a record whose digest
+ *   differs, and finds nothing; it stays claimed until TTL removes it, and a
+ *   token drawn onto it is drawn again.
+ *
+ * A try is counted with a conditional `ADD`, on the record named and no
+ * other, and the item comes back with the count already spent; a consume is a
+ * conditional delete of the record named. Both are one request, which is what
+ * makes them safe against a second caller. Every write DynamoDB refuses only
+ * because a transaction held its item at that moment is sent again, up to
+ * three times, since the SDK does not retry that refusal and nothing was
+ * written. Items carry `expiresAt` for
+ * DynamoDB TTL; the class decides expiry itself, since TTL deletion is lazy,
+ * and an item TTL has not yet retired is what lets it answer "expired" rather
+ * than "none".
+ */
+export declare class LambderDdbOneShotSecretStore implements LambderOneShotSecretStore {
+    readonly tableName: string;
+    readonly keyPrefix: string;
+    private readonly ready;
+    constructor(options: LambderDdbOneShotSecretStoreOptions);
+    private scopeKey;
+    private digestKey;
+    /**
+     * A stored item as a record, with every field checked rather than cast: an
+     * item another writer left in a shared table, or a partial write, is a
+     * record to refuse rather than to trust.
+     */
+    private static recordOf;
+    issue(draft: LambderOneShotSecretDraft, { unlessIssuedAfter }: {
+        unlessIssuedAfter?: number;
+    }): Promise<LambderOneShotIssueOutcome>;
+    findByScope(scope: string): Promise<LambderOneShotSecretRecord | null>;
+    findByDigest(digest: string): Promise<LambderOneShotSecretRecord | null>;
+    attempt(scope: string, id: string): Promise<LambderOneShotSecretRecord | null>;
+    consume(scope: string, id: string): Promise<boolean>;
+    retire(scope: string): Promise<void>;
+}
+export default LambderDdbOneShotSecretStore;