lambder 8.1.2 → 8.3.1

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;
+}

package/dist/stores/LambderMemoryOneShotSecretStore.js

@@ -0,0 +1,93 @@
+import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
+/**
+ * How long past its expiry a record is kept, so the class can still answer
+ * "expired" from it rather than "none", the way a table's lazy TTL leaves an
+ * expired item in place for a while.
+ */
+const EXPIRED_GRACE_SECONDS = 3600;
+/**
+ * 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 class LambderMemoryOneShotSecretStore {
+    records;
+    scopesByDigest;
+    idCounter = 0;
+    constructor(options = {}) {
+        this.records = new LambderExpiringMap({ now: options.now, maxEntries: options.maxEntries });
+        this.scopesByDigest = new LambderExpiringMap({ now: options.now, maxEntries: options.maxEntries });
+    }
+    /** A record as the class reads it: a copy, so a caller writing onto what it got back cannot rewrite the record. */
+    static copyOf(record) {
+        return { ...record, meta: { ...record.meta } };
+    }
+    async issue(draft, { unlessIssuedAfter }) {
+        const current = this.records.get(draft.scope);
+        if (unlessIssuedAfter !== undefined && current && current.issuedAt > unlessIssuedAfter)
+            return { issued: false, refused: "cooldown", issuedAt: current.issuedAt };
+        // A token's digest is its only address, so another scope's record
+        // holding it keeps it; a code's carries its scope, and no other scope
+        // can hold it.
+        const holder = draft.shape === "token" ? this.scopesByDigest.get(draft.digest) : undefined;
+        if (holder !== undefined && holder !== draft.scope && this.records.get(holder)?.digest === draft.digest)
+            return { issued: false, refused: "digestTaken" };
+        if (current)
+            this.scopesByDigest.delete(current.digest);
+        this.idCounter += 1;
+        const id = `secret-${this.idCounter}`;
+        const keepUntil = draft.expiresAt + EXPIRED_GRACE_SECONDS;
+        const { shape: _shape, ...record } = draft;
+        this.records.set(draft.scope, { ...record, id, attempts: 0, meta: { ...draft.meta } }, keepUntil);
+        if (draft.shape === "token")
+            this.scopesByDigest.set(draft.digest, draft.scope, keepUntil);
+        return { issued: true, id };
+    }
+    async findByScope(scope) {
+        const record = this.records.get(scope);
+        return record ? LambderMemoryOneShotSecretStore.copyOf(record) : null;
+    }
+    async findByDigest(digest) {
+        const scope = this.scopesByDigest.get(digest);
+        const record = scope === undefined ? undefined : this.records.get(scope);
+        // The scope may have been issued a newer secret since this digest was
+        // written, in which case this digest is nobody's.
+        return record && record.digest === digest ? LambderMemoryOneShotSecretStore.copyOf(record) : null;
+    }
+    async attempt(scope, id) {
+        const record = this.records.get(scope);
+        if (!record || record.id !== id)
+            return null;
+        record.attempts += 1;
+        return LambderMemoryOneShotSecretStore.copyOf(record);
+    }
+    async consume(scope, id) {
+        const record = this.records.get(scope);
+        if (!record || record.id !== id)
+            return false;
+        this.records.delete(scope);
+        this.scopesByDigest.delete(record.digest);
+        return true;
+    }
+    async retire(scope) {
+        const record = this.records.get(scope);
+        if (!record)
+            return;
+        this.records.delete(scope);
+        this.scopesByDigest.delete(record.digest);
+    }
+    /** Number of live records held. */
+    get size() { return this.records.size; }
+    /** Forgets every record. */
+    reset() {
+        this.records.clear();
+        this.scopesByDigest.clear();
+    }
+}

package/dist/testing/LambderConformanceRunner.d.ts

