@north-light/api 0.3.579 → 0.3.587

package/dist/core/providers/mint.js

@@ -0,0 +1,219 @@
+// The daemon's outbound provider token client (contract 3 "Outbound token",
+// "Acquisition"; D3-TOK-6, D3-ERR-6, D3-ERR-7, D3-POL-8; directory
+// DIR-MINT-1, DIR-MINT-16..22).
+//
+// `outboundToken` is what `provider.call` (R4) calls: it returns the cached
+// token for (audience, `sub`, `grantee`, `initiating_app`, scope set) while it
+// is reusable, and otherwise mints one at `<issuer>/token` with
+// `grant_type=client_credentials` and the runtime client's `private_key_jwt`
+// assertion. A refused mint (an RFC 6749 §5.2 `{error}` body) or an
+// unreachable token endpoint throws a `ProviderError` mapped per the spec's
+// table; nothing is sent to the provider. A grant refusal (`invalid_grant`,
+// grant-coverage `invalid_scope`) carries the grant state the directory read,
+// `grant_rev` and `grant_status`. When that state is newer than the mirror's
+// under the ordering rule (contract 1 "Grant sync"), the refusal also starts
+// one detached fresh grant sync (D3-ERR-7), which replaces the mirror and,
+// through the grant-sync hook, discards that grant's cached tokens. An equal
+// or older state, or a refusal without the fields, starts none: no timer.
+import { createHash } from 'node:crypto';
+import { directoryIssuer } from '../directory/issuer.js';
+import { emitEvent } from '../events/emit.js';
+import { OutboundError } from '../events/outbound.js';
+import { grantSyncStateFor } from '../grants/mirror.js';
+import { assertion, machineRevokedMessage, requestGrantSync, runtimeClient } from '../grants/sync.js';
+import { isUnsandboxedMachine } from '../runtime/unsandboxed.js';
+import { ProviderError } from './errors.js';
+import { cacheKey, cachedToken, discardEpoch, storeToken } from './token-cache.js';
+export { discardFile } from './token-cache.js';
+/** How long the token endpoint has to answer. */
+export const MINT_TIMEOUT_MS = 10_000;
+/** Waits before the second and third attempt at a token endpoint that answered 502, 503 or 504. */
+export const MINT_RETRY_DELAYS_MS = [300, 900];
+function issuerOf(options) {
+    const issuer = options.issuer ?? directoryIssuer();
+    if (!issuer)
+        throw new ProviderError('not_found', 'provider calls need a directory-connected runtime');
+    return issuer;
+}
+function directoryError(code, message, details) {
+    return new ProviderError(code, message, { origin: 'directory', details });
+}
+/** RFC 6749 §5.2 `error` → the contract-2 code the caller sees (contract 3's table). */
+function refusal(status, body, request, issuer) {
+    const oauth = typeof body.error === 'string' ? body.error : null;
+    const description = typeof body.error_description === 'string' ? body.error_description : undefined;
+    const details = { directory_status: status, ...(oauth ? { directory_error: oauth } : {}), ...(description ? { directory_description: description } : {}) };
+    const why = description ? `: ${description}` : '';
+    switch (oauth) {
+        case 'invalid_client':
+            // A joined, non-default machine whose key the directory no longer recognises was removed from the account.
+            // On any other runtime `invalid_client` is an ordinary client-authentication failure and keeps its old mapping.
+            if (isUnsandboxedMachine())
+                return { error: directoryError('machine_revoked', machineRevokedMessage(issuer), details), grantRefusal: false };
+            return { error: directoryError('server_error', `the directory refused the outbound token request (${oauth})${why}`, details), grantRefusal: false };
+        case 'invalid_request':
+            return { error: directoryError('server_error', `the directory refused the outbound token request (${oauth})${why}`, details), grantRefusal: false };
+        case 'invalid_target':
+            return { error: directoryError('not_found', `the directory knows no provider at ${request.audience}${why}`, details), grantRefusal: false };
+        case 'invalid_grant':
+            return { error: directoryError('grant_revoked', `the directory has no active grant for ${request.grantee}${why}`, details), grantRefusal: true };
+        case 'provider_not_connected':
+            return { error: directoryError('provider_not_connected', description ?? 'The user has not connected this provider.', details), grantRefusal: false };
+        case 'invalid_scope': {
+            // oidc-provider names the refused string in `scope`; a lone requested string is the one.
+            const named = typeof body.scope === 'string' && body.scope ? body.scope : request.scope.length === 1 ? request.scope[0] : undefined;
+            const message = named ? `missing scope ${named}` : `the grant does not cover ${request.scope.join(' ')}`;
+            return { error: new ProviderError('scope_missing', message, { origin: 'directory', details, ...(named ? { scope: named } : {}) }), grantRefusal: true };
+        }
+        default:
+            // Includes `unauthorized_client`: in v1 it means a directory without the
+            // outbound mint, not a policy refusal (DIR-MINT-20 is the later stage).
+            return { error: directoryError('server_error', `the directory token endpoint answered ${status}${oauth ? ` ${oauth}` : ''}${why}`, details), grantRefusal: false };
+    }
+}
+function claims(accessToken) {
+    try {
+        return JSON.parse(Buffer.from(accessToken.split('.')[1] ?? '', 'base64url').toString('utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** The refusal's grant state, or null when it carries none (no grant row, or an older directory). */
+function refusedGrantState(body) {
+    const rev = body.grant_rev;
+    const status = body.grant_status;
+    if (typeof rev !== 'number' || !Number.isInteger(rev) || rev < 0 || typeof status !== 'string')
+        return null;
+    return { rev, status };
+}
+/** Whether state `a` is newer than `b` under the ordering `(rev, phase)`,
+ *  phase 0 = active and 1 = not active (contract 1 "Grant sync"). */
+function newer(a, b) {
+    const phase = (state) => state.status === 'active' ? 0 : 1;
+    return a.rev > b.rev || (a.rev === b.rev && phase(a) > phase(b));
+}
+/** Start a detached fresh pull when the directory's grant state is newer than the mirror's. */
+async function syncIfNewer(request, refused, options) {
+    if (!refused)
+        return;
+    // A grant the mirror lacks reads as rev 0, which every directory revision is newer than.
+    const mirrored = await grantSyncStateFor(request.grantee, request.sub) ?? { rev: 0, status: 'removed' };
+    if (!newer(refused, mirrored))
+        return;
+    const sync = options.syncGrants ?? requestGrantSync;
+    // The sync logs its own failure; the caller already has its answer.
+    void Promise.resolve().then(() => sync({ fresh: true })).catch(() => { });
+}
+/** Mint one outbound token (no cache). Throws a mapped `ProviderError`. */
+export async function mintOutboundToken(request, options = {}) {
+    const issuer = issuerOf(options);
+    const endpoint = `${issuer}/token`;
+    const client = runtimeClient();
+    const attempt = async () => {
+        // Each attempt signs its own assertion: the directory accepts a `jti` once.
+        const body = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: client.client_id,
+            client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+            client_assertion: assertion(client, endpoint),
+            audience: request.audience,
+            sub: request.sub,
+            grantee: request.grantee,
+            scope: [...new Set(request.scope)].sort().join(' '),
+            initiating_app: request.initiating_app,
+        });
+        const timeout = AbortSignal.timeout(MINT_TIMEOUT_MS);
+        const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+        const response = await (options.fetch ?? fetch)(endpoint, { method: 'POST', body, signal, headers: { Accept: 'application/json' } });
+        return { response, text: await response.text() };
+    };
+    let response;
+    let text;
+    try {
+        // A 502, 503 or 504 is the directory briefly down, not a refusal of this request: ask again before failing the call.
+        for (let tries = 0;; tries++) {
+            ({ response, text } = await attempt());
+            const delay = MINT_RETRY_DELAYS_MS[tries];
+            if (delay === undefined || ![502, 503, 504].includes(response.status))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        // D3-ERR-6: unreachable (or too slow) is retryable, and nothing reached the provider.
+        throw new ProviderError('server_error', `the directory token endpoint could not be reached: ${error instanceof Error ? error.message : String(error)}`, { origin: 'directory', cause: new OutboundError('directory_token', endpoint, error) });
+    }
+    let parsed = null;
+    try {
+        parsed = text ? JSON.parse(text) : null;
+    }
+    catch {
+        parsed = null;
+    }
+    const json = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    if (!response.ok) {
+        const { error, grantRefusal } = refusal(response.status, json, request, issuer);
+        if (error.code === 'machine_revoked')
+            emitEvent({ level: 'error', event: 'daemon.grants.machine_revoked', fields: { audience: request.audience } });
+        emitEvent({ level: 'info', event: 'daemon.providers.mint_refused', fields: { audience: request.audience, grantee: request.grantee, code: error.code, directory_error: typeof json['error'] === 'string' ? json['error'] : null, status: response.status } });
+        if (grantRefusal)
+            await syncIfNewer(request, refusedGrantState(json), options);
+        throw error;
+    }
+    const accessToken = json['access_token'];
+    if (typeof accessToken !== 'string' || !accessToken) {
+        throw new ProviderError('server_error', 'the directory token response has no access_token', { origin: 'directory' });
+    }
+    const payload = claims(accessToken);
+    const nowS = Math.floor((options.now?.() ?? Date.now()) / 1000);
+    const expiresIn = json['expires_in'];
+    // The reuse window runs on this runtime's clock: `expires_in` is immune to
+    // clock skew, so the earlier of it and the token's own `exp` wins.
+    const relative = typeof expiresIn === 'number' && Number.isFinite(expiresIn) && expiresIn > 0 ? nowS + Math.floor(expiresIn) : null;
+    const absolute = typeof payload.exp === 'number' ? payload.exp : null;
+    const exp = relative !== null && absolute !== null ? Math.min(relative, absolute) : relative ?? absolute;
+    if (exp === null)
+        throw new ProviderError('server_error', 'the directory token response names no expiry', { origin: 'directory' });
+    const jti = typeof payload.jti === 'string' && payload.jti ? payload.jti : createHash('sha256').update(accessToken).digest('hex');
+    // The directory names who is charged; a token without the claim (an older directory) is charged to its sub.
+    const payer = typeof payload.payer === 'string' && payload.payer ? payload.payer : request.sub;
+    return { access_token: accessToken, jti, exp, payer };
+}
+// Concurrent calls for one key share one mint.
+const inflight = new Map();
+/** The outbound token for `request`: the cached one while `now < exp − 30 s`
+ *  (D3-TOK-9), else a fresh mint, cached. Throws a mapped `ProviderError`. */
+export async function outboundToken(request, options = {}) {
+    const key = cacheKey(request);
+    const now = options.now ?? Date.now;
+    const cached = cachedToken(key, now());
+    if (cached)
+        return { ...cached, key };
+    let pending = inflight.get(key);
+    if (!pending) {
+        const epoch = discardEpoch(key);
+        pending = mintOutboundToken(request, { ...options, signal: undefined }).then((token) => {
+            storeToken(key, token, epoch);
+            return token;
+        }).finally(() => { inflight.delete(key); });
+        // Every waiter may have aborted before the mint settles; its failure then
+        // has no reader and must not become an unhandled rejection in crtrd.
+        pending.catch(() => { });
+        inflight.set(key, pending);
+    }
+    const token = options.signal ? await abortable(pending, options.signal) : await pending;
+    return { ...token, key };
+}
+/** A shared mint is not aborted by one caller; that caller just stops waiting. */
+function abortable(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}

package/dist/core/providers/receipts.d.ts

@@ -0,0 +1,26 @@
+import type { Funding } from '../ledger/types.js';
+type ReceiptCall = {
+    provider: string;
+    tool: string;
+    request_id: string;
+    sub: string;
+    grantee: string;
+    run_id: string | null;
+    /** The outbound token's `payer` claim: the principal the directory charges (an app, or the user). */
+    payer: string;
+    /** The app the charge is attributed to when it differs from the receipt's grantee (the person's calls count under `app:terminal`). */
+    ledger_grantee?: string;
+    /** `bill` or `endpoint`, from `payerOf` on the token's payer. */
+    funding: Funding;
+    /** The calling node and the call's `Crtr-Caused-By`; null when none. */
+    node_id: string | null;
+    caused_by: string | null;
+};
+/**
+ * A provider's informational receipts must belong to the call that carried them. The header is one
+ * receipt object or an array of at most {@link MAX_RECEIPTS}; each is checked and recorded on its
+ * own, and one that fails the check is dropped without dropping the others. Returns the first
+ * accepted receipt id.
+ */
+export declare function acceptProviderReceipt(value: string | string[] | undefined, call: ReceiptCall): Promise<string | undefined>;
+export {};

package/dist/core/providers/receipts.js

@@ -0,0 +1,61 @@
+import { withCanvasWrite } from '../canvas/db.js';
+import { receiptChargeId, writeCharge } from '../ledger/index.js';
+/** One response carries a receipt object, or an array of at most this many. */
+const MAX_RECEIPTS = 8;
+/** Fits {@link MAX_RECEIPTS} receipts with maximum-length ids. */
+const MAX_HEADER_BYTES = 65_536;
+function belongsToCall(receipt, call) {
+    if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt))
+        return false;
+    const r = receipt;
+    return typeof r.receipt_id === 'string' && !!r.receipt_id && r.receipt_id.length <= 256 &&
+        r.provider === `app:${call.provider}` && r.tool === call.tool && r.request_id === call.request_id &&
+        r.sub === call.sub && r.grantee === call.grantee && r.payer === call.payer &&
+        (r.run_id ?? null) === call.run_id && typeof r.unit === 'string' && !!r.unit &&
+        typeof r.units === 'number' && Number.isFinite(r.units) && r.units >= 0 &&
+        typeof r.time === 'string' && Number.isFinite(Date.parse(r.time)) &&
+        typeof r.usd_equivalent === 'number' && Number.isFinite(r.usd_equivalent) && r.usd_equivalent >= 0;
+}
+/**
+ * A provider's informational receipts must belong to the call that carried them. The header is one
+ * receipt object or an array of at most {@link MAX_RECEIPTS}; each is checked and recorded on its
+ * own, and one that fails the check is dropped without dropping the others. Returns the first
+ * accepted receipt id.
+ */
+export async function acceptProviderReceipt(value, call) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (!raw || raw.length > MAX_HEADER_BYTES)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (Array.isArray(parsed) && parsed.length > MAX_RECEIPTS)
+        return undefined;
+    const accepted = (Array.isArray(parsed) ? parsed : [parsed]).filter((r) => belongsToCall(r, call));
+    if (!accepted.length)
+        return undefined;
+    await withCanvasWrite(async (db) => {
+        for (const receipt of accepted) {
+            // One row per receipt, keyed by (provider, receipt id): a repeat delivery writes nothing and adds nothing.
+            const { written } = await writeCharge({ id: receiptChargeId(call.provider, receipt.receipt_id), request: call.request_id, kind: 'tool', what: `${call.provider}:${call.tool}`,
+                units: { units: receipt.units, unit: receipt.unit }, usd: receipt.usd_equivalent, payer: call.payer, funding: call.funding, sub: call.sub,
+                grantee: call.ledger_grantee ?? call.grantee, node: call.node_id, run: call.run_id, provider: `app:${call.provider}`, causedBy: call.caused_by, vendorRef: receipt.receipt_id });
+            if (!written)
+                continue;
+            if (!call.run_id)
+                continue;
+            const root = await db.prepare('SELECT usage_json FROM nodes WHERE node_id = ? AND run_id = ?')
+                .get(call.run_id, call.run_id);
+            if (!root)
+                continue;
+            const usage = root.usage_json ? JSON.parse(root.usage_json) : {};
+            usage['cost_usd'] = (typeof usage['cost_usd'] === 'number' ? usage['cost_usd'] : 0) + receipt.usd_equivalent;
+            await db.prepare('UPDATE nodes SET usage_json = ? WHERE node_id = ?').run(JSON.stringify(usage), call.run_id);
+        }
+    });
+    return accepted[0].receipt_id;
+}

