@ashlr/hub 3.4.0 → 3.5.0

package/dist/core/verse/mcp-control-api.js

@@ -0,0 +1,322 @@
+/**
+ * core/verse/mcp-control-api.ts — the HTTP surface for MCP and per-account
+ * CLI management.
+ *
+ * Deliberately a SEPARATE handler from `control-api.ts` rather than new arms
+ * on its `if`-chain: that file is owned by another work stream, and this one
+ * carries a mutation that installs arbitrary code. Keeping them apart means
+ * the review surface for "can the hub run new code" is one file.
+ *
+ * ── Route shape ─────────────────────────────────────────────────────────────
+ *
+ *   GET  /api/verse/mcp              which servers each seat would load
+ *   GET  /api/verse/mcp/cli-health   per-account auth, plan and version drift
+ *   POST /api/verse/mcp/cli-probe    read the installed CLI versions (SPAWNS)
+ *   POST /api/verse/mcp/proposal     validate + disclose a write (writes nothing)
+ *   POST /api/verse/mcp/apply        perform the write the digest confirms
+ *
+ * The two GETs are free: no subprocess, no provider call, no write. Everything
+ * that costs something or changes something is a POST behind
+ * `passesMutationGate`, including `cli-probe` — it launches up to four vendor
+ * binaries, and a read route that does that is a side effect in disguise.
+ *
+ * `proposal` is a POST for the same reason, even though it writes nothing: it
+ * carries an operator-supplied command in its body, and it is the step that
+ * must be authenticated for the resulting digest to mean anything.
+ *
+ * ── Ordering requirement ────────────────────────────────────────────────────
+ *
+ * These paths live under `/api/verse/*`, which `isVerseApiPath()` matches
+ * wholesale and 404s when it does not recognise. So the dispatch call in
+ * `src/core/web/api.ts` MUST come before both `isVerseControlPath` and
+ * `isVerseApiPath`. See the comment at that call site.
+ */
+import { passesMutationGate, readBody, sendJson } from '../web/api.js';
+import { audit } from '../sandbox/audit.js';
+import { buildVerseAccountsSnapshot, readVerseAccountIdentities } from './accounts.js';
+import { getVerseAccountCollector } from './accounts.js';
+import { defaultAccountsRoot, resolveAccountsRoot } from './seats.js';
+import { buildVerseMcpSnapshot } from './mcp-seat-view.js';
+import { readVerseMcpScopeGate } from './mcp-scope.js';
+import { buildVerseCliHealth, probeVerseAccountCliVersions, } from './mcp-cli-health.js';
+import { applyVerseMcpProposal, buildVerseMcpProposal, } from './mcp-mutation.js';
+const MCP_PREFIX = '/api/verse/mcp';
+const MCP_ROUTES = new Set([
+    MCP_PREFIX,
+    `${MCP_PREFIX}/cli-health`,
+    `${MCP_PREFIX}/cli-probe`,
+    `${MCP_PREFIX}/proposal`,
+    `${MCP_PREFIX}/apply`,
+]);
+/** True for exactly the five MCP-management routes. */
+export function isVerseMcpPath(path) {
+    return MCP_ROUTES.has(path);
+}
+const ERROR_STATUS = {
+    VERSE_INVALID: 400,
+    VERSE_REFUSED: 409,
+    VERSE_TOO_LARGE: 413,
+    VERSE_UNAVAILABLE: 503,
+};
+function sendError(res, code, error) {
+    sendJson(res, ERROR_STATUS[code], { code, error });
+}
+function sendInvalid(res, error) {
+    sendError(res, 'VERSE_INVALID', error);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+async function readJsonBody(req, res) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch {
+        sendError(res, 'VERSE_TOO_LARGE', 'request body too large');
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = raw.length === 0 ? {} : JSON.parse(raw);
+    }
+    catch {
+        sendInvalid(res, 'invalid JSON body');
+        return null;
+    }
+    if (!isRecord(parsed)) {
+        sendInvalid(res, 'body must be a JSON object');
+        return null;
+    }
+    return parsed;
+}
+function passesPostGate(ctx, req, res) {
+    if (!ctx.allowDispatch) {
+        sendJson(res, 404, { error: 'not found' });
+        return false;
+    }
+    return passesMutationGate(req, res, ctx.token);
+}
+// ---------------------------------------------------------------------------
+// Shared reads
+// ---------------------------------------------------------------------------
+function accountsRootFor(ctx) {
+    if (ctx.accountsRoot !== undefined)
+        return ctx.accountsRoot;
+    try {
+        return resolveAccountsRoot(ctx.cfg);
+    }
+    catch {
+        return defaultAccountsRoot();
+    }
+}
+/**
+ * Seat inputs for the MCP view, WITHOUT running `discoverSeats()`.
+ *
+ * `discoverSeats` probes Ollama over HTTP and builds telemetry — none of which
+ * this view needs, and all of which would make a cheap read expensive. What
+ * the MCP question turns on is (engine, account), and that is exactly what
+ * `readVerseAccountIdentities` publishes. Seat ids for native seats ARE the
+ * account ids (see VerseSeat.id's own documentation).
+ *
+ * Local seats are collapsed into ONE row on purpose: every Ollama tag is
+ * launched through the same `buildClaudeLaunch` argv, so they are all isolated
+ * identically and listing twelve identical rows would be noise, not detail.
+ */
+export function verseMcpSeatInputs(accountsRoot) {
+    const seats = readVerseAccountIdentities(accountsRoot).map((identity) => ({
+        id: identity.id,
+        label: identity.label,
+        engine: identity.provider,
+        accountId: identity.id,
+    }));
+    seats.push({
+        id: 'local',
+        label: 'Local seats (every Ollama tag)',
+        engine: 'local',
+        accountId: 'local',
+    });
+    return seats;
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle one MCP-management request. Returns true when a response was
+ * written (including errors); false when `path` is not one of these routes.
+ */
+export async function handleVerseMcpApi(ctx, req, res, path, method) {
+    if (!isVerseMcpPath(path))
+        return false;
+    try {
+        const accountsRoot = accountsRootFor(ctx);
+        // ── GET /api/verse/mcp ────────────────────────────────────────────────
+        if (path === MCP_PREFIX) {
+            if (method !== 'GET') {
+                sendJson(res, 404, { error: `not found: ${method} ${path}` });
+                return true;
+            }
+            sendJson(res, 200, buildVerseMcpSnapshot({
+                accountsRoot,
+                seats: verseMcpSeatInputs(accountsRoot),
+            }));
+            return true;
+        }
+        // ── GET /api/verse/mcp/cli-health ─────────────────────────────────────
+        //
+        // Free: derived entirely from the collector's existing records plus the
+        // pinned-version constant. No subprocess. A version NUMBER requires the
+        // probe below; its absence is reported as `unverified`, never faked.
+        if (path === `${MCP_PREFIX}/cli-health`) {
+            if (method !== 'GET') {
+                sendJson(res, 404, { error: `not found: ${method} ${path}` });
+                return true;
+            }
+            const snapshot = buildVerseAccountsSnapshot({
+                accountsRoot,
+                collector: getVerseAccountCollector(),
+            });
+            sendJson(res, 200, buildVerseCliHealth({ accounts: snapshot.accounts }));
+            return true;
+        }
+        // ── POST /api/verse/mcp/cli-probe ─────────────────────────────────────
+        //
+        // Gated because it SPAWNS: help/version invocations only, but four vendor
+        // binaries is a real cost and a real side effect on this machine.
+        if (path === `${MCP_PREFIX}/cli-probe`) {
+            if (method !== 'POST') {
+                sendJson(res, 404, { error: `not found: ${method} ${path}` });
+                return true;
+            }
+            if (!passesPostGate(ctx, req, res))
+                return true;
+            const body = await readJsonBody(req, res);
+            if (!body)
+                return true;
+            for (const key of Object.keys(body)) {
+                sendInvalid(res, `unknown key: ${key}`);
+                return true;
+            }
+            let readings;
+            try {
+                readings = await probeVerseAccountCliVersions({ accountsRoot });
+            }
+            catch {
+                sendError(res, 'VERSE_UNAVAILABLE', 'the CLI version probe could not be run');
+                return true;
+            }
+            const snapshot = buildVerseAccountsSnapshot({
+                accountsRoot,
+                collector: getVerseAccountCollector(),
+            });
+            const health = buildVerseCliHealth({ accounts: snapshot.accounts, readings });
+            audit({
+                action: 'verse.mcp.cli-probe',
+                repo: null,
+                sandboxId: null,
+                summary: `read CLI versions for ${readings.size} account(s); drift=${health.driftDetected}`,
+                result: 'ok',
+            });
+            sendJson(res, 200, health);
+            return true;
+        }
+        // ── POST /api/verse/mcp/proposal ──────────────────────────────────────
+        //
+        // Writes NOTHING. Returns the full command, args and env KEYS (values
+        // redacted), the warnings, the Locus scope, and the digest that the apply
+        // step demands back.
+        if (path === `${MCP_PREFIX}/proposal` || path === `${MCP_PREFIX}/apply`) {
+            const applying = path === `${MCP_PREFIX}/apply`;
+            if (method !== 'POST') {
+                sendJson(res, 404, { error: `not found: ${method} ${path}` });
+                return true;
+            }
+            if (!passesPostGate(ctx, req, res))
+                return true;
+            const body = await readJsonBody(req, res);
+            if (!body)
+                return true;
+            const allowed = applying
+                ? new Set(['target', 'server', 'digest', 'confirm'])
+                : new Set(['target', 'server']);
+            for (const key of Object.keys(body)) {
+                if (!allowed.has(key)) {
+                    sendInvalid(res, `unknown key: ${key}`);
+                    return true;
+                }
+            }
+            const target = body['target'];
+            if (typeof target !== 'string' || target.length === 0 || target.length > 128) {
+                sendInvalid(res, 'target is required');
+                return true;
+            }
+            if (body['server'] === undefined) {
+                sendInvalid(res, 'server is required');
+                return true;
+            }
+            const scope = readVerseMcpScopeGate();
+            if (!applying) {
+                const proposal = buildVerseMcpProposal({
+                    targetId: target,
+                    server: body['server'],
+                    accountsRoot,
+                    scope,
+                });
+                sendRefusableResult(res, proposal);
+                return true;
+            }
+            // An explicit `confirm: true` on top of the digest. The digest is the
+            // real control; this is the second half of "never a one-click install"
+            // being visible in the request itself.
+            if (body['confirm'] !== true) {
+                sendInvalid(res, 'confirm must be true to apply a proposal');
+                return true;
+            }
+            const supplied = body['digest'];
+            if (typeof supplied !== 'string' || supplied.length === 0 || supplied.length > 128) {
+                sendInvalid(res, 'digest is required to apply a proposal');
+                return true;
+            }
+            const result = applyVerseMcpProposal({
+                targetId: target,
+                server: body['server'],
+                accountsRoot,
+                scope,
+                digest: supplied,
+            });
+            // The audit summary names the target and the server NAME. It never
+            // carries the command, args or env — `stripSecrets` is a backstop, not
+            // a licence to hand it a secret.
+            const serverName = isRecord(body['server']) && typeof body['server']['name'] === 'string'
+                ? body['server']['name']
+                : '(unnamed)';
+            audit({
+                action: 'verse.mcp.apply',
+                repo: null,
+                sandboxId: null,
+                summary: result.ok
+                    ? `${result.action} MCP server ${serverName} in ${result.target.ref}`
+                    : `refused MCP server ${serverName} for ${target}: ${result.refusal}`,
+                result: result.ok ? 'ok' : 'refused',
+            });
+            sendRefusableResult(res, result);
+            return true;
+        }
+        /* c8 ignore next 2 -- isVerseMcpPath already narrowed to the five routes. */
+        sendJson(res, 404, { error: `not found: ${method} ${path}` });
+        return true;
+    }
+    catch {
+        sendError(res, 'VERSE_UNAVAILABLE', 'MCP management is unavailable on this server');
+        return true;
+    }
+}
+/**
+ * A refusal is a 409 carrying the full result body with a plain-language
+ * `note` — the same convention `VerseScopeResult` established, which the web
+ * client relies on when it reads `error` and falls back to `note`.
+ */
+function sendRefusableResult(res, result) {
+    sendJson(res, result.ok ? 200 : 409, result);
+}
+//# sourceMappingURL=mcp-control-api.js.map

package/dist/core/verse/mcp-control-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-control-api.js","sourceRoot":"","sources":["../../../src/core/verse/mcp-control-api.ts"],"names":[],"mappings":"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"}

package/dist/core/verse/mcp-mutation.d.ts

@@ -0,0 +1,187 @@
+/**
+ * core/verse/mcp-mutation.ts — adding or editing an MCP server, deliberately
+ * made difficult.
+ *
+ * docs/VERSE-WORKSPACES.md §3: "an MCP server is arbitrary code with the
+ * agent's privileges"; "Adding or editing a server is a privileged,
+ * outward-facing change. It belongs behind the same mutation gate as the other
+ * control-plane writes, and it should show the full command and environment
+ * (redacted) before it is saved — never a one-click install of something the
+ * operator has not read."
+ *
+ * ── How "never one-click" is enforced, rather than just intended ────────────
+ *
+ * A write takes TWO requests, and the second cannot be forged from the first
+ * by a client that did not render it:
+ *
+ *   1. {@link buildVerseMcpProposal} validates the spec, resolves the target,
+ *      and returns a PROPOSAL containing the full command and args verbatim,
+ *      the env KEYS with every value redacted to '<set>', the warnings, and a
+ *      `digest` over exactly what was shown plus the target file's current
+ *      contents. Nothing is written.
+ *   2. {@link applyVerseMcpProposal} refuses unless it is handed that same
+ *      digest back AND the target file is still byte-identical to what the
+ *      digest was taken over. A stale digest is a refusal, not a merge.
+ *
+ * The digest binds the decision to the disclosure. An operator who never saw
+ * the command cannot produce it, and a file that changed underneath the
+ * proposal invalidates it.
+ *
+ * ── What this refuses to do ─────────────────────────────────────────────────
+ *
+ *   - Rewrite TOML. Codex and Grok keep their MCP servers in `config.toml`.
+ *     `src/core/integrations/editors.ts` already established the rule for
+ *     this repo — Codex "is intentionally delegated to its official CLI so
+ *     this module never attempts to parse and rewrite a user's TOML
+ *     configuration" — and a half-understood TOML rewrite of an operator's
+ *     config is a worse outcome than a refusal.
+ *   - Touch ~/.ashlr/config.json, ~/.ashlr/enrollment.json or ~/.ashlr/KILL.
+ *     Those are not MCP registries and are explicitly out of bounds.
+ *   - Write anywhere the caller names freely. Targets are an enumerated set.
+ *
+ * ── What may leave this module ──────────────────────────────────────────────
+ *
+ * Env VALUES never leave, in any form, on any path: not in the proposal, not
+ * in the apply result, not in the audit summary, not in an error message. The
+ * proposal carries `redactEnv`'d specs only. The real values live in the
+ * request body and go straight to disk.
+ */
+import type { McpServerSpec } from '../types.js';
+import { type VerseMcpServerView } from './mcp-seat-view.js';
+import type { VerseMcpScopeGate } from './mcp-scope.js';
+/**
+ * Where a server may be written.
+ *
+ *   `hub`             ~/.ashlr/settings.json — the hub's own aggregated
+ *                     gateway registry (M66; `knownConfigPaths()` scans it).
+ *   `account:<id>`    that account's private JSON registry. Only accounts
+ *                     whose native config is JSON qualify; Codex and Grok keep
+ *                     TOML and are refused by name below.
+ */
+export type VerseMcpTargetId = 'hub' | `account:${string}`;
+export type VerseMcpRefusal = 'mcp-target-unknown' | 'mcp-target-not-json' | 'mcp-target-unresolved' | 'mcp-target-forbidden' | 'mcp-spec-invalid' | 'mcp-digest-mismatch' | 'mcp-target-changed' | 'mcp-scope-refused' | 'mcp-write-failed';
+/** Files that must never be written by this module, whatever a caller asks. */
+export declare const VERSE_MCP_FORBIDDEN_FILES: readonly string[];
+export interface VerseMcpTarget {
+    id: VerseMcpTargetId;
+    /** Absolute path. SERVER-SIDE ONLY — projected to `ref` for transport. */
+    path: string;
+    /** Path relative to $HOME. What the operator is shown. */
+    ref: string;
+    /** Human label for the surface. */
+    label: string;
+}
+/**
+ * Resolve a target id to a file, or explain why not.
+ *
+ * `accountsRoot` is only consulted for `account:` targets. Account state
+ * directories are private and never published — only `ref` crosses out.
+ */
+export declare function resolveVerseMcpTarget(id: string, options: {
+    accountsRoot: string;
+    home?: string;
+}): {
+    ok: true;
+    target: VerseMcpTarget;
+} | {
+    ok: false;
+    refusal: VerseMcpRefusal;
+    error: string;
+};
+export type VerseMcpSpecParse = {
+    ok: true;
+    spec: McpServerSpec;
+    warnings: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate a caller-supplied server spec.
+ *
+ * Strict by construction: unknown keys are rejected, every string is bounded
+ * and printable, and nothing is coerced. Warnings are returned rather than
+ * silently swallowed — they are part of what the operator must read.
+ */
+export declare function parseVerseMcpSpec(body: unknown): VerseMcpSpecParse;
+export interface VerseMcpProposal {
+    ok: true;
+    /** What the operator must read before confirming. Env values are '<set>'. */
+    server: VerseMcpServerView;
+    target: {
+        id: VerseMcpTargetId;
+        ref: string;
+        label: string;
+    };
+    /** 'add' when the name is new in the target, 'replace' when it is not. */
+    action: 'add' | 'replace';
+    /** The server this would overwrite, redacted. Null on an add. */
+    replaces: VerseMcpServerView | null;
+    /** Everything the operator should weigh. Never empty for a real install. */
+    warnings: string[];
+    /** The scope this write lands under, and whether Locus permits it. */
+    scope: VerseMcpScopeGate;
+    /**
+     * Binds this exact disclosure to the target's current contents. `apply`
+     * refuses without it, and refuses again if the file moved underneath.
+     */
+    digest: string;
+    note: string;
+}
+export interface VerseMcpRefusalResult {
+    ok: false;
+    refusal: VerseMcpRefusal;
+    error: string;
+    note: string;
+}
+export declare const VERSE_MCP_PROPOSAL_NOTE: string;
+/**
+ * The digest the operator confirms against.
+ *
+ * Covers the REDACTED spec (what was shown), the target, and a hash of the
+ * target file's current bytes. Env values are deliberately outside it: the
+ * digest must be reproducible from what was displayed.
+ */
+export declare function verseMcpProposalDigest(input: {
+    server: VerseMcpServerView;
+    targetId: string;
+    targetBytes: string;
+}): string;
+export interface VerseMcpProposalOptions {
+    targetId: string;
+    server: unknown;
+    accountsRoot: string;
+    scope: VerseMcpScopeGate;
+    home?: string;
+}
+/**
+ * Validate, disclose, and hand back a digest. Writes nothing.
+ */
+export declare function buildVerseMcpProposal(options: VerseMcpProposalOptions): VerseMcpProposal | VerseMcpRefusalResult;
+export interface VerseMcpApplyResult {
+    ok: true;
+    action: 'add' | 'replace';
+    target: {
+        id: VerseMcpTargetId;
+        ref: string;
+    };
+    /** Re-read from disk after the write, redacted. What was actually persisted. */
+    server: VerseMcpServerView;
+    note: string;
+}
+export declare const VERSE_MCP_APPLIED_NOTE: string;
+export interface VerseMcpApplyOptions extends VerseMcpProposalOptions {
+    /** The digest returned by the proposal. A mismatch is a refusal. */
+    digest: string;
+}
+/**
+ * Apply a proposal the operator confirmed.
+ *
+ * Refuses unless the supplied digest reproduces from (a) the redacted spec it
+ * is about to write and (b) the target file's CURRENT bytes. That second half
+ * is what makes a stale confirmation fail instead of quietly clobbering a
+ * change made in between.
+ *
+ * The write is atomic: a sibling temp file, mode 0600, then rename.
+ */
+export declare function applyVerseMcpProposal(options: VerseMcpApplyOptions): VerseMcpApplyResult | VerseMcpRefusalResult;