@udibo/oauth2 0.1.0 → 0.3.0

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

@@ -37,3 +37,4 @@ export { runTokenFlowStoreContractTests, type TokenFlowStoreContractOptions, } f
 export { type OtpStoreContractOptions, runOtpStoreContractTests, } from "./otp-store.js";
 export { type RateLimitStoreContractOptions, runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { type LockoutStoreContractOptions, runLockoutStoreContractTests, } from "./lockout-store.js";
+export { runTenantContractTests, type TenantContractFixture, type TenantContractOptions, type TenantContractTokens, } from "./tenant.js";

package/esm/testing/contract/mod.js

@@ -37,3 +37,4 @@ export { runTokenFlowStoreContractTests, } from "./token-flow-store.js";
 export { runOtpStoreContractTests, } from "./otp-store.js";
 export { runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { runLockoutStoreContractTests, } from "./lockout-store.js";
+export { runTenantContractTests, } from "./tenant.js";

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

@@ -0,0 +1,97 @@
+/**
+ * Contract test suite for a Udibo tenant's authorization answers: what
+ * introspection reports about a signed-in person, what `GET /api/memberships`
+ * lists for them, and what `POST /api/check` and `POST /api/check/batch`
+ * answer.
+ *
+ * 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
+ * with answers the way the tenant it ships against does. Run it against
+ * another stand-in to hold it to the same answers.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   runTenantContractTests,
+ *   type TenantContractFixture,
+ * } from "@udibo/oauth2/testing/contract";
+ *
+ * declare function startSeededTenant(): Promise<TenantContractFixture>;
+ *
+ * runTenantContractTests({ setup: startSeededTenant });
+ * ```
+ *
+ * @module
+ */
+/** A token response from a completed sign-in. */
+export interface TenantContractTokens {
+    /** The access token the sign-in issued. */
+    access_token: string;
+    /** The refresh token the sign-in issued. */
+    refresh_token: string;
+}
+/** A tenant under test, and how the suite seeds it. */
+export interface TenantContractFixture {
+    /** The tenant's origin; its RFC 8414 metadata is served beneath it. */
+    issuer: string;
+    /**
+     * A confidential client the suite signs in with, introspects with and
+     * refreshes with. It must be allowed the `refresh_token` grant.
+     */
+    client: {
+        id: string;
+        secret: string;
+    };
+    /**
+     * How the suite reaches the tenant. Defaults to the global `fetch`; supply
+     * one when the tenant's host resolves only through a proxy.
+     */
+    fetch?: typeof fetch;
+    /** Adds a person holding `permissions` tenant-wide, and returns their id. */
+    addUser(permissions: string[]): Promise<string>;
+    /** Adds an organization and returns its id. */
+    addOrganization(): Promise<string>;
+    /**
+     * Makes a person a `member` of an organization, holding `permissions`
+     * inside it.
+     */
+    addMember(organizationId: string, userId: string, permissions: string[]): Promise<void>;
+    /** Ends a membership. */
+    removeMember(organizationId: string, userId: string): Promise<void>;
+    /**
+     * Grants `permissions` on one instance of a resource type to a person, or
+     * to every member of an organization. Registers the type if it is new.
+     */
+    grant(grant: {
+        resource: {
+            type: string;
+            id: string;
+        };
+        subject: {
+            type: "user" | "organization";
+            id: string;
+        };
+        permissions: string[];
+    }): Promise<void>;
+    /**
+     * Signs the person in through the authorization-code flow and returns the
+     * tokens it issued. With an organization named, the credential is issued in
+     * it; with none, the sign-in picks nothing, leaving the tenant to decide.
+     */
+    signIn(userId: string, organizationId?: string): Promise<TenantContractTokens>;
+    /** Releases anything `setup` allocated. */
+    cleanup?(): Promise<void> | void;
+}
+/** Options for {@link runTenantContractTests}. */
+export interface TenantContractOptions {
+    /** Overrides the top-level `describe` name. */
+    describeName?: string;
+    /** Builds the tenant once for the whole suite. */
+    setup(): Promise<TenantContractFixture> | TenantContractFixture;
+}
+/**
+ * Registers the tenant contract suite. The permissions and resource type it
+ * seeds are namespaced `contract`, so a tenant shared with other suites is
+ * safe as long as nothing else uses that namespace.
+ */
+export declare function runTenantContractTests(options: TenantContractOptions): void;

package/esm/testing/contract/tenant.js

@@ -0,0 +1,309 @@
+/**
+ * Contract test suite for a Udibo tenant's authorization answers: what
+ * introspection reports about a signed-in person, what `GET /api/memberships`
+ * lists for them, and what `POST /api/check` and `POST /api/check/batch`
+ * answer.
+ *
+ * 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
+ * with answers the way the tenant it ships against does. Run it against
+ * another stand-in to hold it to the same answers.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   runTenantContractTests,
+ *   type TenantContractFixture,
+ * } from "@udibo/oauth2/testing/contract";
+ *
+ * declare function startSeededTenant(): Promise<TenantContractFixture>;
+ *
+ * runTenantContractTests({ setup: startSeededTenant });
+ * ```
+ *
+ * @module
+ */
+import { assert, assertEquals, assertFalse } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import { afterAll, beforeAll, describe, it } from "../../deps/jsr.io/@std/testing/1.0.20/bdd.js";
+import { encodeBasicAuth } from "../../utils/basic-auth.js";
+/**
+ * Registers the tenant contract suite. The permissions and resource type it
+ * seeds are namespaced `contract`, so a tenant shared with other suites is
+ * safe as long as nothing else uses that namespace.
+ */
+export function runTenantContractTests(options) {
+    describe(options.describeName ?? "Udibo tenant contract", () => {
+        let tenant;
+        let metadata;
+        let send;
+        const people = {
+            member: "",
+            outsider: "",
+            leaver: "",
+            solo: "",
+        };
+        const organizations = { home: "", other: "", unjoined: "" };
+        beforeAll(async () => {
+            tenant = await options.setup();
+            send = tenant.fetch ?? fetch;
+            const response = await send(new URL("/.well-known/oauth-authorization-server", tenant.issuer));
+            metadata = await response.json();
+            people.member = await tenant.addUser(["contract:tenant"]);
+            people.outsider = await tenant.addUser([]);
+            people.leaver = await tenant.addUser([]);
+            people.solo = await tenant.addUser([]);
+            organizations.home = await tenant.addOrganization();
+            organizations.other = await tenant.addOrganization();
+            organizations.unjoined = await tenant.addOrganization();
+            await tenant.addMember(organizations.home, people.member, [
+                "contract:home",
+            ]);
+            await tenant.addMember(organizations.other, people.member, [
+                "contract:other",
+            ]);
+            await tenant.addMember(organizations.home, people.outsider, []);
+            await tenant.addMember(organizations.home, people.leaver, [
+                "contract:home",
+            ]);
+            await tenant.addMember(organizations.other, people.solo, [
+                "contract:other",
+            ]);
+            await tenant.grant({
+                resource: { type: "contract_document", id: "direct" },
+                subject: { type: "user", id: people.outsider },
+                permissions: ["contract:read"],
+            });
+            await tenant.grant({
+                resource: { type: "contract_document", id: "shared" },
+                subject: { type: "organization", id: organizations.home },
+                permissions: ["contract:write"],
+            });
+        });
+        afterAll(async () => {
+            await tenant?.cleanup?.();
+        });
+        const clientAuth = () => encodeBasicAuth(tenant.client.id, tenant.client.secret);
+        async function introspect(accessToken) {
+            const response = await send(metadata.introspection_endpoint, {
+                method: "POST",
+                headers: { authorization: clientAuth() },
+                body: new URLSearchParams({ token: accessToken }),
+            });
+            assertEquals(response.status, 200);
+            return await response.json();
+        }
+        async function ask(accessToken, path, body) {
+            const response = await send(new URL(path, tenant.issuer), {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${accessToken}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(body),
+            });
+            const text = await response.text();
+            return { status: response.status, body: text ? JSON.parse(text) : {} };
+        }
+        const sorted = (values) => [...values ?? []].sort();
+        describe("introspection", () => {
+            it("reports tenant-wide permissions and no organization for a sign-in that picked none", async () => {
+                const { access_token } = await tenant.signIn(people.member);
+                const claims = await introspect(access_token);
+                assertEquals(claims.active, true);
+                assertEquals(claims.sub, people.member);
+                assertEquals(sorted(claims.permissions), ["contract:tenant"]);
+                assertFalse(claims.org_id, "a sign-in with no organization names none");
+            });
+            it("picks a person's only organization when the sign-in names none", async () => {
+                const { access_token } = await tenant.signIn(people.solo);
+                const claims = await introspect(access_token);
+                assertEquals(claims.org_id, organizations.other);
+                assertEquals(sorted(claims.permissions), ["contract:other"]);
+            });
+            it("adds the picked organization and its permissions, and no other's", async () => {
+                const { access_token } = await tenant.signIn(people.member, organizations.home);
+                const claims = await introspect(access_token);
+                assertEquals(claims.org_id, organizations.home);
+                assertEquals(sorted(claims.permissions), [
+                    "contract:home",
+                    "contract:tenant",
+                ]);
+            });
+            it("keeps a refreshed credential in the organization it was issued for", async () => {
+                const issued = await tenant.signIn(people.member, organizations.other);
+                await tenant.signIn(people.member, organizations.home);
+                const response = await send(metadata.token_endpoint, {
+                    method: "POST",
+                    headers: { authorization: clientAuth() },
+                    body: new URLSearchParams({
+                        grant_type: "refresh_token",
+                        refresh_token: issued.refresh_token,
+                    }),
+                });
+                assertEquals(response.status, 200);
+                const refreshed = await response.json();
+                const claims = await introspect(refreshed.access_token);
+                assertEquals(claims.org_id, organizations.other);
+            });
+            it("stops answering for an organization once the membership ends", async () => {
+                const { access_token } = await tenant.signIn(people.leaver, organizations.home);
+                await tenant.removeMember(organizations.home, people.leaver);
+                const claims = await introspect(access_token);
+                assertFalse(claims.org_id);
+                assertEquals(sorted(claims.permissions), []);
+            });
+        });
+        describe("GET /api/memberships", () => {
+            it("lists the organizations the caller belongs to, and no others", async () => {
+                const { access_token } = await tenant.signIn(people.member);
+                const response = await send(new URL("/api/memberships", tenant.issuer), { headers: { authorization: `Bearer ${access_token}` } });
+                assertEquals(response.status, 200);
+                const body = await response.json();
+                assertEquals(body.memberships.map((membership) => membership.org_id).sort(), [organizations.home, organizations.other].sort());
+                for (const membership of body.memberships) {
+                    assertEquals(membership.roles, ["member"]);
+                    assert(membership.org_slug, "every membership names its slug");
+                    assert(membership.name, "every membership names its organization");
+                }
+                assertEquals(body.cursor, null);
+            });
+            it("refuses a caller with no bearer token", async () => {
+                const response = await send(new URL("/api/memberships", tenant.issuer));
+                await response.body?.cancel();
+                assertEquals(response.status, 401);
+            });
+        });
+        describe("POST /api/check", () => {
+            it("answers the credential's own organization when no resource is named", async () => {
+                const { access_token } = await tenant.signIn(people.member, organizations.home);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:home", "contract:other", "contract:tenant"],
+                });
+                assertEquals(answer.status, 200);
+                assertEquals(answer.body, {
+                    subject: people.member,
+                    resource: { type: "organization", id: organizations.home },
+                    results: {
+                        "contract:home": true,
+                        "contract:other": false,
+                        "contract:tenant": true,
+                    },
+                });
+            });
+            it("answers tenant scope alone, naming no resource, for a credential with no organization", async () => {
+                const { access_token } = await tenant.signIn(people.member);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:home", "contract:tenant"],
+                });
+                assertEquals(answer.body, {
+                    subject: people.member,
+                    resource: null,
+                    results: { "contract:home": false, "contract:tenant": true },
+                });
+            });
+            it("answers another organization the caller belongs to when it is named", async () => {
+                const { access_token } = await tenant.signIn(people.member, organizations.home);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:other"],
+                    resource: { type: "organization", id: organizations.other },
+                });
+                assertEquals(answer.status, 200);
+                assertEquals(answer.body.results, { "contract:other": true });
+            });
+            it("answers an organization the caller does not belong to from tenant-wide permissions alone", async () => {
+                const { access_token } = await tenant.signIn(people.member);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:other", "contract:tenant"],
+                    resource: { type: "organization", id: organizations.unjoined },
+                });
+                assertEquals(answer.status, 200);
+                assertEquals(answer.body.results, {
+                    "contract:other": false,
+                    "contract:tenant": true,
+                });
+            });
+            it("answers an organization that does not exist as not found", async () => {
+                const { access_token } = await tenant.signIn(people.member);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:tenant"],
+                    resource: { type: "organization", id: crypto.randomUUID() },
+                });
+                assertEquals(answer.status, 404);
+            });
+            it("answers a resource from a grant to the person and from one to their organization", async () => {
+                const { access_token } = await tenant.signIn(people.outsider);
+                const direct = await ask(access_token, "/api/check", {
+                    permissions: ["contract:read", "contract:write"],
+                    resource: { type: "contract_document", id: "direct" },
+                });
+                assertEquals(direct.status, 200);
+                assertEquals(direct.body.results, {
+                    "contract:read": true,
+                    "contract:write": false,
+                });
+                const shared = await ask(access_token, "/api/check", {
+                    permissions: ["contract:write"],
+                    resource: { type: "contract_document", id: "shared" },
+                });
+                assertEquals(shared.body.results, { "contract:write": true });
+            });
+            it("leaves organization permissions out of a resource answer", async () => {
+                const { access_token } = await tenant.signIn(people.member, organizations.home);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:home", "contract:tenant"],
+                    resource: { type: "contract_document", id: "direct" },
+                });
+                assertEquals(answer.body.results, {
+                    "contract:home": false,
+                    "contract:tenant": true,
+                });
+            });
+            it("refuses a resource type the tenant has not registered", async () => {
+                const { access_token } = await tenant.signIn(people.member);
+                const answer = await ask(access_token, "/api/check", {
+                    permissions: ["contract:read"],
+                    resource: { type: "contract_unregistered", id: "x" },
+                });
+                assertEquals(answer.status, 400);
+            });
+            it("refuses a caller with no bearer token", async () => {
+                const response = await send(new URL("/api/check", tenant.issuer), {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ permissions: ["contract:tenant"] }),
+                });
+                await response.body?.cancel();
+                assertEquals(response.status, 401);
+            });
+        });
+        describe("POST /api/check/batch", () => {
+            it("answers each candidate id as /api/check would", async () => {
+                const { access_token } = await tenant.signIn(people.outsider);
+                const answer = await ask(access_token, "/api/check/batch", {
+                    permissions: ["contract:read"],
+                    resource: { type: "contract_document", ids: ["direct", "unseen"] },
+                });
+                assertEquals(answer.status, 200);
+                assertEquals(answer.body, {
+                    subject: people.outsider,
+                    resource: { type: "contract_document" },
+                    results: {
+                        direct: { "contract:read": true },
+                        unseen: { "contract:read": false },
+                    },
+                });
+            });
+            it("refuses more than a hundred candidates", async () => {
+                const { access_token } = await tenant.signIn(people.outsider);
+                const answer = await ask(access_token, "/api/check/batch", {
+                    permissions: ["contract:read"],
+                    resource: {
+                        type: "contract_document",
+                        ids: Array.from({ length: 101 }, (_, i) => `id-${i}`),
+                    },
+                });
+                assert(answer.status === 400, `answered ${answer.status}`);
+            });
+        });
+    });
+}

