@udibo/oauth2 0.9.2 → 0.11.0

package/esm/testing/contract/identity-session.d.ts

@@ -0,0 +1,54 @@
+import type { ListableSessionService, RevocableSessionService, SessionSummary } from "../../identity/session.js";
+/** Session states the application translates into its own storage fields. */
+export type IdentitySessionContractState = "live" | "revoked" | "expired" | "idle-timed-out";
+/** Isolated revocation implementation and app-owned session setup helpers. */
+export interface RevocableSessionServiceContractFixture {
+    /** Implementation under test. */
+    service: RevocableSessionService;
+    /** Two distinct existing owners, using your application's valid user-id format. */
+    userId: string;
+    /** Existing owner whose sessions must survive operations on userId. */
+    otherUserId: string;
+    /** Stable, distinct app-valid non-secret session ids for sequences 1 through 7 and 99. */
+    sessionId(sequence: number): string;
+    /** Seed one unique session with the indicated owner and state. */
+    addSession(userId: string, summary: SessionSummary, state: IdentitySessionContractState): Promise<void>;
+    /** Whether the application would still accept this session after revocation returns. */
+    isLive(sessionId: string): Promise<boolean>;
+    /** Release resources and remove this test's records. */
+    dispose?(): Promise<void> | void;
+}
+/** Options for runRevocableSessionServiceContractTests. */
+export interface RevocableSessionServiceContractOptions {
+    /** Create a fresh empty fixture for each test. */
+    makeFixture(): RevocableSessionServiceContractFixture | Promise<RevocableSessionServiceContractFixture>;
+    /** Override the outer suite name. */
+    describeName?: string;
+}
+/** Fixture for a store that exposes authoritative session display lists. */
+export interface ListableSessionServiceContractFixture extends RevocableSessionServiceContractFixture {
+    /** Both listing and immediate revocation must address the same stored sessions. */
+    service: RevocableSessionService & ListableSessionService;
+}
+/** Options for runListableSessionServiceContractTests. */
+export interface ListableSessionServiceContractOptions {
+    /** Create a fresh empty fixture; translate ended states into your expiry and idle policy. */
+    makeFixture(): ListableSessionServiceContractFixture | Promise<ListableSessionServiceContractFixture>;
+    /** Override the outer suite name. */
+    describeName?: string;
+}
+/**
+ * Register checks for user-scoped, immediately effective session revocation.
+ * The count checks seed live sessions only; they impose no retention policy on
+ * ended rows. Concurrent calls are drained before fixture cleanup. Their
+ * counts must reflect sessions actually revoked rather than double-counting
+ * the same live sessions. This tests observed interleavings, not all races.
+ */
+export declare function runRevocableSessionServiceContractTests(options: RevocableSessionServiceContractOptions): void;
+/**
+ * Register checks for user-scoped, newest-activity-first session display lists.
+ * Verifies base timestamps and only the documented display keys, excluding
+ * token material and secrets. Optional coarse client metadata may be omitted.
+ * Run the separate revocation suite as well to verify its complete contract.
+ */
+export declare function runListableSessionServiceContractTests(options: ListableSessionServiceContractOptions): void;

package/esm/testing/contract/identity-session.js

