@nacre.work/api 0.23.10 → 0.25.0

package/dist/server.js

@@ -13,7 +13,7 @@ import { MIN_PASSWORD_LENGTH } from './recovery.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';
+import { decodeCursor, readPage } from './pagination.js';
 /**
  * The default body cap, in bytes.
  *
@@ -868,6 +868,37 @@ function sendSessionOutcome(res, outcome, instance, requestId) {
     });
     send(res, problem.status, problem.toJSON(), requestId);
 }
+/**
+ * Match a route whose captured segments are percent-decoded, or `null`.
+ *
+ * WHATWG `URL` leaves an invalid escape in `pathname` verbatim, so a bare
+ * `decodeURIComponent` over a captured segment throws `URIError` on
+ * `/v1/documents/%ZZ` — which the error boundary turned into a `500` and an
+ * audit row saying `error`, where the right answer is the `404` every other
+ * unknown id gets. A malformed escape names nothing, so here it is a path
+ * that does not match: the request falls through to the same `notFound` an
+ * unrouted path gets, and any authenticated caller stops being able to fill
+ * the journal with `error` rows on demand. Twelve routes decode a segment;
+ * this is the one place they all do it, and eslint refuses a bare
+ * `decodeURIComponent` in this package so the thirteenth cannot be written
+ * the old way.
+ */
+function pathMatch(pattern, instance) {
+    const matched = pattern.exec(instance);
+    if (matched === null)
+        return null;
+    try {
+        for (let i = 1; i < matched.length; i += 1) {
+            const raw = matched[i];
+            if (raw !== undefined)
+                matched[i] = decodeURIComponent(raw);
+        }
+        return matched;
+    }
+    catch {
+        return null;
+    }
+}
 async function handleAuth(req, res, instance, requestId, options) {
     // Every route here produces a credential and therefore takes a body, with
     // exactly one exception: `/v1/auth/methods` is a **read**, and the contract
@@ -1064,10 +1095,15 @@ async function handleAuth(req, res, instance, requestId, options) {
                 return;
             }
         }
