lambder 8.1.1 → 8.3.1

package/dist/testing/lambderOneShotSecretStoreConformance.js

@@ -0,0 +1,224 @@
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/**
+ * Registers the one-shot secret store rules as cases of the runner, one `it`
+ * each and once per shape, against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderOneShotSecretStoreConformance } from "lambder/testing";
+ *
+ * describe("TicketCodeStore", () => {
+ *     lambderOneShotSecretStoreConformance({
+ *         it, expect,
+ *         create: async () => { await emptyTicketCodes(); return new TicketCodeStore(pool); },
+ *         scopes: [ticketA.id, ticketB.id],
+ *         kinds: { code: "ticketCode" },
+ *         meta: [{}, {}],
+ *     });
+ * });
+ * ```
+ */
+export const lambderOneShotSecretStoreConformance = (options) => {
+    const [scopeA, scopeB] = options.scopes ?? ["register:ada@example.com", "register:grace@example.com"];
+    const kinds = options.kinds ?? { code: "emailCode", token: "activationLink" };
+    const shapes = ["code", "token"].filter((shape) => kinds[shape] !== undefined);
+    if (shapes.length === 0)
+        throw new Error("lambderOneShotSecretStoreConformance: kinds names no shape; give the kind the store holds as a code, as a token, or both.");
+    const { expect } = options;
+    const [metaA, metaB] = options.meta ?? [{ holder: "ada" }, { holder: "grace" }];
+    const lifetimeSeconds = options.lifetimeSeconds ?? 600;
+    const startSeconds = Math.floor(START / 1000);
+    const begin = async () => {
+        const clock = conformanceClock();
+        return { clock, store: await options.create(clock) };
+    };
+    // Every case once per shape the store holds, named for it.
+    for (const shape of shapes) {
+        const kind = kinds[shape];
+        const isToken = shape === "token";
+        const it = (name, run) => options.it(`${shape}: ${name}`, run);
+        /** A record of scope A issued at the start, unless a case says otherwise; the expiry always follows from the issue time. */
+        const draft = (over = {}) => {
+            const issuedAt = over.issuedAt ?? startSeconds;
+            return {
+                kind,
+                scope: over.scope ?? scopeA,
+                shape,
+                digest: over.digest ?? "digest-1",
+                issuedAt,
+                expiresAt: issuedAt + lifetimeSeconds,
+                meta: over.meta ?? (over.scope === scopeB ? metaB : metaA),
+            };
+        };
+        /** The record a store holds for a draft: the draft less its shape, with the id it handed out and no tries. */
+        const recordFor = (written, id) => {
+            const { shape: _shape, ...record } = written;
+            return { ...record, id, attempts: 0 };
+        };
+        /** An issue that went through, or a failure: every rule below is about a record that exists. */
+        const issued = async (store, over = {}) => {
+            const outcome = await store.issue(draft(over), {});
+            if (!outcome.issued)
+                throw new Error(`expected the secret to be issued, refused as ${outcome.refused}`);
+            return outcome.id;
+        };
+        it("holds one record per scope, found by its scope (and a token by its digest), with what was written and no tries", async () => {
+            const { store } = await begin();
+            const id = await issued(store);
+            const byScope = await store.findByScope(scopeA);
+            expect(byScope).toEqual(recordFor(draft(), id));
+            expect(await store.findByScope(scopeB)).toBeNull();
+            if (isToken) {
+                expect(await store.findByDigest("digest-1")).toEqual(byScope);
+                expect(await store.findByDigest("digest-9")).toBeNull();
+            }
+        });
+        it("retires the scope's older record in the act of issuing, so it can be neither found nor spent", async () => {
+            const { store } = await begin();
+            const first = await issued(store, { digest: "digest-1" });
+            const second = await issued(store, { digest: "digest-2", issuedAt: startSeconds + 30 });
+            expect(second).not.toBe(first);
+            expect((await store.findByScope(scopeA))?.digest).toBe("digest-2");
+            if (isToken) {
+                expect(await store.findByDigest("digest-1")).toBeNull();
+                expect((await store.findByDigest("digest-2"))?.id).toBe(second);
+            }
+            else {
+                expect(await store.attempt(scopeA, first)).toBeNull();
+            }
+            expect(await store.consume(scopeA, first)).toBe(false);
+        });
+        it("leaves exactly one live record when two issues for one scope race", async () => {
+            // Retire-then-write done as two statements lets both writers retire
+            // nothing and both write, and the scope then holds two live secrets.
+            // A second of apart, so a store whose id is the issue time tells the
+            // two apart.
+            const { store } = await begin();
+            const [idA, idB] = await Promise.all([
+                issued(store, { digest: "digest-a" }),
+                issued(store, { digest: "digest-b", issuedAt: startSeconds + 1 }),
+            ]);
+            const current = await store.findByScope(scopeA);
+            if (isToken) {
+                const live = [await store.findByDigest("digest-a"), await store.findByDigest("digest-b")].filter((record) => record !== null);
+                expect(live).toHaveLength(1);
+                expect(current?.digest).toBe(live[0].digest);
+            }
+            // Only the scope's current record can be spent.
+            expect([await store.consume(scopeA, idA), await store.consume(scopeA, idB)].filter(Boolean)).toHaveLength(1);
+            expect(current).not.toBeNull();
+        });
+        it("refuses an issue inside the cooldown, naming when the current record was issued, and writes nothing", async () => {
+            const { store } = await begin();
+            await issued(store, { digest: "digest-1", issuedAt: startSeconds });
+            const refused = await store.issue(draft({ digest: "digest-2", issuedAt: startSeconds + 10 }), { unlessIssuedAfter: startSeconds - 1 });
+            expect(refused).toEqual({ issued: false, refused: "cooldown", issuedAt: startSeconds });
+            expect((await store.findByScope(scopeA))?.digest).toBe("digest-1");
+            if (isToken)
+                expect(await store.findByDigest("digest-2")).toBeNull();
+            // At the threshold itself the cooldown is over, and a scope with no record has none.
+            expect((await store.issue(draft({ digest: "digest-3", issuedAt: startSeconds + 30 }), { unlessIssuedAfter: startSeconds })).issued).toBe(true);
+            expect((await store.issue(draft({ scope: scopeB, digest: "digest-4" }), { unlessIssuedAfter: startSeconds + 1000 })).issued).toBe(true);
+        });
+        it("grants exactly one of two issues racing past a cooldown", async () => {
+            const { store } = await begin();
+            await issued(store, { digest: "digest-0", issuedAt: startSeconds - 100 });
+            const [a, b] = await Promise.all([
+                store.issue(draft({ digest: "digest-a" }), { unlessIssuedAfter: startSeconds - 30 }),
+                store.issue(draft({ digest: "digest-b" }), { unlessIssuedAfter: startSeconds - 30 }),
+            ]);
+            expect([a.issued, b.issued].filter(Boolean)).toHaveLength(1);
+        });
+        if (isToken) {
+            it("refuses a digest another scope's record holds, writes nothing, and leaves it with its holder", async () => {
+                // Two scopes that drew the same token would share one digest,
+                // and whoever typed it would redeem the other's record.
+                const { store } = await begin();
+                const holderId = await issued(store, { digest: "digest-x" });
+                expect(await store.issue(draft({ scope: scopeB, digest: "digest-x" }), {})).toEqual({ issued: false, refused: "digestTaken" });
+                expect(await store.findByScope(scopeB)).toBeNull();
+                expect(await store.findByDigest("digest-x")).toEqual(recordFor(draft({ digest: "digest-x" }), holderId));
+            });
+            it("grants a digest to exactly one of two scopes racing for it", async () => {
+                const { store } = await begin();
+                const [a, b] = await Promise.all([
+                    store.issue(draft({ digest: "digest-x" }), {}),
+                    store.issue(draft({ scope: scopeB, digest: "digest-x" }), {}),
+                ]);
+                expect([a, b].filter((outcome) => outcome.issued)).toHaveLength(1);
+                expect([a, b].filter((outcome) => !outcome.issued && outcome.refused === "digestTaken")).toHaveLength(1);
+                const winner = a.issued ? scopeA : scopeB;
+                expect((await store.findByDigest("digest-x"))?.scope).toBe(winner);
+                expect(await store.findByScope(winner === scopeA ? scopeB : scopeA)).toBeNull();
+            });
+        }
+        else {
+            it("counts a try in the act that reads the record, on the record named and no other", async () => {
+                const { store } = await begin();
+                const id = await issued(store);
+                const first = await store.attempt(scopeA, id);
+                expect(first).toMatchObject({ id, digest: "digest-1", attempts: 1, meta: metaA });
+                expect((await store.attempt(scopeA, id))?.attempts).toBe(2);
+                expect((await store.findByScope(scopeA))?.attempts).toBe(2);
+                // The record is scope A's: named under another scope, it is not the one there.
+                expect(await store.attempt(scopeB, id)).toBeNull();
+                expect((await store.findByScope(scopeA))?.attempts).toBe(2);
+            });
+            it("counts tries sent together every one, so a ceiling cannot be raced past", async () => {
+                const { store } = await begin();
+                const id = await issued(store);
+                const counted = await Promise.all(Array.from({ length: 5 }, () => store.attempt(scopeA, id)));
+                expect(counted.map((record) => record?.attempts).sort()).toEqual([1, 2, 3, 4, 5]);
+            });
+        }
+        it("consumes the record named exactly once, after which nothing finds it", async () => {
+            const { store } = await begin();
+            const id = await issued(store);
+            expect(await store.consume(scopeB, id)).toBe(false);
+            expect(await store.consume(scopeA, id)).toBe(true);
+            expect(await store.consume(scopeA, id)).toBe(false);
+            expect(await store.findByScope(scopeA)).toBeNull();
+            if (isToken)
+                expect(await store.findByDigest("digest-1")).toBeNull();
+            else
+                expect(await store.attempt(scopeA, id)).toBeNull();
+        });
+        it("accepts exactly one of two consumes racing for one record", async () => {
+            const { store } = await begin();
+            const id = await issued(store);
+            const outcomes = await Promise.all([store.consume(scopeA, id), store.consume(scopeA, id)]);
+            expect(outcomes.filter(Boolean)).toHaveLength(1);
+        });
+        it("retires whatever the scope holds and nothing of another scope, and nothing when it holds nothing", async () => {
+            const { store } = await begin();
+            await issued(store, { digest: "digest-a" });
+            await issued(store, { scope: scopeB, digest: "digest-b" });
+            await store.retire(scopeA);
+            expect(await store.findByScope(scopeA)).toBeNull();
+            if (isToken)
+                expect(await store.findByDigest("digest-a")).toBeNull();
+            expect((await store.findByScope(scopeB))?.digest).toBe("digest-b");
+            await store.retire(scopeA);
+        });
+        it("keeps an expired record until its own housekeeping removes it, so the class can say expired rather than none", async () => {
+            const { clock, store } = await begin();
+            const id = await issued(store);
+            clock.set(START + (lifetimeSeconds + 1) * 1000);
+            expect((await store.findByScope(scopeA))?.id).toBe(id);
+            if (isToken)
+                expect((await store.findByDigest("digest-1"))?.id).toBe(id);
+        });
+        it("keeps scopes apart, and hands back copies", async () => {
+            const { store } = await begin();
+            const idA = await issued(store, { digest: "digest-a" });
+            const idB = await issued(store, { scope: scopeB, digest: "digest-b" });
+            const a = (await store.findByScope(scopeA));
+            a.meta["planted"] = "changed";
+            a.digest = "changed";
+            expect(await store.findByScope(scopeA)).toEqual(recordFor(draft({ digest: "digest-a" }), idA));
+            expect(await store.findByScope(scopeB)).toEqual(recordFor(draft({ scope: scopeB, digest: "digest-b" }), idB));
+            if (isToken)
+                expect((await store.findByDigest("digest-b"))?.scope).toBe(scopeB);
+        });
+    }
+};

