@oxy.so/protocol 1.0.0

package/dist/esm/node/didWebResolver.js

@@ -0,0 +1,122 @@
+/**
+ * `createDidWebResolver` — a {@link VerificationMethodResolver} for arbitrary
+ * `did:web` subjects, backing the chain engine on multi-subject relay/ingest
+ * paths (where the signer is NOT a local account but any DID that publishes a
+ * DID document).
+ *
+ * It resolves a `did:web:<host>[:<path>]` subject to its `did.json`, fetched via
+ * an INJECTED {@link NodeFetch} — Oxy passes an adapter over `@oxy.so/core/server`
+ * `safeFetch` (so the SSRF/transport policy stays in core); a test passes a
+ * stub. The subject's current verification keys are read from the DID document's
+ * `verificationMethod[].publicKeyHex` (the active assertion methods), and the
+ * engine's `isAuthorizedKey` then applies the uniform self-issued rule.
+ *
+ * `did:web` → URL mapping (W3C did:web):
+ *  - `did:web:example.com`        → `https://example.com/.well-known/did.json`
+ *  - `did:web:example.com:u:123`  → `https://example.com/u/123/did.json`
+ *  - a `%3A` in the host segment is decoded to `:` (an explicit port).
+ */
+import { didDocumentSchema, } from '@oxy.so/contracts';
+import { readBoundedJson } from './httpFetch.js';
+import { DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_DID_DOC_MAX_BYTES, } from './constants.js';
+/**
+ * Map a `did:web` DID to its `did.json` URL, or `null` when `did` is not a
+ * well-formed `did:web` identifier.
+ */
+export function didWebToUrl(did) {
+    const prefix = 'did:web:';
+    if (!did.startsWith(prefix)) {
+        return null;
+    }
+    const msi = did.slice(prefix.length);
+    if (msi.length === 0) {
+        return null;
+    }
+    const [domainPart, ...pathParts] = msi.split(':');
+    const host = domainPart.replace(/%3A/gi, ':');
+    if (host.length === 0 || host.includes('/')) {
+        return null;
+    }
+    const base = `https://${host}`;
+    if (pathParts.length === 0) {
+        return `${base}/.well-known/did.json`;
+    }
+    if (pathParts.some((part) => part.length === 0)) {
+        return null;
+    }
+    return `${base}/${pathParts.join('/')}/did.json`;
+}
+/** True for a secp256k1 verification method (carries `publicKeyHex`). */
+function isSecp256k1Vm(vm) {
+    return vm.type === 'EcdsaSecp256k1VerificationKey2019';
+}
+/**
+ * Collect the subject's current verification keys from its DID document: the
+ * `publicKeyHex` of every secp256k1 verification method referenced by
+ * `assertionMethod` (the keys that may sign assertions/records), deduped. Falls
+ * back to ALL secp256k1 `verificationMethod[]` keys when `assertionMethod`
+ * references nothing local. Non-secp256k1 methods (e.g. the atproto `Multikey`,
+ * which carries the SAME key in multibase form, not hex) are skipped — record
+ * signatures verify against the hex key.
+ */
+function collectCurrentPublicKeys(doc) {
+    const byId = new Map(doc.verificationMethod
+        .filter(isSecp256k1Vm)
+        .map((vm) => [vm.id, vm.publicKeyHex]));
+    const keys = [];
+    for (const id of doc.assertionMethod) {
+        const key = byId.get(id);
+        if (key && !keys.includes(key)) {
+            keys.push(key);
+        }
+    }
+    if (keys.length === 0) {
+        for (const key of byId.values()) {
+            if (!keys.includes(key)) {
+                keys.push(key);
+            }
+        }
+    }
+    return keys;
+}
+/**
+ * Build a {@link VerificationMethodResolver} that resolves `did:web` subjects via
+ * the injected `fetch`. Returns `null` for any subject that is not a `did:web`
+ * DID, whose `did.json` cannot be fetched, or whose document fails schema
+ * validation — the engine then treats the signer as unauthorized.
+ */
+export function createDidWebResolver(fetch, options = {}) {
+    const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
+    const maxBytes = options.maxBytes ?? DEFAULT_DID_DOC_MAX_BYTES;
+    return {
+        async resolve(subjectDid) {
+            const url = didWebToUrl(subjectDid);
+            if (!url) {
+                return null;
+            }
+            try {
+                const res = await fetch(url, { method: 'GET', headersTimeoutMs, maxRedirects });
+                if (res.status < 200 || res.status >= 300) {
+                    res.destroy();
+                    return null;
+                }
+                const body = await readBoundedJson(res, maxBytes);
+                const parsed = didDocumentSchema.safeParse(body);
+                if (!parsed.success) {
+                    return null;
+                }
+                // The DID document `id` MUST match the subject we asked for — a document
+                // served at the subject's URL but claiming another id is not authoritative.
+                if (parsed.data.id !== subjectDid) {
+                    return null;
+                }
+                return { currentPublicKeys: collectCurrentPublicKeys(parsed.data) };
+            }
+            catch (err) {
+                options.onError?.(err, subjectDid);
+                return null;
+            }
+        },
+    };
+}

