@udibo/oauth2 0.9.1 → 0.10.0

package/esm/server/authorization-server.d.ts

@@ -126,6 +126,11 @@ export interface AuthorizationServerContext<Client extends ClientInterface, User
     services: AuthorizationServerServices<Client, User, S>;
     /** The issuer identifier URL for this request. */
     issuer?: string;
+    /**
+     * Scopes advertised for this request in discovery metadata. Overrides the
+     * server-wide default, including when set to an empty array.
+     */
+    scopesSupported?: string[];
     /** URL of the authorization endpoint. Defaults to `${issuer}/authorize`. */
     authorizationEndpoint?: string;
     /** URL of the token endpoint. Defaults to `${issuer}/token`. */
@@ -164,7 +169,10 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
     resolve: (request: Request) => AuthorizationServerContext<Client, User, S> | Promise<AuthorizationServerContext<Client, User, S>>;
     /** Grants the server supports, keyed by `grant_type` (each key must equal `grant.grantType`). */
     grants: AuthorizationServerGrants<Client, User, S>;
-    /** Scopes supported by this server (advertised in RFC 8414 metadata). */
+    /**
+     * Default scopes advertised in RFC 8414 metadata when the request context
+     * does not supply scopesSupported.
+     */
     scopesSupported?: string[];
     /**
      * OIDC issuance keys. Configuring this turns the OIDC provider surface on:

package/esm/server/authorization-server.js

@@ -1099,8 +1099,9 @@ export class AuthorizationServer extends ResourceServer {
             metadata.code_challenge_methods_supported = challengeMethods;
         }
         metadata.response_types_supported = hasAuthCodeGrant ? ["code"] : [];
-        if (this.scopesSupported) {
-            metadata.scopes_supported = this.scopesSupported;
+        const scopesSupported = context.scopesSupported ?? this.scopesSupported;
+        if (scopesSupported) {
+            metadata.scopes_supported = scopesSupported;
         }
         if (this.signingKeys) {
             this.#advertiseEndpoints(metadata, endpoints, true);

package/esm/server/grants/authorization-code.d.ts

@@ -50,10 +50,13 @@ export interface AuthorizationCodeGrantOptions<Client extends ClientInterface, U
      * authentication, never a replacement for it, so a confidential client's
      * secret is still required on this grant.
      *
-     * Defaults to `true`: confidential clients authenticate alongside PKCE.
-     * Public clients, which have no secret, are unaffected. Setting `false`
-     * explicitly enables legacy behavior where PKCE replaces client credentials;
-     * use that opt-out only for an integration that requires it.
+     * Defaults to `true`: confidential clients authenticate alongside PKCE, and
+     * a public client authenticates by `client_id` alone — one that attaches a
+     * `client_secret` it was never issued is refused, as on every other grant.
+     * Setting `false` explicitly enables legacy behavior where PKCE replaces
+     * client credentials: a request carrying a `code_verifier` is looked up by
+     * id, so a presented secret is not checked at all. Use that opt-out only for
+     * an integration that requires it.
      *
      * @default true
      * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1#section-4.1.3

package/esm/server/services/client.d.ts

@@ -17,13 +17,17 @@ export interface ClientServiceInterface<Client extends ClientInterface, User> {
      *   always advertises `none` in `token_endpoint_auth_methods_supported`, so
      *   an implementation that demands a secret from every client makes that
      *   advertisement false.
+     * - A **public** client must resolve `undefined` when a non-empty `secret` is
+     *   presented. It was issued no secret, so a request carrying one is
+     *   misconfigured or confused about the client's type, and the server answers
+     *   `invalid_client` rather than silently treating it as public. An empty
+     *   `secret` carries no credential — a Basic header of `client_id:` decodes
+     *   to one — and counts as presenting none, so the client resolves.
      * - A **confidential** client resolves only with its correct `secret`. With
      *   the secret missing or wrong, resolve `undefined`.
      *
      * `runClientServiceContractTests` from `@udibo/oauth2/testing/contract` pins
-     * both rules; run it against your implementation. It does not pin whether a
-     * public client that presents a `secret` resolves, so do not rely on either
-     * answer.
+     * all three rules; run it against your implementation.
      *
      * @param id The presented `client_id` — unauthenticated input.
      * @param secret The presented `client_secret`, omitted when the request

package/esm/testing/contract/client.js

@@ -82,6 +82,17 @@ export function runClientServiceContractTests(options) {
                 const auth = await clientService.getAuthenticated(client.id);
                 assertEquals(auth?.id, client.id);
             });
+            it("returns undefined for a public client that presents a secret", async () => {
+                const client = makeClient(9);
+                await options.addClient(clientService, client);
+                assertStrictEquals(await clientService.getAuthenticated(client.id, "unissued"), undefined);
+            });
+            it("returns the public client when the presented secret is empty", async () => {
+                const client = makeClient(10);
+                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");

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

@@ -39,4 +39,4 @@ 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";

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 {
     /**

package/esm/testing/contract/tenant.js

@@ -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
@@ -931,5 +933,255 @@ export function runTenantContractTests(options) {
                 assertEquals((await linkedOf(stranger.token)).identities.map((entry) => entry.id), [theirs]);
             });
         });
+        describe("client credentials and the resource-grants API", () => {
+            const ORGANIZATIONS_READ = "identity:organizations:read";
+            const DIRECT = "type=contract_document&id=direct";
+            const RANKED = "type=contract_document&id=ranked";
+            let reader;
+            let unassigned;
+            let readerToken;
+            let userinfoEndpoint;
+            async function addConfidentialClient(permissions) {
+                const client = await tenant.addMachineClient({
+                    scopes: [ORGANIZATIONS_READ],
+                    permissions,
+                });
+                assert(client.secret, "a confidential application is issued a secret");
+                return { id: client.id, secret: client.secret };
+            }
+            async function machineToken(client, scope) {
+                const response = await send(metadata.token_endpoint, {
+                    method: "POST",
+                    headers: client.secret === undefined
+                        ? {}
+                        : { authorization: encodeBasicAuth(client.id, client.secret) },
+                    body: new URLSearchParams({
+                        grant_type: "client_credentials",
+                        ...client.secret === undefined ? { client_id: client.id } : {},
+                        ...scope === undefined ? {} : { scope },
+                    }),
+                });
+                const text = await response.text();
+                return {
+                    status: response.status,
+                    headers: response.headers,
+                    body: text ? JSON.parse(text) : null,
+                };
+            }
+            async function issuedTo(client, scope) {
+                const issued = await machineToken(client, scope);
+                assertEquals(issued.status, 200, JSON.stringify(issued.body));
+                assert(issued.body.access_token);
+                return issued.body.access_token;
+            }
+            async function introspectAs(client, accessToken) {
+                const response = await send(metadata.introspection_endpoint, {
+                    method: "POST",
+                    headers: { authorization: encodeBasicAuth(client.id, client.secret) },
+                    body: new URLSearchParams({ token: accessToken }),
+                });
+                assertEquals(response.status, 200);
+                return await response.json();
+            }
+            function grantsOn(accessToken, query) {
+                return call(accessToken, "GET", `/api/resource-grants?${query}`);
+            }
+            beforeAll(async () => {
+                const response = await send(new URL("/.well-known/openid-configuration", tenant.issuer));
+                ({ userinfo_endpoint: userinfoEndpoint } = await response.json());
+                reader = await addConfidentialClient(["resource_grants.read"]);
+                unassigned = await addConfidentialClient([]);
+                readerToken = await issuedTo(reader, ORGANIZATIONS_READ);
+                const ranked = [
+                    ["contract:review", "user", people.member],
+                    ["contract:share", "user", people.outsider],
+                    ["contract:approve", "user", people.leaver],
+                    ["contract:comment", "user", people.solo],
+                    ["contract:audit", "organization", organizations.home],
+                ];
+                for (const [permission, type, id] of ranked) {
+                    await tenant.grant({
+                        resource: { type: "contract_document", id: "ranked" },
+                        subject: { type, id },
+                        permissions: [permission],
+                    });
+                }
+            });
+            it("issues a machine token with no refresh token, naming no person and no organization", async () => {
+                const issued = await machineToken(reader, ORGANIZATIONS_READ);
+                assertEquals(issued.status, 200, JSON.stringify(issued.body));
+                assertEquals(issued.body.token_type, "Bearer");
+                assert(issued.body.access_token);
+                assertFalse("refresh_token" in issued.body, "a machine token has no refresh token");
+                const claims = await introspectAs(reader, issued.body.access_token);
+                assertEquals(claims.active, true);
+                assertEquals(claims.client_id, reader.id);
+                assertEquals(claims.scope, ORGANIZATIONS_READ);
+                assertFalse(claims.sub, "a machine token names no person");
+                assertFalse(claims.username, "a machine token names no person");
+                assertFalse(claims.org_id, "a machine token belongs to no organization");
+                assertEquals(sorted(claims.permissions), []);
+            });
+            it("answers another application introspecting a machine token that it is inactive", async () => {
+                const claims = await introspectAs(unassigned, readerToken);
+                assertEquals(claims, { active: false });
+            });
+            it("refuses the grant to a public application, which has no secret to authenticate with", async () => {
+                const open = await tenant.addMachineClient({
+                    scopes: [ORGANIZATIONS_READ],
+                    permissions: [],
+                    confidential: false,
+                });
+                assertFalse(open.secret, "a public application is issued no secret");
+                const refused = await machineToken(open, ORGANIZATIONS_READ);
+                assertEquals(refused.status, 401, JSON.stringify(refused.body));
+                assertEquals(refused.body.error, "invalid_client");
+                assertFalse(refused.body.access_token);
+            });
+            it("refuses the grant to an application not registered for it, and refuses a machine token an OIDC scope or one outside its allowlist", async () => {
+                const interactive = await machineToken(tenant.client, ORGANIZATIONS_READ);
+                assertEquals(interactive.status, 401);
+                assertEquals(interactive.body.error, "unauthorized_client");
+                for (const scope of [
+                    "openid",
+                    `${ORGANIZATIONS_READ} identity:organizations:write`,
+                ]) {
+                    const refused = await machineToken(reader, scope);
+                    assertEquals(refused.status, 400, scope);
+                    assertEquals(refused.body.error, "invalid_scope", scope);
+                }
+            });
+            it("accepts organization_id on the refresh_token grant alone", async () => {
+                const response = await send(metadata.token_endpoint, {
+                    method: "POST",
+                    headers: { authorization: encodeBasicAuth(reader.id, reader.secret) },
+                    body: new URLSearchParams({
+                        grant_type: "client_credentials",
+                        scope: ORGANIZATIONS_READ,
+                        organization_id: organizations.home,
+                    }),
+                });
+                const body = await response.json();
+                assertEquals(response.status, 400, JSON.stringify(body));
+                assertEquals(body.error, "invalid_request");
+            });
+            it("refuses a machine token wherever the tenant answers for a person", async () => {
+                const checked = await ask(readerToken, "/api/check", {
+                    permissions: ["contract:tenant"],
+                });
+                assertEquals(checked.status, 403);
+                assertEquals(checked.body.reason, "machine_token");
+                const batch = await ask(readerToken, "/api/check/batch", {
+                    permissions: ["contract:read"],
+                    resource: { type: "contract_document", ids: ["direct"] },
+                });
+                assertEquals(batch.status, 403);
+                assertEquals(batch.body.reason, "machine_token");
+                for (const path of ["/api/memberships", "/api/account"]) {
+                    const reply = await call(readerToken, "GET", path);
+                    assertEquals(reply.status, 403, path);
+                    assertEquals(reply.body.reason, "machine_token", path);
+                }
+                const organizations = await call(readerToken, "GET", "/api/organizations");
+                assertEquals(organizations.status, 403);
+                const userinfo = await send(userinfoEndpoint, {
+                    headers: { authorization: `Bearer ${readerToken}` },
+                });
+                await userinfo.body?.cancel();
+                assertEquals(userinfo.status, 401);
+            });
+            it("lists who holds a grant on a resource, roles named, and an empty list where nobody does", async () => {
+                const direct = await grantsOn(readerToken, DIRECT);
+                assertEquals(direct.status, 200, JSON.stringify(direct.body));
+                assertStringIncludes(direct.headers.get("cache-control") ?? "", "no-store");
+                assertEquals(direct.body.resource, {
+                    type: "contract_document",
+                    id: "direct",
+                });
+                assertEquals(direct.body.grants.length, 1);
+                const [held] = direct.body.grants;
+                assertEquals(Object.keys(held).sort(), [
+                    "builtInRole",
+                    "id",
+                    "roleId",
+                    "roleName",
+                    "roleSlug",
+                    "subjectActive",
+                    "subjectId",
+                    "subjectName",
+                    "subjectRole",
+                    "subjectType",
+                ]);
+                assertEquals(held.subjectType, "user");
+                assertEquals(held.subjectId, people.outsider);
+                assertEquals(held.subjectRole, null);
+                assertEquals(held.subjectActive, true);
+                assert(held.subjectName, "a grant names its holder");
+                assert(held.id, "a grant has an id");
+                assert(held.roleId, "a grant names its role");
+                assert(held.roleSlug, "a grant names its role's slug");
+                assert(held.roleName, "a grant names its role's name");
+                assertEquals(held.builtInRole, null);
+                const shared = await grantsOn(readerToken, "type=contract_document&id=shared");
+                assertEquals(shared.status, 200);
+                assertEquals(shared.body.grants.map((grant) => [grant.subjectType, grant.subjectId]), [["organization", organizations.home]]);
+                const nobody = await grantsOn(readerToken, `type=contract_document&id=nobody-${crypto.randomUUID()}`);
+                assertEquals(nobody.status, 200);
+                assertEquals(nobody.body.grants, []);
+            });
+            it("lists the grants on one resource in role-name order", async () => {
+                const ranked = await grantsOn(readerToken, RANKED);
+                assertEquals(ranked.status, 200, JSON.stringify(ranked.body));
+                assertEquals(ranked.body.grants.map((grant) => grant.subjectId).sort(), [
+                    people.member,
+                    people.outsider,
+                    people.leaver,
+                    people.solo,
+                    organizations.home,
+                ].sort());
+                const names = ranked.body.grants.map((grant) => grant.roleName);
+                assertEquals(new Set(names).size, names.length, "each grant confers a role of its own");
+                assertEquals(names, [...names].sort((a, b) => a.localeCompare(b)));
+            });
+            it("hides the listing from a machine token without the permission or the scope, and refuses a person's token and no token", async () => {
+                const withoutPermission = await issuedTo(unassigned, ORGANIZATIONS_READ);
+                assertEquals((await grantsOn(withoutPermission, DIRECT)).status, 404);
+                const withoutScope = await issuedTo(reader);
+                assertEquals((await grantsOn(withoutScope, DIRECT)).status, 404);
+                const { access_token } = await tenant.signIn(people.member);
+                const person = await call(access_token, "GET", `/api/resource-grants?${DIRECT}`);
+                assertEquals(person.status, 403);
+                assertEquals(person.body.reason, "user_token");
+                assertEquals((await grantsOn(null, DIRECT)).status, 401);
+            });
+            function refusedFields(reply) {
+                assertEquals(reply.status, 400, JSON.stringify(reply.body));
+                const { fieldErrors } = reply.body;
+                return Object.keys(fieldErrors ?? {});
+            }
+            it("refuses a resource type the tenant has not registered, and a resource missing its id", async () => {
+                const unregistered = await grantsOn(readerToken, "type=contract_unregistered&id=direct");
+                assertEquals(refusedFields(unregistered), ["type"]);
+                const missing = await grantsOn(readerToken, "type=contract_document");
+                assertEquals(refusedFields(missing), ["resource"]);
+            });
+            it("bounds the type to 64 characters and the id to 255, refusing ASCII control characters and no other", async () => {
+                const long = await grantsOn(readerToken, `type=${"t".repeat(65)}&id=direct`);
+                assertEquals(refusedFields(long), ["resource"]);
+                const longest = await grantsOn(readerToken, `type=${"t".repeat(64)}&id=direct`);
+                assertEquals(refusedFields(longest), ["type"]);
+                const query = (id) => `type=contract_document&id=${encodeURIComponent(id)}`;
+                const wide = await grantsOn(readerToken, query("i".repeat(256)));
+                assertEquals(refusedFields(wide), ["resource"]);
+                const widest = await grantsOn(readerToken, query("i".repeat(255)));
+                assertEquals(widest.status, 200, JSON.stringify(widest.body));
+                assertEquals(widest.body.grants, []);
+                const control = await grantsOn(readerToken, query("tab\there"));
+                assertEquals(refusedFields(control), ["resource"]);
+                const unicode = await grantsOn(readerToken, query("next\u0085line"));
+                assertEquals(unicode.status, 200, JSON.stringify(unicode.body));
+                assertEquals(unicode.body.grants, []);
+            });
+        });
     });
 }

package/esm/testing/mod.d.ts

@@ -27,11 +27,13 @@
  *   prototypes — never for production.
  *
  * - **A fake Udibo Identity tenant.** {@link createFakeTenant} answers a tenant's
- *   protocol surface, its `/api/check` questions, and its organization and
- *   account APIs 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 Identity tenant can test its own routes without
- *   running the identity service.
+ *   protocol surface, its `/api/check` questions, its organization and
+ *   account APIs, and — to the app's own machine credential — the
+ *   `client_credentials` grant and the resource-grants read, 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
+ *   Identity 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.
@@ -41,4 +43,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 FakeTenantLinkedAccount, type FakeTenantMembership, type FakeTenantOptions, type FakeTenantOrganization, type FakeTenantOrganizationRole, type FakeTenantSignIn, type FakeTenantSubject, type FakeTenantTokenRequest, type FakeTenantUser, } from "./tenant.js";
+export { createFakeTenant, type FakeTenant, type FakeTenantClient, type FakeTenantGrant, type FakeTenantLinkedAccount, type FakeTenantMachinePermission, type FakeTenantMembership, type FakeTenantOptions, type FakeTenantOrganization, type FakeTenantOrganizationRole, type FakeTenantSignIn, type FakeTenantSubject, type FakeTenantTokenRequest, type FakeTenantUser, } from "./tenant.js";

package/esm/testing/mod.js

@@ -27,11 +27,13 @@
  *   prototypes — never for production.
  *
  * - **A fake Udibo Identity tenant.** {@link createFakeTenant} answers a tenant's
- *   protocol surface, its `/api/check` questions, and its organization and
- *   account APIs 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 Identity tenant can test its own routes without
- *   running the identity service.
+ *   protocol surface, its `/api/check` questions, its organization and
+ *   account APIs, and — to the app's own machine credential — the
+ *   `client_credentials` grant and the resource-grants read, 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
+ *   Identity 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.

package/esm/testing/services.d.ts

@@ -99,7 +99,7 @@ export declare class MemoryUserService<U extends MemoryUserShape> implements Use
  * A client is treated as confidential when {@link add} is called with a
  * secret, and public when it is not — there is no separate flag to
  * remember. `getAuthenticated` requires the secret for confidential
- * clients and accepts a missing secret for public clients.
+ * clients, and requires public clients to present none.
  */
 export declare class MemoryClientService<C extends ClientInterface, U> implements ClientServiceInterface<C, U> {
     #private;
@@ -122,7 +122,9 @@ export declare class MemoryClientService<C extends ClientInterface, U> implement
     /**
      * Resolves the client when authentication succeeds, otherwise `undefined`.
      * Confidential clients (registered with a secret) require a matching
-     * `secret`; public clients (registered without one) ignore it.
+     * `secret`; public clients (registered without one) must present none, so a
+     * secret they were never issued fails authentication rather than being
+     * ignored. An empty `secret` counts as none.
      */
     getAuthenticated(id: string, secret?: string): Promise<C | undefined>;
     /**

package/esm/testing/services.js

@@ -109,7 +109,7 @@ export class MemoryUserService {
  * A client is treated as confidential when {@link add} is called with a
  * secret, and public when it is not — there is no separate flag to
  * remember. `getAuthenticated` requires the secret for confidential
- * clients and accepts a missing secret for public clients.
+ * clients, and requires public clients to present none.
  */
 export class MemoryClientService {
     #clientsById = new Map();
@@ -150,19 +150,21 @@ export class MemoryClientService {
     /**
      * Resolves the client when authentication succeeds, otherwise `undefined`.
      * Confidential clients (registered with a secret) require a matching
-     * `secret`; public clients (registered without one) ignore it.
+     * `secret`; public clients (registered without one) must present none, so a
+     * secret they were never issued fails authentication rather than being
+     * ignored. An empty `secret` counts as none.
      */
     async getAuthenticated(id, secret) {
         const client = this.#clientsById.get(id);
         if (!client)
             return undefined;
         const storedHash = this.#secretHashByClientId.get(id);
-        if (storedHash) {
-            if (!secret)
-                return undefined;
-            if (await sha256Hash(secret) !== storedHash)
-                return undefined;
-        }
+        if (!storedHash)
+            return secret ? undefined : client;
+        if (!secret)
+            return undefined;
+        if (await sha256Hash(secret) !== storedHash)
+            return undefined;
         return client;
     }
     /**

package/esm/testing/tenant.d.ts

@@ -35,10 +35,45 @@ export interface FakeTenantUser {
      */
     hasPassword?: boolean;
 }
-/** An OAuth2 application registered in a {@linkcode FakeTenant}. */
+/**
+ * A management permission a tenant administrator assigns a machine
+ * application, apart from any permission a role carries. A real tenant also
+ * knows `resource_grants.write`; the fake answers only the read it serves.
+ */
+export type FakeTenantMachinePermission = "resource_grants.read";
+/**
+ * An OAuth2 application registered in a {@linkcode FakeTenant}. Its `grants`
+ * default to `authorization_code` and `refresh_token`; name
+ * `client_credentials` for a machine application, whose token from that grant
+ * is the application's own and names no person.
+ */
 export interface FakeTenantClient extends ClientInterface {
-    /** Omit for a public client. */
+    /**
+     * Omit for a public client. Only a confidential client may use the
+     * `client_credentials` grant (RFC 6749 §4.4), since a public client has no
+     * credential to authenticate with (§2.1): a public client asking for it is
+     * refused `invalid_client`. Only a confidential client may introspect, and
+     * only the tokens issued to it; any other introspection answers
+     * `active: false`.
+     */
     secret?: string;
+    /**
+     * The scopes a `client_credentials` token may carry, as an administrator
+     * allowlists them on a real tenant. An application allowed that grant has
+     * to state it, as a tenant refuses to register one that does not;
+     * {@linkcode FakeTenant.addClient} throws. The fake's machine vocabulary is
+     * `identity:organizations:read` and `identity:organizations:write`, so a
+     * token asking for any other scope, allowlisted or not, an OIDC scope
+     * included, is refused with `invalid_scope`. Ignored on every other grant.
+     */
+    scopes?: string[];
+    /**
+     * The permissions a tenant administrator assigned this machine application.
+     * `GET /api/resource-grants` answers only a `client_credentials` token of an
+     * application holding `resource_grants.read`, and hides itself with a 404
+     * from every other. Defaults to none.
+     */
+    machinePermissions?: FakeTenantMachinePermission[];
     /**
      * `"jwt"` issues RFC 9068 access tokens signed with the tenant's JWKS key,
      * for a resource server that validates locally. Defaults to `"opaque"`.
@@ -97,6 +132,16 @@ export interface FakeTenantGrant {
     subject: FakeTenantSubject;
     /** What the subject may do on that one resource. */
     permissions: string[];
+    /**
+     * The slug of the role the grant confers, as `GET /api/resource-grants`
+     * reports it: `roleSlug`, with the name {@linkcode FakeTenant.defineOrganizationRole}
+     * gave it as `roleName`, or the slug again. Defaults to a slug built from
+     * `permissions`. A built-in tier (`owner`, `admin`, `member`) is listed as
+     * `builtInRole` with no `roleId`, the way a grant an administrator placed
+     * is. It changes only how the grant is listed; what it confers stays
+     * `permissions`.
+     */
+    role?: string;
 }
 /** An organization role your tenant defines beside the built-in tiers. */
 export interface FakeTenantOrganizationRole {
@@ -161,7 +206,10 @@ export interface FakeTenantOptions {
  * caller's own `GET /api/memberships`, the two authorization questions,
  * `POST /api/check` and `POST /api/check/batch`, the organization API under
  * `/api/organizations`, and the account API under `/api/account`, with the
- * same shapes and refusals a real tenant uses.
+ * same shapes and refusals a real tenant uses. To the app itself it answers
+ * the `client_credentials` grant, for a client registered with it, and
+ * `GET /api/resource-grants` under that machine token, which lists who holds a
+ * grant on one resource once the client holds `resource_grants.read`.
  *
  * Nothing here is interactive: {@linkcode signInAs} decides who the next
  * authorization request authenticates, and there is no consent step. Serve
@@ -200,7 +248,10 @@ export interface FakeTenant {
     defineOrganizationRole(role: FakeTenantOrganizationRole): void;
     /** Registers a resource type, so `/api/check` accepts it. */
     registerResourceType(type: string): void;
-    /** Adds a resource grant. */
+    /**
+     * Adds a resource grant, which `/api/check` answers from and
+     * `GET /api/resource-grants` lists.
+     */
     grant(grant: FakeTenantGrant): void;
     /**
      * Links an external account to a person, as the account API lists it, and

package/esm/testing/tenant.js

@@ -1,9 +1,10 @@
 import { AuthorizationCodeGrant } from "../server/grants/authorization-code.js";
+import { ClientCredentialsGrant, } from "../server/grants/client-credentials.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 { AccessDeniedError, InvalidClientError, InvalidRequestError, } from "../errors.js";
 import { safeReturnTo } from "../utils/url.js";
 import { MemoryAuthorizationCodeService, MemoryClientService, MemoryTokenService, MemoryUserService, } from "./services.js";
 const PATHS = {
@@ -30,10 +31,56 @@ const BUILT_IN_ROLES = [
     { slug: "admin", name: "Admin" },
     { slug: "member", name: "Member" },
 ];
+const ORGANIZATIONS_READ = "identity:organizations:read";
+const MACHINE_SCOPES = [
+    ORGANIZATIONS_READ,
+    "identity:organizations:write",
+];
+const OIDC_SCOPES = ["openid", "profile", "email"];
+const RESOURCE_GRANTS_READ = "resource_grants.read";
+const RESOURCE_TYPE_MAX_LENGTH = 64;
+const RESOURCE_ID_MAX_LENGTH = 255;
+// deno-lint-ignore no-control-regex
+const ASCII_CONTROL_CHARACTERS = /[\x00-\x1f\x7f]/;
+const UNSTATED_ALLOWLIST = "A client_credentials application has to state the scopes its tokens may " +
+    "be granted: pass `scopes`, an empty list to deny every scope.";
+const ORGANIZATION_ID_REFUSAL = "organization_id is only accepted on the refresh_token grant";
+const USER_TOKEN_REFUSAL = "Resource grants are placed and read by your application, not by the person " +
+    "using it. Call this with your application's own client credentials after " +
+    "deciding, in your own logic, that the share is allowed.";
+const MACHINE_TOKEN_REFUSAL = "A machine credential has no self to answer for.";
 const OWNER = "owner";
 const MANAGER_ROLES = ["owner", "admin"];
 const DEFAULT_ROLES = ["member"];
 const ORGANIZATION_NOT_FOUND = "Organization not found";
+class ConfidentialClientCredentialsGrant extends ClientCredentialsGrant {
+    isConfidential;
+    constructor(options, isConfidential) {
+        super(options);
+        this.isConfidential = isConfidential;
+    }
+    async getAuthenticatedClient(request, body) {
+        const client = await super.getAuthenticatedClient(request, body);
+        if (!this.isConfidential(client)) {
+            throw new InvalidClientError("client authentication failed");
+        }
+        return client;
+    }
+}
+function machineScopeCeiling(client) {
+    return client.scopes?.filter((scope) => MACHINE_SCOPES.includes(scope)) ??
+        [];
+}
+function isBuiltInRole(slug) {
+    return BUILT_IN_ROLES.some((role) => role.slug === slug);
+}
+function roleSlugOf(permissions) {
+    const slug = permissions
+        .map((permission) => permission.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""))
+        .filter(Boolean)
+        .join("-");
+    return slug || "grant";
+}
 class TenantTokenService extends MemoryTokenService {
     issuanceOf;
     recordCredential;
@@ -44,9 +91,19 @@ class TenantTokenService extends MemoryTokenService {
         this.recordCredential = recordCredential;
         this.mintJwt = mintJwt;
     }
+    acceptedScope(client, user, scope) {
+        if (!scope || user)
+            return Promise.resolve(scope);
+        const requested = [...scope];
+        if (requested.some((name) => OIDC_SCOPES.includes(name))) {
+            return Promise.resolve(false);
+        }
+        const ceiling = machineScopeCeiling(client);
+        return Promise.resolve(requested.every((name) => ceiling.includes(name)) ? scope : false);
+    }
     async generateAccessToken(client, user, scope) {
         const issuance = (user ? this.issuanceOf(user.id) : undefined) ?? {};
-        const accessToken = client.accessTokenFormat === "jwt" && user
+        const accessToken = client.accessTokenFormat === "jwt"
             ? await this.mintJwt(client, user, scope, issuance.organizationId)
             : await super.generateAccessToken(client, user, scope);
         this.recordCredential(accessToken, issuance, client);
@@ -220,6 +277,7 @@ export async function createFakeTenant(options) {
     const invitations = new Map();
     const resourceTypes = new Set();
     const grants = [];
+    const resourceRoleIds = new Map();
     const loginSessions = new Map();
     const linkedAccounts = new Map();
     const credentials = new Map();
@@ -257,6 +315,8 @@ export async function createFakeTenant(options) {
         };
     };
     const userService = new MemoryUserService();
+    const confidentialClients = new Set();
+    const isConfidential = (client) => confidentialClients.has(client.id);
     const clientService = new MemoryClientService(userService);
     const tokenService = new TenantTokenService({ clientService, userService }, (userId) => pendingIssuance.get(userId), (accessToken, issuance, client) => credentials.set(accessToken, {
         ...issuance,
@@ -267,10 +327,12 @@ export async function createFakeTenant(options) {
         signingKeys,
         issuer,
         audience: client.audience ?? client.id,
-        userClaims: () => ({
-            username: user.username,
-            ...authorizationClaims(user.id, organizationId),
-        }),
+        userClaims: user
+            ? () => ({
+                username: user.username,
+                ...authorizationClaims(user.id, organizationId),
+            })
+            : undefined,
     })(client, user, scope));
     const authorizationCodeService = new MemoryAuthorizationCodeService({ clientService, userService });
     const server = new AuthorizationServer({
@@ -296,9 +358,16 @@ export async function createFakeTenant(options) {
             refresh_token: new RefreshTokenGrant({
                 resolve: () => ({ clientService, tokenService }),
             }),
+            client_credentials: new ConfidentialClientCredentialsGrant({ resolve: () => ({ clientService, tokenService }) }, isConfidential),
         },
         signingKeys,
-        scopesSupported: ["openid", "profile", "email", "offline_access"],
+        scopesSupported: [
+            "openid",
+            "profile",
+            "email",
+            "offline_access",
+            ...MACHINE_SCOPES,
+        ],
         userClaims: (user) => ({
             preferred_username: user.username,
             name: user.name,
@@ -306,10 +375,12 @@ export async function createFakeTenant(options) {
             email_verified: user.email ? user.emailVerified ?? true : undefined,
             ...organizationClaims(user.id, signedIn?.userId === user.id ? signedIn.organizationId : undefined),
         }),
+        canIntrospectToken: (client, token) => isConfidential(client) && client.id === token.client.id,
         introspectionClaims: (token) => token.user
             ? authorizationClaims(token.user.id, credentials.get(token.accessToken)?.organizationId)
             : {},
     });
+    const isMachineToken = (token) => !token.user;
     const withIssuance = async (userId, issuance, work) => {
         if (!userId)
             return await work();
@@ -337,7 +408,7 @@ export async function createFakeTenant(options) {
             return server.handleAuthError(error);
         }
         if (!token.user) {
-            return problem(403, "A machine credential has no self to answer for.", machineRefusal);
+            return problem(403, MACHINE_TOKEN_REFUSAL, machineRefusal);
         }
         const user = users.get(token.user.id) ?? token.user;
         const organizationId = credentials.get(token.accessToken)?.organizationId;
@@ -363,8 +434,9 @@ export async function createFakeTenant(options) {
         return held;
     };
     const answer = (asked, held) => Object.fromEntries(asked.map((p) => [p, held.has(p)]));
+    const personOnly = { reason: "machine_token" };
     const check = async (request) => {
-        const caller = await authenticated(request);
+        const caller = await authenticated(request, personOnly);
         if (caller instanceof Response)
             return caller;
         const body = await request.json().catch(() => null);
@@ -404,7 +476,7 @@ export async function createFakeTenant(options) {
         });
     };
     const checkBatch = async (request) => {
-        const caller = await authenticated(request);
+        const caller = await authenticated(request, personOnly);
         if (caller instanceof Response)
             return caller;
         const body = await request.json().catch(() => null);
@@ -445,7 +517,7 @@ export async function createFakeTenant(options) {
         return organization.id;
     };
     const memberships = async (request) => {
-        const caller = await authenticated(request);
+        const caller = await authenticated(request, personOnly);
         if (caller instanceof Response)
             return caller;
         return Response.json({
@@ -540,6 +612,17 @@ export async function createFakeTenant(options) {
     };
     const token = async (request) => {
         const form = await request.clone().formData().catch(() => null);
+        const organizationId = form?.get("organization_id");
+        if (typeof organizationId === "string" && organizationId.length > 0 &&
+            form?.get("grant_type") !== "refresh_token") {
+            return Response.json({
+                error: "invalid_request",
+                error_description: ORGANIZATION_ID_REFUSAL,
+            }, {
+                status: 400,
+                headers: { "cache-control": "no-store", pragma: "no-cache" },
+            });
+        }
         const code = form?.get("code");
         const refreshToken = form?.get("refresh_token");
         const signIn = typeof code === "string"
@@ -1001,11 +1084,23 @@ export async function createFakeTenant(options) {
         });
     });
     const accountApi = (handler) => async (request, params) => {
-        const caller = await authenticated(request, { reason: "machine_token" });
+        const caller = await authenticated(request, personOnly);
         if (caller instanceof Response)
             return noStore(caller);
         return noStore(await handler(caller, request, params));
     };
+    const userinfo = async (request) => {
+        try {
+            const { token } = await server.authenticate(request);
+            if (isMachineToken(token)) {
+                throw new AccessDeniedError("client credentials have no end user");
+            }
+        }
+        catch (error) {
+            return server.handleAuthError(error);
+        }
+        return await server.handleUserInfoRequest(request);
+    };
     const readAccount = accountApi((caller) => Response.json({
         userMetadata: userMetadata.get(caller.user.id) ?? {},
     }));
@@ -1109,6 +1204,70 @@ export async function createFakeTenant(options) {
         linkedAccounts.delete(account.id);
         return new Response(null, { status: 204 });
     });
+    const machineCaller = async (request) => {
+        let token;
+        try {
+            ({ token } = await server.authenticate(request));
+        }
+        catch (error) {
+            return server.handleAuthError(error);
+        }
+        if (!isMachineToken(token)) {
+            return problem(403, USER_TOKEN_REFUSAL, { reason: "user_token" });
+        }
+        return {
+            client: token.client,
+            scopes: token.scope ? [...token.scope] : [],
+        };
+    };
+    const resourceGrantJson = (grant) => {
+        const holder = grant.subject.type === "user"
+            ? users.get(grant.subject.id)
+            : undefined;
+        const organization = grant.subject.type === "organization"
+            ? organizations.get(grant.subject.id)
+            : undefined;
+        return {
+            id: grant.id,
+            subjectType: grant.subject.type,
+            subjectId: grant.subject.id,
+            subjectRole: null,
+            subjectName: holder
+                ? holder.name ?? holder.username
+                : organization?.name ?? null,
+            subjectActive: holder !== undefined || organization !== undefined,
+            roleId: grant.roleId,
+            builtInRole: isBuiltInRole(grant.role) ? grant.role : null,
+            roleSlug: grant.role,
+            roleName: roleName(grant.role),
+        };
+    };
+    const listResourceGrants = async (request) => {
+        const caller = await machineCaller(request);
+        if (caller instanceof Response)
+            return noStore(caller);
+        if (!caller.scopes.includes(ORGANIZATIONS_READ) ||
+            !caller.client.machinePermissions?.includes(RESOURCE_GRANTS_READ)) {
+            return noStore(problem(404, "Not found"));
+        }
+        const params = new URL(request.url).searchParams;
+        const type = params.get("type");
+        const id = params.get("id");
+        if (!type || type.length > RESOURCE_TYPE_MAX_LENGTH || !id ||
+            id.length > RESOURCE_ID_MAX_LENGTH || ASCII_CONTROL_CHARACTERS.test(id)) {
+            return noStore(invalid("resource", "Pass the resource as `type` and `id` query parameters."));
+        }
+        if (!resourceTypes.has(type)) {
+            return noStore(invalid("type", `No resource type "${type}" is registered for this tenant.`));
+        }
+        return noStore(Response.json({
+            resource: { type, id },
+            grants: grants
+                .filter((grant) => grant.resource.type === type && grant.resource.id === id)
+                .map(resourceGrantJson)
+                .sort((a, b) => a.roleName.localeCompare(b.roleName)),
+        }));
+    };
     const routes = {
         "GET /.well-known/oauth-authorization-server": (r) => server.handleMetadataRequest(r),
         "GET /.well-known/openid-configuration": (r) => server.handleOidcMetadataRequest(r),
@@ -1116,12 +1275,13 @@ export async function createFakeTenant(options) {
         [`POST ${PATHS.token}`]: token,
         [`POST ${PATHS.revocation}`]: revocation,
         [`POST ${PATHS.introspection}`]: (r) => server.handleIntrospectionRequest(r),
-        [`GET ${PATHS.userinfo}`]: (r) => server.handleUserInfoRequest(r),
-        [`POST ${PATHS.userinfo}`]: (r) => server.handleUserInfoRequest(r),
+        [`GET ${PATHS.userinfo}`]: userinfo,
+        [`POST ${PATHS.userinfo}`]: userinfo,
         [`GET ${PATHS.jwks}`]: (r) => server.handleJwksRequest(r),
         "GET /api/memberships": memberships,
         "POST /api/check": check,
         "POST /api/check/batch": checkBatch,
+        "GET /api/resource-grants": listResourceGrants,
     };
     const segment = "([^/]+)";
     const patterns = [
@@ -1218,10 +1378,17 @@ export async function createFakeTenant(options) {
         issuer,
         fetch: (request) => route(request) ?? Promise.resolve(problem(404, "Not found")),
         addClient: async ({ secret, ...client }) => {
-            await clientService.add({
+            const registered = {
                 grants: ["authorization_code", "refresh_token"],
                 ...client,
-            }, secret);
+            };
+            if (registered.grants?.includes("client_credentials") &&
+                registered.scopes === undefined) {
+                throw new Error(UNSTATED_ALLOWLIST);
+            }
+            await clientService.add(registered, secret);
+            if (secret)
+                confidentialClients.add(registered.id);
             for (const uri of client.redirectUris ?? []) {
                 try {
                     redirectOrigins.add(new URL(uri).origin);
@@ -1285,7 +1452,13 @@ export async function createFakeTenant(options) {
             resourceTypes.add(type);
         },
         grant: (grant) => {
-            grants.push(grant);
+            const role = grant.role ?? roleSlugOf(grant.permissions);
+            let roleId = isBuiltInRole(role) ? null : resourceRoleIds.get(role);
+            if (roleId === undefined) {
+                roleId = crypto.randomUUID();
+                resourceRoleIds.set(role, roleId);
+            }
+            grants.push({ ...grant, id: crypto.randomUUID(), role, roleId });
         },
         linkAccount: (userId, account) => {
             if (!users.has(userId)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.9.1",
+  "version": "0.10.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",