@north-light/api 0.3.580 → 0.3.587

package/dist/daemon/api/router.js

@@ -0,0 +1,536 @@
+// The crtrd API router (spec §4.2). A tiny hand-rolled method+path matcher — no
+// framework, matching the CLI's no-dependency ethos (`core/command.ts` is a
+// hand-rolled path walker for the same reason).
+//
+// Routes are a flat table of `{ method, pattern, handler }`. A `pattern` like
+// `/v1/nodes/:id/messages` is matched by splitting both it and the request path
+// on '/'; a `:name` segment captures into `params`. `handle(req, res, ceiling)`
+// resolves the JSON body, dispatches to the matched handler, and wraps EVERY
+// handler so a thrown error becomes a JSON `ErrorBody` with the mapped status
+// (map.ts §8) — a handler throw NEVER crashes the daemon.
+//
+// The operation table authorizes caller class, scope, and resource before dispatch.
+//
+// The WS attach upgrade (`GET /v1/nodes/:id/attach` with `Upgrade: websocket`) is
+// NOT routed here — the server (A-9) owns the upgrade handshake and hands it to
+// `bridge.ts` (A-8). This router serves only non-upgrade HTTP requests.
+import { toErrorBody } from './map.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { scopeAllowed, ScopeDeniedError } from '../../core/scopes.js';
+import { coveredByAny } from '../../shared/env.js';
+import { ApiError } from '../../api/errors.js';
+import { activeGrant, activeGrantsOfPerson, grantFor } from '../../core/grants/mirror.js';
+import { getNode } from '../../core/canvas/canvas.js';
+import { ownedRun, RunError } from '../../core/runs/operations.js';
+import { openDb } from '../../core/canvas/db.js';
+import { check, permits } from '../../core/permissions/evaluator.js';
+import { readerFor } from './reader.js';
+import { checkCronFire } from '../cron/authority.js';
+import { operationFor } from './operations.js';
+import { CONTROL_BODY_MAX_BYTES } from '../../core/llm/body-limits.js';
+import { getRequest, getRequestByInboxTicket } from '../../core/human/requests.js';
+import { requireVisibleReview } from '../../core/review/store.js';
+import { getComment } from '../../core/review/comments.js';
+import { getStructuredRequest } from '../../core/canvas/structured-requests.js';
+async function authorizeHumanBody(operation, principal, params, query, body) {
+    const path = operation.path;
+    const fields = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    if (path === '/v1/human/requests' || path === '/v1/human/reviews') {
+        const origin = path.endsWith('/reviews') ? fields['origin_node_id'] : fields['requester_node_id'];
+        // A page with no reply route names no requester (`requester_node_id: null`): nothing is addressed to any node, and the
+        // handler rejects `delivery.reply` without a requester. A request naming a node must still name the caller.
+        const displayOnly = path === '/v1/human/requests' && (origin === undefined || origin === null);
+        if (origin !== principal.node && !displayOnly)
+            throw new ApiError(403, 'other_app_run', 'a broker may create a human request only for its own node');
+        const source = fields['source'];
+        if (source && typeof source === 'object' && 'nodeId' in source && source.nodeId !== principal.node)
+            throw new ApiError(403, 'other_app_run', 'request source must name the calling node');
+    }
+    if (path === '/v1/human/reviews/self/comments' && operation.method === 'GET' && query.get('actor_node_id') !== principal.node) {
+        throw new ApiError(403, 'other_app_run', 'self review requires the calling node');
+    }
+    if (path.includes('/comments') && operation.method !== 'GET' && fields['actor_node_id'] !== principal.node) {
+        throw new ApiError(403, 'other_app_run', 'comment author must be the calling node');
+    }
+    if (params['comment_id'] && !await getComment(params['comment_id']))
+        throw new ApiError(404, 'not_found', 'comment not found');
+}
+/** Classes whose stored scope list is a second ceiling and whose reach is confined to a run place. */
+function boundedByStoredScopes(principal) {
+    return principal.class === 'broker' || principal.class === 'cron';
+}
+/** The app a non-person caller acts as: a forwarded app actor's app, a forwarded person's terminal, null for the anonymous, a machine and the person. */
+export function appOf(principal) {
+    if (principal.class === 'person' || principal.class === 'anonymous' || principal.class === 'machine' || principal.class === 'import')
+        return null;
+    if (principal.class === 'forwarded')
+        return principal.actor.kind === 'app' ? principal.actor.app : null;
+    return principal.app;
+}
+/** Whether the caller is the install's person, who passes the schema alone: the local person (no `sub`), or a forwarded call the envelope
+ *  makes for the person. A person with a `sub` (a cloud role's directory person bearer) is one of many people and is confined by the evaluator. */
+export function actsAsPerson(principal) {
+    return (principal.class === 'person' && principal.sub === undefined) || (principal.class === 'forwarded' && principal.actor.kind === 'person');
+}
+/** The mirrored grant a forwarded app actor holds, or `403 app_not_granted`: fail closed when it is missing or revoked. */
+async function forwardedGrant(principal) {
+    const grant = await grantFor(principal.actor.app, principal.sub);
+    if (!grant)
+        throw new ApiError(403, 'app_not_granted', `${principal.actor.app} holds no active grant for ${principal.sub} on this machine`);
+    return grant;
+}
+export async function resolvedScopes(principal) {
+    // A cloud role's person (a directory bearer, `sub` set) holds the scopes of their own active grants; a Mac's person (no `sub`) passes the schema alone.
+    if (principal.class === 'person' && principal.sub !== undefined)
+        return (await activeGrantsOfPerson(principal.sub)).flatMap((grant) => grant.resolved);
+    if (principal.class === 'person' || principal.class === 'anonymous' || principal.class === 'machine' || principal.class === 'import')
+        return [];
+    if (principal.class === 'forwarded') {
+        if (principal.actor.kind === 'person')
+            return [];
+        const { resolved } = await forwardedGrant(principal);
+        const stored = principal.actor.node_scopes;
+        return stored === null ? resolved : stored.filter((scope) => coveredByAny(resolved, scope));
+    }
+    if (principal.class === 'app')
+        return principal.scopes;
+    if (principal.class === 'cron') {
+        // The cron authority check, re-run on every call: revocation answers `grant_revoked`, narrowing `scope_missing`.
+        const check = await checkCronFire({ grantee: principal.app, sub: principal.sub, grant_id: principal.grant, scopes: principal.scopes });
+        if (check.allowed)
+            return check.effectiveScopes;
+        if (check.reason === 'grant_missing' || check.reason === 'grant_revoked')
+            throw new ApiError(401, 'grant_revoked', check.message);
+        throw new ApiError(403, 'scope_missing', check.message);
+    }
+    const grant = principal.grant ? await activeGrant(principal.grant) : await grantFor(principal.app, principal.sub);
+    if (grant && grant.grantee === principal.app && grant.sub === principal.sub)
+        return grant.resolved;
+    throw new ApiError(401, 'grant_revoked', 'the node grant is not active');
+}
+export function runCallerApp(principal) {
+    return 'class' in principal ? appOf(principal) : principal.grantee;
+}
+/** The caller as a request principal: an app-token principal (the app listener's) is an app-server call under its grant. */
+function asRequestPrincipal(principal) {
+    return 'class' in principal ? principal : { class: 'app', app: principal.grantee, scopes: principal.resolved, sub: principal.sub };
+}
+/** Whether the caller holds `permission` on a node: the evaluator, with the caller's ceiling (own-app run confinement, `objects` and
+ *  `conversations` scopes, `objects:message`). A person caller passes the schema alone. */
+export async function mayOnNode(principal, permission, nodeId) {
+    const caller = asRequestPrincipal(principal);
+    if (actsAsPerson(caller))
+        return true;
+    if (caller.class === 'anonymous' || caller.class === 'machine' || caller.class === 'import')
+        return false;
+    const db = await openDb();
+    return await check(db, await readerFor(db, { principal: caller }), permission, nodeId);
+}
+/** The ids of the nodes the caller may read, in one query that embeds the evaluator's condition; null when the caller reads every node (the person). */
+export async function readableNodeIds(principal) {
+    if (actsAsPerson(principal))
+        return null;
+    if (principal.class === 'anonymous' || principal.class === 'machine' || principal.class === 'import')
+        return new Set();
+    const db = await openDb();
+    const may = await permits(db, await readerFor(db, { principal }), 'read');
+    const rows = await db.prepareUncached(`SELECT o.id FROM objects o WHERE o.type = 'node' AND o.deleted_at IS NULL AND ${may.sql}`).all(...may.params);
+    return new Set(rows.map((r) => r.id));
+}
+/** An app-wide question that names no node: own app, or the app-wide objects (`conversations`) read scope. */
+async function mayReadApp(principal, grantee, scope) {
+    const caller = asRequestPrincipal(principal);
+    if (actsAsPerson(caller))
+        return true;
+    if (caller.class === 'anonymous' || caller.class === 'machine' || caller.class === 'import')
+        return false;
+    if (appOf(caller) === grantee)
+        return true;
+    return scopeAllowed(await resolvedScopes(caller), scope) && (!boundedByStoredScopes(caller) || scopeAllowed(caller.scopes, scope));
+}
+export async function canReadRun(principal, grantee, target) {
+    return target === undefined ? await mayReadApp(principal, grantee, `crtr:conversations:read:${grantee}`) : await mayOnNode(principal, 'read', target);
+}
+export async function requireRun(principal, id, acting = false, allowDeleting = false) {
+    const root = await getNode(id);
+    if (!root || root.parent !== null || root.run_id !== id || !root.grantee || (root.deleting_at && !allowDeleting))
+        throw new RunError(404, 'not_found', 'run not found');
+    if (!await mayOnNode(principal, 'read', id))
+        throw new RunError(404, 'not_found', 'run not found');
+    if (acting && runCallerApp(principal) !== null && runCallerApp(principal) !== root.grantee) {
+        throw new RunError(403, 'other_app_run', 'cannot change another app\'s run');
+    }
+    return await ownedRun(id, root.grantee, allowDeleting);
+}
+export async function canReadNode(principal, grantee, target) {
+    return target === undefined ? await mayReadApp(principal, grantee, `crtr:objects:read:${grantee}`) : await mayOnNode(principal, 'read', target);
+}
+/** The node-write rows a holder of `crtr:objects:message:<grantee>` may use on another app's node; they ask `message`. Every other node-write row asks `read` on an own-app node. */
+const MESSAGE_ROWS = new Set(['messages.post.58', 'messages.post.59']);
+async function authorizeOperation(operation, principal, params) {
+    if (!operation.classes.includes(principal.class) && !(principal.class !== 'anonymous' && principal.class !== 'machine' && principal.class !== 'import' && principal.class !== 'forwarded' && operation.classes.includes('anonymous')))
+        throw new ApiError(403, 'permission_error', 'this operation is not available to the caller');
+    if (principal.class === 'forwarded' && principal.actor.kind === 'app')
+        await forwardedGrant(principal);
+    if (principal.class === 'anonymous' || principal.class === 'machine' || principal.class === 'import' || actsAsPerson(principal))
+        return;
+    if (principal.class === 'person')
+        return await authorizePersonNode(operation, principal, params);
+    const resolved = await resolvedScopes(principal);
+    if (operation.scope && (!scopeAllowed(resolved, operation.scope) ||
+        (boundedByStoredScopes(principal) && !scopeAllowed(principal.scopes, operation.scope)))) {
+        throw new ApiError(403, 'scope_missing', `missing scope ${operation.scope}`);
+    }
+    if (principal.class === 'app')
+        return;
+    const callerApp = appOf(principal);
+    if (principal.class === 'broker')
+        await authorizeBrokerOnly(operation, principal, params, resolved);
+    const id = params['id'];
+    if ((operation.resource === 'node-read' || operation.resource === 'node-write') && id !== undefined) {
+        const node = await getNode(id);
+        if (!node)
+            return; // Handler returns its ordinary not_found.
+        if (operation.resource === 'node-write') {
+            const message = MESSAGE_ROWS.has(operation.name);
+            if (node.grantee !== callerApp && !message)
+                throw new ApiError(403, 'other_app_run', 'cannot change another app\'s node');
+            if (!await mayOnNode(principal, message && node.grantee !== callerApp ? 'message' : 'read', id)) {
+                if (node.grantee !== callerApp)
+                    throw new ApiError(403, 'other_app_run', 'cannot change another app\'s node');
+                throw new ApiError(404, 'not_found', 'node not found');
+            }
+        }
+        if (operation.resource === 'node-read' && !await mayOnNode(principal, 'read', id)) {
+            throw new ApiError(404, 'not_found', 'node not found');
+        }
+    }
+}
+/** A person confined by its `sub` holds no scope and acts as no app, runs no shell on the daemon host and controls no daemon (the control plane is shared): a node row needs the evaluator's `read` (`message` for a message row). */
+async function authorizePersonNode(operation, principal, params) {
+    if (operation.resource === 'daemon-bash')
+        throw new ApiError(403, 'permission_error', 'a shell on the daemon host is not available to a person bearer');
+    if (operation.resource === 'daemon-control')
+        throw new ApiError(403, 'permission_error', 'restarting, migrating, admitting or draining the daemon is not available to a person bearer');
+    if (operation.resource === 'human')
+        return await authorizePersonHuman(operation, principal, params);
+    if (params['request_id'] !== undefined && operation.path.startsWith('/v1/structured-requests/'))
+        return await authorizePersonStructuredRequest(operation, principal, params['request_id']);
+    const id = params['id'];
+    if ((operation.resource !== 'node-read' && operation.resource !== 'node-write') || id === undefined || !await getNode(id))
+        return;
+    if (!await mayOnNode(principal, MESSAGE_ROWS.has(operation.name) ? 'message' : 'read', id))
+        throw new ApiError(404, 'not_found', 'node not found');
+}
+/** A named human request, ticket, review or comment belongs to the node that raised it: the person confined by its `sub` reads it with `read` on
+ *  that node and settles or edits it with `edit`. One with no requester node, or whose node the person cannot see, answers as an id that does not
+ *  exist (the handler's own not-found, no existence leak). */
+async function authorizePersonHuman(operation, principal, params) {
+    const notFound = params['ticket_id'] !== undefined ? new ApiError(404, 'ticket_not_found', 'no matching ticket') : new ApiError(404, 'not_found', 'no request with that id');
+    const request = params['request_id'] ? await getRequest(params['request_id']) : params['ticket_id'] ? await getRequestByInboxTicket(params['ticket_id']) : null;
+    const comment = params['comment_id'] ? await getComment(params['comment_id']) : null;
+    const review = params['review_id'] ? await requireVisibleReview(params['review_id']).catch(() => null) : comment ? await requireVisibleReview(comment.review_id).catch(() => null) : null;
+    const named = params['request_id'] ?? params['ticket_id'] ?? params['review_id'] ?? params['comment_id'];
+    if (named === undefined)
+        return;
+    const origin = request?.requester_node_id ?? review?.origin_node_id;
+    if (!origin || !await getNode(origin) || !await mayOnNode(principal, operation.method === 'GET' ? 'read' : 'edit', origin))
+        throw notFound;
+}
+/** A structured request belongs to the node it runs on: the person confined by its `sub` reads it with `read` on that node and cancels it with
+ *  `edit`. One bound to no node (not yet bound, or never created one) or to a node the person cannot see answers as an id that does not exist. */
+async function authorizePersonStructuredRequest(operation, principal, requestId) {
+    const row = await getStructuredRequest(requestId);
+    if (row === null)
+        return; // Handler returns its ordinary structured_request_not_found.
+    if (row.node_id === null || !await getNode(row.node_id) || !await mayOnNode(principal, operation.method === 'GET' ? 'read' : 'edit', row.node_id)) {
+        throw new ApiError(404, 'structured_request_not_found', `unknown structured request: ${requestId}`);
+    }
+}
+/** What a request body names, for the person confined by its `sub`: a human request or review is raised by a node the person acts on (`edit`;
+ *  one naming no node, or a node the person cannot act on, is refused), and a structured request aimed at an existing node needs `message` on it,
+ *  as `POST /v1/nodes/:id/messages` does. */
+async function authorizePersonBody(operation, principal, body) {
+    const fields = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    const path = operation.path;
+    if (path === '/v1/human/requests' || path === '/v1/human/reviews') {
+        const source = fields['source'];
+        const raiser = path.endsWith('/reviews') ? fields['origin_node_id'] : fields['requester_node_id'];
+        if (typeof raiser !== 'string')
+            throw new ApiError(403, 'permission_error', 'a request must name a node the person acts on');
+        const sourceNode = path.endsWith('/requests') && source && typeof source === 'object' && 'nodeId' in source ? source.nodeId : undefined;
+        for (const id of [raiser, sourceNode]) {
+            if (id === undefined)
+                continue;
+            if (typeof id !== 'string' || !await getNode(id) || !await mayOnNode(principal, 'edit', id))
+                throw new ApiError(404, 'not_found', 'node not found');
+        }
+    }
+    if (path === '/v1/structured-requests') {
+        const target = fields['target'];
+        const id = target && typeof target === 'object' && 'kind' in target && target.kind === 'node' && 'node_id' in target ? target.node_id : undefined;
+        if (typeof id === 'string' && await getNode(id) && !await mayOnNode(principal, 'message', id))
+            throw new ApiError(404, 'node_not_found', `unknown node: ${id}`);
+    }
+}
+/** The checks that need a calling node: daemon bash, the human inbox and a node's own records. A cron has no node and
+ *  admits none of these operations (operations.ts), so they stay broker-only. */
+async function authorizeBrokerOnly(operation, principal, params, resolved) {
+    if (operation.resource === 'daemon-bash' && (!scopeAllowed(resolved, 'crtr:files:rw:user:.') || !scopeAllowed(principal.scopes, 'crtr:files:rw:user:.'))) {
+        throw new ApiError(403, 'scope_missing', 'missing scope crtr:files:rw:user:.');
+    }
+    if (operation.resource === 'human') {
+        const path = operation.path;
+        const read = operation.method === 'GET';
+        if (!read && (path.endsWith('/respond') || path.endsWith('/submit') || path.endsWith('/dismiss') || path.endsWith('/progress') || path.endsWith('/comment-ranges') || path.includes('/feedback-comments'))) {
+            throw new ApiError(403, 'permission_error', 'only the person may answer or edit the human inbox');
+        }
+        const request = params['request_id'] ? await getRequest(params['request_id']) : params['ticket_id'] ? await getRequestByInboxTicket(params['ticket_id']) : null;
+        const comment = params['comment_id'] ? await getComment(params['comment_id']) : null;
+        const review = params['review_id'] ? await requireVisibleReview(params['review_id']) : comment ? await requireVisibleReview(comment.review_id) : null;
+        const origin = request?.requester_node_id ?? review?.origin_node_id;
+        if (origin !== undefined && origin !== null) {
+            const node = await getNode(origin);
+            if (node && (read ? !await canReadNode(principal, node.grantee ?? 'app:terminal', origin) : node.grantee !== principal.app)) {
+                throw new ApiError(read ? 404 : 403, read ? 'not_found' : 'other_app_run', 'human request belongs to another app');
+            }
+            if (node && !read && !await mayOnNode(principal, 'read', origin)) {
+                throw new ApiError(404, 'not_found', 'human request not found');
+            }
+        }
+        else if (request || review) {
+            throw new ApiError(403, 'permission_error', 'only the person may access a request without a node');
+        }
+    }
+    const id = params['id'];
+    if (operation.resource === 'node-own' && id !== undefined && id !== principal.node) {
+        throw new ApiError(403, 'other_app_run', 'the operation requires the calling node');
+    }
+}
+/** Throw the 403 `scope_denied` a scoped bearer earns when its ceiling lacks
+ *  `scope`. The owner (`null`) always passes. */
+export function assertCeiling(ceiling, scope) {
+    if (scopeAllowed(ceiling, scope))
+        return;
+    throw new ScopeDeniedError('the bearer token', scope);
+}
+/** The 403 `owner_only` a scoped bearer earns on a route no ceiling reaches. */
+export function ownerOnlyError() {
+    return new ApiError(403, 'owner_only', 'this operation is owner-only; a scoped token does not reach it');
+}
+/** The request header that names what caused a request. */
+export const CAUSED_BY_HEADER = 'Crtr-Caused-By';
+const CAUSED_BY = /^(?:message|request|cron_run):[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** The `Crtr-Caused-By` value of a request: exactly `message:<id>`, `request:<id>` or `cron_run:<id>` with a bounded id of
+ *  letters, digits, `.`, `_` and `-` (crouter message ids, UUID request ids, cron run ids). Anything else, including a repeated header, is absent. */
+export function causedByOf(headers) {
+    const value = headers[CAUSED_BY_HEADER.toLowerCase()];
+    return typeof value === 'string' && CAUSED_BY.test(value) ? value : undefined;
+}
+/** Mark every route in `table` owner-only. */
+export function ownerOnly(table) {
+    return table.map((def) => ({ ...def, ownerOnly: true }));
+}
+export class Router {
+    routes = [];
+    /** Register one route. Returns `this` for chaining. */
+    register(def) {
+        const operation = operationFor(def.method, def.pattern);
+        if (!operation)
+            throw new Error(`route has no operation row: ${def.method} ${def.pattern}`);
+        if (this.routes.some((route) => route.method === def.method.toUpperCase() && route.operation.path === def.pattern))
+            throw new Error(`duplicate route: ${def.method} ${def.pattern}`);
+        this.routes.push({
+            operation,
+            method: def.method.toUpperCase(),
+            segments: splitPath(def.pattern),
+            handler: def.handler,
+            maxBodyBytes: def.maxBodyBytes ?? CONTROL_BODY_MAX_BYTES,
+        });
+        return this;
+    }
+    /** Register a whole table at once. */
+    registerAll(table) {
+        for (const def of table)
+            this.register(def);
+        return this;
+    }
+    /** Match a method + pathname against the table, extracting `:name` params.
+     *  Returns null when nothing matches (the caller responds 404). */
+    match(method, path) {
+        const wanted = method.toUpperCase();
+        const parts = splitPath(path);
+        for (const route of this.routes) {
+            if (route.method !== wanted)
+                continue;
+            const params = matchSegments(route.segments, parts);
+            if (params !== null)
+                return { handler: route.handler, params, operation: route.operation, maxBodyBytes: route.maxBodyBytes };
+        }
+        return null;
+    }
+    /** Resolve the JSON body, dispatch to the matched handler, and write the
+     *  response. Every failure path — no route, bad JSON, a handler throw — is
+     *  turned into a JSON `ErrorBody` (map.ts §8); this method never throws and
+     *  never leaves the daemon crashed. */
+    async handle(req, res, ceiling, principal = { class: 'person' }) {
+        try {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const method = (req.method ?? 'GET').toUpperCase();
+            const matched = this.match(method, url.pathname);
+            if (matched === null) {
+                writeError(res, 404, 'not_found', `no route for ${method} ${url.pathname}`);
+                return;
+            }
+            await authorizeOperation(matched.operation, principal, matched.params);
+            if (ceiling !== null) {
+                if (matched.operation.classes.length === 1 && matched.operation.classes[0] === 'person')
+                    throw ownerOnlyError();
+                if (matched.operation.scope)
+                    assertCeiling(ceiling, matched.operation.scope);
+            }
+            let body;
+            try {
+                body = await readJsonBody(req, matched.maxBodyBytes);
+            }
+            catch (err) {
+                const code = err instanceof BodyTooLargeError ? 'payload_too_large' : 'invalid_request';
+                writeError(res, code === 'payload_too_large' ? 413 : 400, code, err.message);
+                return;
+            }
+            if (principal.class === 'person' && principal.sub !== undefined)
+                await authorizePersonBody(matched.operation, principal, body);
+            if (principal.class === 'broker' && matched.operation.resource === 'human')
+                await authorizeHumanBody(matched.operation, principal, matched.params, url.searchParams, body);
+            const causedBy = causedByOf(req.headers);
+            const ctx = {
+                ...(causedBy === undefined ? {} : { causedBy }),
+                method,
+                path: url.pathname,
+                params: matched.params,
+                query: url.searchParams,
+                body,
+                ceiling,
+                principal,
+                ...(principal.class === 'anonymous' && typeof req.headers.authorization === 'string' ? { publishToken: req.headers.authorization.slice(7) } : {}),
+                req,
+                res,
+            };
+            const result = await matched.handler(ctx);
+            if (!res.writableEnded)
+                writeResult(res, result);
+        }
+        catch (err) {
+            // The install's person is not known yet (a hosted first boot before the first grant snapshot): the same answer a broker gets before the snapshot.
+            if (err instanceof Error && err.code === 'person_unresolved') {
+                writeJson(res, 503, { error: { code: 'runtime_starting', message: 'grant sync is not ready', type: 'server_error', origin: 'runtime', retryable: true } });
+                return;
+            }
+            // The handler (or something in dispatch) threw — map it and respond. A
+            // request-listener that throws would crash the whole daemon; never allow
+            // it (mirrors server.ts's belt-and-suspenders 500).
+            const { status, body } = toErrorBody(err);
+            // A 500 body carries only a bounded cause (map.ts:boundedCause); the FULL
+            // error — stack included — lives ONLY here, so it must be logged or the
+            // real cause is lost. (map.ts long claimed "logged server-side"; nothing
+            // actually did until this.) <500 named errors already carry their cause
+            // in the response, so they need no extra log line.
+            if (status >= 500) {
+                emitEvent({
+                    event: 'api.request.failed',
+                    level: 'error',
+                    error: err instanceof Error ? err : new Error(String(err)),
+                    ...(principal.class === 'broker' ? { node_id: principal.node } : {}),
+                    fields: { method: (req.method ?? 'GET').toUpperCase(), path: req.url ?? '' },
+                });
+            }
+            writeJson(res, status, body);
+        }
+    }
+}
+// Matching
+/** Split a path/pattern into non-empty segments (leading/trailing '/' ignored). */
+function splitPath(p) {
+    return p.split('/').filter((s) => s.length > 0);
+}
+/** Match a compiled pattern's segments against a request path's segments,
+ *  returning captured `:name` params, or null when the shapes differ. */
+function matchSegments(pattern, actual) {
+    if (pattern.length !== actual.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < pattern.length; i++) {
+        const seg = pattern[i];
+        const got = actual[i];
+        if (seg.startsWith(':')) {
+            params[seg.slice(1)] = decodeURIComponent(got);
+        }
+        else if (seg !== got) {
+            return null;
+        }
+    }
+    return params;
+}
+// Body + response I/O
+class BodyTooLargeError extends Error {
+}
+/** Read and JSON-parse the request body. Returns `undefined` for an empty body.
+ *  Throws `BodyTooLargeError` past the cap and a plain `Error` on malformed
+ *  JSON (both mapped to 4xx by the caller). */
+async function readJsonBody(req, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > maxBytes) {
+            throw new BodyTooLargeError(`request body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(buf);
+    }
+    if (total === 0)
+        return undefined;
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    if (text === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('request body is not valid JSON');
+    }
+}
+/** Write a handler result: JSON body (if any) at its status, merging headers.
+ *  A 204 or an absent body writes no payload. */
+function writeResult(res, result) {
+    if (res.headersSent)
+        return;
+    const headers = { ...(result.headers ?? {}) };
+    if (result.rawBody !== undefined) {
+        res.writeHead(result.status, headers);
+        res.end(result.rawBody);
+        return;
+    }
+    if (result.status === 204 || result.body === undefined) {
+        res.writeHead(result.status, headers);
+        res.end();
+        return;
+    }
+    if (headers['content-type'] === undefined) {
+        headers['content-type'] = 'application/json; charset=utf-8';
+    }
+    res.writeHead(result.status, headers);
+    res.end(JSON.stringify(result.body));
+}
+function writeJson(res, status, body) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+function writeError(res, status, code, message) {
+    const body = { error: { code, message, origin: 'runtime' } };
+    writeJson(res, status, body);
+}

package/dist/daemon/api/sync-notice.d.ts

@@ -0,0 +1,17 @@
+import { type JwksCache } from '@north-light/identity';
+/** An accepted notice whose sync has not yet finished. `done(true)` records it as applied; `done(false)` releases it so the directory's retry syncs. */
+export interface NoticeTicket {
+    jti: string;
+    done(applied: boolean): void;
+}
+/** jti → exp of every notice applied (or being applied) within its lifetime. */
+export declare class NoticeLedger {
+    private readonly seen;
+    /** Verify the bearer as a sync notice for `audience`. Null for a replay of a notice already applied or being applied. Throws `RunError` 401 when invalid. */
+    accept(authorization: string | undefined, jwks: JwksCache, issuer: string, audience: string): Promise<NoticeTicket | null>;
+}
+/** Apply an accepted notice: pull grants fresh and answer only after the sync commits (a 2xx tells the directory the change is applied).
+ *  A replay (`ticket` null) triggers no second sync. Throws `RunError` 503 when the sync fails, so the directory retries. */
+export declare function applySyncNotice(ticket: NoticeTicket | null, syncGrants: (options?: {
+    fresh?: boolean;
+}) => Promise<void>, requestId: string): Promise<void>;

package/dist/daemon/api/sync-notice.js

@@ -0,0 +1,46 @@
+// A directory grant-sync notice, verified and applied. Shared by the app listener (hosted runtime,
+// notice arrives over HTTPS) and the relay client (laptop, notice arrives as a relayed request).
+import { verifySyncNotice } from '@north-light/identity';
+import { emitEvent } from '../../core/events/emit.js';
+import { RunError } from '../../core/runs/operations.js';
+/** jti → exp of every notice applied (or being applied) within its lifetime. */
+export class NoticeLedger {
+    seen = new Map();
+    /** Verify the bearer as a sync notice for `audience`. Null for a replay of a notice already applied or being applied. Throws `RunError` 401 when invalid. */
+    async accept(authorization, jwks, issuer, audience) {
+        if (!authorization?.startsWith('Bearer ') || authorization.length <= 7)
+            throw new RunError(401, 'unauthorized', 'a directory sync notice token is required');
+        let claims;
+        try {
+            claims = await verifySyncNotice({ token: authorization.slice(7), jwks, issuer, audience });
+        }
+        catch {
+            throw new RunError(401, 'unauthorized', 'invalid directory sync notice token');
+        }
+        const now = Math.floor(Date.now() / 1000);
+        for (const [jti, exp] of this.seen)
+            if (exp + 30 < now)
+                this.seen.delete(jti);
+        if (this.seen.has(claims.jti))
+            return null;
+        // Reserved while the sync runs, so a concurrent duplicate does not sync twice; released if the sync fails so the retry is not swallowed.
+        this.seen.set(claims.jti, claims.exp);
+        return { jti: claims.jti, done: (applied) => { if (!applied)
+                this.seen.delete(claims.jti); } };
+    }
+}
+/** Apply an accepted notice: pull grants fresh and answer only after the sync commits (a 2xx tells the directory the change is applied).
+ *  A replay (`ticket` null) triggers no second sync. Throws `RunError` 503 when the sync fails, so the directory retries. */
+export async function applySyncNotice(ticket, syncGrants, requestId) {
+    if (ticket === null)
+        return;
+    emitEvent({ level: 'info', event: 'daemon.grants.sync_notice', fields: { request_id: requestId } });
+    try {
+        await syncGrants({ fresh: true });
+    }
+    catch {
+        ticket.done(false);
+        throw new RunError(503, 'service_unavailable', 'grant sync failed');
+    }
+    ticket.done(true);
+}

package/dist/daemon/api/viewer-presence.d.ts

@@ -0,0 +1,20 @@
+export declare const VIEWER_ROW_TTL_MS = 90000;
+export declare const VIEWER_ROW_REFRESH_MS = 30000;
+/** How long a viewer stays attending after its broker connection ended, for its redial to land. */
+export declare const VIEWER_REDIAL_HOLD_MS = 60000;
+/** This process's id on the rows it writes. */
+export declare const API_PROCESS_ID: `${string}-${string}-${string}-${string}-${string}`;
+/** Whether an unexpired attending row exists for the node. */
+export declare function hasAttachedBrokerViewers(nodeId: string): Promise<boolean>;
+/** Whether an unexpired attending row has been shown the conversation (the relay forwarded the broker's welcome). */
+export declare function hasPresentedViewer(nodeId: string): Promise<boolean>;
+/** The row id of an attached connection, for diagnostics and tests. */
+export declare function viewerConnectionId(connection: object): string | undefined;
+/** Insert the attending row for `connection` and keep it fresh until {@link detachViewer} or {@link holdViewerForRedial}. Repeating it is a no-op. */
+export declare function attachViewer(nodeId: string, connection: object): Promise<void>;
+/** Mark an attending connection as shown the conversation. Returns true the first time only. */
+export declare function presentViewer(_nodeId: string, connection: object): Promise<boolean>;
+/** A clean viewer close: delete the row. */
+export declare function detachViewer(_nodeId: string, connection: object): Promise<void>;
+/** The broker connection ended under an open viewer: stop refreshing and keep the row 60 s for the viewer's redial. */
+export declare function holdViewerForRedial(_nodeId: string, connection: object): Promise<void>;