package/dist/core/providers/request.d.ts

@@ -0,0 +1,27 @@
+import { type IncomingHttpHeaders } from 'node:http';
+/** The caller builds and authorizes the request once; connection retries reuse it verbatim. */
+export interface ProviderRequestPlan {
+    url: URL | string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface ProviderRequestOptions {
+    connectMs?: number;
+    requestMs?: number;
+    /** Absolute Date.now() deadline, shared by separate sends (e.g. manifest refresh). */
+    deadlineAt?: number;
+    signal?: AbortSignal;
+}
+export interface ProviderResponse {
+    status: number;
+    headers: IncomingHttpHeaders;
+    /** JSON-decoded without output validation; non-JSON response bytes are returned as text. */
+    body: unknown;
+}
+export declare class ProviderTransportError extends Error {
+    readonly kind: 'timeout' | 'connection' | 'aborted';
+    constructor(kind: 'timeout' | 'connection' | 'aborted', message: string, options?: ErrorOptions);
+}
+/** Transport only: no provider response mapping, manifest refresh, or token handling. */
+export declare function sendProviderRequest(plan: ProviderRequestPlan, options?: ProviderRequestOptions): Promise<ProviderResponse>;

package/dist/core/providers/request.js

@@ -0,0 +1,173 @@
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+export class ProviderTransportError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.name = 'ProviderTransportError';
+    }
+}
+const DEFAULT_CONNECT_MS = 10_000;
+const DEFAULT_REQUEST_MS = 30_000;
+const RETRY_START_MS = 250;
+const RETRY_MAX_MS = 2_000;
+const RETRY_CODES = new Set(['ECONNREFUSED', 'ECONNRESET']);
+/** Transport only: no provider response mapping, manifest refresh, or token handling. */
+export async function sendProviderRequest(plan, options = {}) {
+    const url = new URL(plan.url);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new TypeError(`Unsupported provider protocol: ${url.protocol}`);
+    const requestMs = options.requestMs ?? DEFAULT_REQUEST_MS;
+    const connectMs = options.connectMs ?? DEFAULT_CONNECT_MS;
+    if (!Number.isFinite(requestMs) || requestMs <= 0 || !Number.isFinite(connectMs) || connectMs <= 0) {
+        throw new RangeError('Provider timeouts must be positive finite milliseconds');
+    }
+    const deadline = options.deadlineAt ?? Date.now() + requestMs;
+    if (!Number.isFinite(deadline))
+        throw new RangeError('Provider deadline must be finite');
+    let backoff = RETRY_START_MS;
+    let lastConnection;
+    for (;;) {
+        if (options.signal?.aborted)
+            throw aborted();
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw lastConnection
+                ? new ProviderTransportError('connection', 'Provider connection retry deadline exhausted', { cause: lastConnection })
+                : timeout();
+        try {
+            return await sendOnce(url, plan, Math.min(connectMs, remaining), remaining, options.signal);
+        }
+        catch (error) {
+            if (!(error instanceof RetryableConnectionError))
+                throw error;
+            lastConnection = error;
+            if (options.signal?.aborted)
+                throw aborted();
+            const wait = Math.min(backoff, deadline - Date.now());
+            if (wait <= 0)
+                throw exhausted(error);
+            await pause(wait, options.signal);
+            if (options.signal?.aborted)
+                throw aborted();
+            if (Date.now() >= deadline)
+                throw exhausted(error);
+            backoff = Math.min(backoff * 2, RETRY_MAX_MS);
+        }
+    }
+}
+class RetryableConnectionError extends Error {
+}
+function exhausted(cause) {
+    return new ProviderTransportError('connection', 'Provider connection retry deadline exhausted', { cause });
+}
+function timeout() {
+    return new ProviderTransportError('timeout', 'Provider request timed out');
+}
+function aborted() {
+    return new ProviderTransportError('aborted', 'Provider request aborted');
+}
+function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(aborted());
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        function done() { signal?.removeEventListener('abort', onAbort); resolve(); }
+        function onAbort() { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); reject(aborted()); }
+    });
+}
+function sendOnce(url, plan, connectMs, remainingMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(aborted());
+            return;
+        }
+        let settled = false;
+        let received = false;
+        let connected = false;
+        let connectTimer;
+        let deadlineTimer;
+        const req = (url.protocol === 'https:' ? httpsRequest : httpRequest)(url, {
+            method: plan.method,
+            headers: plan.headers,
+            // The request bytes and headers cannot be changed between attempts.
+            agent: false,
+            // Node's 16 KiB default would reject a response carrying eight receipts in `Crtr-Receipt`.
+            maxHeaderSize: 80 * 1024,
+        }, (res) => {
+            received = true;
+            clearTimeout(connectTimer);
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                let body = text;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch { /* Caller owns invalid JSON handling. */ }
+                finish(undefined, { status: res.statusCode ?? 0, headers: res.headers, body });
+            });
+            // Once headers arrive, even a truncated response must not be retried.
+            res.on('error', (error) => finish(new ProviderTransportError('connection', 'Provider response interrupted', { cause: error })));
+            res.on('close', () => {
+                if (!res.complete)
+                    finish(new ProviderTransportError('connection', 'Provider response closed before completion'));
+            });
+        });
+        function cleanup() {
+            clearTimeout(connectTimer);
+            clearTimeout(deadlineTimer);
+            signal?.removeEventListener('abort', onAbort);
+        }
+        function finish(error, value) {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error) {
+                req.destroy();
+                reject(error);
+            }
+            else
+                resolve(value);
+        }
+        function onAbort() { finish(aborted()); }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        connectTimer = setTimeout(() => finish(timeout()), connectMs);
+        deadlineTimer = setTimeout(() => finish(timeout()), remainingMs);
+        req.on('socket', (socket) => {
+            const connectedNow = () => {
+                connected = true;
+                clearTimeout(connectTimer);
+            };
+            if (socket.connecting)
+                socket.once(url.protocol === 'https:' ? 'secureConnect' : 'connect', connectedNow);
+            else
+                connectedNow();
+        });
+        req.on('error', (error) => {
+            if (settled)
+                return;
+            if (!received && RETRY_CODES.has(error.code ?? ''))
+                finish(new RetryableConnectionError(error.message, { cause: error }));
+            else
+                finish(new ProviderTransportError('connection', received ? 'Provider response interrupted' : 'Provider connection failed', { cause: error }));
+        });
+        req.on('close', () => {
+            if (!received && !settled)
+                finish(new RetryableConnectionError(connected ? 'Provider socket closed before response' : 'Provider connection closed before response'));
+        });
+        if (plan.body !== undefined)
+            req.write(plan.body);
+        req.end();
+    });
+}