package/dist/testing/lambderRateLimiterConformance.d.ts

@@ -0,0 +1,20 @@
+import { type LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderRateLimiterConformanceOptions = LambderConformanceRunner & {
+    /** A limiter holding no counts, built for one case over the case's clock. */
+    create: (setup: LambderConformanceSetup) => LambderRateLimiter | Promise<LambderRateLimiter>;
+};
+/**
+ * Registers the rate limiter rules as cases of the runner, one `it` each,
+ * against the limiter `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderRateLimiterConformance } from "lambder/testing";
+ *
+ * describe("RedisRateLimiter", () => {
+ *     lambderRateLimiterConformance({ it, expect, create: ({ now }) => new RedisRateLimiter({ client, now }) });
+ * });
+ * ```
+ */
+export declare const lambderRateLimiterConformance: (options: LambderRateLimiterConformanceOptions) => void;

package/dist/testing/lambderRateLimiterConformance.js

@@ -0,0 +1,72 @@
+import { RATE_LIMIT_WINDOWS } from "../shared/contracts/LambderRateLimiter.js";
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/**
+ * Registers the rate limiter rules as cases of the runner, one `it` each,
+ * against the limiter `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderRateLimiterConformance } from "lambder/testing";
+ *
+ * describe("RedisRateLimiter", () => {
+ *     lambderRateLimiterConformance({ it, expect, create: ({ now }) => new RedisRateLimiter({ client, now }) });
+ * });
+ * ```
+ */
+export const lambderRateLimiterConformance = (options) => {
+    const { it, expect } = options;
+    const begin = async () => {
+        const clock = conformanceClock();
+        return { clock, limiter: await options.create(clock) };
+    };
+    it("counts attempts and refuses the one past the limit, naming the window", async () => {
+        const { limiter } = await begin();
+        expect(await limiter.isRateLimited("k", { perMin: 2 })).toBe(false);
+        expect(await limiter.isRateLimited("k", { perMin: 2 })).toBe(false);
+        const refused = await limiter.isRateLimited("k", { perMin: 2 });
+        expect(refused).toMatchObject({ window: "perMin", limit: 2 });
+        if (refused === false)
+            throw new Error("expected the third attempt to be refused");
+        expect(refused.resetAt).toBeGreaterThan(Math.floor(START / 1000));
+    });
+    it("counts attempts rather than allowed requests, so a refusal does not reset anything", async () => {
+        const { limiter } = await begin();
+        await limiter.isRateLimited("k", { perMin: 1 });
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).not.toBe(false);
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).not.toBe(false);
+    });
+    it("does not enforce a window the policy leaves out or caps at zero", async () => {
+        const { limiter } = await begin();
+        for (let i = 0; i < 5; i += 1) {
+            expect(await limiter.isRateLimited("k", { perHour: 0 })).toBe(false);
+        }
+        expect(await limiter.isRateLimited("k", {})).toBe(false);
+    });
+    it("reports the smallest exceeded window, since that is the one evaluated first", async () => {
+        const { limiter } = await begin();
+        await limiter.isRateLimited("k", { perMin: 1, perHour: 10 });
+        expect(await limiter.isRateLimited("k", { perMin: 1, perHour: 10 })).toMatchObject({ window: "perMin" });
+    });
+    it("keeps tracker keys apart", async () => {
+        const { limiter } = await begin();
+        await limiter.isRateLimited("a", { perMin: 1 });
+        expect(await limiter.isRateLimited("b", { perMin: 1 })).toBe(false);
+    });
+    it("starts a fresh count once the fixed window rolls over", async () => {
+        const { clock, limiter } = await begin();
+        await limiter.isRateLimited("k", { perMin: 1 });
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).not.toBe(false);
+        clock.set(START + 61_000);
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).toBe(false);
+    });
+    for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
+        it(`enforces ${key} and resets after it`, async () => {
+            const { clock, limiter } = await begin();
+            const policy = { [key]: 1 };
+            expect(await limiter.isRateLimited("k", policy)).toBe(false);
+            expect(await limiter.isRateLimited("k", policy)).toMatchObject({ window: key, limit: 1 });
+            clock.set(START + (seconds + 1) * 1000);
+            expect(await limiter.isRateLimited("k", policy)).toBe(false);
+        });
+    }
+};

