@udibo/oauth2 0.9.2 → 0.11.0

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