llm-cli-gateway 2.13.2 → 2.14.0

package/dist/provider-admin-tools.js

@@ -0,0 +1,572 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { executeCli } from "./executor.js";
+import { noopLogger } from "./logger.js";
+import { redactSecrets } from "./secret-redaction.js";
+import { redactAcpMessage } from "./acp/errors.js";
+import { adminSurfaceKind, getAllProviderDefinitions, getProviderDefinition, } from "./provider-definitions.js";
+import { peekProviderCapabilitySet, resolveProviderCapabilitySet, } from "./provider-capability-resolver.js";
+import { getCliSubcommandContract, } from "./upstream-contracts.js";
+import { getRequestContext, resolveOwnerPrincipal, } from "./request-context.js";
+export function adminRiskToExposure(risk) {
+    switch (risk) {
+        case "read_only":
+            return "mcp_readonly";
+        case "writes_local_config":
+        case "auth":
+        case "network":
+        case "destructive":
+            return "mcp_requires_approval";
+        case "starts_server":
+        case "updates_binary":
+        case "executes_agent":
+            return "not_exposed";
+        default: {
+            const never = risk;
+            return never;
+        }
+    }
+}
+const READ_VERBS = new Set([
+    "list",
+    "ls",
+    "get",
+    "show",
+    "status",
+    "view",
+    "info",
+    "doctor",
+    "about",
+    "version",
+    "help",
+    "models",
+    "model",
+    "print",
+    "describe",
+    "cat",
+    "export",
+    "paths",
+    "path",
+    "whoami",
+    "current",
+    "inspect",
+    "trace",
+    "changelog",
+    "completion",
+    "debug",
+]);
+const AUTH_VERBS = new Set(["login", "logout"]);
+const DESTRUCTIVE_VERBS = new Set([
+    "delete",
+    "remove",
+    "rm",
+    "purge",
+    "destroy",
+    "wipe",
+    "reset",
+    "clear",
+    "uninstall",
+]);
+const STARTS_SERVER_VERBS = new Set([
+    "serve",
+    "server",
+    "listen",
+    "daemon",
+    "mcp-server",
+    "app-server",
+]);
+const CONFIG_MUTATE_VERBS = new Set([
+    "add",
+    "set",
+    "enable",
+    "disable",
+    "install",
+    "import",
+    "archive",
+    "fork",
+    "marketplace",
+    "register",
+    "unregister",
+    "edit",
+    "create",
+    "init",
+    "save",
+    "apply",
+    "sync",
+    "start",
+    "run",
+    "exec",
+]);
+export function classifyOperationRisk(operationName, familyRisk, opts = {}) {
+    const n = operationName.trim().toLowerCase();
+    if (READ_VERBS.has(n))
+        return "read_only";
+    if (AUTH_VERBS.has(n))
+        return "auth";
+    if (DESTRUCTIVE_VERBS.has(n))
+        return "destructive";
+    if (STARTS_SERVER_VERBS.has(n))
+        return "starts_server";
+    if (CONFIG_MUTATE_VERBS.has(n))
+        return "writes_local_config";
+    if (opts.isSubcommand && familyRisk === "read_only") {
+        return "writes_local_config";
+    }
+    return familyRisk;
+}
+export function familyBaseRisk(provider, fam) {
+    const contract = getCliSubcommandContract(provider, [fam.family]);
+    if (contract)
+        return contract.risk;
+    return fam.safety === "read-only" ? "read_only" : "writes_local_config";
+}
+function rootAdvertises(discovered, family) {
+    const wanted = family.toLowerCase();
+    return discovered.rootHelp.subcommands.some(s => s.name.toLowerCase() === wanted);
+}
+function familySubHelp(discovered, family) {
+    const wanted = family.toLowerCase();
+    for (const [key, help] of Object.entries(discovered.subcommandHelp)) {
+        const tokens = key.split(/\s+/).filter(Boolean);
+        const first = tokens.find(t => !t.startsWith("-"));
+        if (first && first.toLowerCase() === wanted)
+            return help;
+    }
+    return null;
+}
+export function projectProviderAdminOperations(def, discovered) {
+    const ops = [];
+    for (const fam of def.adminSubcommands) {
+        if (adminSurfaceKind(fam) !== "cli-subcommand")
+            continue;
+        const baseRisk = familyBaseRisk(def.id, fam);
+        if (!discovered) {
+            ops.push({
+                provider: def.id,
+                family: fam.family,
+                operationId: fam.family,
+                argv: [fam.family],
+                risk: baseRisk,
+                exposure: adminRiskToExposure(baseRisk),
+                mutating: adminRiskToExposure(baseRisk) === "mcp_requires_approval",
+                available: false,
+                discoverySource: "no-discovery",
+                summary: fam.evidence,
+            });
+            continue;
+        }
+        const advertised = rootAdvertises(discovered, fam.family);
+        const subHelp = familySubHelp(discovered, fam.family);
+        const subOps = subHelp?.subcommands ?? [];
+        if (subOps.length > 0) {
+            for (const sub of subOps) {
+                if (!isSafeAdminToken(sub.name))
+                    continue;
+                const risk = classifyOperationRisk(sub.name, baseRisk, { isSubcommand: true });
+                const exposure = adminRiskToExposure(risk);
+                ops.push({
+                    provider: def.id,
+                    family: fam.family,
+                    operationId: `${fam.family}.${sub.name}`,
+                    argv: [fam.family, sub.name],
+                    risk,
+                    exposure,
+                    mutating: exposure === "mcp_requires_approval",
+                    available: exposure !== "not_exposed" && exposure !== "tracked_only",
+                    discoverySource: "subcommand-help",
+                    summary: sub.description || fam.evidence,
+                });
+            }
+            continue;
+        }
+        const baseExposure = adminRiskToExposure(baseRisk);
+        const risk = baseExposure === "not_exposed" ? baseRisk : classifyOperationRisk(fam.family, baseRisk);
+        const exposure = adminRiskToExposure(risk);
+        ops.push({
+            provider: def.id,
+            family: fam.family,
+            operationId: fam.family,
+            argv: [fam.family],
+            risk,
+            exposure,
+            mutating: exposure === "mcp_requires_approval",
+            available: advertised && exposure !== "not_exposed" && exposure !== "tracked_only",
+            discoverySource: advertised ? "root-help" : "not-advertised",
+            summary: fam.evidence,
+        });
+    }
+    return ops;
+}
+export function buildProviderAdminCatalog(options = {}) {
+    const lookup = options.lookup ?? ((id) => peekProviderCapabilitySet(id)?.set ?? null);
+    const defs = options.provider
+        ? [getProviderDefinition(options.provider)]
+        : getAllProviderDefinitions();
+    const rows = [];
+    for (const def of defs) {
+        const discovered = lookup(def.id);
+        for (const op of projectProviderAdminOperations(def, discovered)) {
+            if (!options.includeUnavailable && !op.available)
+                continue;
+            rows.push({
+                provider: op.provider,
+                operationId: op.operationId,
+                family: op.family,
+                argv: op.argv,
+                risk: op.risk,
+                exposure: op.exposure,
+                mutating: op.mutating,
+                available: op.available,
+                discoverySource: op.discoverySource,
+                summary: op.summary.length > 80 ? `${op.summary.slice(0, 77).trimEnd()}...` : op.summary,
+            });
+        }
+    }
+    return rows.sort((a, b) => `${a.provider}:${a.operationId}`.localeCompare(`${b.provider}:${b.operationId}`));
+}
+const REDACTED = "[REDACTED]";
+const OAUTH_CODE_RE = /\b(code|verifier|challenge|state|nonce|otp)\s*[:=]\s*[A-Za-z0-9._~+/=-]{6,}/gi;
+const ACCOUNT_ID_RE = /\b(?:user|customer|account|acct|org|tenant)[_-][A-Za-z0-9]{6,}\b/gi;
+export function redactAdminOutput(text) {
+    if (!text)
+        return text;
+    let out = redactSecrets(text);
+    out = out.replace(OAUTH_CODE_RE, (_m, key) => `${key}=${REDACTED}`);
+    out = out.replace(ACCOUNT_ID_RE, REDACTED);
+    out = redactAcpMessage(out);
+    return out;
+}
+const defaultAdminRunner = (executable, argv, options) => executeCli(executable, [...argv], { timeout: options.timeoutMs });
+export function isSafeAdminToken(token) {
+    if (token.length === 0 || token.length > 64)
+        return false;
+    return /^-{0,2}[A-Za-z0-9][A-Za-z0-9._-]*$/.test(token);
+}
+function assertSafeArgv(argv) {
+    for (const token of argv) {
+        if (!isSafeAdminToken(token)) {
+            throw new Error(`Unsafe admin argv token rejected: ${JSON.stringify(token)}`);
+        }
+    }
+}
+export async function runReadOnlyAdminOperation(op, deps = {}) {
+    const logger = deps.logger ?? noopLogger;
+    if (op.exposure !== "mcp_readonly") {
+        return {
+            ok: false,
+            provider: op.provider,
+            operationId: op.operationId,
+            argv: op.argv,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            redacted: true,
+            error: `Operation ${op.operationId} is not read-only (exposure=${op.exposure}); use the mutating admin tool.`,
+        };
+    }
+    if (!op.available) {
+        return {
+            ok: false,
+            provider: op.provider,
+            operationId: op.operationId,
+            argv: op.argv,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            redacted: true,
+            error: `Operation ${op.operationId} is not advertised by the installed ${op.provider} CLI.`,
+        };
+    }
+    assertSafeArgv(op.argv);
+    const def = getProviderDefinition(op.provider);
+    const runner = deps.runner ?? defaultAdminRunner;
+    try {
+        const result = await runner(def.primaryExecutable, op.argv, { timeoutMs: deps.timeoutMs });
+        return {
+            ok: result.code === 0,
+            provider: op.provider,
+            operationId: op.operationId,
+            argv: op.argv,
+            exitCode: result.code,
+            stdout: redactAdminOutput(result.stdout),
+            stderr: redactAdminOutput(result.stderr),
+            redacted: true,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.debug(`admin read-only op failed: ${op.operationId}`, { reason });
+        return {
+            ok: false,
+            provider: op.provider,
+            operationId: op.operationId,
+            argv: op.argv,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            redacted: true,
+            error: redactAdminOutput(reason),
+        };
+    }
+}
+export function defaultAdminAuditPath() {
+    return join(homedir(), ".llm-cli-gateway", "admin-audit.jsonl");
+}
+export function defaultAdminAuditSink(auditPath) {
+    return record => {
+        const path = auditPath ?? defaultAdminAuditPath();
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf-8", mode: 0o600 });
+    };
+}
+function appendAdminAuditBestEffort(record, sink) {
+    try {
+        sink(record);
+    }
+    catch {
+    }
+}
+export function appendAdminAudit(record, auditPath) {
+    appendAdminAuditBestEffort(record, defaultAdminAuditSink(auditPath));
+}
+export async function runMutatingAdminOperation(op, ctx) {
+    const logger = ctx.logger ?? noopLogger;
+    const sink = ctx.auditSink ?? defaultAdminAuditSink(ctx.auditPath);
+    const base = {
+        provider: op.provider,
+        operationId: op.operationId,
+        argv: op.argv,
+        redacted: true,
+    };
+    const fail = (error) => ({
+        ok: false,
+        ...base,
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        error,
+    });
+    const auditBestEffort = (outcome, extra = {}) => appendAdminAuditBestEffort({
+        ts: new Date().toISOString(),
+        provider: op.provider,
+        operationId: op.operationId,
+        argv: op.argv,
+        outcome,
+        principal: ctx.principal,
+        ...extra,
+    }, sink);
+    if (!op.available) {
+        return fail(`Operation ${op.operationId} is not advertised by the installed ${op.provider} CLI.`);
+    }
+    if (op.exposure !== "mcp_requires_approval") {
+        return fail(`Operation ${op.operationId} (exposure=${op.exposure}) is not an approval-gated mutating admin op.`);
+    }
+    if (ctx.remoteCaller && !ctx.remoteAdminAllowed) {
+        auditBestEffort("gate_closed");
+        return fail(`Mutating admin operation ${op.operationId} is not permitted for remote callers. ` +
+            `Set LLM_GATEWAY_CLI_ADMIN=1 and grant the cli:admin OAuth scope to permit it.`);
+    }
+    if (!ctx.allowMutating) {
+        auditBestEffort("gate_closed");
+        return fail(`Mutating admin operation ${op.operationId} is disabled. Set [admin] ` +
+            `allow_mutating_cli_admin_ops = true in ~/.llm-cli-gateway/config.toml to permit it.`);
+    }
+    assertSafeArgv(op.argv);
+    const decision = ctx.approvalManager.decide({
+        cli: op.provider,
+        operation: `cli_admin:${op.operationId}`,
+        prompt: `Provider CLI admin mutation: ${op.provider} ${op.argv.join(" ")} (${op.risk})`,
+        bypassRequested: false,
+        fullAuto: false,
+        requestedMcpServers: [],
+        metadata: { adminOperation: op.operationId, risk: op.risk, argv: op.argv },
+    });
+    if (decision.status !== "approved") {
+        auditBestEffort("denied", { approvalId: decision.id });
+        return fail(`Mutating admin operation ${op.operationId} denied by approval policy (${decision.reasons.join("; ")}).`);
+    }
+    try {
+        sink({
+            ts: new Date().toISOString(),
+            provider: op.provider,
+            operationId: op.operationId,
+            argv: op.argv,
+            outcome: "approved",
+            approvalId: decision.id,
+            principal: ctx.principal,
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error(`admin mutating op aborted: audit write failed for ${op.operationId}`, { reason });
+        return fail(`Mutating admin operation ${op.operationId} aborted: the approved-intent audit record ` +
+            `could not be persisted, so the mutation was not run.`);
+    }
+    const def = getProviderDefinition(op.provider);
+    const runner = ctx.runner ?? defaultAdminRunner;
+    try {
+        const result = await runner(def.primaryExecutable, op.argv, { timeoutMs: ctx.timeoutMs });
+        auditBestEffort("executed", { approvalId: decision.id, exitCode: result.code });
+        return {
+            ok: result.code === 0,
+            ...base,
+            exitCode: result.code,
+            stdout: redactAdminOutput(result.stdout),
+            stderr: redactAdminOutput(result.stderr),
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.debug(`admin mutating op failed: ${op.operationId}`, { reason });
+        auditBestEffort("executed", { approvalId: decision.id, exitCode: null });
+        return fail(redactAdminOutput(reason));
+    }
+}
+export function isRemoteAdminCaller(ctx) {
+    return ctx?.transport === "http" || ctx?.authKind === "oauth";
+}
+export function remoteCliAdminEnabled(ctx) {
+    const scopes = ctx?.authScopes ?? [];
+    return process.env.LLM_GATEWAY_CLI_ADMIN === "1" && scopes.includes("cli:admin");
+}
+async function resolveAdminOperation(provider, operationId, logger) {
+    const def = getProviderDefinition(provider);
+    let discovered = peekProviderCapabilitySet(provider)?.set ?? null;
+    if (!discovered) {
+        const resolved = await resolveProviderCapabilitySet(def, { logger });
+        discovered = resolved?.set ?? null;
+    }
+    const ops = projectProviderAdminOperations(def, discovered);
+    return ops.find(o => o.operationId === operationId) ?? null;
+}
+const PROVIDER_ADMIN_ENUM = z.enum(getAllProviderDefinitions().map(d => d.id));
+function remoteReadOnlyAdminGate(toolName) {
+    const ctx = getRequestContext();
+    if (isRemoteAdminCaller(ctx) && !remoteCliAdminEnabled(ctx)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: false,
+                        error: `${toolName} is not permitted for remote callers. Set LLM_GATEWAY_CLI_ADMIN=1 ` +
+                            `and grant the cli:admin OAuth scope to permit read-only provider admin operations remotely.`,
+                    }),
+                },
+            ],
+        };
+    }
+    return null;
+}
+export function registerProviderAdminTools(server, runtime) {
+    server.tool("provider_admin_list", "List provider CLI admin operations (auth status, model list, mcp list, plugin list, doctor, etc.) available on the installed CLIs, projected from runtime discovery. Read-only.", {
+        provider: z
+            .preprocess(value => (value === "" || value === null ? undefined : value), PROVIDER_ADMIN_ENUM.optional())
+            .describe("Optional provider filter"),
+        includeUnavailable: z
+            .boolean()
+            .default(false)
+            .describe("Include operations the installed CLI does not advertise or the policy hides"),
+    }, {
+        title: "Provider admin operations catalog",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, includeUnavailable }) => {
+        const gate = remoteReadOnlyAdminGate("provider_admin_list");
+        if (gate)
+            return gate;
+        const targets = provider ? [getProviderDefinition(provider)] : getAllProviderDefinitions();
+        await Promise.all(targets.map(def => peekProviderCapabilitySet(def.id)
+            ? Promise.resolve(null)
+            : resolveProviderCapabilitySet(def, { logger: runtime.logger }).catch(() => null)));
+        const rows = buildProviderAdminCatalog({ provider, includeUnavailable });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        schemaVersion: "provider-admin-catalog.v1",
+                        mutatingEnabled: runtime.allowMutatingCliAdminOps,
+                        total: rows.length,
+                        rows,
+                    }),
+                },
+            ],
+        };
+    });
+    server.tool("provider_admin_run", "Execute a READ-ONLY provider CLI admin operation (from provider_admin_list) and return redacted output. Rejects mutating operations.", {
+        provider: PROVIDER_ADMIN_ENUM.describe("Provider whose admin operation to run"),
+        operationId: z
+            .string()
+            .min(1)
+            .describe("Operation id from provider_admin_list, e.g. 'mcp.list' or 'doctor'"),
+    }, {
+        title: "Run read-only provider admin operation",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, operationId }) => {
+        const gate = remoteReadOnlyAdminGate("provider_admin_run");
+        if (gate)
+            return gate;
+        const op = await resolveAdminOperation(provider, operationId, runtime.logger);
+        if (!op) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: `No admin operation '${operationId}' for ${provider} (not advertised by the installed CLI).`,
+                        }),
+                    },
+                ],
+            };
+        }
+        const result = await runReadOnlyAdminOperation(op, { logger: runtime.logger });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    server.tool("provider_admin_mutate", "Execute a MUTATING provider CLI admin operation (mcp add/remove, login/logout, plugin install/remove, session delete/archive, ...). Disabled unless [admin] allow_mutating_cli_admin_ops=true; routed through approval and audited.", {
+        provider: PROVIDER_ADMIN_ENUM.describe("Provider whose admin operation to run"),
+        operationId: z
+            .string()
+            .min(1)
+            .describe("Mutating operation id from provider_admin_list, e.g. 'mcp.remove'"),
+    }, {
+        title: "Run mutating provider admin operation (gated)",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false,
+    }, async ({ provider, operationId }) => {
+        const op = await resolveAdminOperation(provider, operationId, runtime.logger);
+        if (!op) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: `No admin operation '${operationId}' for ${provider} (not advertised by the installed CLI).`,
+                        }),
+                    },
+                ],
+            };
+        }
+        const reqCtx = getRequestContext();
+        const result = await runMutatingAdminOperation(op, {
+            allowMutating: runtime.allowMutatingCliAdminOps,
+            remoteCaller: isRemoteAdminCaller(reqCtx),
+            remoteAdminAllowed: remoteCliAdminEnabled(reqCtx),
+            principal: resolveOwnerPrincipal(reqCtx),
+            approvalManager: runtime.approvalManager,
+            logger: runtime.logger,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+}

package/dist/provider-capability-cache.d.ts

@@ -0,0 +1,46 @@
+import type { CliType } from "./provider-definitions.js";
+import type { DiscoveredCapabilitySet } from "./provider-capability-discovery.js";
+export declare const CAPABILITY_CACHE_SCHEMA_VERSION = "provider-capability-cache.v1";
+export interface CapabilityCacheKeyFields {
+    readonly providerId: CliType;
+    readonly executablePath: string;
+    readonly version: string;
+    readonly rootHelpChecksum: string;
+    readonly subcommandHelpChecksums: Readonly<Record<string, string>>;
+    readonly acpInitializeChecksum: string | null;
+    readonly modelCatalogChecksum: string;
+    readonly gatewayVersion: string;
+}
+export interface CachedCapabilityEntry {
+    readonly schemaVersion: typeof CAPABILITY_CACHE_SCHEMA_VERSION;
+    readonly providerId: CliType;
+    readonly cacheKey: string;
+    readonly keyFields: CapabilityCacheKeyFields;
+    readonly capabilitySet: DiscoveredCapabilitySet;
+    readonly cachedAt: string;
+    readonly source: "discovery";
+}
+export interface CapabilityCacheLookup {
+    readonly hit: boolean;
+    readonly ageMs: number | null;
+    readonly cachedAt: string | null;
+    readonly source: string | null;
+    readonly version: string | null;
+    readonly checksum: string | null;
+    readonly entry: CachedCapabilityEntry | null;
+}
+export declare function capabilityCacheDir(): string;
+export declare function cacheKeyFields(set: DiscoveredCapabilitySet): CapabilityCacheKeyFields;
+export declare function computeCacheKey(set: DiscoveredCapabilitySet): string;
+export declare function scrubString(value: string): string;
+export declare function scrubSecrets<T>(value: T): T;
+export declare function readCapabilityCache(providerId: CliType): CachedCapabilityEntry | null;
+export declare function writeCapabilityCache(set: DiscoveredCapabilitySet): CachedCapabilityEntry;
+export declare function lookupCapabilityCache(freshSet: DiscoveredCapabilitySet): CapabilityCacheLookup;
+export interface ResolvedCapability {
+    readonly set: DiscoveredCapabilitySet;
+    readonly source: "discovery" | "cache" | "minimal";
+    readonly degraded: boolean;
+    readonly reason?: string;
+}
+export declare function resolveCapabilitySet(freshSet: DiscoveredCapabilitySet): ResolvedCapability;