package/esm/testing/mod.d.ts

@@ -24,6 +24,12 @@
  *   user / client / scope types. Suitable for tests, examples, and
  *   prototypes — never for production.
  *
+ * - **A fake Udibo tenant.** {@link createFakeTenant} answers a tenant's
+ *   protocol surface and its `/api/check` questions over `fetch`, with the
+ *   claims a real tenant issues — permissions, the organization picked at
+ *   sign-in, and resource grants — so an app built on a Udibo tenant can test
+ *   its own routes without running the identity service.
+ *
  * Nothing in this module is an OAuth2 primitive — only testing support.
  * Production code should never import from here.
  *
@@ -32,3 +38,4 @@
 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";
+export { createFakeTenant, type FakeTenant, type FakeTenantClient, type FakeTenantGrant, type FakeTenantMembership, type FakeTenantOptions, type FakeTenantOrganization, type FakeTenantSignIn, type FakeTenantSubject, type FakeTenantTokenRequest, type FakeTenantUser, } from "./tenant.js";

package/esm/testing/mod.js

@@ -24,6 +24,12 @@
  *   user / client / scope types. Suitable for tests, examples, and
  *   prototypes — never for production.
  *
+ * - **A fake Udibo tenant.** {@link createFakeTenant} answers a tenant's
+ *   protocol surface and its `/api/check` questions over `fetch`, with the
+ *   claims a real tenant issues — permissions, the organization picked at
+ *   sign-in, and resource grants — so an app built on a Udibo tenant can test
+ *   its own routes without running the identity service.
+ *
  * Nothing in this module is an OAuth2 primitive — only testing support.
  * Production code should never import from here.
  *
