lambder 8.1.1 → 8.3.1

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/util/escapeXmlText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Text made safe to place inside an XML element or a quoted attribute: the
+ * five characters XML gives meaning to become numeric references. For the
+ * small documents storage speaks, a tag set a ticket carries and an error a
+ * memory bucket answers with, which LambderHtml's `xml` template would also
+ * escape but no module in wire/ may import.
+ */
+export declare const escapeXmlText: (text: string) => string;

package/dist/shared/util/escapeXmlText.js

@@ -0,0 +1,8 @@
+/**
+ * Text made safe to place inside an XML element or a quoted attribute: the
+ * five characters XML gives meaning to become numeric references. For the
+ * small documents storage speaks, a tag set a ticket carries and an error a
+ * memory bucket answers with, which LambderHtml's `xml` template would also
+ * escape but no module in wire/ may import.
+ */
+export const escapeXmlText = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);

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/shared/wire/LambderUploadObjectFields.js

@@ -1,5 +1,5 @@
 import { contentDispositionHeader } from "../util/LambderContentDisposition.js";
-const escapeXml = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);
+import { escapeXmlText } from "../util/escapeXmlText.js";
 /**
  * What a ticket's form carries for the stored object, in the fields S3's
  * presigned POST reads them from: the tag set as the XML `tagging` field,
@@ -12,7 +12,7 @@ export const uploadObjectFormFields = (object) => {
     const fields = {};
     const tags = Object.entries(object?.tags ?? {});
     if (tags.length) {
-        fields.tagging = `<Tagging><TagSet>${tags.map(([key, value]) => `<Tag><Key>${escapeXml(key)}</Key><Value>${escapeXml(value)}</Value></Tag>`).join("")}</TagSet></Tagging>`;
+        fields.tagging = `<Tagging><TagSet>${tags.map(([key, value]) => `<Tag><Key>${escapeXmlText(key)}</Key><Value>${escapeXmlText(value)}</Value></Tag>`).join("")}</TagSet></Tagging>`;
     }
     for (const [name, value] of Object.entries(object?.metadata ?? {}))
         fields[`x-amz-meta-${name.toLowerCase()}`] = value;

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;

package/dist/stores/LambderDdbOneShotSecretStore.js

@@ -0,0 +1,266 @@
+import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, } from "./LambderDdbSdk.js";
+import { randomSecret } from "../shared/util/LambderSignedClaims.js";
+/**
+ * Why each item of a cancelled transaction was refused, in the order the
+ * items were sent, or null when the error is not a cancelled transaction.
+ */
+const transactionCancellationReasons = (error) => {
+    if (!error || typeof error !== "object" || error.name !== "TransactionCanceledException")
+        return null;
+    const reasons = error.CancellationReasons;
+    return Array.isArray(reasons) ? reasons : [];
+};
+/**
+ * Whether DynamoDB refused a write only because another transaction held one
+ * of its items at that moment, so nothing was written and the write can be
+ * sent again: a cancelled transaction whose reasons name a conflict and no
+ * failed condition (a condition's answer stands), or a single-item write
+ * refused while a transaction held its item.
+ */
+const isWriteConflict = (error) => {
+    if (error?.name === "TransactionConflictException")
+        return true;
+    const reasons = transactionCancellationReasons(error);
+    return !!reasons
+        && reasons.some((reason) => reason.Code === "TransactionConflict")
+        && !reasons.some((reason) => reason.Code === "ConditionalCheckFailed");
+};
+/** How many times a write refused for a conflict is sent, in all. */
+const CONFLICT_ATTEMPTS = 3;
+/**
+ * Sends a write, and again when DynamoDB refused it for a conflict, which the
+ * SDK does not retry: two issues for one scope at once (a resend tapped
+ * twice), or two scopes racing for one digest. A short random pause first,
+ * so two writers that met do not meet again in step. Past the last attempt
+ * the conflict is thrown.
+ */
+const sendRetryingConflicts = async (write) => {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return await write();
+        }
+        catch (error) {
+            if (attempt >= CONFLICT_ATTEMPTS || !isWriteConflict(error))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 10 + Math.random() * 40 * attempt));
+        }
+    }
+};
+/** A number attribute as stored, or the fallback when it is missing or not a number, since NaN compares false to everything. */
+const storedNumber = (raw, fallback) => {
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : fallback;
+};
+/**
+ * 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 class LambderDdbOneShotSecretStore {
+    tableName;
+    keyPrefix;
+    ready;
+    constructor(options) {
+        if (!options.tableName.trim())
+            throw new Error("tableName is required");
+        this.tableName = options.tableName;
+        this.keyPrefix = options.keyPrefix ?? "OTS";
+        this.ready = createDynamoClientLoader({ user: "LambderDdbOneShotSecretStore", region: options.region, client: options.client });
+    }
+    scopeKey(scope) {
+        return {
+            pk: { S: assertPartitionKeyFits({ user: "LambderDdbOneShotSecretStore", what: "scope", partitionKey: `${this.keyPrefix}#scope#${scope}`, remedy: "Name the scope with an identifier rather than the data itself." }) },
+            sk: { S: "secret" },
+        };
+    }
+    digestKey(digest) {
+        return { pk: { S: `${this.keyPrefix}#digest#${digest}` }, sk: { S: "secret" } };
+    }
+    /**
+     * 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.
+     */
+    static recordOf(item) {
+        const id = item?.id?.S;
+        const kind = item?.kind?.S;
+        const scope = item?.scope?.S;
+        const digest = item?.digest?.S;
+        if (!item || !id || !kind || scope === undefined || !digest)
+            return null;
+        let meta = {};
+        try {
+            const parsed = JSON.parse(item.metaJson?.S ?? "{}");
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                for (const [key, value] of Object.entries(parsed)) {
+                    if (key !== "__proto__" && typeof value === "string")
+                        meta[key] = value;
+                }
+            }
+        }
+        catch {
+            meta = {};
+        }
+        return {
+            id, kind, scope, digest,
+            issuedAt: storedNumber(item.issuedAt?.N, 0),
+            expiresAt: storedNumber(item.expiresAt?.N, 0),
+            attempts: storedNumber(item.attempts?.N, 0),
+            meta,
+        };
+    }
+    async issue(draft, { unlessIssuedAfter }) {
+        const { client, sdk } = await this.ready();
+        const id = randomSecret(12);
+        const scopePut = {
+            TableName: this.tableName,
+            Item: {
+                ...this.scopeKey(draft.scope),
+                id: { S: id },
+                kind: { S: draft.kind },
+                scope: { S: draft.scope },
+                digest: { S: draft.digest },
+                issuedAt: { N: String(draft.issuedAt) },
+                expiresAt: { N: String(draft.expiresAt) },
+                attempts: { N: "0" },
+                metaJson: { S: JSON.stringify(draft.meta) },
+            },
+            // The cooldown, when there is one: an item with no issuedAt
+            // (another writer's, or a partial write) never blocks a scope.
+            ...(unlessIssuedAfter === undefined ? {} : {
+                ConditionExpression: "attribute_not_exists(pk) OR attribute_not_exists(issuedAt) OR issuedAt <= :threshold",
+                ExpressionAttributeValues: { ":threshold": { N: String(unlessIssuedAfter) } },
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+            }),
+        };
+        // Refused with no item to show for it: gone again by the time the
+        // condition was read; the next call resolves it. Reported as issued
+        // this very second, so the caller waits the whole cooldown.
+        const cooldownRefusal = (refusedBy) => ({ issued: false, refused: "cooldown", issuedAt: storedNumber(refusedBy?.issuedAt?.N, draft.issuedAt) });
+        if (draft.shape === "code") {
+            try {
+                await sendRetryingConflicts(() => client.send(new sdk.PutItemCommand(scopePut)));
+            }
+            catch (error) {
+                if (!isConditionalCheckFailure(error))
+                    throw error;
+                return cooldownRefusal(error.Item);
+            }
+            return { issued: true, id };
+        }
+        try {
+            await sendRetryingConflicts(() => client.send(new sdk.TransactWriteItemsCommand({
+                TransactItems: [
+                    { Put: scopePut },
+                    {
+                        Put: {
+                            TableName: this.tableName,
+                            Item: { ...this.digestKey(draft.digest), scope: { S: draft.scope }, expiresAt: { N: String(draft.expiresAt) } },
+                            ConditionExpression: "attribute_not_exists(pk) OR #scope = :scope",
+                            ExpressionAttributeNames: { "#scope": "scope" },
+                            ExpressionAttributeValues: { ":scope": { S: draft.scope } },
+                        },
+                    },
+                ],
+            })));
+        }
+        catch (error) {
+            const reasons = transactionCancellationReasons(error);
+            if (!reasons)
+                throw error;
+            // The scope's own condition first: a scope inside its cooldown is
+            // refused as that, whatever its draw collided with.
+            if (reasons[0]?.Code === "ConditionalCheckFailed")
+                return cooldownRefusal(reasons[0].Item);
+            if (reasons[1]?.Code === "ConditionalCheckFailed")
+                return { issued: false, refused: "digestTaken" };
+            throw error;
+        }
+        return { issued: true, id };
+    }
+    async findByScope(scope) {
+        const { client, sdk } = await this.ready();
+        // Strongly consistent: a redeem that follows an issue by milliseconds
+        // has to see the record the issue wrote.
+        const found = await client.send(new sdk.GetItemCommand({ TableName: this.tableName, Key: this.scopeKey(scope), ConsistentRead: true }));
+        return LambderDdbOneShotSecretStore.recordOf(found.Item);
+    }
+    async findByDigest(digest) {
+        const { client, sdk } = await this.ready();
+        const lookup = await client.send(new sdk.GetItemCommand({ TableName: this.tableName, Key: this.digestKey(digest), ConsistentRead: true }));
+        const scope = lookup.Item?.scope?.S;
+        if (scope === undefined)
+            return null;
+        const record = await this.findByScope(scope);
+        return record && record.digest === digest ? record : null;
+    }
+    async attempt(scope, id) {
+        const { client, sdk } = await this.ready();
+        try {
+            const counted = await sendRetryingConflicts(() => client.send(new sdk.UpdateItemCommand({
+                TableName: this.tableName,
+                Key: this.scopeKey(scope),
+                UpdateExpression: "ADD attempts :one",
+                ConditionExpression: "id = :id",
+                ExpressionAttributeValues: { ":one": { N: "1" }, ":id": { S: id } },
+                ReturnValues: "ALL_NEW",
+            })));
+            return LambderDdbOneShotSecretStore.recordOf(counted.Attributes);
+        }
+        catch (error) {
+            if (!isConditionalCheckFailure(error))
+                throw error;
+            return null;
+        }
+    }
+    async consume(scope, id) {
+        const { client, sdk } = await this.ready();
+        try {
+            await sendRetryingConflicts(() => client.send(new sdk.DeleteItemCommand({
+                TableName: this.tableName,
+                Key: this.scopeKey(scope),
+                ConditionExpression: "id = :id",
+                ExpressionAttributeValues: { ":id": { S: id } },
+            })));
+            return true;
+        }
+        catch (error) {
+            if (!isConditionalCheckFailure(error))
+                throw error;
+            return false;
+        }
+    }
+    async retire(scope) {
+        const { client, sdk } = await this.ready();
+        // The digest item is left to TTL: it points at a scope whose record
+        // is gone or replaced, and finds nothing either way.
+        await sendRetryingConflicts(() => client.send(new sdk.DeleteItemCommand({ TableName: this.tableName, Key: this.scopeKey(scope) })));
+    }
+}
+export default LambderDdbOneShotSecretStore;