@@ -0,0 +1,165 @@
+/**
+ * Contract checks for app-owned identity-session revocation and display lists.
+ * These are distinct from the Hono BFF SessionStore contract.
+ * @module
+ */
+import { assert, assertEquals, assertExists, 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";
+function summary(id, lastSeenAt = Date.now() - 30_000) {
+    return {
+        id,
+        createdAt: new Date(Date.now() - 60_000),
+        lastSeenAt: new Date(lastSeenAt),
+    };
+}
+/**
+ * Register checks for user-scoped, immediately effective session revocation.
+ * The count checks seed live sessions only; they impose no retention policy on
+ * ended rows. Concurrent calls are drained before fixture cleanup. Their
+ * counts must reflect sessions actually revoked rather than double-counting
+ * the same live sessions. This tests observed interleavings, not all races.
+ */
+export function runRevocableSessionServiceContractTests(options) {
+    describe(options.describeName ?? "RevocableSessionService contract", () => {
+        let fixture;
+        beforeEach(async () => {
+            fixture = await options.makeFixture();
+            assert(fixture.userId !== fixture.otherUserId, "session fixture owners must be distinct");
+        });
+        afterEach(async () => {
+            await fixture?.dispose?.();
+        });
+        async function seed() {
+            for (const id of [
+                fixture.sessionId(1),
+                fixture.sessionId(2),
+                fixture.sessionId(3),
+            ]) {
+                await fixture.addSession(fixture.userId, summary(id), "live");
+            }
+            await fixture.addSession(fixture.otherUserId, summary(fixture.sessionId(4)), "live");
+        }
+        it("reports zero for users without sessions", async () => {
+            assertEquals(await fixture.service.revokeAllByUser(fixture.userId), 0);
+            assertEquals(await fixture.service.revokeOthers(fixture.userId, fixture.sessionId(99)), 0);
+        });
+        it("revokes all of the selected user's sessions immediately and only once", async () => {
+            await seed();
+            assertEquals(await fixture.service.revokeAllByUser(fixture.userId), 3);
+            for (const id of [
+                fixture.sessionId(1),
+                fixture.sessionId(2),
+                fixture.sessionId(3),
+            ]) {
+                assertStrictEquals(await fixture.isLive(id), false);
+            }
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(4)), true);
+            assertEquals(await fixture.service.revokeAllByUser(fixture.userId), 0);
+        });
+        it("keeps only the selected current session and preserves another user's sessions", async () => {
+            await seed();
+            assertEquals(await fixture.service.revokeOthers(fixture.userId, fixture.sessionId(2)), 2);
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(1)), false);
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(3)), false);
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(2)), true);
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(4)), true);
+            assertEquals(await fixture.service.revokeOthers(fixture.userId, fixture.sessionId(2)), 0);
+        });
+        it("a foreign keepSessionId cannot exempt the selected user's sessions", async () => {
+            await seed();
+            assertEquals(await fixture.service.revokeOthers(fixture.userId, fixture.sessionId(4)), 3);
+            for (const id of [
+                fixture.sessionId(1),
+                fixture.sessionId(2),
+                fixture.sessionId(3),
+            ]) {
+                assertStrictEquals(await fixture.isLive(id), false);
+            }
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(4)), true);
+        });
+        it("does not double-count concurrent revocations", async () => {
+            await seed();
+            const results = await Promise.allSettled(Array.from({ length: 8 }, () => fixture.service.revokeAllByUser(fixture.userId)));
+            const counts = results.map((result) => {
+                if (result.status === "rejected")
+                    throw result.reason;
+                return result.value;
+            });
+            assertEquals(counts.reduce((sum, count) => sum + count, 0), 3, "concurrent revocation counts must not count a live session twice");
+            for (const id of [
+                fixture.sessionId(1),
+                fixture.sessionId(2),
+                fixture.sessionId(3),
+            ]) {
+                assertStrictEquals(await fixture.isLive(id), false);
+            }
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(4)), true);
+        });
+    });
+}
+/**
+ * Register checks for user-scoped, newest-activity-first session display lists.
+ * Verifies base timestamps and only the documented display keys, excluding
+ * token material and secrets. Optional coarse client metadata may be omitted.
+ * Run the separate revocation suite as well to verify its complete contract.
+ */
+export function runListableSessionServiceContractTests(options) {
+    describe(options.describeName ?? "ListableSessionService contract", () => {
+        let fixture;
+        beforeEach(async () => {
+            fixture = await options.makeFixture();
+            assert(fixture.userId !== fixture.otherUserId, "session fixture owners must be distinct");
+        });
+        afterEach(async () => {
+            await fixture?.dispose?.();
+        });
+        it("returns an empty list for a user without live sessions", async () => {
+            assertEquals(await fixture.service.listByUser(fixture.userId), []);
+        });
+        it("lists only the owner's live sessions in most-recently-active order", async () => {
+            const oldest = summary(fixture.sessionId(1));
+            const newest = {
+                ...summary(fixture.sessionId(2), Date.now() - 1_000),
+                userAgent: "contract-browser",
+                location: "Example City, US",
+            };
+            const middle = summary(fixture.sessionId(3), Date.now() - 2_000);
+            for (const value of [oldest, newest, middle]) {
+                await fixture.addSession(fixture.userId, value, "live");
+            }
+            for (const [index, state] of ["revoked", "expired", "idle-timed-out"].entries()) {
+                await fixture.addSession(fixture.userId, summary(fixture.sessionId(index + 5)), state);
+            }
+            await fixture.addSession(fixture.otherUserId, summary(fixture.sessionId(4)), "live");
+            const rows = await fixture.service.listByUser(fixture.userId);
+            assertEquals(rows.map((row) => row.id), [fixture.sessionId(2), fixture.sessionId(3), fixture.sessionId(1)], "lists must exclude foreign and ended sessions and sort by last activity");
+            const expectedRows = [newest, middle, oldest];
+            for (const [index, expected] of expectedRows.entries()) {
+                const row = rows[index];
+                assertExists(row);
+                assertEquals(row.createdAt, expected.createdAt);
+                assertEquals(row.lastSeenAt, expected.lastSeenAt);
+                assertEquals(Object.keys(row).filter((key) => !["id", "createdAt", "lastSeenAt", "userAgent", "location"]
+                    .includes(key)), [], "session summaries must not expose secret/hash or token material");
+                if (row.userAgent !== undefined) {
+                    assertEquals(row.userAgent, expected.userAgent);
+                }
+                if (row.location !== undefined) {
+                    assertEquals(row.location, expected.location);
+                }
+            }
+            assertEquals((await fixture.service.listByUser(fixture.otherUserId)).map((row) => row.id), [fixture.sessionId(4)]);
+        });
+        it("removes revoked sessions from the authoritative list immediately", async () => {
+            await fixture.addSession(fixture.userId, summary(fixture.sessionId(1)), "live");
+            await fixture.addSession(fixture.userId, summary(fixture.sessionId(2)), "live");
+            await fixture.addSession(fixture.otherUserId, summary(fixture.sessionId(4)), "live");
+            assertEquals(await fixture.service.revokeOthers(fixture.userId, fixture.sessionId(1)), 1);
+            assertEquals((await fixture.service.listByUser(fixture.userId)).map((row) => row.id), [fixture.sessionId(1)]);
+            assertStrictEquals(await fixture.isLive(fixture.sessionId(2)), false);
+            assertEquals(await fixture.service.revokeAllByUser(fixture.userId), 1);
+            assertEquals(await fixture.service.listByUser(fixture.userId), []);
+            assertEquals((await fixture.service.listByUser(fixture.otherUserId)).map((row) => row.id), [fixture.sessionId(4)]);
+        });
+    });
+}