@@ -32,3 +38,4 @@
 import "../_dnt.polyfills.js";
 export { MemoryAuthorizationCodeService, MemoryClientService, MemoryDeviceAuthorizationService, MemoryTokenService, MemoryUserService, } from "./services.js";
 export { createMemoryAuthorizationServer, } from "./server.js";
+export { createFakeTenant, } from "./tenant.js";

package/esm/testing/tenant.d.ts

@@ -0,0 +1,166 @@
+import type { ClientInterface } from "../models/client.js";
+/** A person in a {@linkcode FakeTenant}. */
+export interface FakeTenantUser {
+    /** The subject every token and answer names. */
+    id: string;
+    /** The `username` introspection reports. */
+    username: string;
+    /** The `name` claim UserInfo reports. */
+    name?: string;
+    /** The `email` claim UserInfo reports. */
+    email?: string;
+    /** The `email_verified` claim UserInfo reports. Defaults to `true`. */
+    emailVerified?: boolean;
+    /** Permissions held tenant-wide, in every organization and on every resource. */
+    permissions?: string[];
+}
+/** An OAuth2 application registered in a {@linkcode FakeTenant}. */
+export interface FakeTenantClient extends ClientInterface {
+    /** Omit for a public client. */
+    secret?: string;
+    /**
+     * `"jwt"` issues RFC 9068 access tokens signed with the tenant's JWKS key,
+     * for a resource server that validates locally. Defaults to `"opaque"`.
+     */
+    accessTokenFormat?: "opaque" | "jwt";
+    /** A JWT access token's `aud`. Defaults to the client id. */
+    audience?: string;
+}
+/** An organization in a {@linkcode FakeTenant}. */
+export interface FakeTenantOrganization {
+    /** The id `org_id` carries and every scoped answer is keyed by. */
+    id: string;
+    /** The handle `org_slug` carries. Never an authorization key. */
+    slug: string;
+    /** The display name `/api/memberships` reports. Defaults to the slug. */
+    name?: string;
+}
+/** A person's place in one organization. */
+export interface FakeTenantMembership {
+    /**
+     * The membership's roles, as `org_roles` and `/api/memberships` report
+     * them — `member`, `admin` or `owner` on a real tenant.
+     */
+    roles?: string[];
+    /** Permissions held inside this organization only. */
+    permissions?: string[];
+}
+/** Who a resource grant is for. */
+export type FakeTenantSubject = {
+    type: "user";
+    id: string;
+} | {
+    type: "organization";
+    id: string;
+};
+/** Permissions on one resource instance, for one subject. */
+export interface FakeTenantGrant {
+    /** A type registered with {@linkcode FakeTenant.registerResourceType}, and your id for the instance. */
+    resource: {
+        type: string;
+        id: string;
+    };
+    /** A user, or an organization whose every member it admits. */
+    subject: FakeTenantSubject;
+    /** What the subject may do on that one resource. */
+    permissions: string[];
+}
+/** How the next sign-in resolves. */
+export interface FakeTenantSignIn {
+    /**
+     * The organization the person picks while signing in. Tokens issued from
+     * that sign-in carry its `org_id`, `org_slug` and `org_roles`, and its
+     * permissions join theirs. Omit it and a person in exactly one organization
+     * gets that one, as on a real tenant; a person in several gets none. An
+     * `organization` parameter on the authorization request, by id or slug,
+     * overrides both for that credential, and is refused with
+     * `invalid_request` when the person is not a member.
+     */
+    organizationId?: string;
+}
+/** What {@linkcode FakeTenant.issueAccessToken} mints a token for. */
+export interface FakeTenantTokenRequest {
+    /** The registered client the token is issued to. */
+    clientId: string;
+    /** The person the token is for. */
+    userId: string;
+    /**
+     * The organization the token answers for. Omit it and a person in exactly
+     * one organization gets that one; a person in several gets none.
+     */
+    organizationId?: string;
+    /** The granted scope. Defaults to `openid`. */
+    scope?: string;
+}
+/** Options for {@linkcode createFakeTenant}. */
+export interface FakeTenantOptions {
+    /**
+     * The origin the tenant is served on, exactly as the app under test
+     * configures its issuer. Every advertised endpoint and every JWT `iss` is
+     * built from it.
+     */
+    issuer: string;
+}
+/**
+ * A stand-in for a Udibo tenant, for testing an app that signs in against one
+ * without running the identity service. It answers the tenant's protocol
+ * surface — discovery, authorize, token, introspection, UserInfo, JWKS — the
+ * caller's own `GET /api/memberships`, and the two authorization questions,
+ * `POST /api/check` and `POST /api/check/batch`, with the same shapes a real
+ * tenant uses.
+ *
+ * Nothing here is interactive: {@linkcode signInAs} decides who the next
+ * authorization request authenticates, and there is no consent step. Serve
+ * {@linkcode fetch} on the origin passed as `issuer`.
+ */
+export interface FakeTenant {
+    /** The origin this tenant answers as. */
+    readonly issuer: string;
+    /** Handles one request to the tenant. Serve it on {@linkcode issuer}. */
+    fetch(request: Request): Promise<Response>;
+    /** Registers an application. Throws on a duplicate id. */
+    addClient(client: FakeTenantClient): Promise<void>;
+    /** Adds a person. Throws on a duplicate id or username. */
+    addUser(user: FakeTenantUser): Promise<void>;
+    /** Adds an organization. Throws on a duplicate id. */
+    addOrganization(organization: FakeTenantOrganization): void;
+    /** Makes a person a member of an organization, replacing any earlier membership. */
+    addMember(organizationId: string, userId: string, membership?: FakeTenantMembership): void;
+    /** Ends a membership. Credentials issued in that organization stop answering for it. */
+    removeMember(organizationId: string, userId: string): void;
+    /** Registers a resource type, so `/api/check` accepts it. */
+    registerResourceType(type: string): void;
+    /** Adds a resource grant. */
+    grant(grant: FakeTenantGrant): void;
+    /**
+     * Chooses who the next authorization requests authenticate as, until
+     * called again. With nobody chosen, authorize answers `login_required`.
+     */
+    signInAs(userId: string | null, signIn?: FakeTenantSignIn): void;
+    /**
+     * Mints an access token without the browser flow, for testing an API
+     * directly. JWT or opaque as the client is registered.
+     */
+    issueAccessToken(request: FakeTenantTokenRequest): Promise<string>;
+}
+/**
+ * Creates a {@linkcode FakeTenant}. Serve its `fetch` on the origin you pass
+ * as `issuer`, then point the app under test at that origin.
+ *
+ * @example
+ * ```ts
+ * import { createFakeTenant } from "@udibo/oauth2/testing";
+ *
+ * const server = Deno.serve(
+ *   { hostname: "127.0.0.1", port: 0, onListen() {} },
+ *   (request) => tenant.fetch(request),
+ * );
+ * const tenant = await createFakeTenant({
+ *   issuer: `http://127.0.0.1:${server.addr.port}`,
+ * });
+ * await tenant.addUser({ id: "user-1", username: "ada" });
+ * tenant.signInAs("user-1");
+ * await server.shutdown();
+ * ```
+ */
+export declare function createFakeTenant(options: FakeTenantOptions): Promise<FakeTenant>;