package/dist/stores/LambderMemoryIdempotencyStore.d.ts

@@ -11,8 +11,9 @@ type MemoryIdempotencyRecord = {
  * Idempotency records held in memory: the same claim, settle and replay
  * semantics as LambderDdbIdempotencyStore (owner tokens, pending expiry, lost
  * claims as silent no-ops), over a LambderExpiringMap in place of the table
- * and its TTL. For tests and for the mock runtime; tests/store-conformance
- * drives this and the DynamoDB store through one set of rules.
+ * and its TTL. For tests and for the mock runtime; the conformance suite
+ * (lambderIdempotencyStoreConformance) drives this and the DynamoDB store
+ * through one set of rules.
  *
  * `maxBodyBytes` stands in for the DynamoDB item budget, so the "too-large"
  * path can be exercised; unbounded by default. `now` is injectable so a test

package/dist/stores/LambderMemoryIdempotencyStore.js

@@ -3,8 +3,9 @@ import { LambderExpiringMap, LambderExpiringMapFullError } from "../shared/util/
  * Idempotency records held in memory: the same claim, settle and replay
  * semantics as LambderDdbIdempotencyStore (owner tokens, pending expiry, lost
  * claims as silent no-ops), over a LambderExpiringMap in place of the table
- * and its TTL. For tests and for the mock runtime; tests/store-conformance
- * drives this and the DynamoDB store through one set of rules.
+ * and its TTL. For tests and for the mock runtime; the conformance suite
+ * (lambderIdempotencyStoreConformance) drives this and the DynamoDB store
+ * through one set of rules.
  *
  * `maxBodyBytes` stands in for the DynamoDB item budget, so the "too-large"
  * path can be exercised; unbounded by default. `now` is injectable so a test

package/dist/stores/LambderMemoryOneShotSecretStore.d.ts

@@ -0,0 +1,36 @@
+import type { LambderOneShotIssueOutcome, LambderOneShotSecretDraft, LambderOneShotSecretRecord, LambderOneShotSecretStore } from "../shared/contracts/LambderOneShotSecretStore.js";
+/**
+ * One-shot secrets held in memory: the same one-record-per-scope, count-then-
+ * compare and consume-once semantics as LambderDdbOneShotSecretStore, over a
+ * LambderExpiringMap in place of the table and its TTL. For tests and for an
+ * app's development runtime; lambderOneShotSecretStoreConformance drives
+ * this and the DynamoDB store through one set of rules.
+ *
+ * Two maps, as the table holds two items per secret: the scope's current
+ * record, and the scope a digest belongs to, which is how a token is found by
+ * its value. `now` is injectable so a test can expire a secret without
+ * waiting.
+ */
+export declare class LambderMemoryOneShotSecretStore implements LambderOneShotSecretStore {
+    private readonly records;
+    private readonly scopesByDigest;
+    private idCounter;
+    constructor(options?: {
+        now?: () => number;
+        maxEntries?: number;
+    });
+    /** A record as the class reads it: a copy, so a caller writing onto what it got back cannot rewrite the record. */
+    private static copyOf;
+    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>;
+    /** Number of live records held. */
+    get size(): number;
+    /** Forgets every record. */
+    reset(): void;
+}