package/dist/core/providers/roots.d.ts

@@ -0,0 +1,23 @@
+import type { InstalledPlugin } from '../../types.js';
+/** The single root command name of a provider bundle's `commands.json`, or
+ *  undefined when it declares none or more than one. */
+export declare function rootNameOfCommands(raw: unknown): string | undefined;
+/** An installed provider plugin's root command name, cached per file replacement. */
+export declare function installedRootName(plugin: Pick<InstalledPlugin, 'root'>): string | undefined;
+/** The provider bundles this process serves. A cloud role holds one plugin directory for every account it serves, so a bundle there is
+ *  installed for the deployment, not for a person: the directory's valid provider manifests, with no enabled flag. Anything else lists
+ *  the user scope's plugins. */
+export declare function installedProviderPlugins(): InstalledPlugin[];
+export interface ProviderRootClaims {
+    /** root command name → provider id (the earliest-installed claimant). */
+    byRoot: Map<string, string>;
+    /** Provider ids skipped because an earlier-installed provider claims their root. */
+    skipped: Set<string>;
+}
+/** Every enabled installed provider bundle's root. When two claim one root the
+ *  later-installed is skipped (and logged once), never shadowing the first. */
+export declare function providerRootClaims(plugins?: readonly InstalledPlugin[]): ProviderRootClaims;
+/** A provider id or a root command name → the provider id. An installed id
+ *  wins; an unknown name passes through unchanged. A provider skipped for
+ *  claiming a root another provider serves is unreachable by id as well (`null`). */
+export declare function resolveProviderRef(ref: string): string | null;