package/dist/testing/lambderSessionStoreConformance.d.ts

@@ -0,0 +1,27 @@
+import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderSessionStoreConformanceOptions = LambderConformanceRunner & {
+    /** A store holding no sessions, built for one case over the case's clock. */
+    create: (setup: LambderConformanceSetup) => LambderSessionStore | Promise<LambderSessionStore>;
+    /** What the store's `isMemoryOnly` must say: true only for a store nothing outlives the process of. Default: false. */
+    isMemoryOnly?: boolean;
+};
+/**
+ * Registers the session store rules as cases of the runner, one `it` each,
+ * against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderSessionStoreConformance } from "lambder/testing";
+ *
+ * describe("PostgresSessionStore", () => {
+ *     lambderSessionStoreConformance({ it, expect, create: async () => { await emptySessions(); return new PostgresSessionStore(pool); } });
+ * });
+ * ```
+ *
+ * The records a case writes are dated from the case's clock, which starts at
+ * a fixed moment and stands still unless a case moves it: a store that
+ * expires records by the system clock, rather than by `now`, finds them all
+ * long expired.
+ */
+export declare const lambderSessionStoreConformance: (options: LambderSessionStoreConformanceOptions) => void;

package/dist/testing/lambderSessionStoreConformance.js

@@ -0,0 +1,165 @@
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/**
+ * Registers the session store rules as cases of the runner, one `it` each,
+ * against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderSessionStoreConformance } from "lambder/testing";
+ *
+ * describe("PostgresSessionStore", () => {
+ *     lambderSessionStoreConformance({ it, expect, create: async () => { await emptySessions(); return new PostgresSessionStore(pool); } });
+ * });
+ * ```
+ *
+ * The records a case writes are dated from the case's clock, which starts at
+ * a fixed moment and stands still unless a case moves it: a store that
+ * expires records by the system clock, rather than by `now`, finds them all
+ * long expired.
+ */
+export const lambderSessionStoreConformance = (options) => {
+    const { it, expect } = options;
+    const isMemoryOnly = options.isMemoryOnly ?? false;
+    const startSeconds = Math.floor(START / 1000);
+    const begin = async () => await options.create(conformanceClock());
+    const sessionRecord = (over = {}) => ({
+        sessionKeyHash: "partition-a",
+        secretHash: "secret-1",
+        csrfTokenHash: "csrf-1",
+        sessionKey: "user-1",
+        data: { name: "Ada" },
+        createdAt: startSeconds,
+        expiresAt: startSeconds + 3600,
+        lastAccessedAt: startSeconds,
+        ttlInSeconds: 3600,
+        dataVersion: 0,
+        ...over,
+    });
+    it("says whether it outlives the process, which is what gates non-cryptographic hashing", async () => {
+        expect((await begin()).isMemoryOnly).toBe(isMemoryOnly);
+    });
+    it("round-trips a record under its two hashes", async () => {
+        const store = await begin();
+        await store.create(sessionRecord());
+        const read = await store.get("partition-a", "secret-1");
+        expect(read).toMatchObject({ sessionKey: "user-1", csrfTokenHash: "csrf-1", data: { name: "Ada" }, dataVersion: 0 });
+    });
+    it("answers null for a record that is absent, never throws", async () => {
+        const store = await begin();
+        expect(await store.get("partition-a", "nope")).toBeNull();
+        expect(await store.get("no-such-partition", "secret-1")).toBeNull();
+    });
+    it("refuses to create a record over an existing one: a session is minted once", async () => {
+        const store = await begin();
+        await store.create(sessionRecord());
+        await expect(store.create(sessionRecord({ data: { name: "Grace" } }))).rejects.toThrow();
+        expect(await store.get("partition-a", "secret-1")).toMatchObject({ data: { name: "Ada" } });
+        expect(await store.listSecretHashes("partition-a")).toEqual(["secret-1"]);
+    });
+    it("lists the secret hashes of one partition and nothing from another", async () => {
+        const store = await begin();
+        await store.create(sessionRecord({ secretHash: "secret-1" }));
+        await store.create(sessionRecord({ secretHash: "secret-2" }));
+        await store.create(sessionRecord({ sessionKeyHash: "partition-b", secretHash: "secret-3" }));
+        expect((await store.listSecretHashes("partition-a")).sort()).toEqual(["secret-1", "secret-2"]);
+        expect(await store.listSecretHashes("partition-b")).toEqual(["secret-3"]);
+        expect(await store.listSecretHashes("partition-empty")).toEqual([]);
+    });
+    it("deletes one session without touching its siblings", async () => {
+        const store = await begin();
+        await store.create(sessionRecord({ secretHash: "secret-1" }));
+        await store.create(sessionRecord({ secretHash: "secret-2" }));
+        expect(await store.delete("partition-a", "secret-1")).toMatchObject({ secretHash: "secret-1", sessionKey: "user-1" });
+        expect(await store.get("partition-a", "secret-1")).toBeNull();
+        expect(await store.get("partition-a", "secret-2")).not.toBeNull();
+    });
+    it("hands back the record as it was stored when deleted, a later write included", async () => {
+        const store = await begin();
+        await store.create(sessionRecord());
+        await store.update("partition-a", "secret-1", { data: { name: "Grace" } });
+        expect((await store.delete("partition-a", "secret-1"))?.data).toEqual({ name: "Grace" });
+    });
+    it("deleting a record that is already gone is a no-op that answers null, not an error", async () => {
+        const store = await begin();
+        await expect(store.delete("partition-a", "never-existed")).resolves.toBeNull();
+    });
+    it("updates the named fields of a live record and leaves the rest", async () => {
+        const store = await begin();
+        await store.create(sessionRecord());
+        const at = startSeconds + 30;
+        expect(await store.update("partition-a", "secret-1", { dataExpiresAt: at })).toBe("updated");
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Grace" }, expiresAt: at + 7200, lastAccessedAt: at })).toBe("updated");
+        expect(await store.get("partition-a", "secret-1")).toMatchObject({
+            data: { name: "Grace" }, dataExpiresAt: at, expiresAt: at + 7200, lastAccessedAt: at,
+            sessionKey: "user-1", csrfTokenHash: "csrf-1", createdAt: startSeconds,
+        });
+    });
+    it("never brings back a record that vanished: an update of one answers missing", async () => {
+        // A logout that lands while a renewal is in flight must stay a
+        // logout, so an update of a deleted record writes nothing at all.
+        const store = await begin();
+        await store.create(sessionRecord());
+        await store.delete("partition-a", "secret-1");
+        expect(await store.update("partition-a", "secret-1", { expiresAt: startSeconds + 7200 })).toBe("missing");
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Grace" } }, { dataVersion: 0 })).toBe("missing");
+        expect(await store.get("partition-a", "secret-1")).toBeNull();
+    });
+    it("moves dataVersion by one on each write of data or dataExpiresAt, and on no other write", async () => {
+        const store = await begin();
+        await store.create(sessionRecord());
+        const at = startSeconds + 30;
+        const versionNow = async () => (await store.get("partition-a", "secret-1"))?.dataVersion;
+        await store.update("partition-a", "secret-1", { lastAccessedAt: at, expiresAt: at + 3600 });
+        expect(await versionNow()).toBe(0);
+        await store.update("partition-a", "secret-1", { data: { name: "Grace" } });
+        expect(await versionNow()).toBe(1);
+        await store.update("partition-a", "secret-1", { dataExpiresAt: at });
+        expect(await versionNow()).toBe(2);
+        // One write carrying both, and the slide beside them, is one step.
+        await store.update("partition-a", "secret-1", { data: { name: "Lin" }, dataExpiresAt: at + 600, lastAccessedAt: at });
+        expect(await versionNow()).toBe(3);
+    });
+    it("applies a conditioned update only while dataVersion is the one it was read with, and says stale otherwise", async () => {
+        const store = await begin();
+        await store.create(sessionRecord());
+        const at = startSeconds + 30;
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Grace" }, dataExpiresAt: at }, { dataVersion: 1 })).toBe("stale");
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Grace" }, dataExpiresAt: at }, { dataVersion: 0 })).toBe("updated");
+        // That write moved the version, so the one it named no longer holds.
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Lin" } }, { dataVersion: 0 })).toBe("stale");
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Lin" } }, { dataVersion: 1 })).toBe("updated");
+        expect(await store.get("partition-a", "secret-1")).toMatchObject({ data: { name: "Lin" }, dataExpiresAt: at, dataVersion: 2 });
+    });
+    it("answers stale after a mark that wrote the deadline already stored, in the second a refresh read it", async () => {
+        // The record falls due this second, a read starts its refresh, and a
+        // revocation marks it due in that same second. The deadline reads
+        // exactly as the refresh read it, so a condition on the deadline
+        // would let the refresh land data derived before the revocation for
+        // a whole data TTL. Only the version shows the mark.
+        const store = await begin();
+        await store.create(sessionRecord({ dataExpiresAt: startSeconds }));
+        const read = (await store.get("partition-a", "secret-1"));
+        expect(await store.update("partition-a", "secret-1", { dataExpiresAt: startSeconds })).toBe("updated");
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Grace" }, dataExpiresAt: startSeconds + 600 }, { dataVersion: read.dataVersion })).toBe("stale");
+        expect(await store.get("partition-a", "secret-1")).toMatchObject({ data: { name: "Ada" }, dataExpiresAt: startSeconds });
+    });
+    it("answers stale after a second mark in the second of the first, which a refresh of the first did not see", async () => {
+        // The first revocation marks the record due, a read starts a refresh
+        // that sees only that one, and a second revocation marks it again in
+        // the same second. Both marks write the same deadline, so only the
+        // version tells the refresh that it is one revocation behind.
+        const store = await begin();
+        await store.create(sessionRecord({ dataExpiresAt: startSeconds + 600 }));
+        await store.update("partition-a", "secret-1", { dataExpiresAt: startSeconds });
+        const read = (await store.get("partition-a", "secret-1"));
+        await store.update("partition-a", "secret-1", { dataExpiresAt: startSeconds });
+        expect(await store.update("partition-a", "secret-1", { data: { name: "Grace" }, dataExpiresAt: startSeconds + 600 }, { dataVersion: read.dataVersion })).toBe("stale");
+        expect(await store.get("partition-a", "secret-1")).toMatchObject({ data: { name: "Ada" }, dataExpiresAt: startSeconds, dataVersion: 2 });
+    });
+    it("holds data with an undefined inside it the way JSON does, rather than refusing it", async () => {
+        const store = await begin();
+        await store.create(sessionRecord({ data: { name: "Ada", nickname: undefined } }));
+        await store.update("partition-a", "secret-1", { data: { name: "Grace", nickname: undefined } });
+        expect((await store.get("partition-a", "secret-1"))?.data).toEqual({ name: "Grace" });
+    });
+};