package/esm/testing/tenant.js

@@ -0,0 +1,418 @@
+import { AuthorizationCodeGrant } from "../server/grants/authorization-code.js";
+import { RefreshTokenGrant } from "../server/grants/refresh-token.js";
+import { AuthorizationServer } from "../server/authorization-server.js";
+import { createJwtAccessTokenGenerator, generateSigningKey, StaticSigningKeyProvider, } from "../server/signing-keys.js";
+import { BasicScope } from "../models/scope.js";
+import { InvalidRequestError } from "../errors.js";
+import { MemoryAuthorizationCodeService, MemoryClientService, MemoryTokenService, MemoryUserService, } from "./services.js";
+const PATHS = {
+    authorization: "/api/oauth2/authorize",
+    token: "/api/oauth2/token",
+    revocation: "/api/oauth2/revoke",
+    introspection: "/api/oauth2/introspect",
+    userinfo: "/api/oauth2/userinfo",
+    jwks: "/api/oauth2/jwks",
+};
+const MAX_PERMISSIONS = 50;
+const MAX_BATCH_IDS = 100;
+class TenantTokenService extends MemoryTokenService {
+    organizationOf;
+    recordCredential;
+    mintJwt;
+    constructor(options, organizationOf, recordCredential, mintJwt) {
+        super(options);
+        this.organizationOf = organizationOf;
+        this.recordCredential = recordCredential;
+        this.mintJwt = mintJwt;
+    }
+    async generateAccessToken(client, user, scope) {
+        const organizationId = user ? this.organizationOf(user.id) : undefined;
+        const accessToken = client.accessTokenFormat === "jwt" && user
+            ? await this.mintJwt(client, user, scope, organizationId)
+            : await super.generateAccessToken(client, user, scope);
+        this.recordCredential(accessToken, organizationId);
+        return accessToken;
+    }
+}
+function problem(status, detail) {
+    return Response.json({ status, detail }, {
+        status,
+        headers: { "content-type": "application/problem+json" },
+    });
+}
+function asPermissions(value) {
+    const list = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(list) || list.length === 0 ||
+        list.length > MAX_PERMISSIONS ||
+        !list.every((entry) => typeof entry === "string" && entry.length > 0)) {
+        return undefined;
+    }
+    return list;
+}
+/**
+ * Creates a {@linkcode FakeTenant}. Serve its `fetch` on the origin you pass
+ * as `issuer`, then point the app under test at that origin.
+ *
+ * @example
+ * ```ts
+ * import { createFakeTenant } from "@udibo/oauth2/testing";
+ *
+ * const server = Deno.serve(
+ *   { hostname: "127.0.0.1", port: 0, onListen() {} },
+ *   (request) => tenant.fetch(request),
+ * );
+ * const tenant = await createFakeTenant({
+ *   issuer: `http://127.0.0.1:${server.addr.port}`,
+ * });
+ * await tenant.addUser({ id: "user-1", username: "ada" });
+ * tenant.signInAs("user-1");
+ * await server.shutdown();
+ * ```
+ */
+export async function createFakeTenant(options) {
+    const issuer = new URL(options.issuer).origin;
+    const signingKeys = new StaticSigningKeyProvider(await generateSigningKey());
+    const users = new Map();
+    const organizations = new Map();
+    const resourceTypes = new Set();
+    const grants = [];
+    const credentialOrganization = new Map();
+    let signedIn = null;
+    const pendingOrganization = new Map();
+    const membershipOf = (organizationId, userId) => organizationId
+        ? organizations.get(organizationId)?.members.get(userId)
+        : undefined;
+    const permissionsIn = (userId, organizationId) => new Set([
+        ...users.get(userId)?.permissions ?? [],
+        ...membershipOf(organizationId, userId)?.permissions ?? [],
+    ]);
+    const organizationClaims = (userId, organizationId) => {
+        const membership = membershipOf(organizationId, userId);
+        if (!organizationId || !membership)
+            return {};
+        return {
+            org_id: organizationId,
+            org_slug: organizations.get(organizationId).slug,
+            org_roles: membership.roles ?? [],
+        };
+    };
+    const authorizationClaims = (userId, organizationId) => {
+        const claims = organizationClaims(userId, organizationId);
+        return {
+            permissions: [...permissionsIn(userId, claims.org_id)],
+            ...claims,
+        };
+    };
+    const userService = new MemoryUserService();
+    const clientService = new MemoryClientService(userService);
+    const tokenService = new TenantTokenService({ clientService, userService }, (userId) => pendingOrganization.get(userId), (accessToken, organizationId) => credentialOrganization.set(accessToken, organizationId), (client, user, scope, organizationId) => createJwtAccessTokenGenerator({
+        signingKeys,
+        issuer,
+        audience: client.audience ?? client.id,
+        userClaims: () => ({
+            username: user.username,
+            ...authorizationClaims(user.id, organizationId),
+        }),
+    })(client, user, scope));
+    const authorizationCodeService = new MemoryAuthorizationCodeService({ clientService, userService });
+    const server = new AuthorizationServer({
+        resolve: () => ({
+            services: { clientService, tokenService },
+            issuer,
+            authorizationEndpoint: `${issuer}${PATHS.authorization}`,
+            tokenEndpoint: `${issuer}${PATHS.token}`,
+            revocationEndpoint: `${issuer}${PATHS.revocation}`,
+            introspectionEndpoint: `${issuer}${PATHS.introspection}`,
+            userinfoEndpoint: `${issuer}${PATHS.userinfo}`,
+            jwksEndpoint: `${issuer}${PATHS.jwks}`,
+        }),
+        grants: {
+            authorization_code: new AuthorizationCodeGrant({
+                resolve: () => ({
+                    clientService,
+                    tokenService,
+                    authorizationCodeService,
+                }),
+                allowRefreshToken: true,
+            }),
+            refresh_token: new RefreshTokenGrant({
+                resolve: () => ({ clientService, tokenService }),
+            }),
+        },
+        signingKeys,
+        scopesSupported: ["openid", "profile", "email", "offline_access"],
+        userClaims: (user) => ({
+            preferred_username: user.username,
+            name: user.name,
+            email: user.email,
+            email_verified: user.email ? user.emailVerified ?? true : undefined,
+            ...organizationClaims(user.id, signedIn?.userId === user.id ? signedIn.organizationId : undefined),
+        }),
+        introspectionClaims: (token) => token.user
+            ? authorizationClaims(token.user.id, credentialOrganization.get(token.accessToken))
+            : {},
+    });
+    const withPendingOrganization = async (userId, organizationId, work) => {
+        if (!userId)
+            return await work();
+        pendingOrganization.set(userId, organizationId);
+        try {
+            return await work();
+        }
+        finally {
+            pendingOrganization.delete(userId);
+        }
+    };
+    const authenticated = async (request) => {
+        let token;
+        try {
+            ({ token } = await server.authenticate(request));
+        }
+        catch (error) {
+            return server.handleAuthError(error);
+        }
+        if (!token.user) {
+            return problem(403, "A machine credential has no self to answer for.");
+        }
+        const organizationId = credentialOrganization.get(token.accessToken);
+        return {
+            user: token.user,
+            organizationId: membershipOf(organizationId, token.user.id)
+                ? organizationId
+                : undefined,
+        };
+    };
+    const resourcePermissions = (userId, type, id) => {
+        const held = permissionsIn(userId);
+        for (const grant of grants) {
+            if (grant.resource.type !== type || grant.resource.id !== id)
+                continue;
+            const admits = grant.subject.type === "user"
+                ? grant.subject.id === userId
+                : Boolean(membershipOf(grant.subject.id, userId));
+            if (admits)
+                grant.permissions.forEach((p) => held.add(p));
+        }
+        return held;
+    };
+    const answer = (asked, held) => Object.fromEntries(asked.map((p) => [p, held.has(p)]));
+    const check = async (request) => {
+        const caller = await authenticated(request);
+        if (caller instanceof Response)
+            return caller;
+        const body = await request.json().catch(() => null);
+        const asked = asPermissions(body?.permissions);
+        if (!asked)
+            return problem(400, "permissions is invalid");
+        const resource = body?.resource;
+        if (resource === undefined) {
+            return Response.json({
+                subject: caller.user.id,
+                resource: caller.organizationId
+                    ? { type: "organization", id: caller.organizationId }
+                    : null,
+                results: answer(asked, permissionsIn(caller.user.id, caller.organizationId)),
+            });
+        }
+        if (typeof resource?.type !== "string" || typeof resource.id !== "string") {
+            return problem(400, "resource is invalid");
+        }
+        if (resource.type === "organization") {
+            if (!organizations.has(resource.id)) {
+                return problem(404, "Organization not found");
+            }
+            return Response.json({
+                subject: caller.user.id,
+                resource: { type: "organization", id: resource.id },
+                results: answer(asked, permissionsIn(caller.user.id, resource.id)),
+            });
+        }
+        if (!resourceTypes.has(resource.type)) {
+            return problem(400, `resource.type "${resource.type}" is not registered`);
+        }
+        return Response.json({
+            subject: caller.user.id,
+            resource: { type: resource.type, id: resource.id },
+            results: answer(asked, resourcePermissions(caller.user.id, resource.type, resource.id)),
+        });
+    };
+    const checkBatch = async (request) => {
+        const caller = await authenticated(request);
+        if (caller instanceof Response)
+            return caller;
+        const body = await request.json().catch(() => null);
+        const asked = asPermissions(body?.permissions);
+        if (!asked)
+            return problem(400, "permissions is invalid");
+        const type = body?.resource?.type;
+        const ids = body?.resource?.ids;
+        if (typeof type !== "string" || !Array.isArray(ids) || ids.length === 0 ||
+            ids.length > MAX_BATCH_IDS ||
+            !ids.every((id) => typeof id === "string" && id.length > 0)) {
+            return problem(400, "resource is invalid");
+        }
+        if (!resourceTypes.has(type)) {
+            return problem(400, `resource.type "${type}" is not registered`);
+        }
+        return Response.json({
+            subject: caller.user.id,
+            resource: { type },
+            results: Object.fromEntries(ids.map((id) => [
+                id,
+                answer(asked, resourcePermissions(caller.user.id, type, id)),
+            ])),
+        });
+    };
+    const signInOfCode = new Map();
+    const signInOfRefreshToken = new Map();
+    const soleOrganizationOf = (userId) => {
+        const joined = [...organizations.values()].filter((organization) => organization.members.has(userId));
+        return joined.length === 1 ? joined[0].id : undefined;
+    };
+    const requestedOrganization = (requested, userId) => {
+        const organization = organizations.get(requested) ??
+            [...organizations.values()].find((o) => o.slug === requested);
+        if (!organization?.members.has(userId)) {
+            throw new InvalidRequestError("organization is not available");
+        }
+        return organization.id;
+    };
+    const memberships = async (request) => {
+        const caller = await authenticated(request);
+        if (caller instanceof Response)
+            return caller;
+        return Response.json({
+            memberships: [...organizations.values()]
+                .filter((organization) => organization.members.has(caller.user.id))
+                .map((organization) => ({
+                org_id: organization.id,
+                org_slug: organization.slug,
+                name: organization.name ?? organization.slug,
+                roles: organization.members.get(caller.user.id).roles ?? [],
+            })),
+            cursor: null,
+        });
+    };
+    const authorize = async (request) => {
+        const chosen = signedIn;
+        const requested = new URL(request.url).searchParams.get("organization");
+        let issued;
+        const response = await server.handleAuthorizeRequest(request, () => {
+            const user = chosen ? users.get(chosen.userId) : undefined;
+            if (!user)
+                return Promise.resolve(null);
+            issued = {
+                userId: user.id,
+                organizationId: requested
+                    ? requestedOrganization(requested, user.id)
+                    : chosen?.organizationId ?? soleOrganizationOf(user.id),
+            };
+            return Promise.resolve({ user });
+        });
+        const location = response.headers.get("location");
+        const code = location ? new URL(location).searchParams.get("code") : null;
+        if (code && issued)
+            signInOfCode.set(code, issued);
+        return response;
+    };
+    const token = async (request) => {
+        const form = await request.clone().formData().catch(() => null);
+        const code = form?.get("code");
+        const refreshToken = form?.get("refresh_token");
+        const signIn = typeof code === "string"
+            ? signInOfCode.get(code)
+            : typeof refreshToken === "string"
+                ? signInOfRefreshToken.get(refreshToken)
+                : undefined;
+        const response = await withPendingOrganization(signIn?.userId, signIn?.organizationId, () => server.handleTokenRequest(request));
+        if (response.ok && signIn) {
+            const issued = await response.clone().json();
+            if (issued.refresh_token) {
+                signInOfRefreshToken.set(issued.refresh_token, signIn);
+            }
+        }
+        return response;
+    };
+    const routes = {
+        "GET /.well-known/oauth-authorization-server": (r) => server.handleMetadataRequest(r),
+        "GET /.well-known/openid-configuration": (r) => server.handleOidcMetadataRequest(r),
+        [`GET ${PATHS.authorization}`]: authorize,
+        [`POST ${PATHS.token}`]: token,
+        [`POST ${PATHS.revocation}`]: (r) => server.handleRevocationRequest(r),
+        [`POST ${PATHS.introspection}`]: (r) => server.handleIntrospectionRequest(r),
+        [`GET ${PATHS.userinfo}`]: (r) => server.handleUserInfoRequest(r),
+        [`POST ${PATHS.userinfo}`]: (r) => server.handleUserInfoRequest(r),
+        [`GET ${PATHS.jwks}`]: (r) => server.handleJwksRequest(r),
+        "GET /api/memberships": memberships,
+        "POST /api/check": check,
+        "POST /api/check/batch": checkBatch,
+    };
+    return {
+        issuer,
+        fetch: (request) => {
+            const route = routes[`${request.method} ${new URL(request.url).pathname}`];
+            return route
+                ? route(request)
+                : Promise.resolve(problem(404, "Not found"));
+        },
+        addClient: async ({ secret, ...client }) => {
+            await clientService.add({
+                grants: ["authorization_code", "refresh_token"],
+                ...client,
+            }, secret);
+        },
+        addUser: async (user) => {
+            await userService.add(user, crypto.randomUUID());
+            users.set(user.id, user);
+        },
+        addOrganization: (organization) => {
+            if (organizations.has(organization.id)) {
+                throw new Error(`Organization "${organization.id}" already exists`);
+            }
+            organizations.set(organization.id, {
+                ...organization,
+                members: new Map(),
+            });
+        },
+        addMember: (organizationId, userId, membership = {}) => {
+            const organization = organizations.get(organizationId);
+            if (!organization) {
+                throw new Error(`Organization "${organizationId}" does not exist`);
+            }
+            organization.members.set(userId, membership);
+        },
+        removeMember: (organizationId, userId) => {
+            organizations.get(organizationId)?.members.delete(userId);
+        },
+        registerResourceType: (type) => {
+            resourceTypes.add(type);
+        },
+        grant: (grant) => {
+            grants.push(grant);
+        },
+        signInAs: (userId, signIn = {}) => {
+            signedIn = userId ? { userId, ...signIn } : null;
+        },
+        issueAccessToken: async (request) => {
+            const client = await clientService.get(request.clientId);
+            const user = users.get(request.userId);
+            if (!client) {
+                throw new Error(`Client "${request.clientId}" does not exist`);
+            }
+            if (!user)
+                throw new Error(`User "${request.userId}" does not exist`);
+            const scope = new BasicScope(request.scope ?? "openid");
+            return await withPendingOrganization(user.id, request.organizationId ?? soleOrganizationOf(user.id), async () => {
+                const accessToken = await tokenService.generateAccessToken(client, user, scope);
+                await tokenService.save({
+                    client,
+                    user,
+                    scope,
+                    accessToken,
+                    accessTokenExpiresAt: await tokenService.accessTokenExpiresAt(client, user, scope),
+                });
+                return accessToken;
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "repository": {
     "type": "git",