@udibo/oauth2 0.1.0

package/esm/testing/contract/token-flow-store.js

@@ -0,0 +1,179 @@
+/**
+ * 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 { 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 PURPOSE = "password-reset";
+const OTHER_PURPOSE = "email-verification";
+const SUBJECT = "user-1";
+const OTHER_SUBJECT = "user-2";
+function countTrue(results) {
+    return results.filter((result) => result).length;
+}
+function record(overrides) {
+    const now = Date.now();
+    return {
+        purpose: PURPOSE,
+        subject: SUBJECT,
+        expiresAt: now + 60_000,
+        createdAt: now,
+        ...overrides,
+    };
+}
+/**
+ * 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 function runTokenFlowStoreContractTests(options) {
+    const expectDeleteBySubject = options.deleteBySubject ?? true;
+    describe(options.describeName ?? "TokenFlowStore contract", () => {
+        let store;
+        beforeEach(async () => {
+            store = await options.makeStore();
+        });
+        describe("save / get", () => {
+            it("returns null for an unknown token hash", async () => {
+                assertStrictEquals(await store.get("no-such-hash"), null);
+            });
+            it("round-trips every field of a saved record", async () => {
+                const saved = record({
+                    tokenHash: "hash-1",
+                    data: { email: "user@example.com" },
+                });
+                await store.save(saved);
+                const fetched = await store.get("hash-1");
+                assert(fetched !== null, "a saved record must be readable back");
+                assertEquals(fetched.purpose, saved.purpose);
+                assertEquals(fetched.subject, saved.subject);
+                assertEquals(fetched.data, saved.data);
+                assertStrictEquals(fetched.expiresAt, saved.expiresAt);
+                assertStrictEquals(fetched.createdAt, saved.createdAt);
+                assertStrictEquals(fetched.consumedAt, undefined);
+            });
+            it("returns an expired record rather than hiding it", async () => {
+                await store.save(record({ tokenHash: "hash-expired", expiresAt: Date.now() - 1000 }));
+                const fetched = await store.get("hash-expired");
+                assert(fetched !== null, "expiry is the service's call — it reports `expired` distinctly " +
+                    "from `invalid`, which it cannot do if the store swallows the row");
+            });
+            it("keeps records with different hashes independent", async () => {
+                await store.save(record({ tokenHash: "hash-1" }));
+                await store.save(record({ tokenHash: "hash-2" }));
+                assertStrictEquals((await store.get("hash-1"))?.tokenHash, "hash-1");
+                assertStrictEquals((await store.get("hash-2"))?.tokenHash, "hash-2");
+            });
+        });
+        describe("markConsumed", () => {
+            it("claims a live record and stamps it", async () => {
+                await store.save(record({ tokenHash: "hash-1" }));
+                const consumedAt = Date.now();
+                assertStrictEquals(await store.markConsumed("hash-1", consumedAt), true);
+                assertStrictEquals((await store.get("hash-1"))?.consumedAt, consumedAt);
+            });
+            it("refuses a record already consumed, keeping the first stamp", async () => {
+                await store.save(record({ tokenHash: "hash-1" }));
+                const first = Date.now();
+                await store.markConsumed("hash-1", first);
+                assertStrictEquals(await store.markConsumed("hash-1", first + 5_000), false);
+                assertStrictEquals((await store.get("hash-1"))?.consumedAt, first, "a losing claim must not overwrite the winner's record");
+            });
+            it("refuses an unknown token hash", async () => {
+                assertStrictEquals(await store.markConsumed("no-such-hash", Date.now()), false);
+            });
+            it("claims a token for exactly one of two concurrent redemptions", async () => {
+                await store.save(record({ tokenHash: "hash-1" }));
+                const now = Date.now();
+                const results = await Promise.all([
+                    store.markConsumed("hash-1", now),
+                    store.markConsumed("hash-1", now + 1),
+                ]);
+                assertStrictEquals(countTrue(results), 1, "a link is single-use — two requests racing one link must not both " +
+                    "be told they claimed it");
+            });
+            it("claims both tokens when two different ones are redeemed concurrently", async () => {
+                await store.save(record({ tokenHash: "hash-1" }));
+                await store.save(record({ tokenHash: "hash-2" }));
+                const now = Date.now();
+                const results = await Promise.all([
+                    store.markConsumed("hash-1", now),
+                    store.markConsumed("hash-2", now),
+                ]);
+                assertStrictEquals(countTrue(results), 2);
+                assert((await store.get("hash-1"))?.consumedAt !== undefined &&
+                    (await store.get("hash-2"))?.consumedAt !== undefined, "neither stamp may be lost to the other's stale read");
+            });
+        });
+        if (expectDeleteBySubject) {
+            describe("deleteBySubject", () => {
+                it("is implemented", () => {
+                    assert(typeof store.deleteBySubject === "function", "deleteBySubject is optional, but without it " +
+                        "`TokenFlowService.invalidate` returns false and outstanding " +
+                        "links stay redeemable until they expire. Implement it, or pass " +
+                        "`deleteBySubject: false` to record the gap.");
+                });
+                it("drops the pending tokens for one (purpose, subject)", async () => {
+                    await store.save(record({ tokenHash: "hash-1" }));
+                    await store.save(record({ tokenHash: "hash-2" }));
+                    await store.deleteBySubject(PURPOSE, SUBJECT);
+                    assertStrictEquals(await store.get("hash-1"), null);
+                    assertStrictEquals(await store.get("hash-2"), null);
+                });
+                it("leaves other subjects and other purposes alone", async () => {
+                    await store.save(record({ tokenHash: "hash-mine" }));
+                    await store.save(record({ tokenHash: "hash-other-subject", subject: OTHER_SUBJECT }));
+                    await store.save(record({ tokenHash: "hash-other-purpose", purpose: OTHER_PURPOSE }));
+                    await store.deleteBySubject(PURPOSE, SUBJECT);
+                    assertStrictEquals(await store.get("hash-mine"), null);
+                    assert(await store.get("hash-other-subject") !== null, "another subject's token must survive");
+                    assert(await store.get("hash-other-purpose") !== null, "the same subject's token for another purpose must survive");
+                });
+                it("is a no-op when the pair has no tokens", async () => {
+                    await store.save(record({ tokenHash: "hash-1" }));
+                    await store.deleteBySubject(PURPOSE, OTHER_SUBJECT);
+                    assert(await store.get("hash-1") !== null);
+                });
+                it("keeps an already-consumed record so it still reads as consumed", async () => {
+                    await store.save(record({ tokenHash: "hash-used" }));
+                    await store.save(record({ tokenHash: "hash-pending" }));
+                    assertStrictEquals(await store.markConsumed("hash-used", Date.now()), true);
+                    await store.deleteBySubject(PURPOSE, SUBJECT);
+                    assertStrictEquals(await store.get("hash-pending"), null, "the pending token must be dropped");
+                    const used = await store.get("hash-used");
+                    assert(used !== null, "a consumed record must survive so inspect() can answer " +
+                        "`consumed` rather than the generic `invalid`");
+                    assert(used.consumedAt !== undefined, "the surviving record must still carry its consumedAt stamp");
+                });
+            });
+        }
+        else {
+            it({
+                name: "deleteBySubject is not implemented — outstanding links stay redeemable until they expire (deleteBySubject: false)",
+                ignore: true,
+                fn: () => { },
+            });
+        }
+    });
+}

package/esm/testing/contract/token-reader.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Contract test suite for {@link TokenReaderInterface} implementations.
+ *
+ * A resource server only ever calls `getToken`, so the contract is small
+ * and strict: an accepted token comes back with the same access-token
+ * string and a projected client, and anything the reader cannot validate
+ * resolves to `undefined` rather than throwing — `undefined` is what the
+ * resource server turns into `invalid_token`. Thrown errors are reserved
+ * for transport and misconfiguration.
+ *
+ * Run it against the shipped readers, or against your own reader when your
+ * API validates tokens out of a shared database.
+ *
+ * @example
+ * ```ts
+ * import { runTokenReaderContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { ClientInterface, TokenReaderInterface } from "@udibo/oauth2/server";
+ *
+ * interface AppUser {
+ *   id: string;
+ *   username: string;
+ * }
+ * declare function freshTokenReader(): Promise<
+ *   TokenReaderInterface<ClientInterface, AppUser>
+ * >;
+ *
+ * runTokenReaderContractTests<ClientInterface, AppUser>({
+ *   setup: async () => ({
+ *     reader: await freshTokenReader(),
+ *     validAccessToken: "seeded-token",
+ *     expected: { clientId: "my-client", userId: "u1", scope: "read" },
+ *     invalidAccessTokens: ["unknown-token", "revoked-token"],
+ *   }),
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { TokenReaderInterface } from "../../server/services/token.js";
+/** The reader under test plus the tokens the suite exercises it with. */
+export interface TokenReaderContractFixture<C extends ClientInterface, U, S extends AbstractScope = BasicScope> {
+    /** The reader under test. */
+    reader: TokenReaderInterface<C, U, S>;
+    /** An access token the reader must accept. */
+    validAccessToken: string;
+    /** What the accepted token must project. */
+    expected: {
+        /** `client.id` the reader must report for {@linkcode validAccessToken}. */
+        clientId: string;
+        /** `user.id` the reader must report, when the token represents a user. */
+        userId?: string;
+        /** Granted scope, as its string form, when the token carries one. */
+        scope?: string;
+    };
+    /**
+     * Access tokens the reader must reject with `undefined` — at minimum one
+     * it has never seen. Add the rejection paths specific to your reader
+     * (revoked, expired, wrong audience) to widen the coverage.
+     */
+    invalidAccessTokens: string[];
+    /** Releases anything `setup` allocated (a mock server, a database). */
+    cleanup?(): Promise<void> | void;
+}
+/** Options for {@link runTokenReaderContractTests}. */
+export interface TokenReaderContractOptions<C extends ClientInterface, U, S extends AbstractScope = BasicScope> {
+    /**
+     * Builds a fresh fixture for each test. Must be isolated — one test
+     * leaking state into another defeats the contract guarantees.
+     */
+    setup(): Promise<TokenReaderContractFixture<C, U, S>> | TokenReaderContractFixture<C, U, S>;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/** Runs the {@link TokenReaderInterface} contract suite. */
+export declare function runTokenReaderContractTests<C extends ClientInterface, U, S extends AbstractScope = BasicScope>(options: TokenReaderContractOptions<C, U, S>): void;

package/esm/testing/contract/token-reader.js

@@ -0,0 +1,78 @@
+/**
+ * Contract test suite for {@link TokenReaderInterface} implementations.
+ *
+ * A resource server only ever calls `getToken`, so the contract is small
+ * and strict: an accepted token comes back with the same access-token
+ * string and a projected client, and anything the reader cannot validate
+ * resolves to `undefined` rather than throwing — `undefined` is what the
+ * resource server turns into `invalid_token`. Thrown errors are reserved
+ * for transport and misconfiguration.
+ *
+ * Run it against the shipped readers, or against your own reader when your
+ * API validates tokens out of a shared database.
+ *
+ * @example
+ * ```ts
+ * import { runTokenReaderContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { ClientInterface, TokenReaderInterface } from "@udibo/oauth2/server";
+ *
+ * interface AppUser {
+ *   id: string;
+ *   username: string;
+ * }
+ * declare function freshTokenReader(): Promise<
+ *   TokenReaderInterface<ClientInterface, AppUser>
+ * >;
+ *
+ * runTokenReaderContractTests<ClientInterface, AppUser>({
+ *   setup: async () => ({
+ *     reader: await freshTokenReader(),
+ *     validAccessToken: "seeded-token",
+ *     expected: { clientId: "my-client", userId: "u1", scope: "read" },
+ *     invalidAccessTokens: ["unknown-token", "revoked-token"],
+ *   }),
+ * });
+ * ```
+ *
+ * @module
+ */
+import { assert, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { afterEach, beforeEach, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+/** Runs the {@link TokenReaderInterface} contract suite. */
+export function runTokenReaderContractTests(options) {
+    describe(options.describeName ?? "TokenReaderInterface contract", () => {
+        let fixture;
+        beforeEach(async () => {
+            fixture = await options.setup();
+        });
+        afterEach(async () => {
+            await fixture.cleanup?.();
+        });
+        it("echoes back the access token it was given", async () => {
+            const token = await fixture.reader.getToken(fixture.validAccessToken);
+            assertStrictEquals(token?.accessToken, fixture.validAccessToken);
+        });
+        it("projects the client the token was issued to", async () => {
+            const token = await fixture.reader.getToken(fixture.validAccessToken);
+            assertStrictEquals(token?.client.id, fixture.expected.clientId);
+        });
+        it("projects the user the token was issued for", async () => {
+            const token = await fixture.reader.getToken(fixture.validAccessToken);
+            assertStrictEquals(token?.user?.id, fixture.expected.userId);
+        });
+        it("exposes the granted scope", async () => {
+            const token = await fixture.reader.getToken(fixture.validAccessToken);
+            assertStrictEquals(token?.scope?.toString(), fixture.expected.scope);
+        });
+        it("exposes an expiry as a Date when the token carries one", async () => {
+            const token = await fixture.reader.getToken(fixture.validAccessToken);
+            assert(token?.accessTokenExpiresAt === undefined ||
+                token.accessTokenExpiresAt instanceof Date);
+        });
+        it("resolves undefined for tokens it cannot validate", async () => {
+            for (const accessToken of fixture.invalidAccessTokens) {
+                assertStrictEquals(await fixture.reader.getToken(accessToken), undefined, `expected ${accessToken} to be rejected with undefined`);
+            }
+        });
+    });
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Contract test suite for {@link TokenServiceInterface} implementations.
+ *
+ * Verifies the methods the framework actually calls during the OAuth2
+ * flows: token persistence, refresh-token lookup, revocation by token
+ * value or by authorization code, and per-(client, user) lifetime/scope
+ * generation.
+ *
+ * Both a token with a user and a token without one are exercised. The client
+ * credentials grant (RFC 6749 §4.4) has no resource owner, so the framework
+ * calls `acceptedScope`, `generateAccessToken`, and `accessTokenExpiresAt`
+ * with `user: undefined` and persists a token whose `user` is unset — a store
+ * that requires a user cannot hold a machine token.
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import { BasicScope } from "../../models/scope.js";
+import type { AbstractScope } from "../../models/scope.js";
+import type { ClientServiceInterface } from "../../server/services/client.js";
+import type { TokenServiceInterface } from "../../server/services/token.js";
+import type { UserServiceInterface } from "../../server/services/user.js";
+import type { MemoryUserShape } from "../services.js";
+/** Options for {@link runTokenServiceContractTests}. */
+export interface TokenServiceContractOptions<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /** Returns fresh services for each test. */
+    makeServices(): Promise<{
+        userService: UserServiceInterface<U>;
+        clientService: ClientServiceInterface<C, U>;
+        tokenService: TokenServiceInterface<C, U, S>;
+    }> | {
+        userService: UserServiceInterface<U>;
+        clientService: ClientServiceInterface<C, U>;
+        tokenService: TokenServiceInterface<C, U, S>;
+    };
+    /** Persists a user with the given password into the user service under test. */
+    addUser(service: UserServiceInterface<U>, user: U, password: string): Promise<void>;
+    /** Persists a client (optionally with a secret and owning user) into the client service under test. */
+    addClient(service: ClientServiceInterface<C, U>, client: C, secret?: string, ownerUserId?: string): Promise<void>;
+    /** Builds a distinct user fixture for the given sequence number. Defaults to a minimal `{ id, username }` shape. */
+    makeUser?(seq: number): U;
+    /** Builds a distinct client fixture for the given sequence number. Defaults to a client granting `authorization_code` and `refresh_token`. */
+    makeClient?(seq: number): C;
+    /** Builds a scope from its string value. Defaults to a {@linkcode BasicScope}. */
+    makeScope?(value: string): S;
+    /**
+     * Set to `false` when the service deliberately omits the optional
+     * reuse-detection pair, {@linkcode TokenServiceInterface.getRevokedRefreshToken}
+     * and {@linkcode TokenServiceInterface.revokeFamily}. The suite then
+     * registers an ignored case naming what is not covered — a replayed
+     * rotated-out refresh token cannot be detected, so a stolen token keeps
+     * working alongside the victim's — instead of passing in silence. Defaults to
+     * `true`, so a service that meant to implement the pair and does not fails
+     * loudly rather than losing reuse detection quietly.
+     */
+    refreshTokenReuseDetection?: boolean;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/** Runs the {@link TokenServiceInterface} contract suite. */
+export declare function runTokenServiceContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: TokenServiceContractOptions<C, U, S>): void;