@nacre.work/api 0.3.0 → 0.5.0

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,
@@ -964,34 +984,74 @@ async function handle(req, res, options) {
                 ? body_.external_id
                 : (uploaded?.filename ?? undefined);
             let content = body_.content;
+            let binary;
             if (uploaded !== undefined) {
                 if (typeof content === 'string' || typeof body_.url === 'string') {
                     const problem = badRequest(instance, requestId, "A multipart upload carries the document; 'content' and 'url' are for the JSON body.");
                     send(res, problem.status, problem.toJSON(), requestId);
                     return;
                 }
-                // Decoded here, and refused here, rather than queued and failed later.
-                //
-                // The parser this feeds extracts no binary formats — it is stdlib-only
-                // on purpose, since it runs hostile input through whatever it depends
-                // on. Until this check existed the sidecar decoded with
-                // `errors="replace"`, so a PDF became a string of replacement
-                // characters that was chunked, embedded, stored as the document body
-                // and reported as indexed.
-                //
-                // At the edge the caller learns immediately and nothing is queued. Deep
-                // in the worker they would have learned from a `failed` row minutes
-                // later, if they looked.
-                const decoder = new TextDecoder('utf-8', { fatal: true });
-                try {
-                    content = decoder.decode(uploaded.bytes);
+                // PDF first, and both signals must agree: the part must declare
+                // `application/pdf` AND the bytes must begin with `%PDF-`. Either
+                // alone is a refusal that names the other — a declared type the bytes
+                // contradict is exactly the disagreement the multipart parser's
+                // strictness doctrine exists to refuse, and sniffing alone would turn
+                // the declared type into decoration. Other formats extend this table;
+                // nothing falls through to a guess.
+                const declared = (uploaded.contentType ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
+                const MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2d]; // %PDF-
+                const magic = uploaded.bytes.length >= MAGIC.length && MAGIC.every((b, i) => uploaded.bytes[i] === b);
+                if (declared === 'application/pdf' && !magic) {
+                    const problem = badRequest(instance, requestId, "The file part declares 'application/pdf' but the bytes do not begin with the %PDF- magic. " +
+                        'Both must agree; a declared type the bytes contradict is refused rather than trusted.');
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
                 }
-                catch {
-                    const problem = badRequest(instance, requestId, 'The uploaded file is not UTF-8 text. This installation extracts no binary formats — ' +
-                        'a PDF, a Word file or an image needs an extractor the parser deliberately does not carry.');
+                if (declared !== 'application/pdf' && magic) {
+                    const problem = badRequest(instance, requestId, "The bytes begin with the %PDF- magic but the file part does not declare 'application/pdf'. " +
+                        'Both must agree; declare the type rather than relying on sniffing.');
                     send(res, problem.status, problem.toJSON(), requestId);
                     return;
                 }
+                if (declared === 'application/pdf' && magic) {
+                    // Binary requires object storage, at the edge. The bytes' only home
+                    // is the bucket — `documents.source_ref` is text and stays text — so
+                    // a deployment without one learns on the request, naming the
+                    // variables, not from a `failed` row minutes later.
+                    if (options.objectStorage !== true) {
+                        const problem = badRequest(instance, requestId, 'A PDF upload needs object storage, and this deployment has none configured. ' +
+                            'Set NACRE_S3_* (endpoint, bucket, access key, secret key) to enable binary ingest.');
+                        send(res, problem.status, problem.toJSON(), requestId);
+                        return;
+                    }
+                    binary = { bytes: uploaded.bytes, contentType: 'application/pdf' };
+                }
+                else {
+                    // Decoded here, and refused here, rather than queued and failed
+                    // later.
+                    //
+                    // The parser extracts exactly the formats in the table above — it
+                    // took its first dependency for PDF and nothing else. Until this
+                    // check existed the sidecar decoded with `errors="replace"`, so a
+                    // binary file became a string of replacement characters that was
+                    // chunked, embedded, stored as the document body and reported as
+                    // indexed.
+                    //
+                    // At the edge the caller learns immediately and nothing is queued.
+                    // Deep in the worker they would have learned from a `failed` row
+                    // minutes later, if they looked.
+                    const decoder = new TextDecoder('utf-8', { fatal: true });
+                    try {
+                        content = decoder.decode(uploaded.bytes);
+                    }
+                    catch {
+                        const problem = badRequest(instance, requestId, 'The uploaded file is not UTF-8 text. This installation extracts PDF and nothing else — ' +
+                            'a Word file or an image needs an extractor the parser deliberately does not carry, ' +
+                            'and a PDF must declare application/pdf on the file part.');
+                        send(res, problem.status, problem.toJSON(), requestId);
+                        return;
+                    }
+                }
             }
             const url_ = body_.url;
             if (typeof layer !== 'string' || typeof externalId !== 'string') {
@@ -999,7 +1059,10 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            if ((typeof content === 'string') === (typeof url_ === 'string')) {
+            // A PDF file part is the third source and already excludes the other
+            // two: `content` and `url` beside a file were refused above, before the
+            // bytes were even looked at.
+            if (binary === undefined && (typeof content === 'string') === (typeof url_ === 'string')) {
                 // Accepting both would mean choosing silently, and the choice would
                 // differ from whatever the caller assumed.
                 const problem = badRequest(instance, requestId, "Exactly one of 'content' or 'url' is required.");
@@ -1046,6 +1109,7 @@ async function handle(req, res, options) {
                 ...(typeof body_.title === 'string' ? { title: body_.title } : {}),
                 ...(typeof content === 'string' ? { content } : {}),
                 ...(typeof url_ === 'string' ? { url: url_ } : {}),
+                ...(binary === undefined ? {} : { bytes: binary.bytes, contentType: binary.contentType }),
                 metadata,
             });
             // The accept stage only — parse, chunk and embed happen in the worker,
@@ -1505,6 +1569,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
@@ -1878,6 +1971,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);
     }