package/dist/esm/node/httpFetch.js

@@ -0,0 +1,55 @@
+/**
+ * The injected HTTP transport the node {@link ./nodeClient.NodeClient} and the
+ * {@link ./didWebResolver} drive — plus the bounded-read helpers that make a
+ * response stream safe to consume.
+ *
+ * The protocol package is app-agnostic and MUST NOT depend on `@oxy.so/core`
+ * (core depends on protocol). So instead of importing `@oxy.so/core/server`'s
+ * `safeFetch` directly, the node client/resolver accept a {@link NodeFetch} —
+ * Oxy supplies an adapter over `safeFetch` (HTTPS-only, DNS-pinned, private-IP
+ * denylist, bounded redirects); a test supplies an in-process stub. Either way
+ * the SSRF/transport policy stays in the injected implementation, and the
+ * bounded body read (the cap that stops a malicious node streaming forever)
+ * stays here, close to the parsing.
+ *
+ * A Node `IncomingMessage` (what `safeFetch` returns) satisfies
+ * {@link NodeFetchResponse.body} directly — it is an `AsyncIterable<Buffer>`,
+ * and `Buffer` is a `Uint8Array`.
+ */
+/** Thrown when a response body exceeds the caller's byte ceiling. */
+export class ResponseTooLargeError extends Error {
+    constructor(maxBytes) {
+        super(`response exceeded ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = 'ResponseTooLargeError';
+    }
+}
+/**
+ * Read a response body into a single buffer, aborting (and destroying the
+ * stream) the moment it exceeds `maxBytes`. The bound is the defence against a
+ * node that streams an unbounded body.
+ */
+export async function readBoundedBytes(res, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of res.body) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buf.length;
+            if (total > maxBytes) {
+                throw new ResponseTooLargeError(maxBytes);
+            }
+            chunks.push(buf);
+        }
+    }
+    catch (err) {
+        res.destroy();
+        throw err;
+    }
+    return Buffer.concat(chunks);
+}
+/** Read a bounded response body and parse it as JSON. */
+export async function readBoundedJson(res, maxBytes) {
+    const bytes = await readBoundedBytes(res, maxBytes);
+    return JSON.parse(bytes.toString('utf8'));
+}

package/dist/esm/node/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@oxy.so/protocol/node` — the runnable node substrate.
+ *
+ * The Node-only half of the protocol: the Express app factory that backs any
+ * Oxy-protocol data node ({@link createNodeApp}), the HTTP {@link NodeClient}
+ * that drives a node's routes, the `did:web` verification-method resolver, the
+ * record verifier, and the node-protocol shape constants. A SEPARATE subpath
+ * from the package root so this Express/Node-only code never enters React
+ * Native / web bundles that import `@oxy.so/protocol`.
+ *
+ * Reused by `@oxy.so/node` (the runnable node), a future `mention-node` (an
+ * env-only deployment of the same base), and oxy-api's node sync (which drives
+ * a node via `NodeClient`).
+ */
+// ── Express app factory ───────────────────────────────────────────────────────
+export { createNodeApp, BlobHashMismatchError } from './nodeApp.js';
+// ── Per-IP write rate limiter ──────────────────────────────────────────────────
+export { createRateLimiter, DEFAULT_WRITE_RATE_LIMIT, DEFAULT_MAX_RATE_LIMIT_ENTRIES, } from './rateLimit.js';
+// ── Record verification (signature + v2 + content address) ─────────────────────
+export { verifyNodeRecordEnvelope } from './verifyRecord.js';
+// ── HTTP client ────────────────────────────────────────────────────────────────
+export { NodeClient, NodeClientError, trimTrailingSlashes } from './nodeClient.js';
+// ── Injected transport contract + bounded readers ──────────────────────────────
+export { readBoundedBytes, readBoundedJson, ResponseTooLargeError } from './httpFetch.js';
+// ── did:web verification-method resolver ───────────────────────────────────────
+export { createDidWebResolver, didWebToUrl } from './didWebResolver.js';
+// ── Node-protocol shape constants ──────────────────────────────────────────────
+export { PROTOCOL_VERSION, DEFAULT_WELL_KNOWN_PATH, DEFAULT_SERVICE_TYPE, DEFAULT_APP_NAMESPACE, DEFAULT_PORT, DEFAULT_LOG_LIMIT, MAX_LOG_LIMIT, DEFAULT_MAX_BLOB_BYTES, MAX_SYNC_BATCH, JSON_BODY_LIMIT, OWNER_AUTH_HEADERS, OWNER_AUTH_MAX_AGE_MS, NODE_MODES, OWNER_ACTION_BLOB_PIN, SHA256_HEX, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, NODE_BLOBS_PATH, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, DEFAULT_DID_DOC_MAX_BYTES, } from './constants.js';

package/dist/esm/node/nodeApp.js

@@ -0,0 +1,336 @@
+/**
+ * `createNodeApp` — the app-agnostic Express factory for an Oxy-protocol data
+ * node. A node stores and serves ONE owner's append-only signed-record log
+ * (their "personal repo") plus the content-addressed blobs the records point at.
+ *
+ * This is the engine extracted from `@oxy.so/node` so the SAME code can back many
+ * app-node deployments (the Oxy identity node, a future Mention node) that
+ * differ only by ENV: the namespace they serve, their well-known manifest path,
+ * their advertised protocol id + service-type, and their owner key. Everything
+ * app-specific is INJECTED:
+ *
+ *  - `store`     — a {@link RecordStore} + {@link BlobStore} (the node's SQLite
+ *                  store, or a test stub). The node holds exactly one subject's
+ *                  repo, so the store keys a single global chain and ignores the
+ *                  subject argument; `createNodeApp` passes the node's own key as
+ *                  a stable sentinel.
+ *  - `ownerAuth` — the single write authority. Records and blob pins are
+ *                  authorized against the node's configured owner key. This is
+ *                  injected (rather than importing `@oxy.so/core/server`) so the
+ *                  protocol package never depends on core.
+ *  - `config`    — the wire-shape knobs (well-known path, protocol id,
+ *                  service-type, mode, blob ceiling, collection allowlist).
+ *  - `logger`    — structured logging for the terminal error handler.
+ *
+ * Endpoints:
+ *  - `GET  <wellKnownPath>` — node identity + liveness (a probe target).
+ *  - `GET  /oxy/head`       — chain head `{ seq, headRecordId, recordCount }`.
+ *  - `GET  /oxy/log`        — ordered envelopes from a cursor (ingest).
+ *  - `POST /records`        — owner writes a single signed envelope.
+ *  - `POST /sync/push`      — owner pushes a batch of signed envelopes.
+ *  - `GET  /blobs/:hash`    — serve a content-addressed blob.
+ *  - `PUT  /blobs/:hash`    — owner pins a blob (signed-header auth).
+ *  - `GET  /health`         — container liveness.
+ */
+import express from 'express';
+import { computeRecordId } from '../envelope/recordId.js';
+import { createRateLimiter, DEFAULT_WRITE_RATE_LIMIT } from './rateLimit.js';
+import { verifyNodeRecordEnvelope } from './verifyRecord.js';
+import { DEFAULT_LOG_LIMIT, JSON_BODY_LIMIT, MAX_LOG_LIMIT, MAX_SYNC_BATCH, NODE_BLOBS_PATH, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, OWNER_AUTH_HEADERS, SHA256_HEX, } from './constants.js';
+/**
+ * Thrown by a {@link BlobStore.putBlob} implementation when bytes do not hash to
+ * the supplied address. Defined here (rather than in `@oxy.so/node`) so the node
+ * app can map it to `hash_mismatch` without importing the store implementation.
+ */
+export class BlobHashMismatchError extends Error {
+    constructor(expected, actual) {
+        super(`blob hash mismatch: expected ${expected}, computed ${actual}`);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'BlobHashMismatchError';
+    }
+}
+/**
+ * Coerce a raw Express query value (`string | string[] | ParsedQs | undefined`)
+ * to a single string. A repeated/array param (`?since[]=a&since[]=b`) yields a
+ * non-string under qs; take its first string element so a tampered array can
+ * never reach a `typeof === 'string'` check as a non-string and cause type
+ * confusion. Returns `undefined` for anything that is not a string or a
+ * string-first array.
+ */
+function firstQueryValue(raw) {
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (Array.isArray(raw) && raw.length > 0 && typeof raw[0] === 'string') {
+        return raw[0];
+    }
+    return undefined;
+}
+/** Clamp the `limit` query param into `[1, MAX_LOG_LIMIT]`, defaulting when absent/invalid. */
+function parseLimit(raw) {
+    const value = firstQueryValue(raw);
+    if (value === undefined || value.trim() === '') {
+        return DEFAULT_LOG_LIMIT;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return DEFAULT_LOG_LIMIT;
+    }
+    return Math.min(parsed, MAX_LOG_LIMIT);
+}
+/** HTTP status for a chain-append rejection. */
+function appendStatus(reason) {
+    return reason === 'chain_conflict' ? 409 : 422;
+}
+/** True when `collection` is writable under the node's allowlist (empty = all). */
+function isCollectionAllowed(config, collection) {
+    return config.collections.length === 0 || config.collections.includes(collection);
+}
+/**
+ * Resolve the `/oxy/log` `since` query param to an exclusive lower-bound `seq`.
+ * Returns `null` when the page should be EMPTY (an unknown `recordId` cursor or
+ * an unrecognized cursor shape). Mirrors the legacy in-store cursor resolver,
+ * now split across the protocol `RecordStore` (numeric `getLogSince` +
+ * `resolveCursorSeq`).
+ */
+async function resolveSinceSeq(store, subject, since) {
+    if (since === undefined || since === '') {
+        return -1;
+    }
+    const lower = since.toLowerCase();
+    if (SHA256_HEX.test(lower)) {
+        return store.resolveCursorSeq(subject, lower);
+    }
+    if (/^\d+$/.test(since)) {
+        const parsed = Number(since);
+        return Number.isSafeInteger(parsed) ? parsed : -1;
+    }
+    return null;
+}
+/** Map a stored envelope to the `/oxy/log` wire record. */
+async function toLogWireRecord(env) {
+    return {
+        seq: env.seq ?? 0,
+        recordId: await computeRecordId(env),
+        prev: env.prev ?? null,
+        issuedAt: env.issuedAt,
+        envelope: env,
+    };
+}
+export function createNodeApp(deps) {
+    const { store, config, ownerAuth, logger } = deps;
+    // The node holds one subject's repo; the store keys a single global chain and
+    // ignores the subject argument. Pass the node's own key as a stable sentinel.
+    const subject = config.nodePublicKey;
+    const app = express();
+    app.disable('x-powered-by');
+    // JSON parser applies only to JSON bodies (it checks Content-Type), so the raw
+    // blob upload below is untouched by it.
+    const jsonParser = express.json({ limit: JSON_BODY_LIMIT });
+    // Per-IP rate limiter on the owner-authorized write routes. Caps request rate
+    // BEFORE signature verification so a flood of bogus envelopes can't pin CPU.
+    // It owns a background sweep timer; expose its teardown as `app.stop()`.
+    const writeRateLimit = createRateLimiter(config.writeRateLimit ?? DEFAULT_WRITE_RATE_LIMIT);
+    app.stop = () => writeRateLimit.stop();
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok' });
+    });
+    // ── Node identity / liveness ────────────────────────────────────────────────
+    app.get(config.wellKnownPath, async (_req, res, next) => {
+        try {
+            const head = await store.getHead(subject);
+            res.json({
+                nodePublicKey: config.nodePublicKey,
+                mode: config.mode,
+                version: config.protocolId,
+                serviceType: config.serviceType,
+                head: head && head.headRecordId !== null ? { seq: head.seq, headRecordId: head.headRecordId } : null,
+            });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Chain head ──────────────────────────────────────────────────────────────
+    app.get(NODE_HEAD_PATH, async (_req, res, next) => {
+        try {
+            const head = await store.getHead(subject);
+            if (!head || head.headRecordId === null) {
+                res.json({ seq: null, headRecordId: null, recordCount: 0 });
+                return;
+            }
+            res.json({ seq: head.seq, headRecordId: head.headRecordId, recordCount: head.recordCount });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Ordered log (ingest) ──────────────────────────────────────────────────────
+    app.get(NODE_LOG_PATH, async (req, res, next) => {
+        try {
+            const since = firstQueryValue(req.query.since);
+            const limit = parseLimit(req.query.limit);
+            const head = await store.getHead(subject);
+            const headWire = head && head.headRecordId !== null ? { seq: head.seq, headRecordId: head.headRecordId } : null;
+            const sinceSeq = await resolveSinceSeq(store, subject, since);
+            if (sinceSeq === null) {
+                res.json({ records: [], count: 0, head: headWire });
+                return;
+            }
+            const envelopes = await store.getLogSince(subject, sinceSeq, limit);
+            const records = await Promise.all(envelopes.map(toLogWireRecord));
+            res.json({ records, count: records.length, head: headWire });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Owner write: a single signed envelope ────────────────────────────────────
+    app.post(NODE_RECORDS_PATH, writeRateLimit, jsonParser, async (req, res, next) => {
+        try {
+            const verification = await verifyNodeRecordEnvelope(req.body);
+            if (!verification.ok) {
+                res.status(400).json({ error: verification.reason });
+                return;
+            }
+            if (!ownerAuth.isOwnerKey(verification.envelope.publicKey)) {
+                res.status(403).json({ error: 'not_owner' });
+                return;
+            }
+            if (!isCollectionAllowed(config, verification.envelope.collection ?? '')) {
+                res.status(403).json({ error: 'foreign_collection' });
+                return;
+            }
+            const outcome = await store.append(subject, verification.envelope, verification.recordId);
+            if (!outcome.ok) {
+                res.status(appendStatus(outcome.reason)).json({ error: outcome.reason });
+                return;
+            }
+            res.status(201).json({ recordId: outcome.recordId, seq: outcome.seq });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Owner write: a batch push (verified + appended in order) ──────────────────
+    app.post(NODE_SYNC_PUSH_PATH, writeRateLimit, jsonParser, async (req, res, next) => {
+        try {
+            const body = req.body;
+            const items = typeof body === 'object' && body !== null && Array.isArray(body.records)
+                ? body.records
+                : null;
+            if (!items) {
+                res.status(400).json({ error: 'invalid_batch' });
+                return;
+            }
+            if (items.length > MAX_SYNC_BATCH) {
+                res.status(400).json({ error: 'batch_too_large' });
+                return;
+            }
+            const results = [];
+            for (const item of items) {
+                const verification = await verifyNodeRecordEnvelope(item);
+                if (!verification.ok) {
+                    results.push({ ok: false, reason: verification.reason });
+                    continue;
+                }
+                if (!ownerAuth.isOwnerKey(verification.envelope.publicKey)) {
+                    results.push({ ok: false, reason: 'not_owner' });
+                    continue;
+                }
+                if (!isCollectionAllowed(config, verification.envelope.collection ?? '')) {
+                    results.push({ ok: false, reason: 'foreign_collection' });
+                    continue;
+                }
+                const outcome = await store.append(subject, verification.envelope, verification.recordId);
+                results.push(outcome.ok
+                    ? { ok: true, recordId: outcome.recordId, seq: outcome.seq }
+                    : { ok: false, reason: outcome.reason });
+            }
+            const accepted = results.filter((result) => result.ok).length;
+            res.json({ accepted, results });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Serve a content-addressed blob ───────────────────────────────────────────
+    app.get(`${NODE_BLOBS_PATH}/:hash`, async (req, res, next) => {
+        try {
+            const hash = req.params.hash.toLowerCase();
+            if (!SHA256_HEX.test(hash)) {
+                res.status(400).json({ error: 'invalid_hash' });
+                return;
+            }
+            const bytes = await store.getBlob(hash);
+            if (!bytes) {
+                res.status(404).json({ error: 'not_found' });
+                return;
+            }
+            res.setHeader('Content-Type', 'application/octet-stream');
+            // Content-addressed → immutable, safe to cache aggressively.
+            res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+            res.send(Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Owner pins a blob (signed-header authorization) ──────────────────────────
+    app.put(`${NODE_BLOBS_PATH}/:hash`, writeRateLimit, express.raw({ type: () => true, limit: config.maxBlobBytes }), async (req, res, next) => {
+        try {
+            const rawHash = req.params.hash;
+            if (typeof rawHash !== 'string') {
+                res.status(400).json({ error: 'invalid_hash' });
+                return;
+            }
+            const hash = rawHash.toLowerCase();
+            if (!SHA256_HEX.test(hash)) {
+                res.status(400).json({ error: 'invalid_hash' });
+                return;
+            }
+            const publicKey = req.header(OWNER_AUTH_HEADERS.publicKey);
+            const signature = req.header(OWNER_AUTH_HEADERS.signature);
+            const timestampRaw = req.header(OWNER_AUTH_HEADERS.timestamp);
+            if (!publicKey || !signature || !timestampRaw) {
+                res.status(401).json({ error: 'missing_owner_auth' });
+                return;
+            }
+            const authorized = await ownerAuth.verifyBlobPin(hash, {
+                publicKey,
+                signature,
+                timestamp: Number(timestampRaw),
+            });
+            if (!authorized) {
+                res.status(403).json({ error: 'unauthorized' });
+                return;
+            }
+            const bytes = req.body;
+            if (!Buffer.isBuffer(bytes) || bytes.length === 0) {
+                res.status(400).json({ error: 'empty_blob' });
+                return;
+            }
+            try {
+                await store.putBlob(hash, bytes);
+            }
+            catch (error) {
+                if (error instanceof BlobHashMismatchError) {
+                    res.status(400).json({ error: 'hash_mismatch' });
+                    return;
+                }
+                throw error;
+            }
+            res.status(201).json({ hash, size: bytes.length });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // ── Terminal error handler ───────────────────────────────────────────────────
+    app.use((error, _req, res, _next) => {
+        logger.error({ err: error }, 'unhandled request error');
+        res.status(500).json({ error: 'internal_error' });
+    });
+    return app;
+}