package/dist/core/providers/roots.js

@@ -0,0 +1,118 @@
+// A provider bundle's root command name. The provider id (random for a third
+// party) keys scope, mint, bundle URL, call and receipts; the person types the
+// bundle's single root command, which this module maps back to the id.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { emitEvent } from '../events/emit.js';
+import { isCloudRole } from '../canvas/person-state.js';
+import { readState } from '../config.js';
+import { readPluginManifest } from '../manifest.js';
+import { listInstalledPlugins } from '../resolver.js';
+import { pluginsDir } from '../scope.js';
+/** The single root command name of a provider bundle's `commands.json`, or
+ *  undefined when it declares none or more than one. */
+export function rootNameOfCommands(raw) {
+    const mounts = raw?.mounts;
+    if (!Array.isArray(mounts))
+        return undefined;
+    const names = new Set();
+    for (const mount of mounts) {
+        if (Array.isArray(mount?.parent) && mount.parent.length === 0 && typeof mount.node?.name === 'string')
+            names.add(mount.node.name);
+    }
+    return names.size === 1 ? [...names][0] : undefined;
+}
+const rootCache = new Map();
+/** An installed provider plugin's root command name, cached per file replacement. */
+export function installedRootName(plugin) {
+    const file = join(plugin.root, 'commands.json');
+    try {
+        const stat = statSync(file);
+        const stamp = `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+        const cached = rootCache.get(file);
+        if (cached?.stamp === stamp)
+            return cached.root;
+        const root = rootNameOfCommands(JSON.parse(readFileSync(file, 'utf8')));
+        rootCache.set(file, { stamp, root });
+        return root;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The provider bundles this process serves. A cloud role holds one plugin directory for every account it serves, so a bundle there is
+ *  installed for the deployment, not for a person: the directory's valid provider manifests, with no enabled flag. Anything else lists
+ *  the user scope's plugins. */
+export function installedProviderPlugins() {
+    if (!isCloudRole())
+        return listInstalledPlugins('user');
+    const dir = pluginsDir('user');
+    let names;
+    try {
+        names = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.flatMap((name) => {
+        const root = join(dir, name);
+        const manifest = readPluginManifest(root);
+        return manifest?.provider === undefined ? [] : [{ name, scope: 'user', root, manifest, enabled: true, version: manifest.version }];
+    });
+}
+const reportedDuplicates = new Set();
+/** Every enabled installed provider bundle's root. When two claim one root the
+ *  later-installed is skipped (and logged once), never shadowing the first. */
+export function providerRootClaims(plugins = installedProviderPlugins()) {
+    const providers = plugins.filter((plugin) => plugin.enabled && plugin.manifest.provider !== undefined && plugin.manifest.provider.id === plugin.name);
+    // Install order is only needed to break a tie, so the scoped state is read only then:
+    // discovery on a home with nothing to break must not touch it.
+    const roots = new Map(providers.map((plugin) => [plugin.name, installedRootName(plugin)]));
+    const claimed = new Set();
+    const dupes = new Set();
+    for (const root of roots.values()) {
+        if (root === undefined)
+            continue;
+        if (claimed.has(root))
+            dupes.add(root);
+        claimed.add(root);
+    }
+    if (dupes.size > 0) {
+        // A cloud role has no person's state to read: name order breaks the tie.
+        const state = isCloudRole() ? {} : readState('user').plugins;
+        providers.sort((a, b) => (state[a.name]?.last_updated ?? '').localeCompare(state[b.name]?.last_updated ?? '') || a.name.localeCompare(b.name));
+    }
+    const byRoot = new Map();
+    const skipped = new Set();
+    for (const plugin of providers) {
+        const root = roots.get(plugin.name);
+        if (root === undefined)
+            continue;
+        const owner = byRoot.get(root);
+        if (owner === undefined) {
+            byRoot.set(root, plugin.name);
+            continue;
+        }
+        skipped.add(plugin.name);
+        const key = `${plugin.name}\0${root}\0${owner}`;
+        if (!reportedDuplicates.has(key)) {
+            reportedDuplicates.add(key);
+            emitEvent({ level: 'error', event: 'daemon.providers.bundle_invalid', fields: { provider: plugin.name, issues: [{ code: 'root_command_claimed', message: `root command "${root}" is already served by provider "${owner}"; "${plugin.name}" is skipped` }] } });
+        }
+    }
+    return { byRoot, skipped };
+}
+/** A provider id or a root command name → the provider id. An installed id
+ *  wins; an unknown name passes through unchanged. A provider skipped for
+ *  claiming a root another provider serves is unreachable by id as well (`null`). */
+export function resolveProviderRef(ref) {
+    const plugins = installedProviderPlugins();
+    const claims = providerRootClaims(plugins);
+    if (claims.skipped.has(ref))
+        return null;
+    if (plugins.some((plugin) => plugin.name === ref && plugin.manifest.provider !== undefined))
+        return ref;
+    return claims.byRoot.get(ref) ?? ref;
+}