@@ -0,0 +1,46 @@
+/** The runner's `it`: registers one case under a name. */
+export type LambderConformanceIt = (name: string, run: () => Promise<void>) => unknown;
+/** The part of a jest-style assertion the suites use, which vitest's and jest's `expect` both provide. */
+export type LambderConformanceAssertion = {
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toMatchObject(expected: object): void;
+    toBeNull(): void;
+    toBeUndefined(): void;
+    toBeTruthy(): void;
+    toHaveLength(length: number): void;
+    toBeGreaterThan(value: number): void;
+    not: {
+        toBe(expected: unknown): void;
+        toBeNull(): void;
+    };
+    rejects: {
+        toThrow(): Promise<unknown>;
+    };
+    resolves: {
+        toBeNull(): Promise<unknown>;
+    };
+};
+/** The runner's `expect`. */
+export type LambderConformanceExpect = (actual: unknown) => LambderConformanceAssertion;
+/** The two things every suite takes from the runner. */
+export type LambderConformanceRunner = {
+    it: LambderConformanceIt;
+    expect: LambderConformanceExpect;
+};
+/**
+ * What a store factory is handed for one case: the clock the case moves, in
+ * epoch milliseconds. A store that judges time itself (a memory store
+ * expiring its entries) must read it from here; the system clock does not
+ * move with it, so a store that read Date.now() behind its `now` option
+ * would see time standing still and fail the expiry rules.
+ */
+export type LambderConformanceSetup = {
+    now: () => number;
+};
+/** Where every case's clock starts: a fixed moment, so the records a case writes are the same on every run. */
+export declare const CONFORMANCE_START_MILLIS = 1700000000000;
+/** The clock of one case: `now` for the store, `set` for the case. */
+export declare const conformanceClock: () => LambderConformanceSetup & {
+    set(millis: number): void;
+};

package/dist/testing/LambderConformanceRunner.js

@@ -0,0 +1,21 @@
+/*
+ * What the store conformance suites register their cases with, and the clock
+ * each case runs on.
+ *
+ * A suite is the set of rules one store interface promises, written once and
+ * driven through every implementation: Lambder's own memory and DynamoDB
+ * stores, and any store an app writes over its own database. The suites take
+ * the test runner's `it` and `expect` rather than importing one, so they run
+ * under vitest, jest, or any runner with a jest-style `expect`, and the
+ * package depends on none of them.
+ */
+/** Where every case's clock starts: a fixed moment, so the records a case writes are the same on every run. */
+export const CONFORMANCE_START_MILLIS = 1_700_000_000_000;
+/** The clock of one case: `now` for the store, `set` for the case. */
+export const conformanceClock = () => {
+    let millis = CONFORMANCE_START_MILLIS;
+    return {
+        now: () => millis,
+        set: (next) => { millis = next; },
+    };
+};

package/dist/testing/lambderIdempotencyStoreConformance.d.ts

@@ -0,0 +1,33 @@
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderIdempotencyStoreConformanceOptions = LambderConformanceRunner & {
+    /** A store holding nothing, built for one case over the case's clock. */
+    create: (setup: LambderConformanceSetup) => LambderIdempotencyStore | Promise<LambderIdempotencyStore>;
+    /**
+     * A body this store will not hold. The budget is the store's own business
+     * (a DynamoDB store measures what it writes after compression, a memory
+     * store the bytes), so each says what "too big" means for it.
+     */
+    oversizedBody: string;
+    /** The other side of the same budget: the largest body this store does hold, so the boundary is pinned from both directions. */
+    largestStorableBody: string;
+};
+/**
+ * Registers the idempotency store rules as cases of the runner, one `it`
+ * each, against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderIdempotencyStoreConformance } from "lambder/testing";
+ *
+ * describe("OrderIdempotencyStore", () => {
+ *     lambderIdempotencyStoreConformance({
+ *         it, expect,
+ *         create: ({ now }) => new OrderIdempotencyStore({ pool, now }),
+ *         oversizedBody: "x".repeat(2_000_000),
+ *         largestStorableBody: "x".repeat(1_000_000),
+ *     });
+ * });
+ * ```
+ */
+export declare const lambderIdempotencyStoreConformance: (options: LambderIdempotencyStoreConformanceOptions) => void;