@udibo/oauth2 0.1.0

package/esm/testing/contract/device-authorization.js

@@ -0,0 +1,193 @@
+/**
+ * Contract test suite for {@link DeviceAuthorizationServiceInterface}
+ * implementations (RFC 8628).
+ *
+ * @module
+ */
+import { assert, assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
+const defaultMakeClient = (seq) => ({
+    id: `client-${seq}`,
+    grants: ["urn:ietf:params:oauth:grant-type:device_code"],
+});
+/** Runs the {@link DeviceAuthorizationServiceInterface} contract suite. */
+export function runDeviceAuthorizationServiceContractTests(options) {
+    const makeUser = options.makeUser ?? (defaultMakeUser);
+    const makeClient = options.makeClient ?? (defaultMakeClient);
+    describe(options.describeName ??
+        "DeviceAuthorizationServiceInterface contract", () => {
+        let userService;
+        let clientService;
+        let deviceService;
+        let user;
+        let client;
+        beforeEach(async () => {
+            const services = await options.makeServices();
+            userService = services.userService;
+            clientService = services.clientService;
+            deviceService = services.deviceAuthorizationService;
+            user = makeUser(1);
+            client = makeClient(1);
+            await options.addUser(userService, user, "pw");
+            await options.addClient(clientService, client);
+        });
+        async function makeDeviceAuth() {
+            return {
+                deviceCode: await deviceService.generateDeviceCode(client),
+                userCode: await deviceService.generateUserCode(client),
+                expiresAt: await deviceService.expiresAt(client),
+                client,
+                interval: deviceService.interval,
+            };
+        }
+        it("generateDeviceCode and generateUserCode produce unique strings", async () => {
+            const d1 = await deviceService.generateDeviceCode(client);
+            const d2 = await deviceService.generateDeviceCode(client);
+            const u1 = await deviceService.generateUserCode(client);
+            const u2 = await deviceService.generateUserCode(client);
+            assert(d1 !== d2, "device codes should not collide");
+            assert(u1 !== u2, "user codes should not collide");
+        });
+        it("save + lookup by device code", async () => {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            const fetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assertEquals(fetched?.deviceCode, auth.deviceCode);
+            assertEquals(fetched?.client.id, client.id);
+        });
+        it("save + lookup by user code", async () => {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            const fetched = await deviceService.getByUserCode(auth.userCode);
+            assertEquals(fetched?.userCode, auth.userCode);
+        });
+        it("getByDeviceCode / getByUserCode return undefined for unknown codes", async () => {
+            assertStrictEquals(await deviceService.getByDeviceCode("missing"), undefined);
+            assertStrictEquals(await deviceService.getByUserCode("missing"), undefined);
+        });
+        it("approve marks the authorization with the approving user", async () => {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            const approved = await deviceService.approve(auth, user);
+            assertStrictEquals(approved.authorized, true);
+            assertEquals(approved.user.id, user.id);
+            const refetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assertStrictEquals(refetched?.authorized, true);
+        });
+        it("deny marks the authorization as denied", async () => {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            const denied = await deviceService.deny(auth);
+            assertStrictEquals(denied.denied, true);
+            const refetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assertStrictEquals(refetched?.denied, true);
+        });
+        it("updateLastPolled records a poll time", async () => {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            const updated = await deviceService.updateLastPolled(auth);
+            assert(updated.lastPolled instanceof Date);
+            const refetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assert(refetched?.lastPolled instanceof Date);
+        });
+        it("revoke deletes by object and by string", async () => {
+            const auth1 = await makeDeviceAuth();
+            await deviceService.save(auth1);
+            assertStrictEquals(await deviceService.revoke(auth1), true);
+            assertStrictEquals(await deviceService.getByDeviceCode(auth1.deviceCode), undefined);
+            const auth2 = await makeDeviceAuth();
+            await deviceService.save(auth2);
+            assertStrictEquals(await deviceService.revoke(auth2.deviceCode), true);
+            assertStrictEquals(await deviceService.getByDeviceCode(auth2.deviceCode), undefined);
+        });
+        it("revoke answers true only for the call that removed a live authorization", async () => {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            assertStrictEquals(await deviceService.revoke(auth), true);
+            assertStrictEquals(await deviceService.revoke(auth), false);
+            assertStrictEquals(await deviceService.revoke(auth.deviceCode), false);
+        });
+        async function saveDeviceAuth() {
+            const auth = await makeDeviceAuth();
+            await deviceService.save(auth);
+            const byDeviceCode = await deviceService.getByDeviceCode(auth.deviceCode);
+            const byUserCode = await deviceService.getByUserCode(auth.userCode);
+            assert(byDeviceCode, "getByDeviceCode should resolve what was saved");
+            assert(byUserCode, "getByUserCode should resolve what was saved");
+            return { auth, byDeviceCode, byUserCode };
+        }
+        async function assertUnreachableByEitherCode(auth) {
+            assertStrictEquals(await deviceService.getByDeviceCode(auth.deviceCode), undefined, "a revoked authorization must not resolve by its device code");
+            assertStrictEquals(await deviceService.getByUserCode(auth.userCode), undefined, "a revoked authorization must not resolve by its user code");
+        }
+        it("revoke by full record clears both the device-code and user-code lookups", async () => {
+            const { auth } = await saveDeviceAuth();
+            assertStrictEquals(await deviceService.revoke(auth), true);
+            await assertUnreachableByEitherCode(auth);
+        });
+        it("revoke by raw device code clears both the device-code and user-code lookups", async () => {
+            const { auth } = await saveDeviceAuth();
+            assertStrictEquals(await deviceService.revoke(auth.deviceCode), true);
+            await assertUnreachableByEitherCode(auth);
+        });
+        it("revoke accepts the record getByDeviceCode returns and clears both lookups", async () => {
+            const { auth, byDeviceCode } = await saveDeviceAuth();
+            assertStrictEquals(await deviceService.revoke(byDeviceCode), true);
+            await assertUnreachableByEitherCode(auth);
+        });
+        it("revoke accepts the record getByUserCode returns and clears both lookups", async () => {
+            const { auth, byUserCode } = await saveDeviceAuth();
+            assertStrictEquals(await deviceService.revoke(byUserCode), true);
+            await assertUnreachableByEitherCode(auth);
+        });
+        it("revoke answers true once across the hydrated shapes of one authorization", async () => {
+            const { byDeviceCode, byUserCode } = await saveDeviceAuth();
+            assertStrictEquals(await deviceService.revoke(byDeviceCode), true);
+            assertStrictEquals(await deviceService.revoke(byUserCode), false);
+        });
+        it("revoke answers true to exactly one of two concurrent claims", async () => {
+            const { auth, byDeviceCode } = await saveDeviceAuth();
+            const claims = await Promise.all([
+                deviceService.revoke(byDeviceCode),
+                deviceService.revoke(byDeviceCode),
+            ]);
+            assertEquals(claims.filter(Boolean).length, 1, "concurrent polls of one device code must not both be told they claimed it");
+            await assertUnreachableByEitherCode(auth);
+        });
+        it("revoke of a user-code-hydrated record consumes the device code", async () => {
+            const { auth, byUserCode } = await saveDeviceAuth();
+            await deviceService.approve(byUserCode, user);
+            await deviceService.revoke(byUserCode);
+            assertStrictEquals(await deviceService.getByDeviceCode(auth.deviceCode), undefined, "a cancelled authorization must not stay redeemable by its device code");
+        });
+        it("approve accepts the record getByUserCode returns", async () => {
+            const { auth, byUserCode } = await saveDeviceAuth();
+            const approved = await deviceService.approve(byUserCode, user);
+            assertStrictEquals(approved.authorized, true);
+            const refetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assertStrictEquals(refetched?.authorized, true);
+            assertEquals(refetched?.user?.id, user.id);
+        });
+        it("approve accepts the record getByDeviceCode returns", async () => {
+            const { auth, byDeviceCode } = await saveDeviceAuth();
+            await deviceService.approve(byDeviceCode, user);
+            const refetched = await deviceService.getByUserCode(auth.userCode);
+            assertStrictEquals(refetched?.authorized, true);
+        });
+        it("deny accepts the record getByUserCode returns", async () => {
+            const { auth, byUserCode } = await saveDeviceAuth();
+            const denied = await deviceService.deny(byUserCode);
+            assertStrictEquals(denied.denied, true);
+            const refetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assertStrictEquals(refetched?.denied, true);
+        });
+        it("updateLastPolled accepts the record getByDeviceCode returns", async () => {
+            const { auth, byDeviceCode } = await saveDeviceAuth();
+            const updated = await deviceService.updateLastPolled(byDeviceCode);
+            assert(updated.lastPolled instanceof Date);
+            const refetched = await deviceService.getByDeviceCode(auth.deviceCode);
+            assert(refetched?.lastPolled instanceof Date, "the poll time must be visible to the next read");
+        });
+    });
+}

package/esm/testing/contract/lockout-store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Contract test suite for {@link LockoutStore} implementations — the
+ * per-account failure counter behind `AccountLockout`.
+ *
+ * `AccountLockout` locks on the failure count `increment` returns, so a store
+ * that lets concurrent failed sign-ins share a count undershoots the threshold:
+ * the brute-force floor the lockout is meant to be moves up by however many
+ * attempts an attacker can land at once.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runLockoutStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { LockoutStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshLockoutStore(): Promise<LockoutStore>;
+ *
+ * runLockoutStoreContractTests({
+ *   describeName: "DrizzleLockoutStore satisfies LockoutStore contract",
+ *   makeStore: freshLockoutStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { LockoutStore } from "../../identity/lockout.js";
+/** Options for {@link runLockoutStoreContractTests}. */
+export interface LockoutStoreContractOptions {
+    /**
+     * Returns a fresh, empty store for each test. Isolation is required — a
+     * failure count surviving into the next test shifts every count the suite
+     * asserts.
+     */
+    makeStore(): Promise<LockoutStore> | LockoutStore;
+    /**
+     * Overrides the name passed to the outer `describe` block. Defaults to
+     * `"LockoutStore contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link LockoutStore} contract suite. Call it from your own test
+ * file — it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * `now` is passed explicitly on every call, so the lock-expiry cases are
+ * clock-free and never need a timer.
+ */
+export declare function runLockoutStoreContractTests(options: LockoutStoreContractOptions): void;

package/esm/testing/contract/lockout-store.js

@@ -0,0 +1,122 @@
+/**
+ * Contract test suite for {@link LockoutStore} implementations — the
+ * per-account failure counter behind `AccountLockout`.
+ *
+ * `AccountLockout` locks on the failure count `increment` returns, so a store
+ * that lets concurrent failed sign-ins share a count undershoots the threshold:
+ * the brute-force floor the lockout is meant to be moves up by however many
+ * attempts an attacker can land at once.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runLockoutStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { LockoutStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshLockoutStore(): Promise<LockoutStore>;
+ *
+ * runLockoutStoreContractTests({
+ *   describeName: "DrizzleLockoutStore satisfies LockoutStore contract",
+ *   makeStore: freshLockoutStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import { assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+const USER = "user-1";
+const OTHER_USER = "user-2";
+/**
+ * Runs the {@link LockoutStore} contract suite. Call it from your own test
+ * file — it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * `now` is passed explicitly on every call, so the lock-expiry cases are
+ * clock-free and never need a timer.
+ */
+export function runLockoutStoreContractTests(options) {
+    describe(options.describeName ?? "LockoutStore contract", () => {
+        let store;
+        let now;
+        beforeEach(async () => {
+            store = await options.makeStore();
+            now = Date.now();
+        });
+        describe("get", () => {
+            it("returns undefined for an account with no record", async () => {
+                assertStrictEquals(await store.get(USER), undefined);
+            });
+        });
+        describe("increment", () => {
+            it("records the first failure as one", async () => {
+                const result = await store.increment(USER, now);
+                assertEquals(result.failures, 1);
+                assertStrictEquals(result.lockedUntil, undefined);
+                assertEquals((await store.get(USER))?.failures, 1);
+            });
+            it("adds one failure per call", async () => {
+                await store.increment(USER, now);
+                await store.increment(USER, now);
+                assertEquals((await store.increment(USER, now)).failures, 3);
+            });
+            it("counts each account on its own", async () => {
+                await store.increment(USER, now);
+                await store.increment(USER, now);
+                assertEquals((await store.increment(OTHER_USER, now)).failures, 1);
+            });
+            it("keeps an active lock while counting the failure", async () => {
+                const lockedUntil = now + 60_000;
+                await store.set(USER, { failures: 10, lockedUntil });
+                const result = await store.increment(USER, now);
+                assertEquals(result.failures, 11);
+                assertStrictEquals(result.lockedUntil, lockedUntil, "a failed attempt against a locked account must not extend or drop " +
+                    "the lock the store is holding");
+            });
+            it("starts a fresh count once the lock has expired", async () => {
+                await store.set(USER, { failures: 10, lockedUntil: now - 1 });
+                const result = await store.increment(USER, now);
+                assertEquals(result.failures, 1);
+                assertStrictEquals(result.lockedUntil, undefined, "an expired lock must be dropped, not carried into the next window");
+            });
+            it("gives every concurrent failure its own count", async () => {
+                const results = await Promise.all(Array.from({ length: 5 }, () => store.increment(USER, now)));
+                assertEquals(results.map((result) => result.failures).sort((a, b) => a - b), [1, 2, 3, 4, 5], "the lockout triggers on the returned count — concurrent failures " +
+                    "sharing a count undershoot the threshold");
+                assertEquals((await store.get(USER))?.failures, 5);
+            });
+        });
+        describe("set", () => {
+            it("persists the record as given", async () => {
+                const lockedUntil = now + 60_000;
+                await store.set(USER, { failures: 10, lockedUntil });
+                const record = await store.get(USER);
+                assertEquals(record?.failures, 10);
+                assertStrictEquals(record?.lockedUntil, lockedUntil);
+            });
+            it("replaces a record that was already there", async () => {
+                await store.increment(USER, now);
+                await store.set(USER, { failures: 4 });
+                const record = await store.get(USER);
+                assertEquals(record?.failures, 4);
+                assertStrictEquals(record?.lockedUntil, undefined);
+            });
+        });
+        describe("clear", () => {
+            it("drops the account's failures and lock", async () => {
+                await store.set(USER, { failures: 10, lockedUntil: now + 60_000 });
+                await store.clear(USER);
+                assertStrictEquals(await store.get(USER), undefined);
+                assertEquals((await store.increment(USER, now)).failures, 1);
+            });
+            it("clears only the account it is given", async () => {
+                await store.increment(USER, now);
+                await store.increment(OTHER_USER, now);
+                await store.clear(USER);
+                assertEquals((await store.get(OTHER_USER))?.failures, 1);
+            });
+            it("is a no-op for an account with no record", async () => {
+                await store.clear(USER);
+                assertStrictEquals(await store.get(USER), undefined);
+            });
+        });
+    });
+}

package/esm/testing/contract/mfa-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Contract test suite for {@link MfaStore} implementations.
+ *
+ * `MfaService` leans on three store methods for its concurrency guarantees —
+ * `activateTotp` (compare-and-swap on the pending secret), `advanceLastStep`
+ * (monotonic replay guard), and `consumeRecoveryHash` (single-use recovery
+ * codes). This suite checks each of them with concurrent calls, so a
+ * read-modify-write implementation fails here instead of silently letting two
+ * requests spend one recovery code.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runMfaStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { MfaStore } from "@udibo/oauth2/identity/mfa";
+ *
+ * declare function freshMfaStore(): Promise<MfaStore>;
+ *
+ * runMfaStoreContractTests({
+ *   describeName: "DrizzleMfaStore satisfies MfaStore contract",
+ *   makeStore: freshMfaStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { MfaStore } from "../../identity/mfa/service.js";
+/** Options for {@link runMfaStoreContractTests}. */
+export interface MfaStoreContractOptions {
+    /**
+     * Returns a fresh, empty store for each test. Isolation is required — a
+     * recovery hash left behind by one test makes the single-use checks
+     * meaningless.
+     */
+    makeStore(): Promise<MfaStore> | MfaStore;
+    /**
+     * Overrides the name passed to the outer `describe` block. Defaults to
+     * `"MfaStore contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link MfaStore} contract suite. Call it from your own test file —
+ * it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The atomicity cases issue two or more overlapping calls and assert the
+ * outcome a conditional write produces. An implementation that reads, then
+ * awaits, then writes fails them, which is the point: the same store passes
+ * every sequential check.
+ */
+export declare function runMfaStoreContractTests(options: MfaStoreContractOptions): void;

package/esm/testing/contract/mfa-store.js

@@ -0,0 +1,226 @@
+/**
+ * Contract test suite for {@link MfaStore} implementations.
+ *
+ * `MfaService` leans on three store methods for its concurrency guarantees —
+ * `activateTotp` (compare-and-swap on the pending secret), `advanceLastStep`
+ * (monotonic replay guard), and `consumeRecoveryHash` (single-use recovery
+ * codes). This suite checks each of them with concurrent calls, so a
+ * read-modify-write implementation fails here instead of silently letting two
+ * requests spend one recovery code.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runMfaStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { MfaStore } from "@udibo/oauth2/identity/mfa";
+ *
+ * declare function freshMfaStore(): Promise<MfaStore>;
+ *
+ * runMfaStoreContractTests({
+ *   describeName: "DrizzleMfaStore satisfies MfaStore contract",
+ *   makeStore: freshMfaStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import { assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+const USER = "user-1";
+const OTHER_USER = "user-2";
+const SECRET_A = "AAAAAAAAAAAAAAAA";
+const SECRET_B = "BBBBBBBBBBBBBBBB";
+function countTrue(results) {
+    return results.filter((result) => result).length;
+}
+/**
+ * Runs the {@link MfaStore} contract suite. Call it from your own test file —
+ * it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The atomicity cases issue two or more overlapping calls and assert the
+ * outcome a conditional write produces. An implementation that reads, then
+ * awaits, then writes fails them, which is the point: the same store passes
+ * every sequential check.
+ */
+export function runMfaStoreContractTests(options) {
+    describe(options.describeName ?? "MfaStore contract", () => {
+        let store;
+        beforeEach(async () => {
+            store = await options.makeStore();
+        });
+        describe("getTotp / setPendingTotp", () => {
+            it("returns undefined for a user with no record", async () => {
+                assertStrictEquals(await store.getTotp(USER), undefined);
+            });
+            it("stores a pending secret without activating it", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                const record = await store.getTotp(USER);
+                assertEquals(record?.pendingSecretBase32, SECRET_A);
+                assertStrictEquals(record?.secretBase32, undefined);
+            });
+            it("replaces a previous pending secret", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                await store.setPendingTotp(USER, SECRET_B);
+                const record = await store.getTotp(USER);
+                assertEquals(record?.pendingSecretBase32, SECRET_B);
+            });
+            it("keeps an active credential when a new enrollment starts", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                await store.activateTotp(USER, SECRET_A, 100);
+                await store.setPendingTotp(USER, SECRET_B);
+                const record = await store.getTotp(USER);
+                assertEquals(record?.secretBase32, SECRET_A);
+                assertEquals(record?.lastStep, 100);
+                assertEquals(record?.pendingSecretBase32, SECRET_B);
+            });
+            it("keeps each user's record separate", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                assertStrictEquals(await store.getTotp(OTHER_USER), undefined);
+            });
+        });
+        describe("activateTotp", () => {
+            it("promotes the matching pending secret and clears it", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                assertStrictEquals(await store.activateTotp(USER, SECRET_A, 42), true);
+                const record = await store.getTotp(USER);
+                assertEquals(record?.secretBase32, SECRET_A);
+                assertEquals(record?.lastStep, 42);
+                assertStrictEquals(record?.pendingSecretBase32, undefined);
+            });
+            it("refuses when the user has no pending secret", async () => {
+                assertStrictEquals(await store.activateTotp(USER, SECRET_A, 42), false);
+                assertStrictEquals(await store.getTotp(USER), undefined);
+            });
+            it("refuses a secret a newer enrollment replaced, changing nothing", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                await store.setPendingTotp(USER, SECRET_B);
+                assertStrictEquals(await store.activateTotp(USER, SECRET_A, 42), false);
+                const record = await store.getTotp(USER);
+                assertStrictEquals(record?.secretBase32, undefined);
+                assertEquals(record?.pendingSecretBase32, SECRET_B);
+            });
+            it("activates for exactly one of two concurrent confirmations", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                const results = await Promise.all([
+                    store.activateTotp(USER, SECRET_A, 10),
+                    store.activateTotp(USER, SECRET_A, 20),
+                ]);
+                assertStrictEquals(countTrue(results), 1, "the pending secret must be claimable once — a second concurrent " +
+                    "confirmation finds it already spent");
+                const record = await store.getTotp(USER);
+                assertEquals(record?.secretBase32, SECRET_A);
+                assertStrictEquals(record?.pendingSecretBase32, undefined);
+            });
+            it("activates for exactly one of two concurrent enrollments", async () => {
+                await store.setPendingTotp(USER, SECRET_B);
+                const results = await Promise.all([
+                    store.activateTotp(USER, SECRET_A, 10),
+                    store.activateTotp(USER, SECRET_B, 20),
+                ]);
+                assertStrictEquals(countTrue(results), 1);
+                const record = await store.getTotp(USER);
+                assertEquals(record?.secretBase32, SECRET_B, "only the secret that was actually pending may become active");
+            });
+        });
+        describe("clearTotp", () => {
+            it("removes the active credential and any pending secret", async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                await store.activateTotp(USER, SECRET_A, 5);
+                await store.setPendingTotp(USER, SECRET_B);
+                await store.clearTotp(USER);
+                assertStrictEquals(await store.getTotp(USER), undefined);
+            });
+            it("is a no-op for a user with no record", async () => {
+                await store.clearTotp(USER);
+                assertStrictEquals(await store.getTotp(USER), undefined);
+            });
+        });
+        describe("advanceLastStep", () => {
+            beforeEach(async () => {
+                await store.setPendingTotp(USER, SECRET_A);
+                await store.activateTotp(USER, SECRET_A, 100);
+            });
+            it("advances to a higher step", async () => {
+                assertStrictEquals(await store.advanceLastStep(USER, 101), true);
+                assertEquals((await store.getTotp(USER))?.lastStep, 101);
+            });
+            it("refuses the step already spent", async () => {
+                assertStrictEquals(await store.advanceLastStep(USER, 100), false);
+                assertEquals((await store.getTotp(USER))?.lastStep, 100);
+            });
+            it("refuses an earlier step, leaving the guard where it was", async () => {
+                assertStrictEquals(await store.advanceLastStep(USER, 99), false);
+                assertEquals((await store.getTotp(USER))?.lastStep, 100);
+            });
+            it("refuses for a user with no record", async () => {
+                assertStrictEquals(await store.advanceLastStep(OTHER_USER, 1), false);
+            });
+            it("admits exactly one of two concurrent claims on the same step", async () => {
+                const results = await Promise.all([
+                    store.advanceLastStep(USER, 101),
+                    store.advanceLastStep(USER, 101),
+                ]);
+                assertStrictEquals(countTrue(results), 1, "a time step is spendable once — the loser must read as a replay");
+                assertEquals((await store.getTotp(USER))?.lastStep, 101);
+            });
+            it("never regresses under concurrent claims on different steps", async () => {
+                await Promise.all([
+                    store.advanceLastStep(USER, 105),
+                    store.advanceLastStep(USER, 101),
+                ]);
+                assertEquals((await store.getTotp(USER))?.lastStep, 105, "the highest accepted step must survive a concurrent lower one");
+            });
+        });
+        describe("recovery hashes", () => {
+            it("returns an empty list for a user with none", async () => {
+                assertEquals(await store.getRecoveryHashes(USER), []);
+            });
+            it("replaces the stored set exactly", async () => {
+                await store.setRecoveryHashes(USER, ["h1", "h2", "h3"]);
+                assertEquals([...await store.getRecoveryHashes(USER)].sort(), ["h1", "h2", "h3"]);
+                await store.setRecoveryHashes(USER, ["h4"]);
+                assertEquals(await store.getRecoveryHashes(USER), ["h4"]);
+            });
+            it("clears the set when given an empty list", async () => {
+                await store.setRecoveryHashes(USER, ["h1"]);
+                await store.setRecoveryHashes(USER, []);
+                assertEquals(await store.getRecoveryHashes(USER), []);
+            });
+            it("keeps each user's codes separate", async () => {
+                await store.setRecoveryHashes(USER, ["h1"]);
+                assertEquals(await store.getRecoveryHashes(OTHER_USER), []);
+                assertStrictEquals(await store.consumeRecoveryHash(OTHER_USER, "h1"), false);
+                assertEquals(await store.getRecoveryHashes(USER), ["h1"]);
+            });
+            it("burns a consumed hash and refuses it afterwards", async () => {
+                await store.setRecoveryHashes(USER, ["h1", "h2"]);
+                assertStrictEquals(await store.consumeRecoveryHash(USER, "h1"), true);
+                assertStrictEquals(await store.consumeRecoveryHash(USER, "h1"), false);
+                assertEquals(await store.getRecoveryHashes(USER), ["h2"]);
+            });
+            it("refuses a hash that was never stored", async () => {
+                await store.setRecoveryHashes(USER, ["h1"]);
+                assertStrictEquals(await store.consumeRecoveryHash(USER, "nope"), false);
+                assertEquals(await store.getRecoveryHashes(USER), ["h1"]);
+            });
+            it("burns a code for exactly one of two concurrent redemptions", async () => {
+                await store.setRecoveryHashes(USER, ["h1", "h2"]);
+                const results = await Promise.all([
+                    store.consumeRecoveryHash(USER, "h1"),
+                    store.consumeRecoveryHash(USER, "h1"),
+                ]);
+                assertStrictEquals(countTrue(results), 1, "a recovery code is single-use — two requests racing one code must " +
+                    "not both be told they redeemed it");
+                assertEquals(await store.getRecoveryHashes(USER), ["h2"]);
+            });
+            it("burns both codes when two different ones are redeemed concurrently", async () => {
+                await store.setRecoveryHashes(USER, ["h1", "h2", "h3"]);
+                const results = await Promise.all([
+                    store.consumeRecoveryHash(USER, "h1"),
+                    store.consumeRecoveryHash(USER, "h2"),
+                ]);
+                assertStrictEquals(countTrue(results), 2);
+                assertEquals(await store.getRecoveryHashes(USER), ["h3"], "neither deletion may be lost to the other's stale read");
+            });
+        });
+    });
+}