@nacre.work/api 0.0.0 → 0.1.0

package/dist/server.js

@@ -1,11 +1,47 @@
 import { createServer } from 'node:http';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 // Imported rather than taken from the global scope: `lib` is ES2023 with no
 // DOM, so the global URL is not typed here.
 import { URL } from 'node:url';
+import { MetadataError, parseFilters, parseMetadata, PROTECTED_RESOURCE_PATH, TooBusy, } from '@nacre.work/core';
 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 { clientSource } from './source.js';
+import { auditFormat, auditJson, readAuditQuery, toCsv, toNdjson, } from './audit-export.js';
+import { readPage } from './pagination.js';
+/**
+ * The default body cap, in bytes.
+ *
+ * `NACRE_MAX_DOCUMENT_BYTES` overrides it — the variable was validated at
+ * startup and read by nothing, so `docs/api.md` promised 50 MB while the server
+ * refused anything over 1 MB, and refused it with a `400` whose message did not
+ * mention size. An operator raising the documented limit saw no change.
+ */
 const MAX_BODY_BYTES = 1_000_000;
+/** Distinguishable from a malformed body, because the answers differ: 413, not 400. */
+class BodyTooLarge extends Error {
+}
+/**
+ * `top_k`, clamped to what the contract declares.
+ *
+ * It was passed through as whatever JSON produced: `1e309` becomes `Infinity`
+ * and reached Qdrant's `limit` verbatim, and with reranking on the same number
+ * decided how many rows to hydrate from Postgres. Negative and fractional
+ * values went through too.
+ *
+ * Clamped rather than refused. The bound is a resource limit and not a
+ * permission one, so a client that asks for more than the maximum is answered
+ * with the maximum — the same thing every paginated endpoint here does.
+ */
+const MAX_TOP_K = 50;
+const isStringArray = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string');
+const boundedTopK = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 10;
+    return Math.min(MAX_TOP_K, Math.max(1, Math.floor(value)));
+};
 const PRINCIPAL_TYPES = ['user', 'group', 'service_account'];
 const PERMISSIONS = ['read', 'write', 'admin'];
 function accountJson(a) {
@@ -78,27 +114,324 @@ function parseGrant(body) {
         permission: permission,
     };
 }
