@nacre.work/api 0.4.0 → 0.5.1

package/dist/server.js

@@ -8,6 +8,7 @@ import { authenticate, rejectTenantOverride } from './auth.js';
 import { badRequest, internal, notFound, Problem } from './errors.js';
 import { isConflict, isReplay } from './idempotency.js';
 import { limitHeaders } from './limits.js';
+import { looksLikeEmail } from './principals.js';
 import { clientSource } from './source.js';
 import { auditFormat, auditJson, readAuditQuery, toCsv, toNdjson, } from './audit-export.js';
 import { readPage } from './pagination.js';
@@ -55,6 +56,25 @@ function accountJson(a) {
         revoked_at: a.revokedAt,
     };
 }
+function userJson(u) {
+    return {
+        id: u.id,
+        email: u.email,
+        role: u.role,
+        created_at: u.createdAt,
+        disabled_at: u.disabledAt,
+        // Whether one is set, never anything derived from it. False is an SSO-only
+        // account, which is a fact an administrator needs and which says nothing
+        // about the credential.
+        has_password: u.hasPassword,
+    };
+}
+function groupJson(g) {
+    return { id: g.id, name: g.name, created_at: g.createdAt, member_count: g.memberCount };
+}
+function memberJson(m) {
+    return { type: m.type, id: m.id, label: m.label };
+}
 function grantJson(g) {
     return {
         id: g.id,
@@ -81,6 +101,8 @@ function grantJson(g) {
  * this build does not have, which is not a question about whether an object
  * exists, so invariant I4 has no bearing and saying so plainly is right.
  */
+/** Shape only. Existence is the adapter's, and answers `404` rather than `400`. */
+const UUID_SHAPE = /^[0-9a-f-]{36}$/i;
 function parseGrant(body) {
     const principalType = body.principal_type;
     const principalId = body.principal_id;
@@ -91,6 +113,24 @@ function parseGrant(body) {
     if (typeof principalId !== 'string' || typeof scopeId !== 'string') {
         return "'principal_id' and 'scope_id' are required.";
     }
+    // Shape, here, and existence in the adapter — because the two answers are
+    // different and only one of them is allowed to be specific.
+    //
+    // A value that is not a uuid is a fact about the caller's own request: it
+    // discloses nothing, so it gets a `400` naming the field they got wrong.
+    // A well-formed uuid that names nothing is `404`, indistinguishable from one
+    // they may not administer, which is invariant 4.
+    //
+    // Collapsing the two is what sent somebody looking at the wrong half of a
+    // form: they typed a service account's *name* into `principal_id`, and the
+    // only answer was "no such scope" — about the field that was correct.
+    if (!UUID_SHAPE.test(principalId)) {
+        return "'principal_id' must be a uuid. It is the principal's id, not its name — " +
+            'a service account, a user or a group listed in this organization.';
+    }
+    if (!UUID_SHAPE.test(scopeId)) {
+        return "'scope_id' must be a uuid — the id of the workspace or layer being granted on.";
+    }
     if (typeof principalType !== 'string' || !PRINCIPAL_TYPES.includes(principalType)) {
         return `'principal_type' must be one of ${PRINCIPAL_TYPES.join(', ')}.`;
     }
@@ -699,6 +739,32 @@ async function handle(req, res, options) {
         await handleAuth(req, res, instance, requestId, options);
         return;
     }
+    // A path this server does not route is `404`, and it says so **before**
+    // asking for a credential.
+    //
+    // Everything unauthenticated is already handled above — `/metrics`, the two
+    // `/.well-known` documents, health, readiness, sign-in. So anything left that
+    // is not under `/v1/` is not part of this API at all, and answering `401`
+    // for it claims a path exists and is merely gated.
+    //
+    // That is not a hypothetical reading. A client pointed at this port looking
+    // for an MCP endpoint probed `/.well-known/oauth-authorization-server`,
+    // `/.well-known/openid-configuration` and `/register`, got `401 "A bearer
+    // token is required"` from each, and concluded the deployment had OAuth
+    // discovery behind a middleware that needed lifting. There is no such
+    // middleware and there are no such routes: this is a resource server and
+    // declines the authorization-server role — see docs/mcp.md. An afternoon
+    // went into un-gating endpoints that do not exist.
+    //
+    // Unknown paths *under* `/v1/` still answer `401`, and that is the line
+    // rather than an omission: they are inside the authenticated surface, where
+    // presenting a credential is the price of being told anything. Nothing is
+    // concealed by it — every route this API serves is in docs/openapi.yaml.
+    if (!instance.startsWith('/v1/')) {
+        const problem = notFound(instance, requestId);
+        send(res, problem.status, problem.toJSON(), requestId);
+        return;
+    }
     const auth = await authenticate(req.headers.authorization, options.verify, instance, requestId);
     if (auth instanceof Problem) {
         // Counted by what was presented, never by why it failed.
@@ -1549,6 +1615,35 @@ async function handle(req, res, options) {
             send(res, 204, null, requestId);
             return;
         }
+        if (req.method === 'DELETE' && layerMatch !== null) {
+            const layerId = layerMatch[1];
+            if (options.layers?.remove === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const removed = await options.layers.remove(auth, layerId);
+            // Recorded whichever way it went, and before the answer. Deleting a layer
+            // takes every document in it out of every answer at once, which is the
+            // largest single thing a caller can do here — a refused attempt is worth
+            // as much to an investigation as a successful one.
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'delete_layer',
+                result: removed ? 'allow' : 'deny',
+                target: { layer_id: layerId },
+                detail: { layer_id: layerId },
+                requestId,
+            });
+            if (!removed) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            send(res, 204, null, requestId);
+            return;
+        }
         // `/v1/admin/...` — routes a commercial module mounted.
         //
         // After authentication and after `rejectTenantOverride`, deliberately. A
@@ -1922,6 +2017,389 @@ async function handle(req, res, options) {
             send(res, 204, null, requestId);
             return;
         }
+        // ───────────────────────────── principals ─────────────────────────────
+        //
+        // Users and groups. `org_admin`, on the same argument service accounts
+        // make: a principal belongs to the organization rather than to a scope
+        // inside it, so there is nothing to check `admin` against — and someone
+        // holding admin on one layer must not be able to mint one.
+        //
+        // The refusal writes a `deny` event. It surfaces as `404`, which is what
+        // makes it easy to miss: an early return that answers "no such path" is
+        // still a refusal, and `docs/audit.md` counts every one.
+        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') {
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'administer_principals',
+                    result: 'deny',
+                    detail: { path: instance, method: req.method ?? 'GET', reason: 'not an org_admin' },
+                    requestId,
+                });
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+        }
+        if (instance === '/v1/users' && options.users !== undefined) {
+            if (req.method === 'GET') {
+                const page = readPage(url.searchParams, instance, requestId);
+                if (page instanceof Problem) {
+                    send(res, page.status, page.toJSON(), requestId);
+                    return;
+                }
+                const { items, nextCursor } = await options.users.list(auth, page);
+                send(res, 200, { items: items.map(userJson), next_cursor: nextCursor }, requestId);
+                return;
+            }
+            if (req.method === 'POST') {
+                const fields = (body ?? {});
+                const email = typeof fields.email === 'string' ? fields.email.trim() : '';
+                if (!looksLikeEmail(email)) {
+                    const problem = badRequest(instance, requestId, "'email' is required and must be an address.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const role = fields.role ?? 'member';
+                // `platform_admin` is deliberately not creatable here, and this is the
+                // one refusal in this block that is about the model rather than about
+                // input. That role administers the *installation* and spans tenants in
+                // the multi-tenancy module; an org_admin minting one would be
+                // escalating out of their own organization through an endpoint scoped
+                // to it. It is set by whoever runs `init`, and stays there.
+                if (role !== 'member' && role !== 'org_admin') {
+                    const problem = badRequest(instance, requestId, "'role' must be 'member' or 'org_admin'. 'platform_admin' administers the " +
+                        'installation rather than this organization and is not issued here.');
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const created = await options.users.create(auth, email, role);
+                if (created === undefined) {
+                    await options.audit.write({
+                        orgId: auth.orgId,
+                        actor: `${auth.principal.type}:${auth.principal.id}`,
+                        action: 'create_user',
+                        result: 'deny',
+                        detail: { email, reason: 'address taken' },
+                        requestId,
+                    });
+                    const problem = new Problem({
+                        type: 'https://nacre.work/errors/conflict',
+                        title: 'Conflict',
+                        status: 409,
+                        detail: `A user with the address '${email}' already exists in this organization.`,
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'create_user',
+                    result: 'allow',
+                    // The address and the role. Never the password — this row is readable
+                    // by anyone with the audit log, and the password is not recoverable
+                    // from anywhere else by design.
+                    detail: { user_id: created.user.id, email, role },
+                    requestId,
+                });
+                // The only time the password exists outside the caller's process.
+                send(res, 201, { ...userJson(created.user), password: created.password }, requestId);
+                return;
+            }
+        }
+        const userMatch = /^\/v1\/users\/([^/]+)$/.exec(instance);
+        if (userMatch && options.users !== undefined) {
+            const id = decodeURIComponent(userMatch[1]);
+            if (req.method === 'DELETE') {
+                // Disabled, never deleted, which is what `DELETE` means on every
+                // removable thing here: a document is tombstoned, a key is revoked, and
+                // a user keeps their row because the audit log names its id and
+                // `grants.created_by` references it with no cascade. `PATCH` with
+                // `disabled: false` is how somebody comes back.
+                //
+                // Through the same call `PATCH` makes rather than a second statement,
+                // so the last-administrator guard covers both spellings. Two removals
+                // with one check between them is how the guarded one gets routed
+                // around.
+                const disabled = await options.users.update(auth, id, { disabled: true });
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'disable_user',
+                    result: disabled === 'updated' ? 'allow' : 'deny',
+                    detail: { user_id: id, ...(disabled === 'updated' ? {} : { reason: disabled }) },
+                    requestId,
+                });
+                if (disabled === 'last-admin') {
+                    const problem = new Problem({
+                        type: 'https://nacre.work/errors/conflict',
+                        title: 'Conflict',
+                        status: 409,
+                        detail: 'This is the only active org_admin in the organization. Promote another user ' +
+                            'first — an organization with none has no route back through the API.',
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                if (disabled === 'no-user') {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                send(res, 204, null, requestId);
+                return;
+            }
+            if (req.method === 'PATCH') {
+                const fields = (body ?? {});
+                const wantsRole = 'role' in fields;
+                const wantsDisabled = 'disabled' in fields;
+                if (!wantsRole && !wantsDisabled) {
+                    const problem = badRequest(instance, requestId, "Give at least one of 'role' or 'disabled'.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                if (wantsRole && fields.role !== 'member' && fields.role !== 'org_admin') {
+                    const problem = badRequest(instance, requestId, "'role' must be 'member' or 'org_admin'. 'platform_admin' administers the " +
+                        'installation rather than this organization and is not issued here.');
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                if (wantsDisabled && typeof fields.disabled !== 'boolean') {
+                    const problem = badRequest(instance, requestId, "'disabled' must be a boolean.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                // The last administrator cannot demote or disable themselves through
+                // this path. Not paternalism: an organization with no `org_admin` has
+                // no route back — every endpoint that could restore one is behind the
+                // role that was just given up, and the remedy would be SQL. The check
+                // is in the adapter, where it can count in the same transaction.
+                const changed = await options.users.update(auth, id, {
+                    ...(wantsRole ? { role: fields.role } : {}),
+                    ...(wantsDisabled ? { disabled: fields.disabled } : {}),
+                });
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'update_user',
+                    result: changed === 'updated' ? 'allow' : 'deny',
+                    detail: {
+                        user_id: id,
+                        ...(wantsRole ? { role: fields.role } : {}),
+                        ...(wantsDisabled ? { disabled: fields.disabled } : {}),
+                        ...(changed === 'updated' ? {} : { reason: changed }),
+                    },
+                    requestId,
+                });
+                if (changed === 'last-admin') {
+                    // 409 rather than 404: the caller is looking straight at this user —
+                    // it is their own account or one they just listed — so the answer is
+                    // about the organization's state and not about what they can see.
+                    // Invariant 4 is about invisibility, and nothing here is invisible.
+                    const problem = new Problem({
+                        type: 'https://nacre.work/errors/conflict',
+                        title: 'Conflict',
+                        status: 409,
+                        detail: 'This is the only active org_admin in the organization. Promote another user ' +
+                            'first — an organization with none has no route back through the API.',
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                if (changed === 'no-user') {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                send(res, 204, null, requestId);
+                return;
+            }
+        }
+        const passwordMatch = /^\/v1\/users\/([^/]+)\/password$/.exec(instance);
+        if (req.method === 'POST' && passwordMatch && options.users !== undefined) {
+            const id = decodeURIComponent(passwordMatch[1]);
+            const password = await options.users.resetPassword(auth, id);
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'reset_password',
+                result: password === undefined ? 'deny' : 'allow',
+                // That it happened and to whom. Never the value.
+                detail: { user_id: id },
+                requestId,
+            });
+            if (password === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // Generated rather than chosen, for the reason `init` gives: an argument
+            // ends up in a shell history, and a password an administrator picked is
+            // one they know. This is the only time it exists outside the process.
+            send(res, 200, { password }, requestId);
+            return;
+        }
+        if (instance === '/v1/groups' && options.groups !== undefined) {
+            if (req.method === 'GET') {
+                const page = readPage(url.searchParams, instance, requestId);
+                if (page instanceof Problem) {
+                    send(res, page.status, page.toJSON(), requestId);
+                    return;
+                }
+                const { items, nextCursor } = await options.groups.list(auth, page);
+                send(res, 200, { items: items.map(groupJson), next_cursor: nextCursor }, requestId);
+                return;
+            }
+            if (req.method === 'POST') {
+                const name = (body ?? {}).name;
+                if (typeof name !== 'string' || name.trim().length === 0) {
+                    const problem = badRequest(instance, requestId, "'name' is required.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const created = await options.groups.create(auth, name.trim());
+                if (created === undefined) {
+                    await options.audit.write({
+                        orgId: auth.orgId,
+                        actor: `${auth.principal.type}:${auth.principal.id}`,
+                        action: 'create_group',
+                        result: 'deny',
+                        detail: { name: name.trim(), reason: 'name taken' },
+                        requestId,
+                    });
+                    const problem = new Problem({
+                        type: 'https://nacre.work/errors/conflict',
+                        title: 'Conflict',
+                        status: 409,
+                        detail: `A group named '${name.trim()}' already exists in this organization.`,
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'create_group',
+                    result: 'allow',
+                    detail: { group_id: created.id, name: created.name },
+                    requestId,
+                });
+                send(res, 201, groupJson(created), requestId);
+                return;
+            }
+        }
+        const groupMatch = /^\/v1\/groups\/([^/]+)$/.exec(instance);
+        if (req.method === 'DELETE' && groupMatch && options.groups !== undefined) {
+            const id = decodeURIComponent(groupMatch[1]);
+            const removed = await options.groups.remove(auth, id);
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'delete_group',
+                result: removed ? 'allow' : 'deny',
+                detail: { group_id: id },
+                requestId,
+            });
+            if (!removed) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            send(res, 204, null, requestId);
+            return;
+        }
+        const membersMatch = /^\/v1\/groups\/([^/]+)\/members$/.exec(instance);
+        if (membersMatch && options.groups !== undefined) {
+            const groupId = decodeURIComponent(membersMatch[1]);
+            if (req.method === 'GET') {
+                const page = readPage(url.searchParams, instance, requestId);
+                if (page instanceof Problem) {
+                    send(res, page.status, page.toJSON(), requestId);
+                    return;
+                }
+                const result = await options.groups.members(auth, groupId, page);
+                if (result === undefined) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                send(res, 200, { items: result.items.map(memberJson), next_cursor: result.nextCursor }, requestId);
+                return;
+            }
+            if (req.method === 'POST') {
+                const fields = (body ?? {});
+                const type = fields.type;
+                const memberId = fields.id;
+                if ((type !== 'user' && type !== 'group') || typeof memberId !== 'string') {
+                    const problem = badRequest(instance, requestId, "'type' must be 'user' or 'group', and 'id' is required.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const outcome = await options.groups.addMember(auth, groupId, { type, id: memberId });
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'add_group_member',
+                    result: outcome === 'no-group' || outcome === 'no-member' ? 'deny' : 'allow',
+                    detail: {
+                        group_id: groupId,
+                        member_type: type,
+                        member_id: memberId,
+                        ...(outcome === 'already' ? { note: 'already a member' } : {}),
+                        ...(outcome === 'no-group' || outcome === 'no-member' ? { reason: outcome } : {}),
+                    },
+                    requestId,
+                });
+                if (outcome === 'no-group' || outcome === 'no-member') {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                // 204 for both `added` and `already`. The request asked for a state and
+                // that state holds either way, and distinguishing them would tell a
+                // caller whether somebody was already in a group — which is a fact
+                // about the group and not about their request.
+                send(res, 204, null, requestId);
+                return;
+            }
+        }
+        // `{type}/{id}` rather than `{id}` alone: the edge is keyed by which member
+        // column it uses, so a bare uuid does not identify one. Same shape `grants`
+        // uses for the other end of the same relationship.
+        const memberMatch = /^\/v1\/groups\/([^/]+)\/members\/(user|group)\/([^/]+)$/.exec(instance);
+        if (req.method === 'DELETE' && memberMatch && options.groups !== undefined) {
+            const groupId = decodeURIComponent(memberMatch[1]);
+            const type = memberMatch[2];
+            const memberId = decodeURIComponent(memberMatch[3]);
+            const removed = await options.groups.removeMember(auth, groupId, { type, id: memberId });
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'remove_group_member',
+                result: removed ? 'allow' : 'deny',
+                detail: { group_id: groupId, member_type: type, member_id: memberId },
+                requestId,
+            });
+            if (!removed) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            send(res, 204, null, requestId);
+            return;
+        }
         const problem = notFound(instance, requestId);
         send(res, problem.status, problem.toJSON(), requestId);
     }