package/esm/testing/contract/identity-user-store.d.ts

@@ -0,0 +1,52 @@
+import type { IdentityUser, IdentityUserStore } from "../../identity/service.js";
+/** App-specific profile and lookup keys for one fresh test user. */
+export interface IdentityUserContractProfile {
+    /** Valid sign-up fields for your application. */
+    profile: Record<string, unknown>;
+    /** Identifier that findByIdentifier must resolve for this profile. */
+    identifier: string;
+    /** Email that findByEmail must resolve for this profile. */
+    email: string;
+}
+/** Isolated store and app-owned setup helpers for one test. */
+export interface IdentityUserStoreContractFixture<User extends IdentityUser> {
+    /** Fresh, empty implementation being verified. */
+    store: IdentityUserStore<User>;
+    /** Valid app-shaped user id that is absent from this fixture. */
+    unknownUserId: string;
+    /** Distinct valid profiles; return the same profile for the same sequence (1 or 2). */
+    makeProfile(sequence: number): IdentityUserContractProfile;
+    /** Remove a native credential to exercise compare-and-set from undefined. */
+    removeCredential?(userId: string): Promise<void>;
+    /** Change the current email without verifying it. Required for emailVerification. */
+    setEmail?(userId: string, email: string): Promise<void>;
+    /** Read the persisted verification flag. Required for emailVerification. */
+    isEmailVerified?(userId: string): Promise<boolean>;
+    /** Seed an imported hash. Required for legacyCredentials. */
+    setLegacyCredential?(userId: string, hash: string): Promise<void>;
+    /** Release resources and remove this test's records after all calls finish. */
+    dispose?(): Promise<void> | void;
+}
+/** Options for runIdentityUserStoreContractTests. */
+export interface IdentityUserStoreContractOptions<User extends IdentityUser> {
+    /** Create an isolated fixture for each test. */
+    makeFixture(): IdentityUserStoreContractFixture<User> | Promise<IdentityUserStoreContractFixture<User>>;
+    /** Override the outer suite's name. */
+    describeName?: string;
+    /** Require the optional atomic credential-replacement capability and its setup helper. */
+    replaceCredential?: boolean;
+    /** Require guarded, idempotent email verification and its observation helpers. */
+    emailVerification?: boolean;
+    /** Require imported credential lookup and clearing, plus its setup helper. */
+    legacyCredentials?: boolean;
+}
+/**
+ * Register the IdentityUserStore suite in a Deno test file. Credential fixtures
+ * are serialized values, not real passwords: these checks verify persistence,
+ * lookup, and conditional writes, rather than password hashing. Concurrent
+ * checks can expose read-then-write races but cannot prove every interleaving.
+ * Enable each optional capability your application uses; disabled capabilities
+ * are not verified. Application validation and identifier normalization remain
+ * app-owned and are outside this suite.
+ */
+export declare function runIdentityUserStoreContractTests<User extends IdentityUser>(options: IdentityUserStoreContractOptions<User>): void;