package/dist/testing.d.ts

@@ -9,15 +9,29 @@
  *
  * The sibling of `lambder/mock`, which serves a contract from mock handlers
  * for frontend work. This one runs the real handlers.
+ *
+ * Beside the test app, the store conformance suites: the rules each store
+ * interface promises the engines, for an app to run against a store it
+ * writes itself.
  */
 export { lambderTestApp } from "./testing/LambderTestApp.js";
 export type { LambderTestApp, LambderTestAppOptions, LambderTestedInstance } from "./testing/LambderTestApp.js";
 export type { LambderTestVisitor, LambderTestVisitorOptions, LambderTestRequestInit } from "./testing/LambderTestVisitor.js";
 export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export { lambderSessionStoreConformance } from "./testing/lambderSessionStoreConformance.js";
+export type { LambderSessionStoreConformanceOptions } from "./testing/lambderSessionStoreConformance.js";
+export { lambderIdempotencyStoreConformance } from "./testing/lambderIdempotencyStoreConformance.js";
+export type { LambderIdempotencyStoreConformanceOptions } from "./testing/lambderIdempotencyStoreConformance.js";
+export { lambderRateLimiterConformance } from "./testing/lambderRateLimiterConformance.js";
+export type { LambderRateLimiterConformanceOptions } from "./testing/lambderRateLimiterConformance.js";
+export { lambderOneShotSecretStoreConformance } from "./testing/lambderOneShotSecretStoreConformance.js";
+export type { LambderOneShotSecretStoreConformanceOptions } from "./testing/lambderOneShotSecretStoreConformance.js";
+export type { LambderConformanceRunner, LambderConformanceIt, LambderConformanceExpect, LambderConformanceAssertion, LambderConformanceSetup, } from "./testing/LambderConformanceRunner.js";
 export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
 export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