-        // Awaited, but its failure is swallowed: the answer is the same either way,
-        // and an unhandled rejection would take the process down over a relay being
-        // briefly unreachable.
-        await options.recovery.request(email.email).catch((error) => {
+        // Deliberately not awaited. The body is the same `204` either way, but the
+        // *time* to it was not: a miss returns after one SELECT and a hit does a
+        // full SMTP round trip — hundreds of milliseconds against a couple — so an
+        // awaited request() made the one endpoint reachable without a credential a
+        // timing oracle for "does this address have an account", which is exactly
+        // what the module's own header says it must not be. The failure is still
+        // swallowed into a log line: an unhandled rejection would take the process
+        // down over a relay being briefly unreachable.
+        void options.recovery.request(email.email).catch((error) => {
             logger.warn('could not start a password recovery', {
                 request_id: requestId,
                 error: String(error).slice(0, 200),
@@ -2348,9 +2384,9 @@ async function handle(req, res, options) {
             send(res, outcome.unchanged ? 200 : 202, { document_id: outcome.documentId, job_id: outcome.jobId, status: outcome.unchanged ? 'indexed' : 'queued' }, requestId);
             return;
         }
-        const documentMatch = /^\/v1\/documents\/([^/]+)$/.exec(instance);
+        const documentMatch = pathMatch(/^\/v1\/documents\/([^/]+)$/, instance);
         if (req.method === 'DELETE' && documentMatch) {
-            const id = decodeURIComponent(documentMatch[1]);
+            const id = documentMatch[1];
             const removed = await options.ingest.remove(auth, id);
             await options.audit.write({
                 orgId: auth.orgId,
@@ -2369,8 +2405,51 @@ async function handle(req, res, options) {
             send(res, 204, null, requestId);
             return;
         }
+        const retryMatch = pathMatch(/^\/v1\/documents\/([^/]+)\/retry$/, instance);
+        if (req.method === 'POST' && retryMatch) {
+            const id = retryMatch[1];
+            if (options.documents.retry === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const outcome = await options.documents.retry(auth, id);
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'retry_document',
+                result: outcome === 'requeued' ? 'allow' : 'deny',
+                target: { document_id: id },
+                detail: { document_id: id, outcome },
+                requestId,
+            });
+            if (outcome === 'unreachable') {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (outcome === 'not-failed') {
+                const problem = new Problem({
+                    type: 'https://nacre.work/errors/conflict',
+                    title: 'Conflict',
+                    status: 409,
+                    detail: 'This document has not failed, so there is nothing to retry. ' +
+                        'Only a document whose status is `failed` can be requeued this way; ' +
+                        'send it again through POST /v1/documents to re-index one that has not.',
+                    instance,
+                    requestId,
+                });
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // `204`, and never the document, for the same reason the PATCH beside it
+            // does: rule 6 means a caller may hold `write` without `read`, so a body
+            // describing what was requeued would be a read this caller has not got.
+            send(res, 204, null, requestId);
+            return;
+        }
         if (req.method === 'PATCH' && documentMatch) {
-            const id = decodeURIComponent(documentMatch[1]);
+            const id = documentMatch[1];
             if (options.documents.updateMetadata === undefined) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
@@ -2417,7 +2496,7 @@ async function handle(req, res, options) {
             return;
         }
         if (req.method === 'GET' && documentMatch) {
-            const id = decodeURIComponent(documentMatch[1]);
+            const id = documentMatch[1];
             const document = await options.documents.read(auth, id);
             if (document === undefined) {
                 // T8. The same response for "no such document" and "another
@@ -2448,9 +2527,9 @@ async function handle(req, res, options) {
             send(res, 200, document, requestId);
             return;
         }
-        const jobMatch = /^\/v1\/jobs\/([^/]+)$/.exec(instance);
+        const jobMatch = pathMatch(/^\/v1\/jobs\/([^/]+)$/, instance);
         if (req.method === 'GET' && jobMatch && options.jobs !== undefined) {
-            const id = decodeURIComponent(jobMatch[1]);
+            const id = jobMatch[1];
             const job = await options.jobs.read(auth, id);
             if (job === undefined) {
                 // A job names a document, so it is as much of an oracle as the document
@@ -2816,7 +2895,7 @@ async function handle(req, res, options) {
         }
         if (instance === '/v1/workspaces' && options.workspaces !== undefined) {
             if (req.method === 'GET') {
-                const page = readPage(url.searchParams, instance, requestId);
+                const page = readPage(url.searchParams, instance, requestId, 'uuid');
                 if (page instanceof Problem) {
                     send(res, page.status, page.toJSON(), requestId);
                     return;
@@ -2889,7 +2968,7 @@ async function handle(req, res, options) {
             }
         }
         if (req.method === 'GET' && instance === '/v1/layers' && options.layers !== undefined) {
-            const page = readPage(url.searchParams, instance, requestId);
+            const page = readPage(url.searchParams, instance, requestId, 'uuid');
             if (page instanceof Problem) {
                 send(res, page.status, page.toJSON(), requestId);
                 return;
@@ -2979,7 +3058,7 @@ async function handle(req, res, options) {
             return;
         }
         if (req.method === 'GET' && instance === '/v1/grants' && options.grants !== undefined) {
-            const page = readPage(url.searchParams, instance, requestId);
+            const page = readPage(url.searchParams, instance, requestId, 'uuid');
             if (page instanceof Problem) {
                 send(res, page.status, page.toJSON(), requestId);
                 return;
@@ -3018,9 +3097,9 @@ async function handle(req, res, options) {
             send(res, 201, grantJson(issued), requestId);
             return;
         }
-        const grantMatch = /^\/v1\/grants\/([^/]+)$/.exec(instance);
+        const grantMatch = pathMatch(/^\/v1\/grants\/([^/]+)$/, instance);
         if (req.method === 'DELETE' && grantMatch && options.grants !== undefined) {
-            const id = decodeURIComponent(grantMatch[1]);
+            const id = grantMatch[1];
             const revoked = await options.grants.revoke(auth, id);
             // Written before the response either way. A revocation nobody can prove
             // happened is not a revocation an auditor will accept, and a *refused*
@@ -3339,7 +3418,7 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            const page = readPage(url.searchParams, instance, requestId);
+            const page = readPage(url.searchParams, instance, requestId, 'sequence');
             if (page instanceof Problem) {
                 send(res, page.status, page.toJSON(), requestId);
                 return;
@@ -3609,11 +3688,31 @@ 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.
+            //
+            // The whole listing, not one page of it. A `find` over the first 200
+            // used to stand here, so in an organization with more accounts than
+            // that, approving one ordered past the cut answered `404`
+            // indistinguishably from "no such agent" — a valid consent refused with
+            // nothing on the screen to say why. The loop terminates because the
+            // listing seeks on `(created_at, id)`, and it stops early on a hit.
             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) {
+                let visible = false;
+                if (options.serviceAccounts !== undefined) {
+                    let after;
+                    for (;;) {
+                        const found = await options.serviceAccounts.list(auth, { limit: 200, after });
+                        if (found.items.some((a) => a.id === serviceAccountId)) {
+                            visible = true;
+                            break;
+                        }
+                        if (found.nextCursor === null)
+                            break;
+                        after = decodeCursor(found.nextCursor, 'uuid');
+                        if (after === undefined)
+                            break;
+                    }
+                }
+                if (!visible) {
                     const problem = notFound(instance, requestId);
                     send(res, problem.status, problem.toJSON(), requestId);
                     return;
@@ -3628,10 +3727,26 @@ async function handle(req, res, options) {
             // 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((l) => !readable.includes(l.id))) {
+                // The whole listing, for the reason the agent lookup above walks its
+                // pages: one fixed page refused any layer ordered past the cut. The
+                // loop stops early once every named layer has been seen.
+                const readable = new Set();
+                if (options.layers !== undefined) {
+                    let after;
+                    for (;;) {
+                        const found = await options.layers.list(auth, { limit: 500, after });
+                        for (const layer of found.items)
+                            readable.add(layer.id);
+                        if (narrowing.every((l) => readable.has(l.id)))
+                            break;
+                        if (found.nextCursor === null)
+                            break;
+                        after = decodeCursor(found.nextCursor, 'uuid');
+                        if (after === undefined)
+                            break;
+                    }
+                }
+                if (narrowing.some((l) => !readable.has(l.id))) {
                     const problem = notFound(instance, requestId);
                     send(res, problem.status, problem.toJSON(), requestId);
                     return;
@@ -3723,7 +3838,7 @@ async function handle(req, res, options) {
                 return;
             }
             if (req.method === 'GET') {
-                const page = readPage(url.searchParams, instance, requestId);
+                const page = readPage(url.searchParams, instance, requestId, 'uuid');
                 if (page instanceof Problem) {
                     send(res, page.status, page.toJSON(), requestId);
                     return;
@@ -3782,14 +3897,14 @@ async function handle(req, res, options) {
                 return;
             }
         }
-        const accountMatch = /^\/v1\/service-accounts\/([^/]+)$/.exec(instance);
+        const accountMatch = pathMatch(/^\/v1\/service-accounts\/([^/]+)$/, instance);
         if (req.method === 'DELETE' && accountMatch && options.serviceAccounts !== undefined) {
             if (!administers(auth)) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            const id = decodeURIComponent(accountMatch[1]);
+            const id = accountMatch[1];
             const revoked = await options.serviceAccounts.revoke(auth, id);
             await options.audit.write({
                 orgId: auth.orgId,
@@ -3838,7 +3953,7 @@ async function handle(req, res, options) {
         }
         if (instance === '/v1/users' && options.users !== undefined) {
             if (req.method === 'GET') {
-                const page = readPage(url.searchParams, instance, requestId);
+                const page = readPage(url.searchParams, instance, requestId, 'uuid');
                 if (page instanceof Problem) {
                     send(res, page.status, page.toJSON(), requestId);
                     return;
@@ -3924,9 +4039,9 @@ async function handle(req, res, options) {
                 return;
             }
         }
-        const userMatch = /^\/v1\/users\/([^/]+)$/.exec(instance);
+        const userMatch = pathMatch(/^\/v1\/users\/([^/]+)$/, instance);
         if (userMatch && options.users !== undefined) {
-            const id = decodeURIComponent(userMatch[1]);
+            const id = 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
@@ -4047,9 +4162,9 @@ async function handle(req, res, options) {
                 return;
             }
         }
-        const passwordMatch = /^\/v1\/users\/([^/]+)\/password$/.exec(instance);
+        const passwordMatch = pathMatch(/^\/v1\/users\/([^/]+)\/password$/, instance);
         if (req.method === 'POST' && passwordMatch && options.users !== undefined) {
-            const id = decodeURIComponent(passwordMatch[1]);
+            const id = passwordMatch[1];
             const reset = await options.users.resetPassword(auth, id);
             const refused = typeof reset === 'string' ? reset : undefined;
             await options.audit.write({
@@ -4085,7 +4200,7 @@ async function handle(req, res, options) {
         }
         if (instance === '/v1/groups' && options.groups !== undefined) {
             if (req.method === 'GET') {
-                const page = readPage(url.searchParams, instance, requestId);
+                const page = readPage(url.searchParams, instance, requestId, 'uuid');
                 if (page instanceof Problem) {
                     send(res, page.status, page.toJSON(), requestId);
                     return;
@@ -4136,9 +4251,9 @@ async function handle(req, res, options) {
                 return;
             }
         }
-        const groupMatch = /^\/v1\/groups\/([^/]+)$/.exec(instance);
+        const groupMatch = pathMatch(/^\/v1\/groups\/([^/]+)$/, instance);
         if (req.method === 'DELETE' && groupMatch && options.groups !== undefined) {
-            const id = decodeURIComponent(groupMatch[1]);
+            const id = groupMatch[1];
             const removed = await options.groups.remove(auth, id);
             await options.audit.write({
                 orgId: auth.orgId,
@@ -4157,11 +4272,11 @@ async function handle(req, res, options) {
             send(res, 204, null, requestId);
             return;
         }
-        const membersMatch = /^\/v1\/groups\/([^/]+)\/members$/.exec(instance);
+        const membersMatch = pathMatch(/^\/v1\/groups\/([^/]+)\/members$/, instance);
         if (membersMatch && options.groups !== undefined) {
-            const groupId = decodeURIComponent(membersMatch[1]);
+            const groupId = membersMatch[1];
             if (req.method === 'GET') {
-                const page = readPage(url.searchParams, instance, requestId);
+                const page = readPage(url.searchParams, instance, requestId, 'uuid');
                 if (page instanceof Problem) {
                     send(res, page.status, page.toJSON(), requestId);
                     return;
@@ -4213,11 +4328,11 @@ async function handle(req, res, options) {
         // `{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);
+        const memberMatch = pathMatch(/^\/v1\/groups\/([^/]+)\/members\/(user|group)\/([^/]+)$/, instance);
         if (req.method === 'DELETE' && memberMatch && options.groups !== undefined) {
-            const groupId = decodeURIComponent(memberMatch[1]);
+            const groupId = memberMatch[1];
             const type = memberMatch[2];
-            const memberId = decodeURIComponent(memberMatch[3]);
+            const memberId = memberMatch[3];
             const removed = await options.groups.removeMember(auth, groupId, { type, id: memberId });
             await options.audit.write({
                 orgId: auth.orgId,