@udibo/oauth2 0.1.0

package/esm/testing/contract/mod.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Contract test suites for the framework's service and store interfaces.
+ *
+ * These runners register `describe` / `it` blocks that verify a
+ * consumer's implementation of `UserServiceInterface`,
+ * `ClientServiceInterface`, `TokenServiceInterface`,
+ * `TokenReaderInterface`, `AuthorizationCodeServiceInterface`, or
+ * `DeviceAuthorizationServiceInterface` satisfies what the framework
+ * expects. The same suites run against the library's `Memory*Service`
+ * fixtures and shipped token readers internally, so consumers and the
+ * library are tested by the exact same checks.
+ *
+ * The identity layer's storage seams — `MfaStore`, `TokenFlowStore`,
+ * `OtpStore`, `RateLimitStore`, `LockoutStore` — have runners of their
+ * own. Those interfaces document methods that **must be atomic**
+ * (single-use recovery codes, single-use links, the TOTP replay guard,
+ * the guess and failure budgets), and each suite checks that claim with
+ * overlapping calls: a read-modify-write implementation passes every
+ * sequential case and fails the concurrent one, which is the whole
+ * reason the suites exist.
+ *
+ * Each runner takes a factory + seed-helpers because `add` / `register`
+ * methods aren't part of the public service interface — the consumer
+ * tells the runner how to populate test data.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { runUserServiceContractTests, type UserServiceContractOptions, } from "./user.js";
+export { type ClientServiceContractOptions, runClientServiceContractTests, } from "./client.js";
+export { runTokenServiceContractTests, type TokenServiceContractOptions, } from "./token.js";
+export { runTokenReaderContractTests, type TokenReaderContractFixture, type TokenReaderContractOptions, } from "./token-reader.js";
+export { type AuthorizationCodeServiceContractOptions, runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
+export { type DeviceAuthorizationServiceContractOptions, runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";
+export { type MfaStoreContractOptions, runMfaStoreContractTests, } from "./mfa-store.js";
+export { runTokenFlowStoreContractTests, type TokenFlowStoreContractOptions, } from "./token-flow-store.js";
+export { type OtpStoreContractOptions, runOtpStoreContractTests, } from "./otp-store.js";
+export { type RateLimitStoreContractOptions, runRateLimitStoreContractTests, } from "./rate-limit-store.js";
+export { type LockoutStoreContractOptions, runLockoutStoreContractTests, } from "./lockout-store.js";

package/esm/testing/contract/mod.js

@@ -0,0 +1,39 @@
+/**
+ * Contract test suites for the framework's service and store interfaces.
+ *
+ * These runners register `describe` / `it` blocks that verify a
+ * consumer's implementation of `UserServiceInterface`,
+ * `ClientServiceInterface`, `TokenServiceInterface`,
+ * `TokenReaderInterface`, `AuthorizationCodeServiceInterface`, or
+ * `DeviceAuthorizationServiceInterface` satisfies what the framework
+ * expects. The same suites run against the library's `Memory*Service`
+ * fixtures and shipped token readers internally, so consumers and the
+ * library are tested by the exact same checks.
+ *
+ * The identity layer's storage seams — `MfaStore`, `TokenFlowStore`,
+ * `OtpStore`, `RateLimitStore`, `LockoutStore` — have runners of their
+ * own. Those interfaces document methods that **must be atomic**
+ * (single-use recovery codes, single-use links, the TOTP replay guard,
+ * the guess and failure budgets), and each suite checks that claim with
+ * overlapping calls: a read-modify-write implementation passes every
+ * sequential case and fails the concurrent one, which is the whole
+ * reason the suites exist.
+ *
+ * Each runner takes a factory + seed-helpers because `add` / `register`
+ * methods aren't part of the public service interface — the consumer
+ * tells the runner how to populate test data.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { runUserServiceContractTests, } from "./user.js";
+export { runClientServiceContractTests, } from "./client.js";
+export { runTokenServiceContractTests, } from "./token.js";
+export { runTokenReaderContractTests, } from "./token-reader.js";
+export { runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
+export { runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";
+export { runMfaStoreContractTests, } from "./mfa-store.js";
+export { runTokenFlowStoreContractTests, } from "./token-flow-store.js";
+export { runOtpStoreContractTests, } from "./otp-store.js";
+export { runRateLimitStoreContractTests, } from "./rate-limit-store.js";
+export { runLockoutStoreContractTests, } from "./lockout-store.js";

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

@@ -0,0 +1,48 @@
+/**
+ * Contract test suite for {@link OtpStore} implementations — the storage behind
+ * emailed one-time codes.
+ *
+ * A six-digit code is guessable online, so the attempt budget is the only thing
+ * standing between an attacker and a one-in-a-million draw. `recordAttempt` is
+ * what enforces it, and it only enforces it when concurrent guesses cannot
+ * share a count — which is what this suite checks.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runOtpStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { OtpStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshOtpStore(): Promise<OtpStore>;
+ *
+ * runOtpStoreContractTests({
+ *   describeName: "DrizzleOtpStore satisfies OtpStore contract",
+ *   makeStore: freshOtpStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { OtpStore } from "../../identity/otp.js";
+/** Options for {@link runOtpStoreContractTests}. */
+export interface OtpStoreContractOptions {
+    /**
+     * Returns a fresh, empty store for each test. Isolation is required — an
+     * active code left behind by one test makes the `findActive` checks
+     * meaningless.
+     */
+    makeStore(): Promise<OtpStore> | OtpStore;
+    /**
+     * Overrides the name passed to the outer `describe` block. Defaults to
+     * `"OtpStore contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link OtpStore} contract suite. Call it from your own test file —
+ * it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The concurrency case fires overlapping `recordAttempt` calls and requires
+ * each to see a distinct count; a store that reads, awaits, then writes hands
+ * the same count to every guess and fails it.
+ */
+export declare function runOtpStoreContractTests(options: OtpStoreContractOptions): void;

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

@@ -0,0 +1,197 @@
+/**
+ * Contract test suite for {@link OtpStore} implementations — the storage behind
+ * emailed one-time codes.
+ *
+ * A six-digit code is guessable online, so the attempt budget is the only thing
+ * standing between an attacker and a one-in-a-million draw. `recordAttempt` is
+ * what enforces it, and it only enforces it when concurrent guesses cannot
+ * share a count — which is what this suite checks.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runOtpStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { OtpStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshOtpStore(): Promise<OtpStore>;
+ *
+ * runOtpStoreContractTests({
+ *   describeName: "DrizzleOtpStore satisfies OtpStore contract",
+ *   makeStore: freshOtpStore,
+ * });
+ * ```
+ *
+ * @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 EMAIL = "user@example.com";
+const OTHER_EMAIL = "other@example.com";
+const PURPOSE = "signin";
+const OTHER_PURPOSE = "step-up";
+let sequence = 0;
+function record(overrides = {}) {
+    const now = Date.now();
+    return {
+        id: `otp-${++sequence}`,
+        email: EMAIL,
+        purpose: PURPOSE,
+        codeHash: "hash",
+        expiresAt: now + 600_000,
+        attempts: 0,
+        maxAttempts: 5,
+        createdAt: now,
+        ...overrides,
+    };
+}
+/**
+ * Runs the {@link OtpStore} contract suite. Call it from your own test file —
+ * it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The concurrency case fires overlapping `recordAttempt` calls and requires
+ * each to see a distinct count; a store that reads, awaits, then writes hands
+ * the same count to every guess and fails it.
+ */
+export function runOtpStoreContractTests(options) {
+    describe(options.describeName ?? "OtpStore contract", () => {
+        let store;
+        beforeEach(async () => {
+            store = await options.makeStore();
+        });
+        describe("create / findActive", () => {
+            it("returns null when the pair has no code", async () => {
+                assertStrictEquals(await store.findActive(EMAIL, PURPOSE), null);
+            });
+            it("round-trips every field of a created record", async () => {
+                const created = record({ codeHash: "hash-1", maxAttempts: 3 });
+                await store.create(created);
+                const found = await store.findActive(EMAIL, PURPOSE);
+                assert(found !== null, "a created record must be findable");
+                assertStrictEquals(found.id, created.id);
+                assertStrictEquals(found.email, created.email);
+                assertStrictEquals(found.purpose, created.purpose);
+                assertStrictEquals(found.codeHash, created.codeHash);
+                assertStrictEquals(found.expiresAt, created.expiresAt);
+                assertStrictEquals(found.attempts, 0);
+                assertStrictEquals(found.maxAttempts, 3);
+            });
+            it("returns the most recently created active record", async () => {
+                const now = Date.now();
+                const older = record({ createdAt: now - 1000, codeHash: "old" });
+                const newer = record({ createdAt: now, codeHash: "new" });
+                await store.create(older);
+                await store.create(newer);
+                assertStrictEquals((await store.findActive(EMAIL, PURPOSE))?.id, newer.id, "a re-send supersedes the code before it");
+            });
+            it("returns an expired record rather than hiding it", async () => {
+                await store.create(record({ expiresAt: Date.now() - 1000 }));
+                assert(await store.findActive(EMAIL, PURPOSE) !== null, "expiry is the service's call — it reports `expired` distinctly " +
+                    "from `invalid`, which it cannot do if the store swallows the row");
+            });
+            it("scopes lookups by email and by purpose", async () => {
+                await store.create(record());
+                assertStrictEquals(await store.findActive(OTHER_EMAIL, PURPOSE), null);
+                assertStrictEquals(await store.findActive(EMAIL, OTHER_PURPOSE), null);
+            });
+        });
+        describe("consume", () => {
+            it("claims an active code only once under concurrency", async () => {
+                const created = record();
+                await store.create(created);
+                const results = await Promise.all([
+                    store.consume(created.id),
+                    store.consume(created.id),
+                ]);
+                assertEquals(results.sort(), [false, true]);
+                assertStrictEquals(await store.consume("missing-code"), false);
+            });
+            it("takes the record out of the active set", async () => {
+                const created = record();
+                await store.create(created);
+                await store.consume(created.id);
+                assertStrictEquals(await store.findActive(EMAIL, PURPOSE), null);
+            });
+            it("leaves an older active code findable", async () => {
+                const now = Date.now();
+                const older = record({ createdAt: now - 1000 });
+                const newer = record({ createdAt: now });
+                await store.create(older);
+                await store.create(newer);
+                await store.consume(newer.id);
+                assertStrictEquals((await store.findActive(EMAIL, PURPOSE))?.id, older.id);
+            });
+            it("is a no-op for an unknown id", async () => {
+                const created = record();
+                await store.create(created);
+                await store.consume("no-such-id");
+                assertStrictEquals((await store.findActive(EMAIL, PURPOSE))?.id, created.id);
+            });
+        });
+        describe("invalidateById", () => {
+            it("deactivates only the named record", async () => {
+                const now = Date.now();
+                const undelivered = record({ createdAt: now });
+                const previous = record({ createdAt: now - 1000 });
+                await store.create(previous);
+                await store.create(undelivered);
+                await store.invalidateById(undelivered.id);
+                assertStrictEquals((await store.findActive(EMAIL, PURPOSE))?.id, previous.id, "discarding an undeliverable code must not take a concurrent " +
+                    "request's code with it");
+            });
+            it("is a no-op for an unknown id", async () => {
+                const created = record();
+                await store.create(created);
+                await store.invalidateById("no-such-id");
+                assertStrictEquals((await store.findActive(EMAIL, PURPOSE))?.id, created.id);
+            });
+        });
+        describe("invalidate", () => {
+            it("deactivates every active code for the pair", async () => {
+                await store.create(record({ createdAt: Date.now() - 1000 }));
+                await store.create(record());
+                await store.invalidate(EMAIL, PURPOSE);
+                assertStrictEquals(await store.findActive(EMAIL, PURPOSE), null);
+            });
+            it("leaves other emails and other purposes alone", async () => {
+                await store.create(record());
+                await store.create(record({ email: OTHER_EMAIL }));
+                await store.create(record({ purpose: OTHER_PURPOSE }));
+                await store.invalidate(EMAIL, PURPOSE);
+                assert(await store.findActive(OTHER_EMAIL, PURPOSE) !== null);
+                assert(await store.findActive(EMAIL, OTHER_PURPOSE) !== null);
+            });
+            it("is a no-op when the pair has no active code", async () => {
+                await store.invalidate(EMAIL, PURPOSE);
+                assertStrictEquals(await store.findActive(EMAIL, PURPOSE), null);
+            });
+        });
+        describe("recordAttempt", () => {
+            it("returns the count after the increment", async () => {
+                const created = record();
+                await store.create(created);
+                assertStrictEquals(await store.recordAttempt(created.id), 1);
+                assertStrictEquals(await store.recordAttempt(created.id), 2);
+                assertStrictEquals(await store.recordAttempt(created.id), 3);
+            });
+            it("returns 0 for an unknown id", async () => {
+                assertStrictEquals(await store.recordAttempt("no-such-id"), 0);
+            });
+            it("counts each record separately", async () => {
+                const mine = record();
+                const theirs = record({ email: OTHER_EMAIL });
+                await store.create(mine);
+                await store.create(theirs);
+                await store.recordAttempt(mine.id);
+                await store.recordAttempt(mine.id);
+                assertStrictEquals(await store.recordAttempt(theirs.id), 1);
+            });
+            it("gives every concurrent guess its own count", async () => {
+                const created = record({ maxAttempts: 5 });
+                await store.create(created);
+                const counts = await Promise.all(Array.from({ length: 5 }, () => store.recordAttempt(created.id)));
+                assertEquals([...counts].sort((a, b) => a - b), [1, 2, 3, 4, 5], "the guess budget is spent by the returned count — concurrent " +
+                    "guesses sharing one count spend the budget once and let the " +
+                    "rest through");
+            });
+        });
+    });
+}

package/esm/testing/contract/rate-limit-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Contract test suite for {@link RateLimitStore} implementations — the shared
+ * counter behind `RateLimiter`.
+ *
+ * The limiter allows or denies on the count `increment` returns, so a store
+ * that lets two concurrent attempts read the same count raises the effective
+ * threshold by exactly the burst the limiter exists to catch. That is the case
+ * this suite exists for.
+ *
+ * @example Verify a Redis-backed store
+ * ```ts
+ * import { runRateLimitStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { RateLimitStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshRateLimitStore(): Promise<RateLimitStore>;
+ *
+ * runRateLimitStoreContractTests({
+ *   describeName: "RedisRateLimitStore satisfies RateLimitStore contract",
+ *   makeStore: freshRateLimitStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { RateLimitStore } from "../../identity/rate-limit.js";
+/** Options for {@link runRateLimitStoreContractTests}. */
+export interface RateLimitStoreContractOptions {
+    /**
+     * Returns a fresh, empty store for each test. Isolation is required — a
+     * counter surviving into the next test shifts every count the suite asserts.
+     */
+    makeStore(): Promise<RateLimitStore> | RateLimitStore;
+    /**
+     * How far `resetAt` may sit from `now + windowMs`, in ms — headroom for a
+     * store whose backend rounds a TTL (Redis rounds to whole seconds). Defaults
+     * to 1000.
+     */
+    resetAtToleranceMs?: number;
+    /**
+     * Overrides the name passed to the outer `describe` block. Defaults to
+     * `"RateLimitStore contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link RateLimitStore} 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 window cases are clock-free
+ * and never need a timer.
+ */
+export declare function runRateLimitStoreContractTests(options: RateLimitStoreContractOptions): void;

package/esm/testing/contract/rate-limit-store.js

@@ -0,0 +1,105 @@
+/**
+ * Contract test suite for {@link RateLimitStore} implementations — the shared
+ * counter behind `RateLimiter`.
+ *
+ * The limiter allows or denies on the count `increment` returns, so a store
+ * that lets two concurrent attempts read the same count raises the effective
+ * threshold by exactly the burst the limiter exists to catch. That is the case
+ * this suite exists for.
+ *
+ * @example Verify a Redis-backed store
+ * ```ts
+ * import { runRateLimitStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { RateLimitStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshRateLimitStore(): Promise<RateLimitStore>;
+ *
+ * runRateLimitStoreContractTests({
+ *   describeName: "RedisRateLimitStore satisfies RateLimitStore contract",
+ *   makeStore: freshRateLimitStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import { assert, assertAlmostEquals, assertEquals } 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 KEY = "signin:1.2.3.4";
+const OTHER_KEY = "signin:5.6.7.8";
+const WINDOW_MS = 60_000;
+/**
+ * Runs the {@link RateLimitStore} 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 window cases are clock-free
+ * and never need a timer.
+ */
+export function runRateLimitStoreContractTests(options) {
+    const tolerance = options.resetAtToleranceMs ?? 1000;
+    describe(options.describeName ?? "RateLimitStore contract", () => {
+        let store;
+        let now;
+        beforeEach(async () => {
+            store = await options.makeStore();
+            now = Date.now();
+        });
+        describe("increment", () => {
+            it("opens a window at count 1 that ends one window from now", async () => {
+                const result = await store.increment(KEY, WINDOW_MS, now);
+                assertEquals(result.count, 1);
+                assertAlmostEquals(result.resetAt, now + WINDOW_MS, tolerance);
+            });
+            it("counts up within the window without moving its end", async () => {
+                const first = await store.increment(KEY, WINDOW_MS, now);
+                const second = await store.increment(KEY, WINDOW_MS, now + 10);
+                const third = await store.increment(KEY, WINDOW_MS, now + 20);
+                assertEquals([second.count, third.count], [2, 3]);
+                assertEquals([second.resetAt, third.resetAt], [first.resetAt, first.resetAt], "a fixed window ends when it ends — hits inside it must not push " +
+                    "the reset out");
+            });
+            it("opens a fresh window once the previous one has lapsed", async () => {
+                const first = await store.increment(KEY, WINDOW_MS, now);
+                const after = first.resetAt + 1;
+                const result = await store.increment(KEY, WINDOW_MS, after);
+                assertEquals(result.count, 1);
+                assertAlmostEquals(result.resetAt, after + WINDOW_MS, tolerance);
+            });
+            it("counts each key on its own", async () => {
+                await store.increment(KEY, WINDOW_MS, now);
+                await store.increment(KEY, WINDOW_MS, now);
+                const other = await store.increment(OTHER_KEY, WINDOW_MS, now);
+                assertEquals(other.count, 1);
+            });
+            it("gives every concurrent hit its own count", async () => {
+                const results = await Promise.all(Array.from({ length: 5 }, () => store.increment(KEY, WINDOW_MS, now)));
+                assertEquals(results.map((result) => result.count).sort((a, b) => a - b), [1, 2, 3, 4, 5], "the limiter decides on the returned count — concurrent hits " +
+                    "sharing a count are exactly the burst that slips past the " +
+                    "threshold");
+                const next = await store.increment(KEY, WINDOW_MS, now);
+                assertEquals(next.count, 6, "no hit may be lost to a stale read");
+            });
+        });
+        describe("reset", () => {
+            it("sends the key back to a fresh window", async () => {
+                await store.increment(KEY, WINDOW_MS, now);
+                await store.increment(KEY, WINDOW_MS, now);
+                await store.reset(KEY);
+                const result = await store.increment(KEY, WINDOW_MS, now);
+                assertEquals(result.count, 1);
+                assertAlmostEquals(result.resetAt, now + WINDOW_MS, tolerance);
+            });
+            it("clears only the key it is given", async () => {
+                await store.increment(KEY, WINDOW_MS, now);
+                await store.increment(OTHER_KEY, WINDOW_MS, now);
+                await store.reset(KEY);
+                const other = await store.increment(OTHER_KEY, WINDOW_MS, now);
+                assertEquals(other.count, 2);
+            });
+            it("is a no-op for a key with no counter", async () => {
+                await store.reset("never-seen");
+                const result = await store.increment("never-seen", WINDOW_MS, now);
+                assert(result.count === 1);
+            });
+        });
+    });
+}

package/esm/testing/contract/token-flow-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Contract test suite for {@link TokenFlowStore} implementations — the storage
+ * behind verification links, password-reset links, and magic links.
+ *
+ * The load-bearing method is `markConsumed`: it is what makes a link
+ * single-use, and only a conditional write survives two requests redeeming one
+ * link at the same time. This suite issues those two requests.
+ *
+ * @example Verify a database-backed store
+ * ```ts
+ * import { runTokenFlowStoreContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { TokenFlowStore } from "@udibo/oauth2/identity";
+ *
+ * declare function freshTokenFlowStore(): Promise<TokenFlowStore>;
+ *
+ * runTokenFlowStoreContractTests({
+ *   describeName: "DrizzleTokenFlowStore satisfies TokenFlowStore contract",
+ *   makeStore: freshTokenFlowStore,
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { TokenFlowStore } from "../../identity/token-flow.js";
+/** Options for {@link runTokenFlowStoreContractTests}. */
+export interface TokenFlowStoreContractOptions {
+    /**
+     * Returns a fresh, empty store for each test. Isolation is required — a
+     * record surviving into the next test makes the single-use checks
+     * meaningless.
+     */
+    makeStore(): Promise<TokenFlowStore> | TokenFlowStore;
+    /**
+     * Set to `false` when the store deliberately omits the optional
+     * {@link TokenFlowStore.deleteBySubject}. The suite then registers an ignored
+     * case naming what is not covered — outstanding links stay redeemable until
+     * they expire — instead of passing in silence. Defaults to `true`, so a store
+     * that meant to implement it and does not fails loudly.
+     */
+    deleteBySubject?: boolean;
+    /**
+     * Overrides the name passed to the outer `describe` block. Defaults to
+     * `"TokenFlowStore contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link TokenFlowStore} contract suite. Call it from your own test
+ * file — it registers `describe` / `it` blocks the test runner picks up.
+ *
+ * The concurrency cases redeem one token from two callers at once; a store that
+ * reads, awaits, then writes hands the token to both and fails them.
+ */
+export declare function runTokenFlowStoreContractTests(options: TokenFlowStoreContractOptions): void;