-async function readBody(req) {
+async function readBody(req, limit = MAX_BODY_BYTES) {
     const chunks = [];
     let size = 0;
     for await (const chunk of req) {
         size += chunk.length;
-        if (size > MAX_BODY_BYTES)
-            throw new Error('body too large');
+        if (size > limit)
+            throw new BodyTooLarge('body too large');
         chunks.push(chunk);
     }
     if (chunks.length === 0)
         return undefined;
     return JSON.parse(Buffer.concat(chunks).toString('utf8'));
 }
-function send(res, status, body, requestId) {
+/** The wire shape of a reindex, snake case like every other response here. */
+function reindexJson(status) {
+    return {
+        layer_id: status.layerId,
+        status: status.status,
+        phase: status.phase,
+        // Both names, because "which model is search using right now" and "which
+        // one is being built" are different questions and an operator watching a
+        // migration needs to see them move independently.
+        current_vector: status.currentVector,
+        shadow_vector: status.shadowVector,
+        provider_id: status.providerId,
+        started_at: status.startedAt,
+        finished_at: status.finishedAt,
+        total: status.total,
+        done: status.done,
+        failed: status.failed,
+        progress: status.progress,
+        error: status.error,
+    };
+}
+function send(res, status, body, requestId, extra = {}) {
+    // 204 means no content, and it meant it while this function wrote the four
+    // bytes `null` into the body. Some clients tolerate that and some treat a
+    // body on a 204 as a framing error.
+    if (status === 204) {
+        res.writeHead(204, { 'x-request-id': requestId, ...extra });
+        res.end();
+        return;
+    }
     const json = JSON.stringify(body);
     res.writeHead(status, {
         'content-type': status >= 400 ? 'application/problem+json' : 'application/json',
         'x-request-id': requestId,
+        ...extra,
     });
     res.end(json);
 }
+/**
+ * Merge headers into whatever the handler writes, and capture the body.
+ *
+ * `writeHead` is patched rather than wrapped at each call site because the
+ * headers apply to every response on the request, including the ones produced
+ * deep inside a handler's error path. `end` is patched to hand the serialized
+ * body to the idempotency store — after the response is on the wire, since a
+ * cache write must never be what delays an answer.
+ */
+function decorate(res, extra, store) {
+    if (Object.keys(extra).length === 0 && store === undefined)
+        return;
+    const writeHead = res.writeHead.bind(res);
+    let status = 200;
+    res.writeHead = ((code, ...rest) => {
+        status = code;
+        const headers = rest.find((r) => typeof r === 'object' && r !== null);
+        return writeHead(code, { ...extra, ...(headers ?? {}) });
+    });
+    if (store === undefined)
+        return;
+    const end = res.end.bind(res);
+    res.end = ((chunk, ...rest) => {
+        if (typeof chunk === 'string' && chunk.length > 0) {
+            try {
+                // Only a JSON body is worth replaying. A 204 has none, and anything
+                // else on this API would be a bug rather than a response to cache.
+                void store(status, JSON.parse(chunk));
+            }
+            catch {
+                // Not JSON — nothing to replay, and refusing to answer over it would
+                // be absurd.
+            }
+        }
+        else if (status === 204) {
+            void store(status, null);
+        }
+        return end(chunk, ...rest);
+    });
+}
+/**
+ * Which limit a request counts against, or none.
+ *
+ * Search and ingest are the two the contract names, and they are the two that
+ * cost real money — an embedding call each. Reads of metadata are cheap and are
+ * not counted; adding them later means adding a policy, not restructuring this.
+ */
+function resourceFor(method, instance) {
+    if (method === 'POST' && instance === '/v1/search')
+        return 'search';
+    if (method === 'POST' && instance === '/v1/documents')
+        return 'ingest';
+    return undefined;
+}
+/**
+ * Paths whose responses must never enter the idempotency cache.
+ *
+ * `/v1/service-accounts` is here because its response carries the key itself,
+ * once, and the key is stored hashed precisely so that it cannot be recovered
+ * from the database or from a backup. Caching that response puts the plaintext
+ * key in Redis for 24 hours and undoes the whole reason for hashing it — a
+ * convenience feature quietly weakening a credential store. The endpoint is
+ * already safe to retry without a cache: the unique name constraint answers a
+ * duplicate with `409` rather than minting a second key.
+ *
+ * `/v1/documents` is here for a different reason and not a security one: it is
+ * already idempotent on `(layer, external_id)` and the content hash, which
+ * survives this cache expiring and is therefore the stronger guarantee.
+ * Wrapping it would add a weaker one on top and a second thing to reason about.
+ *
+ * `/v1/search` is here because it is the one response made entirely of other
+ * people's documents. Caching it put chunk text in Redis for 24 hours — the
+ * defect already found once with service account keys, on the endpoint that
+ * returns the most sensitive thing in the product. A search is also safe to
+ * repeat by definition, so idempotency bought it nothing in the first place.
+ *
+ * The test for adding a path: **would the response be a problem in a cache
+ * dump?** If a response is only ever shown once on purpose, or is assembled
+ * from what one caller in particular may read, it does not go in a store with a
+ * 24-hour TTL and no access control of its own.
+ */
+const NEVER_CACHED = ['/v1/service-accounts', '/v1/documents', '/v1/search'];
+/** Prefix rather than exact match, so `/v1/service-accounts/{id}` is covered too. */
+const neverCached = (instance) => NEVER_CACHED.some((path) => instance === path || instance.startsWith(`${path}/`));
+/**
+ * `/v1/auth/*`: the endpoints that exist to produce a credential.
+ *
+ * Separate from `handle` because everything there assumes an `AuthContext`, and
+ * these three run before there is one. The refusals are deliberately
+ * indistinguishable: unknown address, wrong password, wrong organization,
+ * disabled account and an account with no password set are one `401` with one
+ * message, and `Login` spends the same time on each.
+ *
+ * Rate limited on the address rather than the organization, because there is no
+ * organization yet and because the thing being defended against is guessing one
+ * account's password. That is the one limit keyed on something a caller
+ * chooses, so it is normalized and hashed into the key rather than used raw —
+ * an unbounded string from an unauthenticated request should not become a Redis
+ * key, and an operator reading `KEYS nacre:rl:*` should not be reading a list
+ * of who has an account here.
+ */
+async function handleAuth(req, res, instance, requestId, options) {
+    if (options.login === undefined || req.method !== 'POST') {
+        const problem = notFound(instance, requestId);
+        send(res, problem.status, problem.toJSON(), requestId);
+        return;
+    }
+    let body;
+    try {
+        body = await readBody(req);
+    }
+    catch {
+        const problem = badRequest(instance, requestId, 'The request body could not be read.');
+        send(res, problem.status, problem.toJSON(), requestId);
+        return;
+    }
+    const refuse = () => {
+        const problem = new Problem({
+            type: 'https://nacre.work/errors/unauthorized',
+            title: 'Unauthorized',
+            status: 401,
+            // One message for every reason. A wrong password and an address with no
+            // account must not be tellable apart, or this endpoint enumerates users.
+            detail: 'Those credentials are not valid.',
+            instance,
+            requestId,
+        });
+        send(res, problem.status, problem.toJSON(), requestId);
+    };
+    if (instance === '/v1/auth/login') {
+        const { email, password, organization } = (body ?? {});
+        if (typeof email !== 'string' || typeof password !== 'string') {
+            const problem = badRequest(instance, requestId, "'email' and 'password' are required.");
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        if (options.limits !== undefined && options.limitPolicies?.login !== undefined) {
+            // Two limits, on two different things, because either alone leaves a
+            // hole. The address limit stops one account being ground down; on its own
+            // it does nothing about the attack that is actually run, which is one
+            // password against a directory — that never repeats an address and never
+            // meets the limit. The source limit bounds that; on its own it would
+            // over-trust topology, because an office behind one NAT is one source.
+            //
+            // Checked in that order and reported as one 429 with the address limit's
+            // headers, which is the tighter of the two: the alternative is a response
+            // whose RateLimit-Remaining depends on which limit fired, and that is a
+            // signal about other people's traffic.
+            const subject = createHash('sha256').update(email.trim().toLowerCase()).digest('hex').slice(0, 32);
+            const source = clientSource(req, { trustProxy: options.trustProxy ?? 0 });
+            const decisions = [await options.limits.check(subject, 'login')];
+            // `undefined` means the transport gave no address to key on. Skipped
+            // rather than folded into a shared bucket — one bucket for every client
+            // that cannot be identified is a denial of service with extra steps.
+            if (source !== undefined && options.limitPolicies.login_source !== undefined) {
+                decisions.push(await options.limits.check(`src:${source}`, 'login_source'));
+            }
+            const refused = decisions.find((d) => !d.allowed);
+            if (refused !== undefined) {
+                const problem = new Problem({
+                    type: 'https://nacre.work/errors/rate-limited',
+                    title: 'Too many requests',
+                    status: 429,
+                    detail: `Too many sign-in attempts. Try again in ${refused.reset} seconds.`,
+                    instance,
+                    requestId,
+                });
+                send(res, problem.status, problem.toJSON(), requestId, limitHeaders(decisions[0], options.limitPolicies.login, 'login'));
+                return;
+            }
+        }
+        let tokens;
+        try {
+            tokens = await options.login.login({
+                email,
+                password,
+                ...(typeof organization === 'string' ? { organization } : {}),
+            });
+        }
+        catch (error) {
+            // The process is already verifying as many passwords as it will. scrypt
+            // runs on libuv's thread pool, which is shared with DNS and file I/O, so
+            // an unbounded login endpoint stops the *rest* of the API on a name
+            // lookup — see the gate in core/passwords.ts.
+            //
+            // 503 and not 401: nothing was decided about these credentials, and
+            // answering "not valid" to a request that was never checked is a lie the
+            // client will act on. 503 with Retry-After is the honest one.
+            //
+            // Not an oracle either. It depends on how loaded the process is and not
+            // at all on whether the account exists.
+            if (error instanceof TooBusy) {
+                const problem = new Problem({
+                    type: 'https://nacre.work/errors/unavailable',
+                    title: 'Service unavailable',
+                    status: 503,
+                    detail: 'Too many sign-in attempts are being processed. Try again shortly.',
+                    instance,
+                    requestId,
+                });
+                send(res, problem.status, problem.toJSON(), requestId, { 'retry-after': '2' });
+                return;
+            }
+            throw error;
+        }
+        if (tokens === undefined) {
+            // Logged rather than audited, and the difference is not laziness. The
+            // audit log is per-organization; an address that matches no user belongs
+            // to no tenant, and giving that row an owner would put one
+            // organization's failed attempts into another's access log. A security
+            // team watching for password spraying wants this across the whole
+            // installation anyway, which is what a log line is.
+            //
+            // The address, never the password, and never how far the attempt got —
+            // "no such user" and "wrong password" must not be tellable apart from a
+            // log any more than from a response.
+            console.warn(JSON.stringify({ msg: 'sign-in refused', email: email.trim().toLowerCase(), request_id: requestId }));
+            refuse();
+            return;
+        }
+        // The successful one does have an organization to belong to, and it is the
+        // event that answers "who has been in here". Awaited: a lost audit event is
+        // worse than a slow response.
+        await options.audit.write({
+            orgId: tokens.orgId,
+            actor: `user:${tokens.userId}`,
+            action: 'login',
+            result: 'allow',
+            detail: {},
+            requestId,
+        });
+        send(res, 200, tokenJson(tokens), requestId);
+        return;
+    }
+    const token = body?.refresh_token;
+    if (typeof token !== 'string' || token === '') {
+        const problem = badRequest(instance, requestId, "'refresh_token' is required.");
+        send(res, problem.status, problem.toJSON(), requestId);
+        return;
+    }
+    if (instance === '/v1/auth/refresh') {
+        const tokens = await options.login.refresh(token);
+        if (tokens === undefined) {
+            refuse();
+            return;
+        }
+        send(res, 200, tokenJson(tokens), requestId);
+        return;
+    }
+    if (instance === '/v1/auth/logout') {
+        // 204 whether or not the token was live. Saying "that token did not exist"
+        // tells whoever is holding a stolen one whether it is still worth using.
+        await options.login.logout(token);
+        send(res, 204, null, requestId);
+        return;
+    }
+    const problem = notFound(instance, requestId);
+    send(res, problem.status, problem.toJSON(), requestId);
+}
+function tokenJson(tokens) {
+    return {
+        access_token: tokens.accessToken,
+        token_type: 'Bearer',
+        expires_in: tokens.expiresIn,
+        refresh_token: tokens.refreshToken,
+    };
+}
 export function createApi(options) {
     return createServer((req, res) => {
         void handle(req, res, options).catch(() => {
@@ -114,37 +447,146 @@ async function handle(req, res, options) {
     const url = new URL(req.url ?? '/', 'http://localhost');
     const instance = url.pathname;
     if (req.method === 'GET' && instance === '/metrics') {
-        // Unauthenticated, like every Prometheus endpoint, and therefore carrying
-        // nothing that is not already a count. No document ids, no query text, no
-        // organization ids — organizations appear by slug, which is in the URL of
-        // every request that tenant makes anyway.
+        // Unauthenticated by default, like every Prometheus endpoint, and therefore
+        // carrying nothing that is not already a count. No document ids, no query
+        // text, no organization ids — organizations appear by slug, which is in the
+        // URL of every request that tenant makes anyway.
+        //
+        // A token is available and off unless configured. Requiring one would break
+        // every existing scrape config for a product people self-host, and the
+        // default is right for the deployment this is designed around: the port is
+        // on an internal network. It stops being right the moment somebody puts the
+        // API behind a public ingress without carving this path out, which is a
+        // thing that happens — so `NACRE_METRICS_TOKEN` exists for the operator who
+        // knows they are in that situation. See docs/config.md.
         if (options.metrics === undefined) {
             const problem = notFound(instance, requestId);
             send(res, problem.status, problem.toJSON(), requestId);
             return;
         }
+        if (options.metricsToken !== undefined) {
+            const header = req.headers.authorization;
+            const presented = header?.startsWith('Bearer ') === true ? header.slice(7) : undefined;
+            // Constant time, and length-checked first because timingSafeEqual throws
+            // on a mismatch. A scrape token is a credential like any other.
+            const expected = Buffer.from(options.metricsToken, 'utf8');
+            const given = Buffer.from(presented ?? '', 'utf8');
+            if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+                // 404 rather than 401, for the same reason invariant 4 gives: a
+                // deployment that hides its metrics endpoint should not confirm it has
+                // one. There is nothing to authenticate *into* here, so a challenge
+                // would only say "keep guessing".
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+        }
         const body = await options.metrics.render();
         res.writeHead(200, { 'content-type': 'text/plain; version=0.0.4; charset=utf-8' });
         res.end(body);
         return;
     }
+    if (req.method === 'GET' && instance === PROTECTED_RESOURCE_PATH) {
+        // RFC 9728 discovery, and unauthenticated by definition: it is what a
+        // client reads *because* it has no credential yet. Every 401 from the MCP
+        // transport names this path in `WWW-Authenticate`, and nothing served it —
+        // so a client doing exactly what the header told it to got a 404.
+        //
+        // Absent means the deployment did not configure a canonical URL, which
+        // cannot happen: it is required at startup.
+        if (options.resourceMetadata === undefined) {
+            const problem = notFound(instance, requestId);
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        send(res, 200, options.resourceMetadata, requestId);
+        return;
+    }
     if (req.method === 'GET' && instance === '/v1/health') {
         // Liveness touches no dependency. A health check that calls Postgres turns
         // one slow database into a cascading restart loop.
         send(res, 200, { status: 'ok' }, requestId);
         return;
     }
+    if (req.method === 'GET' && instance === '/v1/ready') {
+        // Readiness, which is the opposite of liveness and touches everything this
+        // process cannot serve a request without.
+        //
+        // `docs/config.md` has told operators to point a Kubernetes readinessProbe
+        // here since before there was a server, and the path answered `401` — it
+        // fell through to the authenticator, so the probe never succeeded and the
+        // rollout never completed. Unauthenticated for the same reason `/metrics`
+        // is: a probe has no credential to present, and the body says only which
+        // dependency is unhappy, never why.
+        //
+        // `503` rather than `200` with a body to parse. An orchestrator reads the
+        // status code, and a readiness endpoint that answers 200 while saying it is
+        // not ready is a readiness endpoint that does nothing.
+        if (options.ready === undefined) {
+            const problem = notFound(instance, requestId);
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        const checks = await options.ready();
+        const ok = Object.values(checks).every(Boolean);
+        send(res, ok ? 200 : 503, { status: ok ? 'ready' : 'not ready', checks }, requestId);
+        return;
+    }
+    // Sign-in, before authentication, because it is what produces the credential
+    // everything below this line requires.
+    //
+    // `rejectTenantOverride` does not apply here and must not: it refuses a body
+    // naming an organization, and naming one is exactly what a login on a
+    // multi-organization installation is allowed to do. The invariant is kept a
+    // different way — see login.ts. The organization in the issued token comes
+    // from the row that authenticated, never from the request.
+    if (instance.startsWith('/v1/auth/')) {
+        await handleAuth(req, res, instance, requestId, options);
+        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.
+        //
+        // `authenticate` answers one 401 with one message for every reason, on
+        // purpose — "revoked key" and "wrong audience" and "expired" must not be
+        // tellable apart by a caller. A label carrying the reason would put that
+        // distinction back on an endpoint that is unauthenticated by default, so
+        // this counts the *kind of credential* instead, which is what an operator
+        // actually needs and what no caller learns anything from.
+        //
+        // Rotating the signing key is the case it exists for: every outstanding
+        // access token 401s at once and there is no dual-key window, so an operator
+        // needs to watch that spike drain. Nothing here logs requests, so before
+        // this there was no way to see it at all.
+        const presented = req.headers.authorization;
+        const kind = presented === undefined || !presented.startsWith('Bearer ')
+            ? 'missing'
+            : presented.slice(7).startsWith('nacre_sk_')
+                ? 'service_key'
+                : 'jwt';
+        options.observe?.authFailures.inc({ kind });
         send(res, auth.status, auth.toJSON(), requestId);
         return;
     }
     let body;
     try {
-        body = await readBody(req);
+        body = await readBody(req, options.maxBodyBytes ?? MAX_BODY_BYTES);
     }
-    catch {
-        const problem = badRequest(instance, requestId, 'The request body could not be read.');
+    catch (error) {
+        // 413 for size and 400 for anything else. They were one answer, and the
+        // message said neither — a caller over the limit was told their body could
+        // not be read, which is true and useless.
+        const problem = error instanceof BodyTooLarge
+            ? new Problem({
+                type: 'https://nacre.work/errors/payload-too-large',
+                title: 'Payload too large',
+                status: 413,
+                detail: `The request body is over the ${options.maxBodyBytes ?? MAX_BODY_BYTES} byte limit set by NACRE_MAX_DOCUMENT_BYTES.`,
+                instance,
+                requestId,
+            })
+            : badRequest(instance, requestId, 'The request body could not be read.');
         send(res, problem.status, problem.toJSON(), requestId);
         return;
     }
@@ -163,21 +605,160 @@ async function handle(req, res, options) {
         send(res, override.status, override.toJSON(), requestId);
         return;
     }
+    // Rate limiting, after the token is verified and before any work is done.
+    //
+    // After verification because the limit is per organization and the
+    // organization comes from the token — there is nothing to count against
+    // until it has been read. Before the handler because the point is to refuse
+    // before spending an embedding call.
+    //
+    // The headers go on the successful response too. A client that only learns
+    // its budget by being refused has to be refused to learn it.
+    let rateHeaders = {};
+    const resource = resourceFor(req.method ?? 'GET', instance);
+    if (resource !== undefined && options.limits !== undefined && options.limitPolicies !== undefined) {
+        const decision = await options.limits.check(auth.orgId, resource);
+        rateHeaders = limitHeaders(decision, options.limitPolicies[resource], resource);
+        if (!decision.allowed) {
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'rate_limited',
+                result: 'deny',
+                detail: { resource, limit: decision.limit },
+                requestId,
+            });
+            const problem = new Problem({
+                type: 'https://nacre.work/errors/rate-limited',
+                title: 'Too many requests',
+                status: 429,
+                detail: `The ${resource} limit for this organization is ${decision.limit} per ${options.limitPolicies[resource].windowSeconds} seconds. Try again in ${decision.reset} seconds.`,
+                instance,
+                requestId,
+            });
+            send(res, problem.status, problem.toJSON(), requestId, rateHeaders);
+            return;
+        }
+    }
+    // Idempotency-Key, for the unsafe methods that are not already idempotent.
+    const idempotencyKey = req.headers['idempotency-key'];
+    let storeIdempotent;
+    if (typeof idempotencyKey === 'string' &&
+        idempotencyKey.length > 0 &&
+        options.idempotency !== undefined &&
+        ['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method ?? '') &&
+        !neverCached(instance)) {
+        const outcome = await options.idempotency.begin(idempotencyKey, 
+        // The principal, not just the organization. Two principals in one tenant
+        // see different things, so a response cached for one must never be
+        // replayed to another — a replay is sent before any handler runs, so
+        // there is no permission check left to catch it.
+        { orgId: auth.orgId, type: auth.principal.type, id: auth.principal.id }, req.method ?? '', instance, body);
+        if (isReplay(outcome)) {
+            // `send` drops the body on a 204, so a replayed delete replays as a
+            // delete rather than as a 204 with `null` in it.
+            send(res, outcome.cached.status, outcome.cached.body, requestId, {
+                ...rateHeaders,
+                'idempotency-replayed': 'true',
+            });
+            return;
+        }
+        if (isConflict(outcome)) {
+            // The same key with a different body, or the first attempt still running.
+            // Replaying a response that does not match what was asked for — or does
+            // not exist yet — is worse than saying so.
+            const problem = new Problem({
+                type: 'https://nacre.work/errors/conflict',
+                title: 'Conflict',
+                status: 409,
+                detail: 'This Idempotency-Key is in use for a different request, or the first ' +
+                    'attempt has not finished. Use a new key, or retry the identical request.',
+                instance,
+                requestId,
+            });
+            send(res, problem.status, problem.toJSON(), requestId, rateHeaders);
+            return;
+        }
+        storeIdempotent = outcome.store;
+    }
+    // The response is decorated rather than every `send` call being rewritten.
+    //
+    // Thirty handlers each remembering to attach rate headers and to cache their
+    // body is thirty chances to forget, and the one that forgets is invisible
+    // until a client asks why its budget headers vanished on one endpoint. This
+    // patches `writeHead` and `end` once, so the handlers stay unaware.
+    decorate(res, rateHeaders, storeIdempotent);
     try {
         if (req.method === 'POST' && instance === '/v1/search') {
-            const query = body?.query;
-            const topK = body?.top_k;
+            const request = (body ?? {});
+            const query = request.query;
             if (typeof query !== 'string' || query.length === 0) {
                 const problem = badRequest(instance, requestId, "'query' is required.");
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            const results = await options.search.search(auth, query, typeof topK === 'number' ? topK : 10);
+            if (request.layers !== undefined && !isStringArray(request.layers)) {
+                const problem = badRequest(instance, requestId, "'layers' must be an array of layer slugs.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // Narrowing, and only ever narrowing.
+            //
+            // `filters` was in the contract from before there was a server and read
+            // by nothing, then refused with 400 rather than ignored — because a
+            // caller who filters a search and gets everything back believes they
+            // scoped it. It is applied now, and the shape it is applied in is the
+            // point: it never becomes a filter the caller assembled. `buildFilter`
+            // turns each entry into a `must` on a namespaced payload key alongside
+            // the permission constraint, so the only thing a filter can do is remove
+            // results the caller was already permitted to see.
+            let filters;
+            try {
+                filters = parseFilters(request.filters);
+            }
+            catch (error) {
+                const problem = badRequest(instance, requestId, error instanceof MetadataError ? error.message : "'filters' is not usable.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const started = process.hrtime.bigint();
+            const results = await options.search.search(auth, query, boundedTopK(request.top_k), {
+                ...(Object.keys(filters).length === 0 ? {} : { filters }),
+                // Only ever a way to turn it off; a deployment with no reranker
+                // configured does not acquire one because a client asked.
+                ...(request.rerank === false ? { rerank: false } : {}),
+                ...(isStringArray(request.layers) && request.layers.length > 0
+                    ? { layers: request.layers }
+                    : {}),
+                ...(request.include_content === false ? { includeContent: false } : {}),
+            });
+            // Measured around the whole thing — resolve, embed, traverse, hydrate,
+            // rerank — because that is what a caller waits for and what the p95
+            // target in docs/config.md is about. It was never observed at all, so the
+            // histogram rendered no series and the target was unmeasurable.
+            options.observe?.searchDuration.observe(Number(process.hrtime.bigint() - started) / 1e9);
+            options.observe?.searchResults.inc({}, results.length);
+            if (results.length === 0) {
+                // Zero permitted results is what a denial looks like on this endpoint:
+                // there is no 403 to count, by design. Without it the denial counter sat
+                // at zero forever, which reads as "nobody is being refused".
+                options.observe?.aclDenials.inc({ reason: 'search_empty' });
+            }
             await options.audit.write({
                 orgId: auth.orgId,
                 actor: `${auth.principal.type}:${auth.principal.id}`,
                 action: 'search',
                 result: 'allow',
+                // `docs/audit.md` opens by promising that "show me which documents your
+                // agent read last quarter has to get a precise answer". That needs the
+                // ids, and this wrote a count. The query text is deliberately still not
+                // here — CLAUDE.md forbids logging it, and `NACRE_AUDIT_QUERY_TEXT`
+                // exists for deployments that decide otherwise.
+                target: {
+                    returned_docs: [...new Set(results.map((r) => r.doc_id))],
+                    layers: [...new Set(results.map((r) => r.layer))],
+                    top_k: boundedTopK(request.top_k),
+                },
                 detail: { returned: results.length },
                 requestId,
             });
@@ -202,14 +783,37 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
+            // Declared in openapi.yaml with no caveat and read by nothing until now,
+            // which made it the quietest of the parameters that were: a caller tagged
+            // a document, got 202, and the tag existed nowhere. Refused rather than
+            // trimmed when it is malformed — a dropped key is a document the caller
+            // believes is tagged and a filter that will never match it.
+            let metadata;
+            try {
+                metadata = parseMetadata(body_.metadata);
+            }
+            catch (error) {
+                const problem = badRequest(instance, requestId, error instanceof MetadataError ? error.message : "'metadata' is not usable.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const queuedAt = process.hrtime.bigint();
             const outcome = await options.ingest.queue(auth, {
                 layer,
                 externalId,
                 ...(typeof body_.title === 'string' ? { title: body_.title } : {}),
                 ...(typeof content === 'string' ? { content } : {}),
                 ...(typeof url_ === 'string' ? { url: url_ } : {}),
+                metadata,
+            });
+            // The accept stage only — parse, chunk and embed happen in the worker,
+            // which has no registry of its own. Labelled so the rest can join it
+            // later without changing the metric's meaning.
+            options.observe?.ingestDuration.observe(Number(process.hrtime.bigint() - queuedAt) / 1e9, {
+                stage: 'accept',
             });
             if (outcome === undefined) {
+                options.observe?.aclDenials.inc({ reason: 'ingest_layer' });
                 // Not 403. A caller without write access must not learn which layers
                 // exist by seeing which ones refuse differently from which ones are
                 // absent.
@@ -218,6 +822,7 @@ async function handle(req, res, options) {
                     actor: `${auth.principal.type}:${auth.principal.id}`,
                     action: 'ingest',
                     result: 'deny',
+                    target: { layer },
                     detail: { layer },
                     requestId,
                 });
@@ -230,6 +835,7 @@ async function handle(req, res, options) {
                 actor: `${auth.principal.type}:${auth.principal.id}`,
                 action: 'ingest',
                 result: 'allow',
+                target: { layer, document_id: outcome.documentId },
                 detail: { document_id: outcome.documentId, unchanged: outcome.unchanged },
                 requestId,
             });
@@ -248,6 +854,7 @@ async function handle(req, res, options) {
                 actor: `${auth.principal.type}:${auth.principal.id}`,
                 action: 'delete_document',
                 result: removed ? 'allow' : 'deny',
+                target: { document_id: id },
                 detail: { document_id: id },
                 requestId,
             });
@@ -256,8 +863,54 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            res.writeHead(204, { 'x-request-id': requestId });
-            res.end();
+            send(res, 204, null, requestId);
+            return;
+        }
+        if (req.method === 'PATCH' && documentMatch) {
+            const id = decodeURIComponent(documentMatch[1]);
+            if (options.documents.updateMetadata === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const body_ = (body ?? {});
+            if (body_.metadata === undefined) {
+                const problem = badRequest(instance, requestId, "'metadata' is required. It is the only field this endpoint changes: " +
+                    'content goes through POST /v1/documents, which re-indexes.');
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            let patch;
+            try {
+                patch = parseMetadata(body_.metadata);
+            }
+            catch (error) {
+                const problem = badRequest(instance, requestId, error instanceof MetadataError ? error.message : "'metadata' is not usable.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const updated = await options.documents.updateMetadata(auth, id, patch);
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'update_metadata',
+                result: updated ? 'allow' : 'deny',
+                target: { document_id: id },
+                // The keys, never the values. A tag can carry anything a caller puts in
+                // it, and the journal is read by more people than the document is.
+                detail: { document_id: id, keys: Object.keys(patch).sort() },
+                requestId,
+            });
+            if (!updated) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // 204, not the updated document. Rule 6: `write` does not imply `read`,
+            // so a caller who may retag a document and not read it must not learn its
+            // title or its layer from a successful PATCH. `GET` is where the document
+            // is, for whoever may see it.
+            send(res, 204, null, requestId);
             return;
         }
         if (req.method === 'GET' && documentMatch) {
@@ -272,6 +925,7 @@ async function handle(req, res, options) {
                     actor: `${auth.principal.type}:${auth.principal.id}`,
                     action: 'get_document',
                     result: 'deny',
+                    target: { document_id: id },
                     detail: { document_id: id },
                     requestId,
                 });
@@ -284,6 +938,7 @@ async function handle(req, res, options) {
                 actor: `${auth.principal.type}:${auth.principal.id}`,
                 action: 'get_document',
                 result: 'allow',
+                target: { document_id: id },
                 detail: { document_id: id },
                 requestId,
             });
@@ -310,12 +965,88 @@ async function handle(req, res, options) {
             }, requestId);
             return;
         }
+        if (instance === '/v1/workspaces' && options.workspaces !== 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.workspaces.list(auth, page);
+                // No audit event, for the same reason the layer listing has none: this
+                // returns what the caller may already reach, and one event per listing
+                // buries the ones that matter.
+                send(res, 200, {
+                    items: items.map((w) => ({
+                        id: w.id,
+                        slug: w.slug,
+                        name: w.name,
+                        layer_count: w.layerCount,
+                        created_at: w.createdAt,
+                    })),
+                    next_cursor: nextCursor,
+                }, requestId);
+                return;
+            }
+            if (req.method === 'POST') {
+                const body_ = (body ?? {});
+                const slug = body_.slug;
+                const name = body_.name;
+                if (typeof slug !== 'string' || typeof name !== 'string') {
+                    const problem = badRequest(instance, requestId, "'slug' and 'name' are required.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const outcome = await options.workspaces.create(auth, { slug, name });
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `${auth.principal.type}:${auth.principal.id}`,
+                    action: 'create_workspace',
+                    result: outcome.kind === 'created' ? 'allow' : 'deny',
+                    detail: { slug, outcome: outcome.kind },
+                    requestId,
+                });
+                if (outcome.kind === 'denied') {
+                    // 404, not 403. Whether an organization has workspaces a caller
+                    // cannot administer is not something they are told.
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                if (outcome.kind === 'conflict') {
+                    const problem = new Problem({
+                        type: 'https://nacre.work/errors/conflict',
+                        title: 'Conflict',
+                        status: 409,
+                        detail: `A workspace with the slug '${slug}' already exists in this organization.`,
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const created = outcome.workspace;
+                send(res, 201, {
+                    id: created.id,
+                    slug: created.slug,
+                    name: created.name,
+                    layer_count: created.layerCount,
+                    created_at: created.createdAt,
+                }, requestId);
+                return;
+            }
+        }
         if (req.method === 'GET' && instance === '/v1/layers' && options.layers !== undefined) {
-            const layers = await options.layers.list(auth);
+            const page = readPage(url.searchParams, instance, requestId);
+            if (page instanceof Problem) {
+                send(res, page.status, page.toJSON(), requestId);
+                return;
+            }
+            const { items, nextCursor } = await options.layers.list(auth, page);
             // No audit event: this returns what the caller may already read, and one
             // event per listing buries the ones that matter.
             send(res, 200, {
-                items: layers.map((l) => ({
+                items: items.map((l) => ({
                     id: l.id,
                     slug: l.slug,
                     name: l.name,
@@ -323,6 +1054,7 @@ async function handle(req, res, options) {
                     description: l.description,
                     document_count: l.documentCount,
                 })),
+                next_cursor: nextCursor,
             }, requestId);
             return;
         }
@@ -336,7 +1068,18 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            const outcome = await options.layers.create(auth, { workspaceId, slug, name });
+            const providerId = body_.provider_id;
+            if (providerId !== undefined && (typeof providerId !== 'string' || !/^[0-9a-f-]{36}$/i.test(providerId))) {
+                const problem = badRequest(instance, requestId, "'provider_id' must be a uuid.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const outcome = await options.layers.create(auth, {
+                workspaceId,
+                slug,
+                name,
+                ...(providerId === undefined ? {} : { providerId }),
+            });
             await options.audit.write({
                 orgId: auth.orgId,
                 actor: `${auth.principal.type}:${auth.principal.id}`,
@@ -352,6 +1095,11 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
+            if (outcome.kind === 'provider') {
+                const problem = badRequest(instance, requestId, outcome.detail);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
             if (outcome.kind === 'conflict') {
                 const problem = new Problem({
                     type: 'https://nacre.work/errors/conflict',
@@ -376,8 +1124,13 @@ async function handle(req, res, options) {
             return;
         }
         if (req.method === 'GET' && instance === '/v1/grants' && options.grants !== undefined) {
-            const grants = await options.grants.list(auth);
-            send(res, 200, { items: grants.map(grantJson) }, requestId);
+            const page = readPage(url.searchParams, instance, requestId);
+            if (page instanceof Problem) {
+                send(res, page.status, page.toJSON(), requestId);
+                return;
+            }
+            const { items, nextCursor } = await options.grants.list(auth, page);
+            send(res, 200, { items: items.map(grantJson), next_cursor: nextCursor }, requestId);
             return;
         }
         if (req.method === 'POST' && instance === '/v1/grants' && options.grants !== undefined) {
@@ -435,6 +1188,234 @@ async function handle(req, res, options) {
             send(res, 204, null, requestId);
             return;
         }
+        const layerMatch = /^\/v1\/layers\/([0-9a-f-]{36})$/i.exec(instance);
+        if (req.method === 'PATCH' && layerMatch !== null) {
+            const layerId = layerMatch[1];
+            if (options.layers?.update === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const body_ = (body ?? {});
+            const name = body_.name;
+            const description = body_.description;
+            if (name !== undefined && typeof name !== 'string') {
+                const problem = badRequest(instance, requestId, "'name' must be a string.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (description !== undefined && typeof description !== 'string') {
+                const problem = badRequest(instance, requestId, "'description' must be a string.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (name === undefined && description === undefined) {
+                const problem = badRequest(instance, requestId, "One of 'name' or 'description' is required. The slug is not editable — " +
+                    'clients address a layer by it — and the embedding model changes through ' +
+                    'POST /v1/layers/{id}/reindex, which rebuilds the vectors.');
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const updated = await options.layers.update(auth, layerId, {
+                ...(typeof name === 'string' ? { name } : {}),
+                ...(typeof description === 'string' ? { description } : {}),
+            });
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'update_layer',
+                result: updated ? 'allow' : 'deny',
+                target: { layer_id: layerId },
+                detail: { layer_id: layerId, fields: Object.keys(body_).sort() },
+                requestId,
+            });
+            if (!updated) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            send(res, 204, null, requestId);
+            return;
+        }
+        // `/v1/layers/{id}/reindex`
+        const reindexPath = /^\/v1\/layers\/([0-9a-f-]{36})\/reindex$/i.exec(instance);
+        if (reindexPath !== null) {
+            const layerId = reindexPath[1];
+            if (options.reindex === undefined || (req.method !== 'POST' && req.method !== 'GET')) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (req.method === 'GET') {
+                const status = await options.reindex.status(auth, layerId);
+                if (status === undefined) {
+                    // No reindex, no such layer, and no permission are one answer. The
+                    // first is not a permission fact and the other two must not be
+                    // separable, so all three are 404 — see invariant 4.
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                send(res, 200, reindexJson(status), requestId);
+                return;
+            }
+            const providerId = body?.provider_id;
+            if (typeof providerId !== 'string' || !/^[0-9a-f-]{36}$/i.test(providerId)) {
+                const problem = badRequest(instance, requestId, "'provider_id' must be a uuid.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const outcome = await options.reindex.start(auth, layerId, providerId);
+            if (outcome === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (outcome.kind === 'unknown_provider') {
+                // 400 and not 404: the caller has already proved they administer this
+                // layer, so this is a statement about their request rather than about
+                // what exists. A provider is installation-level configuration, not a
+                // tenant object with visibility rules of its own.
+                const problem = badRequest(instance, requestId, 'No embedding provider with that id is available to this organization.');
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (outcome.kind === 'already_current') {
+                const problem = badRequest(instance, requestId, `This layer already uses ${outcome.vectorName}. Reindexing onto the model it ` +
+                    'is on would rewrite every vector to the same values.');
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (outcome.kind === 'conflict') {
+                const problem = new Problem({
+                    type: 'https://nacre.work/errors/conflict',
+                    title: 'Conflict',
+                    status: 409,
+                    detail: `A reindex onto ${outcome.status.shadowVector} is already running for this layer. ` +
+                        'Wait for it, or let it fail — two at once would race to switch vector_name.',
+                    instance,
+                    requestId,
+                });
+                // The problem body and not the status object: a 409 is an error
+                // response and RFC 9457 says what shape one has. `GET` on this same
+                // path is where the state lives, and the detail above names what to
+                // wait for.
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            await options.audit?.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'layer.reindex',
+                result: 'allow',
+                surface: 'api',
+                target: { layer_id: layerId, shadow_vector: outcome.status.shadowVector },
+                detail: { provider_id: providerId, total: outcome.status.total },
+                requestId,
+            });
+            // 202: the work happens in the worker. docs/api.md says an operation that
+            // outlives its request answers 202 with somewhere to poll, which is this
+            // same path with GET.
+            send(res, 202, reindexJson(outcome.status), requestId);
+            return;
+        }
+        if (instance === '/v1/audit') {
+            // 404 rather than 403 for a caller who may not read it, and rather than
+            // 405 for a method this path does not have. Invariant 4 reserves 403 for
+            // an operation forbidden on an object the caller can already see, and
+            // whether an organization keeps an audit log is not something a member is
+            // told. The contract published this answer before the endpoint existed.
+            if (options.auditReader === undefined || req.method !== 'GET') {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            // Two roles, two different logs, and the difference is rule 2 rather than
+            // a convenience.
+            //
+            // `org_admin` administers the tenant and sees its log in full — including
+            // which documents were read, which is the question docs/audit.md opens
+            // with. `platform_admin` administers the *installation*: it sees grants
+            // issued, accounts created, configuration changed, and deliberately not
+            // the record of who read what. A platform administrator who can read
+            // every tenant's document-access log has the access the permission model
+            // spends its whole effort denying, obtained through the journal that
+            // exists to prove they did not.
+            //
+            // On a single-organization community install the two sit in the same
+            // organization and this reads as an odd distinction. It is not for this
+            // 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') {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const page = readPage(url.searchParams, instance, requestId);
+            if (page instanceof Problem) {
+                send(res, page.status, page.toJSON(), requestId);
+                return;
+            }
+            const query = readAuditQuery(url.searchParams, instance, requestId);
+            if (query instanceof Problem) {
+                send(res, query.status, query.toJSON(), requestId);
+                return;
+            }
+            const format = auditFormat(req.headers.accept);
+            if (format === undefined) {
+                const problem = new Problem({
+                    type: 'https://nacre.work/errors/not-acceptable',
+                    title: 'Not acceptable',
+                    status: 406,
+                    detail: 'This endpoint serves application/json, application/x-ndjson and text/csv. ' +
+                        'Ask for one of those, or send no Accept header for JSON.',
+                    instance,
+                    requestId,
+                });
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const { items, nextCursor } = await options.auditReader.read(auth, 
+            // `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);
+            // 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
+            // guarantee this endpoint exists to provide.
+            await options.audit?.write({
+                orgId: auth.orgId,
+                actor: `${auth.principal.type}:${auth.principal.id}`,
+                action: 'audit.read',
+                result: 'allow',
+                surface: 'api',
+                target: { format, returned: items.length, ...query },
+                detail: {},
+                requestId,
+            });
+            if (format === 'json') {
+                send(res, 200, { items: items.map(auditJson), next_cursor: nextCursor }, requestId);
+                return;
+            }
+            // JSONL and CSV are exports, so they carry no cursor — a client streaming
+            // to a file has nowhere to put one. `Link` is where the contract puts it,
+            // which keeps the body a clean stream of records rather than a stream
+            // with a footer that every consumer has to know to strip.
+            const headers = {
+                'content-type': format === 'ndjson' ? 'application/x-ndjson' : 'text/csv; charset=utf-8',
+                'x-request-id': requestId,
+            };
+            if (nextCursor !== null) {
+                const next = new URL(url.href);
+                next.searchParams.set('cursor', nextCursor);
+                headers.link = `<${next.pathname}${next.search}>; rel="next"`;
+            }
+            res.writeHead(200, headers);
+            res.end(format === 'ndjson' ? toNdjson(items) : toCsv(items));
+            return;
+        }
         if (instance === '/v1/service-accounts' && options.serviceAccounts !== undefined) {
             // org_admin, not "admin on some scope". A service account is a principal
             // in the organization rather than an object inside a workspace, and there
@@ -446,7 +1427,13 @@ async function handle(req, res, options) {
                 return;
             }
             if (req.method === 'GET') {
-                send(res, 200, { items: (await options.serviceAccounts.list(auth)).map(accountJson) }, requestId);
+                const page = readPage(url.searchParams, instance, requestId);
+                if (page instanceof Problem) {
+                    send(res, page.status, page.toJSON(), requestId);
+                    return;
+                }
+                const { items, nextCursor } = await options.serviceAccounts.list(auth, page);
+                send(res, 200, { items: items.map(accountJson), next_cursor: nextCursor }, requestId);
                 return;
             }
             if (req.method === 'POST') {
@@ -456,7 +1443,31 @@ async function handle(req, res, options) {
                     send(res, problem.status, problem.toJSON(), requestId);
                     return;
                 }
-                const { account, key } = await options.serviceAccounts.create(auth, name.trim());
+                const created = await options.serviceAccounts.create(auth, name.trim());
+                if (created === undefined) {
+                    // 409, not 500. The name is unique per organization and a duplicate
+                    // is something the caller typed — it surfaced as an internal error
+                    // with the constraint name in the log and nothing on screen.
+                    await options.audit.write({
+                        orgId: auth.orgId,
+                        actor: `${auth.principal.type}:${auth.principal.id}`,
+                        action: 'create_service_account',
+                        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 service account named '${name.trim()}' already exists in this organization.`,
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const { account, key } = created;
                 await options.audit.write({
                     orgId: auth.orgId,
                     actor: `${auth.principal.type}:${auth.principal.id}`,