@udibo/oauth2 0.1.0

package/esm/server/signing-keys.js

@@ -0,0 +1,225 @@
+/**
+ * OIDC signing keys and compact JWS signing — Web Crypto only, no
+ * dependencies. Backs id_token issuance, the JWKS endpoint, and the optional
+ * signed (JWT) access-token generator.
+ *
+ * Keys are ES256 (the OIDC-recommended default with broad library support).
+ * Generate once with {@link generateSigningKey}, persist via
+ * {@link exportSigningKeyJwk}, and load on boot with {@link importSigningKeyJwk}
+ * so every instance of a multi-instance deploy signs with the same key (an
+ * ephemeral per-instance key would fail verification across instances).
+ *
+ * @module
+ */
+import { base64urlDecode, base64urlEncode } from "../utils/crypto.js";
+import { snapshotAuthenticationContext } from "../utils/authentication-context.js";
+/** A {@link SigningKeyProvider} over one fixed key. */
+export class StaticSigningKeyProvider {
+    #key;
+    /** Fixes the single key this provider signs with and publishes. */
+    constructor(key) {
+        this.#key = key;
+    }
+    /** The fixed key passed at construction. */
+    getSigningKey() {
+        return Promise.resolve(this.#key);
+    }
+    /** A JWKS containing only the fixed key's public JWK. */
+    getPublicJwks() {
+        return Promise.resolve({ keys: [this.#key.publicJwk] });
+    }
+}
+/**
+ * A {@link SigningKeyProvider} for rotating the signing key through a JWKS
+ * grace window: sign with {@link RotatingSigningKeyProviderOptions.current}
+ * only, while {@link RotatingSigningKeyProviderOptions.previous} keys stay
+ * published so outstanding tokens keep validating until they expire and every
+ * consumer has refetched JWKS.
+ *
+ * Rotation is: promote the new key to `current`, move the old one into
+ * `previous`, and hold that grace window for at least the longest token
+ * lifetime before dropping the old key from `previous`. Because
+ * {@link signJwt} stamps the current key's `kid` into every JWS header and each
+ * published JWK carries its own `kid`, verifiers select the right key by `kid`
+ * across the window. Keys are published current-first and de-duplicated by
+ * `kid`.
+ *
+ * A single-key configuration (`previous` empty or omitted) publishes exactly
+ * the one key and is behaviourally identical to
+ * {@link StaticSigningKeyProvider} — adopting this provider does not change a
+ * deployment that has not started a rotation.
+ *
+ * @example
+ * ```ts
+ * const provider = new RotatingSigningKeyProvider({
+ *   current: await importSigningKeyJwk(JSON.parse(currentJwk)),
+ *   previous: [await importSigningKeyJwk(JSON.parse(oldJwk))],
+ * });
+ * ```
+ */
+export class RotatingSigningKeyProvider {
+    #current;
+    #publicJwks;
+    /** Fixes the current signing key and the published set (current + previous). */
+    constructor(options) {
+        this.#current = options.current;
+        const seen = new Set();
+        const keys = [];
+        for (const key of [options.current, ...(options.previous ?? [])]) {
+            if (seen.has(key.kid))
+                continue;
+            seen.add(key.kid);
+            keys.push(key.publicJwk);
+        }
+        this.#publicJwks = { keys };
+    }
+    /** The current key — the only key new tokens are ever signed with. */
+    getSigningKey() {
+        return Promise.resolve(this.#current);
+    }
+    /** Public JWKs for the current key and every still-published previous key. */
+    getPublicJwks() {
+        return Promise.resolve({ keys: [...this.#publicJwks.keys] });
+    }
+}
+const ES256_PARAMS = { name: "ECDSA", namedCurve: "P-256" };
+const ES256_SIGN_PARAMS = { name: "ECDSA", hash: "SHA-256" };
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function encodeSegment(value) {
+    return base64urlEncode(encoder.encode(JSON.stringify(value)));
+}
+/** Maps a user to a JWT `sub` claim: the user's `id` property, else the user itself. */
+export function defaultSubjectOf(user) {
+    return String(user?.id ?? user);
+}
+function publicJwkOf(jwk, kid) {
+    return {
+        kty: jwk.kty,
+        crv: jwk.crv,
+        x: jwk.x,
+        y: jwk.y,
+        kid,
+        alg: "ES256",
+        use: "sig",
+    };
+}
+/** Generate a fresh ES256 signing key with a random `kid`. */
+export async function generateSigningKey() {
+    const pair = await crypto.subtle.generateKey(ES256_PARAMS, true, [
+        "sign",
+        "verify",
+    ]);
+    const kid = crypto.randomUUID();
+    const jwk = await crypto.subtle.exportKey("jwk", pair.publicKey);
+    return {
+        kid,
+        alg: "ES256",
+        privateKey: pair.privateKey,
+        publicJwk: publicJwkOf(jwk, kid),
+    };
+}
+/**
+ * Export a signing key (including private material) as a JWK for persistence
+ * — e.g. into a secret-manager entry the app loads on boot. Guard it like any
+ * credential.
+ */
+export async function exportSigningKeyJwk(key) {
+    const jwk = await crypto.subtle.exportKey("jwk", key.privateKey);
+    return { ...jwk, kid: key.kid, alg: key.alg };
+}
+/** Import a signing key previously exported with {@link exportSigningKeyJwk}. */
+export async function importSigningKeyJwk(jwk) {
+    const privateKey = await crypto.subtle.importKey("jwk", jwk, ES256_PARAMS, true, ["sign"]);
+    const kid = jwk.kid ?? crypto.randomUUID();
+    return {
+        kid,
+        alg: "ES256",
+        privateKey,
+        publicJwk: publicJwkOf(jwk, kid),
+    };
+}
+/**
+ * Sign a compact JWS (`header.payload.signature`) with the given key —
+ * the primitive behind id_tokens and JWT access tokens.
+ */
+export async function signJwt(key, payload, header = {}) {
+    const signingInput = `${encodeSegment({ alg: key.alg, typ: "JWT", kid: key.kid, ...header })}.${encodeSegment(payload)}`;
+    const signature = await crypto.subtle.sign(ES256_SIGN_PARAMS, key.privateKey, encoder.encode(signingInput));
+    return `${signingInput}.${base64urlEncode(new Uint8Array(signature))}`;
+}
+/**
+ * Verify a compact JWS against a public JWK and return its payload, or
+ * `undefined` when the signature (or shape) is invalid or the payload's `exp`
+ * is in the past. Exported for tests and lightweight in-process verification;
+ * production resource servers should verify against the JWKS endpoint with
+ * their JOSE library of choice.
+ */
+export async function verifyJwt(jwt, publicJwk, options = {}) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    const [headerPart, payloadPart, signaturePart] = parts;
+    try {
+        const publicKey = await crypto.subtle.importKey("jwk", publicJwk, ES256_PARAMS, false, ["verify"]);
+        const valid = await crypto.subtle.verify(ES256_SIGN_PARAMS, publicKey, new Uint8Array(base64urlDecode(signaturePart)), encoder.encode(`${headerPart}.${payloadPart}`));
+        if (!valid)
+            return undefined;
+        const payload = JSON.parse(decoder.decode(base64urlDecode(payloadPart)));
+        if (!options.ignoreExpiration &&
+            typeof payload.exp === "number" && payload.exp * 1000 <= Date.now()) {
+            return undefined;
+        }
+        return payload;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a `generateAccessToken` implementation that issues **signed JWT
+ * access tokens** (RFC 9068 `at+jwt`) instead of opaque strings — the
+ * "verifiable signed-token option": resource servers can validate offline
+ * against the JWKS endpoint. Wire it into your token service:
+ *
+ * ```ts
+ * class JwtTokenService extends MyTokenService {
+ *   override generateAccessToken = createJwtAccessTokenGenerator({
+ *     signingKeys, issuer: "https://auth.example.com",
+ *   });
+ * }
+ * ```
+ *
+ * The token store still persists the (hashed) JWT string, so revocation and
+ * introspection keep working exactly as with opaque tokens.
+ */
+export function createJwtAccessTokenGenerator(options) {
+    const lifetime = options.lifetimeSeconds ?? 3600;
+    const subjectOf = options.subjectOf ?? defaultSubjectOf;
+    return async (client, user, scope, authenticationContext) => {
+        const event = user
+            ? snapshotAuthenticationContext(authenticationContext)
+            : undefined;
+        const key = await options.signingKeys.getSigningKey();
+        const now = Math.floor(Date.now() / 1000);
+        const extraClaims = user && options.userClaims
+            ? await options.userClaims(user, scope, client, event)
+            : undefined;
+        const payload = {
+            ...extraClaims,
+            iss: options.issuer,
+            sub: user ? subjectOf(user) : client.id,
+            client_id: client.id,
+            aud: options.audience ?? client.id,
+            iat: now,
+            exp: now + lifetime,
+            jti: crypto.randomUUID(),
+        };
+        const scopeText = scope?.toString();
+        if (scopeText)
+            payload.scope = scopeText;
+        else
+            delete payload.scope;
+        return await signJwt(key, payload, { typ: "at+jwt" });
+    };
+}

package/esm/server/utils/hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hashing utilities for secure token and secret storage.
+ * @module
+ */
+/** Hashes a high-entropy string (UUID, token, secret) using SHA-256. */
+export declare function sha256Hash(value: string): Promise<string>;

package/esm/server/utils/hash.js

@@ -0,0 +1,11 @@
+/**
+ * Hashing utilities for secure token and secret storage.
+ * @module
+ */
+import { encodeHex } from "../../deps/jsr.io/@std/encoding/1.0.11/hex.js";
+/** Hashes a high-entropy string (UUID, token, secret) using SHA-256. */
+export async function sha256Hash(value) {
+    const data = new TextEncoder().encode(value);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return encodeHex(hash);
+}

package/esm/testing/contract/authorization-code.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Contract test suite for {@link AuthorizationCodeServiceInterface}
+ * implementations.
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { AuthorizationCodeServiceInterface } from "../../server/services/authorization-code.js";
+import type { ClientServiceInterface } from "../../server/services/client.js";
+import type { UserServiceInterface } from "../../server/services/user.js";
+import type { MemoryUserShape } from "../services.js";
+/** Options for {@link runAuthorizationCodeServiceContractTests}. */
+export interface AuthorizationCodeServiceContractOptions<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>;
+        authorizationCodeService: AuthorizationCodeServiceInterface<C, U, S>;
+    }> | {
+        userService: UserServiceInterface<U>;
+        clientService: ClientServiceInterface<C, U>;
+        authorizationCodeService: AuthorizationCodeServiceInterface<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`. */
+    makeClient?(seq: number): C;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/** Runs the {@link AuthorizationCodeServiceInterface} contract suite. */
+export declare function runAuthorizationCodeServiceContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: AuthorizationCodeServiceContractOptions<C, U, S>): void;

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

@@ -0,0 +1,93 @@
+/**
+ * Contract test suite for {@link AuthorizationCodeServiceInterface}
+ * implementations.
+ *
+ * @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}` });
+const defaultMakeClient = (seq) => ({ id: `client-${seq}`, grants: ["authorization_code"] });
+/** Runs the {@link AuthorizationCodeServiceInterface} contract suite. */
+export function runAuthorizationCodeServiceContractTests(options) {
+    const makeUser = options.makeUser ?? (defaultMakeUser);
+    const makeClient = options.makeClient ?? (defaultMakeClient);
+    describe(options.describeName ?? "AuthorizationCodeServiceInterface contract", () => {
+        let userService;
+        let clientService;
+        let codeService;
+        let user;
+        let client;
+        beforeEach(async () => {
+            const services = await options.makeServices();
+            userService = services.userService;
+            clientService = services.clientService;
+            codeService = services.authorizationCodeService;
+            user = makeUser(1);
+            client = makeClient(1);
+            await options.addUser(userService, user, "pw");
+            await options.addClient(clientService, client);
+        });
+        it("generateCode returns unique strings", async () => {
+            const a = await codeService.generateCode(client, user);
+            const b = await codeService.generateCode(client, user);
+            assertEquals(a !== b, true);
+        });
+        it("expiresAt returns a future date", async () => {
+            const expires = await codeService.expiresAt(client, user);
+            assertEquals(expires.getTime() > Date.now(), true);
+        });
+        it("save + get round-trips an authorization code", async () => {
+            const code = await codeService.generateCode(client, user);
+            const expiresAt = await codeService.expiresAt(client, user);
+            const ac = {
+                code,
+                expiresAt,
+                client,
+                user,
+                redirectUri: "http://app/cb",
+                challenge: "abc",
+                challengeMethod: "S256",
+                nonce: "nonce-1",
+            };
+            await codeService.save(ac);
+            const fetched = await codeService.get(code);
+            assertEquals(fetched?.code, code);
+            assertEquals(fetched?.client.id, client.id);
+            assertEquals(fetched?.redirectUri, "http://app/cb");
+            assertEquals(fetched?.challenge, "abc");
+            assertEquals(fetched?.nonce, "nonce-1");
+        });
+        it("get returns undefined for an unknown code", async () => {
+            assertStrictEquals(await codeService.get("missing"), undefined);
+        });
+        it("revoke deletes the code by string", async () => {
+            const code = await codeService.generateCode(client, user);
+            await codeService.save({
+                code,
+                expiresAt: await codeService.expiresAt(client, user),
+                client,
+                user,
+            });
+            const ok = await codeService.revoke(code);
+            assertStrictEquals(ok, true);
+            assertStrictEquals(await codeService.get(code), undefined);
+        });
+        it("revoke deletes the code by object", async () => {
+            const code = await codeService.generateCode(client, user);
+            const ac = {
+                code,
+                expiresAt: await codeService.expiresAt(client, user),
+                client,
+                user,
+            };
+            await codeService.save(ac);
+            const ok = await codeService.revoke(ac);
+            assertStrictEquals(ok, true);
+            assertStrictEquals(await codeService.get(code), undefined);
+        });
+        it("revoke returns false for an unknown code", async () => {
+            assertStrictEquals(await codeService.revoke("missing"), false);
+        });
+    });
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Contract test suite for {@link ClientServiceInterface} implementations.
+ *
+ * `getUser` is contract-conformant either way: resolving a user and resolving
+ * nothing are both required to pass. A client that resolves nothing is a
+ * machine client whose token carries no resource owner (RFC 6749 §4.4), not a
+ * misconfiguration — the client credentials grant issues it a user-less token.
+ * Resolve a user only when that user is a principal of its own, such as a
+ * per-application service account; resolving a human owner hands the machine
+ * that person's identity (RFC 9700 §4.15).
+ *
+ * @example
+ * ```ts
+ * import { runClientServiceContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { ClientInterface } from "@udibo/oauth2/server";
+ * import type {
+ *   ClientServiceInterface,
+ *   UserServiceInterface,
+ * } from "@udibo/oauth2/server/authorization";
+ *
+ * interface AppUser {
+ *   id: string;
+ *   username: string;
+ * }
+ * interface DrizzleUserService extends UserServiceInterface<AppUser> {
+ *   register(user: AppUser, password: string): Promise<void>;
+ * }
+ * interface DrizzleClientService
+ *   extends ClientServiceInterface<ClientInterface, AppUser> {
+ *   register(
+ *     client: ClientInterface,
+ *     secret?: string,
+ *     ownerUserId?: string,
+ *   ): Promise<void>;
+ * }
+ * declare function freshServices(): Promise<{
+ *   userService: DrizzleUserService;
+ *   clientService: DrizzleClientService;
+ * }>;
+ *
+ * runClientServiceContractTests<ClientInterface, AppUser>({
+ *   makeServices: freshServices,
+ *   addUser: (svc, user, pw) => (svc as DrizzleUserService).register(user, pw),
+ *   addClient: (svc, client, secret, ownerUserId) =>
+ *     (svc as DrizzleClientService).register(client, secret, ownerUserId),
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { ClientServiceInterface } from "../../server/services/client.js";
+import type { UserServiceInterface } from "../../server/services/user.js";
+import type { MemoryUserShape } from "../services.js";
+/** Options for {@link runClientServiceContractTests}. */
+export interface ClientServiceContractOptions<C extends ClientInterface, U extends MemoryUserShape> {
+    /**
+     * Returns fresh services for each test. The `userService` is needed
+     * because `clientService.getUser(client)` resolves through it.
+     */
+    makeServices(): Promise<{
+        userService: UserServiceInterface<U>;
+        clientService: ClientServiceInterface<C, U>;
+    }> | {
+        userService: UserServiceInterface<U>;
+        clientService: ClientServiceInterface<C, U>;
+    };
+    /** Adds a user via the consumer's preferred mechanism. */
+    addUser(service: UserServiceInterface<U>, user: U, password: string): Promise<void>;
+    /**
+     * Adds a client. Pass `secret` to register a confidential client; omit
+     * for public. `ownerUserId` is the user returned by `getUser`; omit it to
+     * register a client that resolves no user, which the suite requires to be
+     * supported.
+     */
+    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 `client_credentials`. */
+    makeClient?(seq: number): C;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/** Runs the {@link ClientServiceInterface} contract suite. */
+export declare function runClientServiceContractTests<C extends ClientInterface, U extends MemoryUserShape>(options: ClientServiceContractOptions<C, U>): void;

package/esm/testing/contract/client.js

@@ -0,0 +1,126 @@
+/**
+ * Contract test suite for {@link ClientServiceInterface} implementations.
+ *
+ * `getUser` is contract-conformant either way: resolving a user and resolving
+ * nothing are both required to pass. A client that resolves nothing is a
+ * machine client whose token carries no resource owner (RFC 6749 §4.4), not a
+ * misconfiguration — the client credentials grant issues it a user-less token.
+ * Resolve a user only when that user is a principal of its own, such as a
+ * per-application service account; resolving a human owner hands the machine
+ * that person's identity (RFC 9700 §4.15).
+ *
+ * @example
+ * ```ts
+ * import { runClientServiceContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { ClientInterface } from "@udibo/oauth2/server";
+ * import type {
+ *   ClientServiceInterface,
+ *   UserServiceInterface,
+ * } from "@udibo/oauth2/server/authorization";
+ *
+ * interface AppUser {
+ *   id: string;
+ *   username: string;
+ * }
+ * interface DrizzleUserService extends UserServiceInterface<AppUser> {
+ *   register(user: AppUser, password: string): Promise<void>;
+ * }
+ * interface DrizzleClientService
+ *   extends ClientServiceInterface<ClientInterface, AppUser> {
+ *   register(
+ *     client: ClientInterface,
+ *     secret?: string,
+ *     ownerUserId?: string,
+ *   ): Promise<void>;
+ * }
+ * declare function freshServices(): Promise<{
+ *   userService: DrizzleUserService;
+ *   clientService: DrizzleClientService;
+ * }>;
+ *
+ * runClientServiceContractTests<ClientInterface, AppUser>({
+ *   makeServices: freshServices,
+ *   addUser: (svc, user, pw) => (svc as DrizzleUserService).register(user, pw),
+ *   addClient: (svc, client, secret, ownerUserId) =>
+ *     (svc as DrizzleClientService).register(client, secret, ownerUserId),
+ * });
+ * ```
+ *
+ * @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}` });
+const defaultMakeClient = (seq) => ({ id: `client-${seq}`, grants: ["client_credentials"] });
+/** Runs the {@link ClientServiceInterface} contract suite. */
+export function runClientServiceContractTests(options) {
+    const makeUser = options.makeUser ?? (defaultMakeUser);
+    const makeClient = options.makeClient ?? (defaultMakeClient);
+    describe(options.describeName ?? "ClientServiceInterface contract", () => {
+        let userService;
+        let clientService;
+        beforeEach(async () => {
+            const services = await options.makeServices();
+            userService = services.userService;
+            clientService = services.clientService;
+        });
+        describe("get", () => {
+            it("returns undefined for an unknown id", async () => {
+                assertStrictEquals(await clientService.get("missing"), undefined);
+            });
+            it("returns the registered client", async () => {
+                const client = makeClient(1);
+                await options.addClient(clientService, client);
+                const fetched = await clientService.get(client.id);
+                assertEquals(fetched?.id, client.id);
+            });
+        });
+        describe("getAuthenticated", () => {
+            it("returns the public client without a secret", async () => {
+                const client = makeClient(2);
+                await options.addClient(clientService, client);
+                const auth = await clientService.getAuthenticated(client.id);
+                assertEquals(auth?.id, client.id);
+            });
+            it("returns undefined for a confidential client when no secret is supplied", async () => {
+                const client = makeClient(3);
+                await options.addClient(clientService, client, "secret");
+                assertStrictEquals(await clientService.getAuthenticated(client.id), undefined);
+            });
+            it("returns undefined for a confidential client with a wrong secret", async () => {
+                const client = makeClient(4);
+                await options.addClient(clientService, client, "correct");
+                assertStrictEquals(await clientService.getAuthenticated(client.id, "wrong"), undefined);
+            });
+            it("returns the confidential client with a matching secret", async () => {
+                const client = makeClient(5);
+                await options.addClient(clientService, client, "matching");
+                const auth = await clientService.getAuthenticated(client.id, "matching");
+                assertEquals(auth?.id, client.id);
+            });
+        });
+        describe("getUser", () => {
+            it("resolves nothing for a client registered without a user, rather than failing", async () => {
+                const client = makeClient(6);
+                await options.addClient(clientService, client);
+                assertStrictEquals(await clientService.getUser(client), undefined);
+            });
+            it("returns the associated user when one was registered", async () => {
+                const user = makeUser(7);
+                const client = makeClient(7);
+                await options.addUser(userService, user, "pw");
+                await options.addClient(clientService, client, undefined, user.id);
+                const owner = await clientService.getUser(client);
+                assertEquals(owner?.id, user.id);
+            });
+            it("accepts a client id (not just a client object)", async () => {
+                const user = makeUser(8);
+                const client = makeClient(8);
+                await options.addUser(userService, user, "pw");
+                await options.addClient(clientService, client, undefined, user.id);
+                const owner = await clientService.getUser(client.id);
+                assertEquals(owner?.id, user.id);
+            });
+        });
+    });
+}

package/esm/testing/contract/device-authorization.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Contract test suite for {@link DeviceAuthorizationServiceInterface}
+ * implementations (RFC 8628).
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { ClientServiceInterface } from "../../server/services/client.js";
+import type { DeviceAuthorizationServiceInterface } from "../../server/services/device-authorization.js";
+import type { UserServiceInterface } from "../../server/services/user.js";
+import type { MemoryUserShape } from "../services.js";
+/** Options for {@link runDeviceAuthorizationServiceContractTests}. */
+export interface DeviceAuthorizationServiceContractOptions<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>;
+        deviceAuthorizationService: DeviceAuthorizationServiceInterface<C, U, S>;
+    }> | {
+        userService: UserServiceInterface<U>;
+        clientService: ClientServiceInterface<C, U>;
+        deviceAuthorizationService: DeviceAuthorizationServiceInterface<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 the device-code grant. */
+    makeClient?(seq: number): C;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/** Runs the {@link DeviceAuthorizationServiceInterface} contract suite. */
+export declare function runDeviceAuthorizationServiceContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: DeviceAuthorizationServiceContractOptions<C, U, S>): void;