+export { LambderMemoryOneShotSecretStore } from "./stores/LambderMemoryOneShotSecretStore.js";
 export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
 export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
 export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";

package/dist/testing.js

@@ -9,15 +9,27 @@
  *
  * The sibling of `lambder/mock`, which serves a contract from mock handlers
  * for frontend work. This one runs the real handlers.
+ *
+ * Beside the test app, the store conformance suites: the rules each store
+ * interface promises the engines, for an app to run against a store it
+ * writes itself.
  */
 export { lambderTestApp } from "./testing/LambderTestApp.js";
 export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+// The rules each store interface promises, as cases an app registers with its
+// own runner's `it` and `expect` to hold a store it writes over its own
+// database to the same rules Lambder's memory and DynamoDB stores meet.
+export { lambderSessionStoreConformance } from "./testing/lambderSessionStoreConformance.js";
+export { lambderIdempotencyStoreConformance } from "./testing/lambderIdempotencyStoreConformance.js";
+export { lambderRateLimiterConformance } from "./testing/lambderRateLimiterConformance.js";
+export { lambderOneShotSecretStoreConformance } from "./testing/lambderOneShotSecretStoreConformance.js";
 // What a test reaches for beside the test app: the stores to inspect or to
 // hand it, a file source over fixtures, the refusal codes to assert on, and
 // the types of what a visitor and its session hand back.
 export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
 export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
+export { LambderMemoryOneShotSecretStore } from "./stores/LambderMemoryOneShotSecretStore.js";
 export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
 export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
 export { LambderLocalFileSource } from "./stores/LambderLocalFileSource.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "8.1.1",
+  "version": "8.3.1",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [