@nacre.work/api 0.5.8 → 0.7.0

package/dist/server.js

@@ -4,7 +4,7 @@ import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 // DOM, so the global URL is not typed here.
 import { URL } from 'node:url';
 import { logger, MetadataError, MultipartError, multipartBoundary, parseMultipart, queryAudit, parseFilters, parseMetadata, PROTECTED_RESOURCE_PATH, JWKS_PATH, AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, CODE_TTL_MS, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, consentRedirect, generateClientId, generateCode, redirectAllowed, verifierMatches, ADMIN_PREFIX, adminRoutes, withAuditSinks, TooBusy, } from '@nacre.work/core';
-import { authenticate, rejectTenantOverride } from './auth.js';
+import { administers, administersTenants, authenticate, rejectTenantOverride, } from './auth.js';
 import { badRequest, internal, notFound, Problem } from './errors.js';
 import { isConflict, isReplay } from './idempotency.js';
 import { limitHeaders } from './limits.js';
@@ -793,15 +793,17 @@ async function handle(req, res, options) {
     // ─────────────────────── the authorization server ───────────────────────
     //
     // Three endpoints, and one decision running through all of them: the token
-    // this flow issues acts as a **service account**, never as the person who
-    // signed in. A consent screen that hands an agent your authority collapses
-    // "what may this agent read" into "what may you read", which is the
+    // this flow issues acts as whatever the *person* chose at consent — as them,
+    // or as an agent. Both are offered because they are different acts. A
+    // delegation reaches exactly what its person reaches and is recomputed every
+    // request; an agent is a principal with its own grants, and collapsing "what
+    // may this agent read" into "what may you read" would throw away the
     // distinction this whole product is built on.
     //
     // Unauthenticated by necessity — a client arrives here with no credential,
     // which is what it came to get. Authority is created at exactly one point:
     // `POST /v1/oauth/consent`, which is inside the authenticated surface and is
-    // where a signed-in person picks the agent.
+    // where a signed-in person makes that choice.
     if (options.oauth !== undefined && (instance === REGISTER_PATH || instance === AUTHORIZE_PATH || instance === TOKEN_PATH)) {
         const oauth = options.oauth;
         // RFC 7591. Open, which is what an MCP client expects and what the RFC is
@@ -1959,7 +1961,7 @@ async function handle(req, res, options) {
             // about what a caller can tell apart — it is that a member must not
             // reach module code at all, and "the module happened to have no matching
             // route" is not a reason to be safe.
-            if (auth.role !== 'platform_admin' && auth.role !== 'org_admin') {
+            if (!administersTenants(auth) && !administers(auth)) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
@@ -2154,7 +2156,7 @@ async function handle(req, res, options) {
             // build; it is for the multi-tenancy module, which inherits this endpoint
             // and where a platform administrator spans tenants. Writing the rule now
             // costs three lines. Retrofitting it later means auditing every caller.
-            if (auth.role !== 'org_admin' && auth.role !== 'platform_admin') {
+            if (!administers(auth) && !administersTenants(auth)) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
@@ -2187,7 +2189,7 @@ async function handle(req, res, options) {
             // `administrativeOnly` is set here and never read from the request. A
             // caller cannot widen their own view by omitting a parameter, which is
             // the shape this would take if it were a query filter.
-            { ...query, administrativeOnly: auth.role === 'platform_admin' }, page);
+            { ...query, administrativeOnly: administersTenants(auth) }, page);
             // Reading the log is itself an access worth recording. It is the one
             // action where leaving it out is self-serving: an administrator who can
             // read who-read-what without that read appearing is a hole in exactly the
@@ -2270,9 +2272,16 @@ async function handle(req, res, options) {
                     id: c.id,
                     client_id: c.clientId,
                     client_name: c.clientName,
-                    service_account_id: c.serviceAccountId,
+                    // What it acts as, named rather than inferred from which of the
+                    // two id fields came back — the screen has to tell a person "this
+                    // application acts as you" from "this application acts as an
+                    // agent", and those are different sentences.
+                    acts_as: c.subject.actsAs,
+                    service_account_id: c.subject.actsAs === 'service_account' ? c.subject.serviceAccountId : null,
                     service_account_name: c.serviceAccountName,
                     approved_by: c.approvedBy,
+                    // Empty means the delegation reaches everything its approver does.
+                    layers: c.layers,
                     created_at: c.createdAt,
                     last_refreshed_at: c.lastRefreshedAt,
                     revoked_at: c.revokedAt,
@@ -2331,8 +2340,66 @@ async function handle(req, res, options) {
             const redirectUri = need('redirect_uri');
             const codeChallenge = need('code_challenge');
             const serviceAccountId = need('service_account_id');
-            if (clientId === undefined || redirectUri === undefined || codeChallenge === undefined || serviceAccountId === undefined) {
-                const problem = badRequest(instance, requestId, "'client_id', 'redirect_uri', 'code_challenge' and 'service_account_id' are required.");
+            if (clientId === undefined || redirectUri === undefined || codeChallenge === undefined) {
+                const problem = badRequest(instance, requestId, "'client_id', 'redirect_uri' and 'code_challenge' are required.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // Naming an agent is what makes this the agent flow; naming nobody is a
+            // delegation. Not a mode flag beside the field, because two ways to say
+            // one thing is two ways for them to disagree — and this endpoint used to
+            // *require* the agent, which is exactly why a member reached a screen
+            // they could not complete.
+            const delegating = serviceAccountId === undefined;
+            // Never delegable. It spans tenants in the multi-tenancy module, so a
+            // delegation of it would be an escalation out of the organization this
+            // screen is scoped to — the same argument that already refuses minting
+            // one from an org-scoped endpoint. Refused here *and* again at
+            // validation: this is the reachable path, the other is the one that holds
+            // if a token is ever minted some other way.
+            if (delegating && administersTenants(auth)) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // The narrowing, which can only ever remove. Ids rather than slugs: this
+            // is stored and read on the authentication path, and a slug is renameable
+            // — a narrowing that follows a rename is one that silently changes what a
+            // person approved.
+            const narrowing = consent['layers'];
+            if (narrowing !== undefined && !isStringArray(narrowing)) {
+                const problem = badRequest(instance, requestId, "'layers' must be an array of layer ids.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // The permission ceiling, which is the dimension a person reaches for
+            // first. Validated here rather than left to the database, so a typo is a
+            // 400 naming the field instead of a constraint violation as a 500.
+            const ceiling = consent['permissions'];
+            if (ceiling !== undefined && (!isStringArray(ceiling) || ceiling.some((p) => !PERMISSIONS.includes(p)))) {
+                const problem = badRequest(instance, requestId, "'permissions' must be an array of 'read', 'write' or 'admin'.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (delegating && isStringArray(ceiling) && ceiling.length === 0) {
+                // Empty is not "no ceiling", it is a delegation that can do nothing —
+                // a restriction nobody meant to write, and the database refuses one
+                // too. Omitting the field is how a caller says there is no ceiling.
+                const problem = badRequest(instance, requestId, "'permissions' cannot be empty. Omit it for a delegation with no restriction.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (!delegating && ceiling !== undefined) {
+                // An agent's reach is its grants, which are an administrator's to set.
+                const problem = badRequest(instance, requestId, "'permissions' restricts a delegation, and this consent names an agent.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (!delegating && narrowing !== undefined && narrowing.length > 0) {
+                // An agent's reach is its grants, and those are an administrator's to
+                // set. Accepting a narrowing here and storing it against a connection
+                // nothing reads it for would be a control that does nothing.
+                const problem = badRequest(instance, requestId, "'layers' narrows a delegation, and this consent names an agent.");
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
@@ -2351,23 +2418,45 @@ async function handle(req, res, options) {
             // consent theirs to give. `404` for anything else, because an agent they
             // cannot see and one that does not exist are the same answer here as
             // everywhere.
-            const visible = options.serviceAccounts === undefined
-                ? undefined
-                : (await options.serviceAccounts.list(auth, { limit: 200, after: undefined })).items.find((a) => a.id === serviceAccountId);
-            if (visible === undefined) {
-                const problem = notFound(instance, requestId);
-                send(res, problem.status, problem.toJSON(), requestId);
-                return;
+            if (!delegating) {
+                const visible = options.serviceAccounts === undefined
+                    ? undefined
+                    : (await options.serviceAccounts.list(auth, { limit: 200, after: undefined })).items.find((a) => a.id === serviceAccountId);
+                if (visible === undefined) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+            }
+            // Every named layer has to be one this caller can read.
+            //
+            // Not a security check — a narrowing can only remove, so a layer they
+            // cannot reach would simply contribute nothing. It is here because the
+            // alternative is a foreign key violation surfacing as a 500 on a typo,
+            // and because a person approving a restriction should be told when the
+            // restriction they wrote is not the one they meant. `404` for an unknown
+            // id and for an unreadable one alike, on invariant I6.
+            if (delegating && narrowing !== undefined && narrowing.length > 0) {
+                const readable = options.layers === undefined
+                    ? []
+                    : (await options.layers.list(auth, { limit: 500, after: undefined })).items.map((l) => l.id);
+                if (narrowing.some((id) => !readable.includes(id))) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
             }
             // The standing connection first, then the code that points at it. That
             // order matters: the code is exchanged for a refresh token hung on the
             // connection, and a code with no connection would mint access nobody can
             // ever take back — which is the gap this closes.
-            const consentId = await options.oauth.consents.record(auth, clientId, serviceAccountId);
+            const subject = delegating
+                ? { actsAs: 'user', userId: auth.principal.id }
+                : { actsAs: 'service_account', serviceAccountId: serviceAccountId };
+            const consentId = await options.oauth.consents.record(auth, clientId, subject, narrowing === undefined ? [] : narrowing, isStringArray(ceiling) ? ceiling : undefined);
             const code = generateCode();
-            await options.oauth.authorizations.approve(auth, {
+            const common = {
                 orgId: auth.orgId,
-                serviceAccountId,
                 clientId,
                 redirectUri,
                 codeChallenge,
@@ -2375,7 +2464,13 @@ async function handle(req, res, options) {
                 code,
                 consentId,
                 expiresAt: new Date(Date.now() + CODE_TTL_MS),
-            });
+            };
+            // Two calls rather than one with a union in it. The delegated shape
+            // *requires* the connection id and the agent shape does not, and writing
+            // that as one object hands the compiler a value it cannot place in either
+            // arm — which is the same reason 0025 gave the database a CHECK per mode
+            // instead of one that permits both halves.
+            await options.oauth.authorizations.approve(auth, subject.actsAs === 'user' ? { ...common, subject } : { ...common, subject });
             // Recorded, because "why does this agent hold a token" is a question an
             // administrator will ask and the grant table cannot answer: the grants
             // were there before, and what changed is that a client was handed the
@@ -2385,7 +2480,20 @@ async function handle(req, res, options) {
                 actor: `${auth.principal.type}:${auth.principal.id}`,
                 action: 'oauth.consent',
                 result: 'allow',
-                detail: { client_id: clientId, client_name: client.clientName, service_account_id: serviceAccountId },
+                detail: {
+                    client_id: clientId,
+                    client_name: client.clientName,
+                    acts_as: subject.actsAs,
+                    ...(delegating
+                        ? {
+                            delegation_id: consentId,
+                            layers: narrowing ?? [],
+                            // Recorded because it is the answer to "why can this
+                            // application not delete anything", asked six months later.
+                            permissions: isStringArray(ceiling) ? ceiling : 'no ceiling',
+                        }
+                        : { service_account_id: serviceAccountId }),
+                },
                 requestId,
             });
             // The redirect is returned rather than performed: this is an API call
@@ -2405,7 +2513,7 @@ async function handle(req, res, options) {
             // in the organization rather than an object inside a workspace, and there
             // is no scope to check it against — someone holding admin on one layer
             // must not be able to mint credentials.
-            if (auth.role !== 'org_admin') {
+            if (!administers(auth)) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
@@ -2470,7 +2578,7 @@ async function handle(req, res, options) {
         }
         const accountMatch = /^\/v1\/service-accounts\/([^/]+)$/.exec(instance);
         if (req.method === 'DELETE' && accountMatch && options.serviceAccounts !== undefined) {
-            if (auth.role !== 'org_admin') {
+            if (!administers(auth)) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
@@ -2506,7 +2614,7 @@ async function handle(req, res, options) {
         const principalPath = /^\/v1\/(users|groups)(\/.*)?$/.exec(instance);
         if (principalPath !== null) {
             const port = principalPath[1] === 'users' ? options.users : options.groups;
-            if (port !== undefined && auth.role !== 'org_admin') {
+            if (port !== undefined && !administers(auth)) {
                 await options.audit.write({
                     orgId: auth.orgId,
                     actor: `${auth.principal.type}:${auth.principal.id}`,