@udibo/oauth2 0.1.0

package/esm/testing/contract/token.js

@@ -0,0 +1,287 @@
+/**
+ * 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 { 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";
+import { BasicScope } from "../../models/scope.js";
+const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
+const defaultMakeClient = (seq) => ({
+    id: `client-${seq}`,
+    grants: ["authorization_code", "refresh_token"],
+});
+const defaultMakeScope = (value) => new BasicScope(value);
+/** Runs the {@link TokenServiceInterface} contract suite. */
+export function runTokenServiceContractTests(options) {
+    const makeUser = options.makeUser ?? (defaultMakeUser);
+    const makeClient = options.makeClient ?? (defaultMakeClient);
+    const makeScope = options.makeScope ?? (defaultMakeScope);
+    const expectReuseDetection = options.refreshTokenReuseDetection ?? true;
+    describe(options.describeName ?? "TokenServiceInterface contract", () => {
+        let userService;
+        let clientService;
+        let tokenService;
+        let user;
+        let client;
+        beforeEach(async () => {
+            const services = await options.makeServices();
+            userService = services.userService;
+            clientService = services.clientService;
+            tokenService = services.tokenService;
+            user = makeUser(1);
+            client = makeClient(1);
+            await options.addUser(userService, user, "pw");
+            await options.addClient(clientService, client);
+        });
+        describe("generateAccessToken / generateRefreshToken", () => {
+            it("produces unique access tokens", async () => {
+                const a = await tokenService.generateAccessToken(client, user);
+                const b = await tokenService.generateAccessToken(client, user);
+                assertEquals(typeof a, "string");
+                assertEquals(typeof b, "string");
+                assert(a !== b, "access tokens should not collide");
+            });
+            it("produces unique refresh tokens (or undefined to opt out)", async () => {
+                const a = await tokenService.generateRefreshToken(client, user);
+                const b = await tokenService.generateRefreshToken(client, user);
+                if (a !== undefined && b !== undefined) {
+                    assert(a !== b, "refresh tokens should not collide");
+                }
+            });
+        });
+        describe("acceptedScope", () => {
+            it("returns the requested scope unchanged for the simple case", async () => {
+                const requested = makeScope("read");
+                const result = await tokenService.acceptedScope(client, user, requested);
+                assertEquals(result?.toString(), "read");
+            });
+        });
+        describe("save + getToken", () => {
+            it("round-trips an access-only token", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user);
+                const expiresAt = new Date(Date.now() + 60_000);
+                const token = {
+                    accessToken,
+                    accessTokenExpiresAt: expiresAt,
+                    client,
+                    user,
+                };
+                await tokenService.save(token);
+                const fetched = await tokenService.getToken(accessToken);
+                assertEquals(fetched?.client.id, client.id);
+                assertEquals(fetched?.user?.id, user.id);
+                assertStrictEquals(fetched?.accessTokenExpiresAt?.getTime(), expiresAt.getTime());
+            });
+            it("returns undefined for an unknown access token", async () => {
+                assertStrictEquals(await tokenService.getToken("nope"), undefined);
+            });
+        });
+        describe("tokens with no user", () => {
+            it("generates an access token for a client with no user", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, undefined);
+                assertEquals(typeof accessToken, "string");
+            });
+            it("accepts scope for a client with no user", async () => {
+                const result = await tokenService.acceptedScope(client, undefined, makeScope("read"));
+                assert(result !== false, "scope must not be rejected for lack of a user");
+            });
+            it("dates the expiry of an access token with no user", async () => {
+                const expiresAt = await tokenService.accessTokenExpiresAt(client, undefined);
+                if (expiresAt)
+                    assert(expiresAt.getTime() > Date.now());
+            });
+            it("round-trips a token with no user", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, undefined);
+                await tokenService.save({ accessToken, client });
+                const fetched = await tokenService.getToken(accessToken);
+                assertEquals(fetched?.client.id, client.id);
+                assertStrictEquals(fetched?.user, undefined);
+            });
+            it("revokes a token with no user", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, undefined);
+                await tokenService.save({ accessToken, client });
+                assertStrictEquals(await tokenService.revoke(accessToken), true);
+                assertStrictEquals(await tokenService.getToken(accessToken), undefined);
+            });
+        });
+        describe("save + getRefreshToken", () => {
+            it("round-trips a refresh token", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user);
+                const refreshToken = (await tokenService.generateRefreshToken(client, user));
+                const token = {
+                    accessToken,
+                    accessTokenExpiresAt: new Date(Date.now() + 60_000),
+                    refreshToken,
+                    refreshTokenExpiresAt: new Date(Date.now() + 600_000),
+                    client,
+                    user,
+                };
+                await tokenService.save(token);
+                const fetched = await tokenService.getRefreshToken(refreshToken);
+                assertEquals(fetched?.client.id, client.id);
+            });
+            it("returns undefined for an unknown refresh token", async () => {
+                assertStrictEquals(await tokenService.getRefreshToken("nope"), undefined);
+            });
+        });
+        describe("revoke", () => {
+            it("revokes by token object", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user);
+                const token = {
+                    accessToken,
+                    client,
+                    user,
+                };
+                await tokenService.save(token);
+                const ok = await tokenService.revoke(token);
+                assertStrictEquals(ok, true);
+                assertStrictEquals(await tokenService.getToken(accessToken), undefined);
+            });
+            it("revokes by access token string", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user);
+                await tokenService.save({ accessToken, client, user });
+                const ok = await tokenService.revoke(accessToken);
+                assertStrictEquals(ok, true);
+                assertStrictEquals(await tokenService.getToken(accessToken), undefined);
+            });
+            it("revokes by refresh token string when hint='refresh_token'", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user);
+                const refreshToken = (await tokenService.generateRefreshToken(client, user));
+                await tokenService.save({
+                    accessToken,
+                    refreshToken,
+                    client,
+                    user,
+                });
+                const ok = await tokenService.revoke(refreshToken, "refresh_token");
+                assertStrictEquals(ok, true);
+                assertStrictEquals(await tokenService.getRefreshToken(refreshToken), undefined);
+                assertStrictEquals(await tokenService.getToken(accessToken), undefined);
+            });
+            it("returns false for an unknown token string", async () => {
+                assertStrictEquals(await tokenService.revoke("missing"), false);
+            });
+            it("answers true only for the call that removed a live token", async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user);
+                const token = { accessToken, client, user };
+                assertStrictEquals(await tokenService.revoke(token), false, "a token that was never saved was not revoked by this call — " +
+                    "answering true makes a single-use check built on the result inert");
+                await tokenService.save(token);
+                assertStrictEquals(await tokenService.revoke(token), true);
+                assertStrictEquals(await tokenService.revoke(token), false);
+            });
+        });
+        describe("revokeCode", () => {
+            it("revokes every token issued under a given authorization code", async () => {
+                const code = "shared-code";
+                const accessToken1 = await tokenService.generateAccessToken(client, user);
+                const accessToken2 = await tokenService.generateAccessToken(client, user);
+                await tokenService.save({
+                    accessToken: accessToken1,
+                    code,
+                    client,
+                    user,
+                });
+                await tokenService.save({
+                    accessToken: accessToken2,
+                    code,
+                    client,
+                    user,
+                });
+                const ok = await tokenService.revokeCode(code);
+                assertStrictEquals(ok, true);
+                assertStrictEquals(await tokenService.getToken(accessToken1), undefined);
+                assertStrictEquals(await tokenService.getToken(accessToken2), undefined);
+            });
+            it("returns false when no tokens were issued for the code", async () => {
+                assertStrictEquals(await tokenService.revokeCode("never-used"), false);
+            });
+        });
+        if (expectReuseDetection) {
+            describe("refresh-token rotation family", () => {
+                const FAMILY = "family-1";
+                const OTHER_FAMILY = "family-2";
+                async function saveFamilyMember(familyId) {
+                    const accessToken = await tokenService.generateAccessToken(client, user);
+                    const refreshToken = (await tokenService.generateRefreshToken(client, user));
+                    const token = {
+                        accessToken,
+                        accessTokenExpiresAt: new Date(Date.now() + 60_000),
+                        refreshToken,
+                        refreshTokenExpiresAt: new Date(Date.now() + 600_000),
+                        familyId,
+                        familyCreatedAt: new Date(Date.now() - 60_000),
+                        client,
+                        user,
+                    };
+                    await tokenService.save(token);
+                    return token;
+                }
+                it("implements both halves of reuse detection", () => {
+                    assert(typeof tokenService.getRevokedRefreshToken === "function" &&
+                        typeof tokenService.revokeFamily === "function", "getRevokedRefreshToken and revokeFamily are optional, but " +
+                        "without both the refresh grant cannot tell a replayed " +
+                        "rotated-out token from an unknown one and reuse detection is " +
+                        "silently disabled. Implement them, or pass " +
+                        "`refreshTokenReuseDetection: false` to record the gap.");
+                });
+                it("keeps a rotated-out refresh token findable, with its family", async () => {
+                    const token = await saveFamilyMember(FAMILY);
+                    await tokenService.revoke(token.refreshToken, "refresh_token");
+                    assertStrictEquals(await tokenService.getRefreshToken(token.refreshToken), undefined, "a rotated-out token must no longer refresh");
+                    const revoked = await tokenService.getRevokedRefreshToken(token.refreshToken);
+                    assert(revoked !== undefined, "a revoked refresh token must stay findable — deleting the row " +
+                        "is what turns a replay into an ordinary unknown token");
+                    assertStrictEquals(revoked.familyId, FAMILY);
+                });
+                it("does not report a live refresh token as revoked", async () => {
+                    const token = await saveFamilyMember(FAMILY);
+                    assertStrictEquals(await tokenService.getRevokedRefreshToken(token.refreshToken), undefined, "reporting a live token as revoked turns every legitimate " +
+                        "refresh into a detected replay");
+                });
+                it("returns undefined for a refresh token that was never issued", async () => {
+                    assertStrictEquals(await tokenService.getRevokedRefreshToken("never-issued"), undefined);
+                });
+                it("revokes every live member of a replayed token's family", async () => {
+                    const first = await saveFamilyMember(FAMILY);
+                    const second = await saveFamilyMember(FAMILY);
+                    assertStrictEquals(await tokenService.revokeFamily(FAMILY), true);
+                    assertStrictEquals(await tokenService.getRefreshToken(first.refreshToken), undefined);
+                    assertStrictEquals(await tokenService.getRefreshToken(second.refreshToken), undefined);
+                    assertStrictEquals(await tokenService.getToken(second.accessToken), undefined, "the family's access tokens die with it — leaving them live " +
+                        "keeps the thief's session alive for their remaining lifetime");
+                });
+                it("leaves other families untouched", async () => {
+                    const mine = await saveFamilyMember(FAMILY);
+                    const theirs = await saveFamilyMember(OTHER_FAMILY);
+                    await tokenService.revokeFamily(FAMILY);
+                    assertStrictEquals(await tokenService.getRefreshToken(mine.refreshToken), undefined);
+                    assert(await tokenService.getRefreshToken(theirs.refreshToken) !==
+                        undefined, "one compromised family must not sign every other session out");
+                });
+                it("returns false when the family has no live tokens", async () => {
+                    assertStrictEquals(await tokenService.revokeFamily("never-issued"), false);
+                });
+            });
+        }
+        else {
+            it({
+                name: "refresh-token reuse detection is not implemented — a replayed rotated-out token cannot be detected (refreshTokenReuseDetection: false)",
+                ignore: true,
+                fn: () => { },
+            });
+        }
+    });
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Contract test suite for {@link UserServiceInterface} implementations.
+ *
+ * Apps that swap a `MemoryUserService` for a DB-backed implementation
+ * can run this suite against their factory to verify they satisfy what
+ * the framework expects.
+ *
+ * @example
+ * ```ts
+ * import { runUserServiceContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { UserServiceInterface } from "@udibo/oauth2/server/authorization";
+ *
+ * interface AppUser {
+ *   id: string;
+ *   username: string;
+ * }
+ * interface DrizzleUserService extends UserServiceInterface<AppUser> {
+ *   register(user: AppUser, password: string): Promise<void>;
+ * }
+ * declare function freshUserService(): Promise<DrizzleUserService>;
+ *
+ * runUserServiceContractTests<AppUser>({
+ *   makeService: freshUserService,
+ *   addUser: (svc, user, password) =>
+ *     (svc as DrizzleUserService).register(user, password),
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { UserServiceInterface } from "../../server/services/user.js";
+import type { MemoryUserShape } from "../services.js";
+/** Options for {@link runUserServiceContractTests}. */
+export interface UserServiceContractOptions<U extends MemoryUserShape> {
+    /**
+     * Returns a fresh service for each test. Must be isolated — one test
+     * leaking state into another defeats the contract guarantees.
+     */
+    makeService(): Promise<UserServiceInterface<U>> | UserServiceInterface<U>;
+    /**
+     * Adds a user with the given password to the service. Not part of the
+     * interface, so the consumer supplies it. For the framework's own
+     * `MemoryUserService` this is `(svc, user, pw) => svc.add(user, pw)`.
+     */
+    addUser(service: UserServiceInterface<U>, user: U, password: string): Promise<void>;
+    /**
+     * Optional factory for the test user. Defaults to a sequenced
+     * `{ id, username }` shape that satisfies {@link MemoryUserShape}.
+     * Override when your `User` requires extra fields.
+     */
+    makeUser?(seq: number): U;
+    /**
+     * Optional name for the inner `describe` block. Defaults to
+     * `"UserServiceInterface contract"`.
+     */
+    describeName?: string;
+}
+/**
+ * Runs the {@link UserServiceInterface} contract suite. Call from your
+ * own test file — the suite registers `describe` / `it` blocks that the
+ * runner picks up.
+ */
+export declare function runUserServiceContractTests<U extends MemoryUserShape>(options: UserServiceContractOptions<U>): void;

package/esm/testing/contract/user.js

@@ -0,0 +1,75 @@
+/**
+ * Contract test suite for {@link UserServiceInterface} implementations.
+ *
+ * Apps that swap a `MemoryUserService` for a DB-backed implementation
+ * can run this suite against their factory to verify they satisfy what
+ * the framework expects.
+ *
+ * @example
+ * ```ts
+ * import { runUserServiceContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { UserServiceInterface } from "@udibo/oauth2/server/authorization";
+ *
+ * interface AppUser {
+ *   id: string;
+ *   username: string;
+ * }
+ * interface DrizzleUserService extends UserServiceInterface<AppUser> {
+ *   register(user: AppUser, password: string): Promise<void>;
+ * }
+ * declare function freshUserService(): Promise<DrizzleUserService>;
+ *
+ * runUserServiceContractTests<AppUser>({
+ *   makeService: freshUserService,
+ *   addUser: (svc, user, password) =>
+ *     (svc as DrizzleUserService).register(user, password),
+ * });
+ * ```
+ *
+ * @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 defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
+/**
+ * Runs the {@link UserServiceInterface} contract suite. Call from your
+ * own test file — the suite registers `describe` / `it` blocks that the
+ * runner picks up.
+ */
+export function runUserServiceContractTests(options) {
+    const makeUser = options.makeUser ?? (defaultMakeUser);
+    describe(options.describeName ?? "UserServiceInterface contract", () => {
+        let service;
+        beforeEach(async () => {
+            service = await options.makeService();
+        });
+        describe("get", () => {
+            it("returns undefined for an unknown id", async () => {
+                assertStrictEquals(await service.get("does-not-exist"), undefined);
+            });
+            it("returns the user for a known id", async () => {
+                const user = makeUser(1);
+                await options.addUser(service, user, "pw");
+                const fetched = await service.get(user.id);
+                assertEquals(fetched?.id, user.id);
+                assertEquals(fetched?.username, user.username);
+            });
+        });
+        describe("getAuthenticated", () => {
+            it("returns undefined for an unknown username", async () => {
+                assertStrictEquals(await service.getAuthenticated("nobody", "pw"), undefined);
+            });
+            it("returns undefined for a wrong password", async () => {
+                const user = makeUser(2);
+                await options.addUser(service, user, "correct");
+                assertStrictEquals(await service.getAuthenticated(user.username, "wrong"), undefined);
+            });
+            it("returns the user when username + password match", async () => {
+                const user = makeUser(3);
+                await options.addUser(service, user, "secret");
+                const auth = await service.getAuthenticated(user.username, "secret");
+                assertEquals(auth?.id, user.id);
+            });
+        });
+    });
+}

package/esm/testing/mod.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Testing helpers for apps that use `@udibo/oauth2`.
+ *
+ * Two layers ship:
+ *
+ * - **Testing surface for the OAuth2 protocol.** The recommended pattern
+ *   for testing apps that use the resource server is to expose your
+ *   `IntrospectionTokenReader` instance from your app's OAuth2 wiring module
+ *   and stub `tokenReader.getToken` directly with `@std/testing/mock`'s
+ *   `stub` —
+ *   one method on one object, no `fetch` indirection, no wire format to
+ *   fake. For tests that need the OAuth2 protocol end-to-end (BFF flows,
+ *   SPA integration), build a real in-process authorization server with
+ *   {@link createMemoryAuthorizationServer} and pass its `fetch` to your
+ *   `DirectClient` via the constructor's `fetch` option. Both patterns
+ *   are constructor- or method-scoped — they never touch
+ *   `globalThis.fetch`, which silently captures every other outbound
+ *   request the app makes.
+ *
+ * - **In-memory service implementations.** `MemoryUserService`,
+ *   `MemoryClientService`, `MemoryTokenService`,
+ *   `MemoryAuthorizationCodeService`, and `MemoryDeviceAuthorizationService`
+ *   satisfy every server-side service contract, generic over the consumer's
+ *   user / client / scope types. Suitable for tests, examples, and
+ *   prototypes — never for production.
+ *
+ * Nothing in this module is an OAuth2 primitive — only testing support.
+ * Production code should never import from here.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { MemoryAuthorizationCodeService, type MemoryAuthorizationCodeServiceOptions, MemoryClientService, MemoryDeviceAuthorizationService, type MemoryDeviceAuthorizationServiceOptions, MemoryTokenService, type MemoryTokenServiceOptions, MemoryUserService, type MemoryUserServiceOptions, type MemoryUserShape, } from "./services.js";
+export { createMemoryAuthorizationServer, type CreateMemoryAuthorizationServerOptions, type MemoryAuthorizationServerClientSeed, type MemoryAuthorizationServerGrants, type MemoryAuthorizationServerHarness, type MemoryAuthorizationServerUserSeed, } from "./server.js";

package/esm/testing/mod.js

@@ -0,0 +1,34 @@
+/**
+ * Testing helpers for apps that use `@udibo/oauth2`.
+ *
+ * Two layers ship:
+ *
+ * - **Testing surface for the OAuth2 protocol.** The recommended pattern
+ *   for testing apps that use the resource server is to expose your
+ *   `IntrospectionTokenReader` instance from your app's OAuth2 wiring module
+ *   and stub `tokenReader.getToken` directly with `@std/testing/mock`'s
+ *   `stub` —
+ *   one method on one object, no `fetch` indirection, no wire format to
+ *   fake. For tests that need the OAuth2 protocol end-to-end (BFF flows,
+ *   SPA integration), build a real in-process authorization server with
+ *   {@link createMemoryAuthorizationServer} and pass its `fetch` to your
+ *   `DirectClient` via the constructor's `fetch` option. Both patterns
+ *   are constructor- or method-scoped — they never touch
+ *   `globalThis.fetch`, which silently captures every other outbound
+ *   request the app makes.
+ *
+ * - **In-memory service implementations.** `MemoryUserService`,
+ *   `MemoryClientService`, `MemoryTokenService`,
+ *   `MemoryAuthorizationCodeService`, and `MemoryDeviceAuthorizationService`
+ *   satisfy every server-side service contract, generic over the consumer's
+ *   user / client / scope types. Suitable for tests, examples, and
+ *   prototypes — never for production.
+ *
+ * Nothing in this module is an OAuth2 primitive — only testing support.
+ * Production code should never import from here.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { MemoryAuthorizationCodeService, MemoryClientService, MemoryDeviceAuthorizationService, MemoryTokenService, MemoryUserService, } from "./services.js";
+export { createMemoryAuthorizationServer, } from "./server.js";