package/esm/testing/contract/identity-user-store.js

@@ -0,0 +1,176 @@
+/**
+ * Reusable checks for app-owned identity users and password credentials.
+ * Optional capabilities are selected explicitly so an omitted implementation
+ * cannot silently pass a capability the application intends to provide.
+ * @module
+ */
+import { assert, assertEquals, assertExists, 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";
+const ORIGINAL = {
+    hash: "11".repeat(32),
+    salt: "22".repeat(16),
+    params: { algorithm: "pbkdf2-sha256", iterations: 600_000 },
+};
+const REPLACEMENT = {
+    hash: "33".repeat(32),
+    salt: "44".repeat(16),
+    params: { algorithm: "pbkdf2-sha256", iterations: 700_000 },
+};
+async function drain(calls) {
+    const results = await Promise.allSettled(calls);
+    return results.map((result) => {
+        if (result.status === "rejected")
+            throw result.reason;
+        return result.value;
+    });
+}
+/**
+ * Register the IdentityUserStore suite in a Deno test file. Credential fixtures
+ * are serialized values, not real passwords: these checks verify persistence,
+ * lookup, and conditional writes, rather than password hashing. Concurrent
+ * checks can expose read-then-write races but cannot prove every interleaving.
+ * Enable each optional capability your application uses; disabled capabilities
+ * are not verified. Application validation and identifier normalization remain
+ * app-owned and are outside this suite.
+ */
+export function runIdentityUserStoreContractTests(options) {
+    describe(options.describeName ?? "IdentityUserStore contract", () => {
+        let fixture;
+        let store;
+        beforeEach(async () => {
+            fixture = await options.makeFixture();
+            store = fixture.store;
+        });
+        afterEach(async () => {
+            await fixture?.dispose?.();
+        });
+        async function create(sequence = 1) {
+            return await store.create(fixture.makeProfile(sequence).profile, structuredClone(ORIGINAL));
+        }
+        it("returns undefined for unknown lookup keys and credentials", async () => {
+            assertStrictEquals(await store.findByIdentifier("missing-identity-contract@example.invalid"), undefined);
+            assertStrictEquals(await store.findByEmail("missing-identity-contract@example.invalid"), undefined);
+            assertStrictEquals(await store.getCredential(fixture.unknownUserId), undefined);
+        });
+        it("creates distinct users and resolves each profile's lookup keys", async () => {
+            const first = await create();
+            const second = await create(2);
+            assert(first.id.length > 0);
+            assert(second.id.length > 0);
+            assert(first.id !== second.id, "distinct users must have distinct ids");
+            for (const [sequence, user] of [[1, first], [2, second]]) {
+                const profile = fixture.makeProfile(sequence);
+                assertEquals((await store.findByIdentifier(profile.identifier))?.id, user.id);
+                assertEquals((await store.findByEmail(profile.email))?.id, user.id);
+                assertEquals(await store.getCredential(user.id), ORIGINAL);
+            }
+        });
+        it("replaces every credential field without changing another user", async () => {
+            const first = await create();
+            const second = await create(2);
+            await store.setCredential(first.id, structuredClone(REPLACEMENT));
+            assertEquals(await store.getCredential(first.id), REPLACEMENT);
+            assertEquals(await store.getCredential(second.id), ORIGINAL);
+            await store.setCredential(first.id, {
+                hash: ORIGINAL.hash,
+                salt: ORIGINAL.salt,
+            });
+            assertEquals(await store.getCredential(first.id), {
+                hash: ORIGINAL.hash,
+                salt: ORIGINAL.salt,
+            });
+        });
+        if (options.replaceCredential) {
+            it("compares credential values, including every parameter and absent params", async () => {
+                const user = await create();
+                assertExists(store.replaceCredential, "replaceCredential capability is required");
+                const mismatches = [
+                    { ...ORIGINAL, hash: REPLACEMENT.hash },
+                    { ...ORIGINAL, salt: REPLACEMENT.salt },
+                    { ...ORIGINAL, params: { algorithm: "other", iterations: 600_000 } },
+                    {
+                        ...ORIGINAL,
+                        params: { algorithm: "pbkdf2-sha256", iterations: 600_001 },
+                    },
+                    { hash: ORIGINAL.hash, salt: ORIGINAL.salt },
+                ];
+                for (const expected of mismatches) {
+                    assertStrictEquals(await store.replaceCredential(user.id, expected, REPLACEMENT), false);
+                    assertEquals(await store.getCredential(user.id), ORIGINAL, "a failed compare-and-set must preserve the winner");
+                }
+                assertStrictEquals(await store.replaceCredential(user.id, structuredClone(ORIGINAL), REPLACEMENT), true);
+                assertEquals(await store.getCredential(user.id), REPLACEMENT);
+                assertStrictEquals(await store.replaceCredential(user.id, ORIGINAL, ORIGINAL), false);
+                assertEquals(await store.getCredential(user.id), REPLACEMENT, "read after a lost compare-and-set must see the committed credential");
+                await store.setCredential(user.id, {
+                    hash: ORIGINAL.hash,
+                    salt: ORIGINAL.salt,
+                });
+                assertStrictEquals(await store.replaceCredential(user.id, {
+                    hash: ORIGINAL.hash,
+                    salt: ORIGINAL.salt,
+                }, REPLACEMENT), true);
+            });
+            it("upgrades an absent credential only once", async () => {
+                const user = await create();
+                assertExists(store.replaceCredential);
+                assertExists(fixture.removeCredential, "removeCredential setup helper is required");
+                await fixture.removeCredential(user.id);
+                assertStrictEquals(await store.getCredential(user.id), undefined);
+                const results = await drain(Array.from({ length: 8 }, () => store.replaceCredential(user.id, undefined, structuredClone(REPLACEMENT))));
+                assertEquals(results.filter(Boolean).length, 1, "exactly one concurrent imported upgrade may win");
+                assertEquals(await store.getCredential(user.id), REPLACEMENT);
+            });
+            it("allows exactly one concurrent replacement of the same credential", async () => {
+                const user = await create();
+                const other = await create(2);
+                assertExists(store.replaceCredential);
+                const candidates = Array.from({ length: 8 }, (_, index) => ({
+                    ...REPLACEMENT,
+                    hash: (index + 5).toString(16).padStart(2, "0").repeat(32),
+                }));
+                const results = await drain(candidates.map((credential) => store.replaceCredential(user.id, structuredClone(ORIGINAL), credential)));
+                assertEquals(results.filter(Boolean).length, 1, "exactly one concurrent replacement may win");
+                assertEquals(await store.getCredential(user.id), candidates[results.indexOf(true)]);
+                assertEquals(await store.getCredential(other.id), ORIGINAL);
+            });
+        }
+        if (options.emailVerification) {
+            it("verifies only the issued-for email and is idempotent", async () => {
+                const user = await create();
+                const other = await create(2);
+                assertExists(store.markEmailVerified, "email verification capability is required");
+                assertExists(fixture.setEmail);
+                assertExists(fixture.isEmailVerified);
+                const originalEmail = fixture.makeProfile(1).email;
+                const changedEmail = "changed-identity-contract@example.invalid";
+                assertStrictEquals(await fixture.isEmailVerified(user.id), false);
+                await fixture.setEmail(user.id, changedEmail);
+                await store.markEmailVerified(user.id, originalEmail);
+                assertStrictEquals(await fixture.isEmailVerified(user.id), false, "a token for an old email must not verify the new email");
+                await store.markEmailVerified(user.id, changedEmail);
+                await store.markEmailVerified(user.id, changedEmail);
+                assertStrictEquals(await fixture.isEmailVerified(user.id), true);
+                assertStrictEquals(await fixture.isEmailVerified(other.id), false);
+            });
+        }
+        if (options.legacyCredentials) {
+            it("clears the selected imported credential and is idempotent", async () => {
+                const user = await create();
+                const other = await create(2);
+                assertExists(store.getLegacyCredential, "legacy credential lookup capability is required");
+                assertExists(store.clearLegacyCredential, "legacy credential clearing capability is required");
+                assertExists(fixture.setLegacyCredential);
+                assertStrictEquals(await store.getLegacyCredential(user.id), null);
+                await fixture.setLegacyCredential(user.id, "imported-hash-one");
+                await fixture.setLegacyCredential(other.id, "imported-hash-two");
+                assertEquals(await store.getLegacyCredential(user.id), "imported-hash-one");
+                await store.clearLegacyCredential(user.id);
+                await store.clearLegacyCredential(user.id);
+                assertStrictEquals(await store.getLegacyCredential(user.id), null);
+                assertEquals(await store.getLegacyCredential(other.id), "imported-hash-two");
+                assertEquals(await store.getCredential(user.id), ORIGINAL);
+            });
+        }
+    });
+}

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

@@ -20,6 +20,10 @@
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
+ * Identity user storage, session revocation, and authoritative session listing
+ * also have separate suites. They use app-owned fixture helpers to verify
+ * conditional credential writes and immediate, user-scoped session revocation.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -39,4 +43,6 @@ export { type OtpStoreContractOptions, runOtpStoreContractTests, } from "./otp-s
 export { type RateLimitStoreContractOptions, runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { type LockoutStoreContractOptions, runLockoutStoreContractTests, } from "./lockout-store.js";
 export { type AuthRequestStorageContractOptions, runAuthRequestStorageContractTests, } from "./auth-request-storage.js";
-export { runTenantContractTests, type TenantContractFixture, type TenantContractOptions, type TenantContractProfile, type TenantContractSignInOptions, type TenantContractTokens, } from "./tenant.js";
+export { runTenantContractTests, type TenantContractClient, type TenantContractFixture, type TenantContractMachineClientOptions, type TenantContractMachinePermission, type TenantContractOptions, type TenantContractProfile, type TenantContractSignInOptions, type TenantContractTokens, } from "./tenant.js";
+export { type IdentityUserContractProfile, type IdentityUserStoreContractFixture, type IdentityUserStoreContractOptions, runIdentityUserStoreContractTests, } from "./identity-user-store.js";
+export { type IdentitySessionContractState, type ListableSessionServiceContractFixture, type ListableSessionServiceContractOptions, type RevocableSessionServiceContractFixture, type RevocableSessionServiceContractOptions, runListableSessionServiceContractTests, runRevocableSessionServiceContractTests, } from "./identity-session.js";

package/esm/testing/contract/mod.js

@@ -20,6 +20,10 @@
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
+ * Identity user storage, session revocation, and authoritative session listing
+ * also have separate suites. They use app-owned fixture helpers to verify
+ * conditional credential writes and immediate, user-scoped session revocation.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -40,3 +44,5 @@ export { runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { runLockoutStoreContractTests, } from "./lockout-store.js";
 export { runAuthRequestStorageContractTests, } from "./auth-request-storage.js";
 export { runTenantContractTests, } from "./tenant.js";
+export { runIdentityUserStoreContractTests, } from "./identity-user-store.js";
+export { runListableSessionServiceContractTests, runRevocableSessionServiceContractTests, } from "./identity-session.js";

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

@@ -3,7 +3,9 @@
  * about its signed-in people: what introspection reports, what
  * `GET /api/memberships` lists, what `POST /api/check` and
  * `POST /api/check/batch` answer, the organization API under
- * `/api/organizations`, and the account API under `/api/account`.
+ * `/api/organizations`, and the account API under `/api/account` — and what it
+ * answers the application itself: the `client_credentials` grant, and
+ * `GET /api/resource-grants` under the application's own machine token.
  *
  * It runs against `createFakeTenant` from `@udibo/oauth2/testing` and against the
  * real identity service in Udibo's own repository, so the fake an app tests
@@ -94,9 +96,50 @@ export interface TenantContractFixture {
      * own, unless `options.sameBrowser` says otherwise.
      */
     signIn(userId: string, organizationId?: string, options?: TenantContractSignInOptions): Promise<TenantContractTokens>;
+    /**
+     * Registers an application allowed the `client_credentials` grant and no
+     * other, whose tokens may carry `options.scopes` and nothing else, and which
+     * a tenant administrator has assigned `options.permissions`. It is
+     * confidential unless `options.confidential` is `false`. Returns the
+     * credentials it signs in with: its id, and its secret when it has one.
+     */
+    addMachineClient(options: TenantContractMachineClientOptions): Promise<TenantContractClient>;
     /** Releases anything `setup` allocated. */
     cleanup?(): Promise<void> | void;
 }
+/** An application's credentials at the token endpoint. */
+export interface TenantContractClient {
+    /** The client id. */
+    id: string;
+    /** The client secret, which a public application is never issued. */
+    secret?: string;
+}
+/**
+ * A management permission a tenant administrator assigns a machine
+ * application. The suite assigns `resource_grants.read`, which is what
+ * `GET /api/resource-grants` requires.
+ */
+export type TenantContractMachinePermission = "resource_grants.read";
+/** What `TenantContractFixture.addMachineClient` registers. */
+export interface TenantContractMachineClientOptions {
+    /**
+     * The scopes the application's tokens may carry. The suite names
+     * `identity:organizations:read` alone, and expects a token asking for any
+     * other to be refused.
+     */
+    scopes: string[];
+    /** The permissions an administrator assigned the application. */
+    permissions: TenantContractMachinePermission[];
+    /**
+     * Whether the application is confidential, authenticating with a secret.
+     * Defaults to `true`. With `false` it is public and issued no secret, and
+     * the suite expects the token endpoint to refuse it the grant as
+     * `invalid_client`. A tenant that refuses to register a public application
+     * allowed the grant may leave the grant off, since that refusal is client
+     * authentication's and comes before the grant is considered.
+     */
+    confidential?: boolean;
+}
 /** How `TenantContractFixture.signIn` signs a person in. */
 export interface TenantContractSignInOptions {
     /**