@wardby/cli 0.7.0 → 0.9.0

package/dist/core/mcp-servers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Remote MCP servers: the owner-side domain. Validates a server's URL and name, loads the owner's
+ * brokered secrets for it, builds the McpFetch that sends them (brokeredFetch over safeFetch), takes
+ * the redacted tool snapshot, and diffs snapshots. Secret values never leave this file in any output:
+ * snapshots are redacted by exact value (every encoded form) plus token shapes before they are returned.
+ */
+import type { PrismaClient } from "#prisma";
+import { type McpFetch, type McpServerInfo, type McpToolEntry } from "./mcp-client/client.js";
+import type { SecretsAccessor } from "./secrets.js";
+import type { Logger } from "./logger.js";
+import type { SecretCipher } from "../providers/secrets/types.js";
+import { safeFetch } from "../sandbox/safe-fetch.js";
+export declare class McpServerInputError extends Error {
+    constructor(message: string);
+}
+/** What the server's owner (or an admin) sees when a stored secret of the server can't be decrypted. */
+export declare const CREDENTIALS_UNAVAILABLE_MESSAGE = "The MCP server's credentials can't be decrypted on this server. Check that every Wardby process (control plane, scheduler, native gateway) uses the same SECRET_APP_KEY, or set the secret again.";
+/**
+ * A server's brokered secret exists but its stored value can't be decrypted (another
+ * SECRET_APP_KEY, a key-id mismatch, a corrupt ciphertext). Not an input problem: the message is
+ * fixed and never carries the cipher's error, the ciphertext or a value.
+ */
+export declare class McpCredentialsUnavailableError extends Error {
+    /** Empty while a server is being registered (it has no id yet). */
+    readonly serverId: string;
+    readonly serverName: string;
+    readonly secretName: string;
+    readonly code = "mcp_server_credentials_unavailable";
+    constructor(
+    /** Empty while a server is being registered (it has no id yet). */
+    serverId: string, serverName: string, secretName: string);
+}
+/** The one operator line for an undecryptable server secret: ids and names only, never the cipher's error text. */
+export declare function logCredentialsUnavailable(log: Pick<Logger, "warn">, error: McpCredentialsUnavailableError): void;
+export interface McpServerRow {
+    id: string;
+    ownerId: string;
+    name: string;
+    url: string;
+    secretNames: string[];
+}
+/** Validates a server URL: https, no userinfo, no fragment, default port; returns the normalised string. */
+export declare function normaliseServerUrl(raw: string): string;
+export declare function assertServerName(name: string): void;
+/** The tool name the model sees: `<server>__<tool>` with any other character mapped to `_`. */
+export declare function exposedToolName(serverName: string, toolName: string): string;
+/** A server's saved tool list (toolSnapshot); anything but an array reads as empty. */
+export declare function snapshotOf(server: {
+    toolSnapshot: unknown;
+}): McpToolEntry[];
+/** Exposed names of allowed tools; a name too long to expose is left out (refused at attach anyway). */
+export declare function exposedNames(serverName: string, allowedTools: readonly string[]): string[];
+/** Added, removed and changed (description or schema) tool names between two snapshots; order-independent. */
+export declare function diffSnapshots(before: McpToolEntry[], after: McpToolEntry[]): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
+/** Redacts every secret value of this server (exact, every encoded and escaped form) plus token shapes. */
+export declare function redactForServer(text: string, values: string[]): string;
+/** The same error with its message redacted; an McpClientError keeps its code, any other keeps its name. */
+export declare function redactError(error: unknown, values: string[]): Error;
+type SecretDb = Pick<PrismaClient, "secret">;
+/**
+ * Loads the owner's secrets for the server; each must exist, be owned by ownerId, be brokered, and list
+ * the URL's host (McpServerInputError otherwise). A stored value that can't be decrypted throws
+ * McpCredentialsUnavailableError.
+ */
+export declare function loadServerSecrets(db: SecretDb, cipher: Pick<SecretCipher, "decrypt">, server: McpServerRow): Promise<{
+    accessor: SecretsAccessor;
+    values: string[];
+}>;
+/** The McpFetch for one server: brokeredFetch over safeFetch with the timeout and signal; text body, lower-case headers. */
+export declare function serverFetch(server: McpServerRow, accessor: SecretsAccessor, options: {
+    timeoutMs: number;
+    fetchImpl?: typeof safeFetch;
+}): McpFetch;
+/** initialize + listTools + close; the result is redacted (as JSON text) before it is returned. */
+export declare function fetchSnapshot(server: McpServerRow, deps: {
+    db: SecretDb;
+    cipher: Pick<SecretCipher, "decrypt">;
+    fetchImpl?: typeof safeFetch;
+    timeoutMs?: number;
+}): Promise<{
+    serverInfo: McpServerInfo;
+    tools: McpToolEntry[];
+}>;
+/** For the secret delete guard: names of the owner's MCP servers whose secretNames include the secret. */
+export declare function mcpServersUsingSecret(db: Pick<PrismaClient, "mcpServer">, ownerId: string, secretName: string): Promise<string[]>;
+export {};

package/dist/core/mcp-servers.js

@@ -0,0 +1,230 @@
+import { redactTokenShapedValues } from "../coding/protocol.js";
+import { McpClientError, McpHttpClient, } from "./mcp-client/client.js";
+import { parseSecretBrokerConfig } from "./secret-broker-config.js";
+import { redactExactSecretValues, withEscapedForms } from "./secret-spans.js";
+import { brokeredFetch } from "../sandbox/brokered-fetch.js";
+import { safeFetch } from "../sandbox/safe-fetch.js";
+import { consoleRedactionValues, encodedForms } from "../sandbox/secret-broker.js";
+export class McpServerInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpServerInputError";
+    }
+}
+/** What the server's owner (or an admin) sees when a stored secret of the server can't be decrypted. */
+export const CREDENTIALS_UNAVAILABLE_MESSAGE = "The MCP server's credentials can't be decrypted on this server. Check that every Wardby process (control plane, scheduler, native gateway) uses the same SECRET_APP_KEY, or set the secret again.";
+/**
+ * A server's brokered secret exists but its stored value can't be decrypted (another
+ * SECRET_APP_KEY, a key-id mismatch, a corrupt ciphertext). Not an input problem: the message is
+ * fixed and never carries the cipher's error, the ciphertext or a value.
+ */
+export class McpCredentialsUnavailableError extends Error {
+    serverId;
+    serverName;
+    secretName;
+    code = "mcp_server_credentials_unavailable";
+    constructor(
+    /** Empty while a server is being registered (it has no id yet). */
+    serverId, serverName, secretName) {
+        super(CREDENTIALS_UNAVAILABLE_MESSAGE);
+        this.serverId = serverId;
+        this.serverName = serverName;
+        this.secretName = secretName;
+        this.name = "McpCredentialsUnavailableError";
+    }
+}
+/** The one operator line for an undecryptable server secret: ids and names only, never the cipher's error text. */
+export function logCredentialsUnavailable(log, error) {
+    log.warn({
+        reason: "mcp_secret_decrypt_failed",
+        ...(error.serverId !== "" ? { serverId: error.serverId } : {}),
+        serverName: error.serverName,
+        secretName: error.secretName,
+    }, "MCP server secret could not be decrypted");
+}
+const SERVER_NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const EXPOSED_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Validates a server URL: https, no userinfo, no fragment, default port; returns the normalised string. */
+export function normaliseServerUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new McpServerInputError("The MCP server URL is not a valid URL.");
+    }
+    if (url.protocol !== "https:")
+        throw new McpServerInputError("The MCP server URL must use https.");
+    if (url.username !== "" || url.password !== "")
+        throw new McpServerInputError("The MCP server URL must not contain a username or password; use a brokered secret.");
+    if (url.hash !== "")
+        throw new McpServerInputError("The MCP server URL must not contain a fragment (#).");
+    if (url.port !== "")
+        throw new McpServerInputError("The MCP server URL must use the default https port (443).");
+    return url.href;
+}
+export function assertServerName(name) {
+    if (!SERVER_NAME.test(name)) {
+        throw new McpServerInputError("The MCP server name must be 1-32 characters: lower-case letters, digits, _ or -, starting with a letter or digit.");
+    }
+}
+/** The tool name the model sees: `<server>__<tool>` with any other character mapped to `_`. */
+export function exposedToolName(serverName, toolName) {
+    const name = `${serverName}__${toolName}`.replace(/[^A-Za-z0-9_-]/g, "_");
+    if (!EXPOSED_NAME.test(name)) {
+        throw new McpServerInputError(`The tool name "${name.slice(0, 40)}..." is longer than 64 characters once prefixed.`);
+    }
+    return name;
+}
+/** A server's saved tool list (toolSnapshot); anything but an array reads as empty. */
+export function snapshotOf(server) {
+    return Array.isArray(server.toolSnapshot) ? server.toolSnapshot : [];
+}
+/** Exposed names of allowed tools; a name too long to expose is left out (refused at attach anyway). */
+export function exposedNames(serverName, allowedTools) {
+    return allowedTools.flatMap((tool) => {
+        try {
+            return [exposedToolName(serverName, tool)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** Added, removed and changed (description or schema) tool names between two snapshots; order-independent. */
+export function diffSnapshots(before, after) {
+    const old = new Map(before.map((t) => [t.name, t]));
+    const next = new Map(after.map((t) => [t.name, t]));
+    const added = [...next.keys()].filter((n) => !old.has(n)).sort();
+    const removed = [...old.keys()].filter((n) => !next.has(n)).sort();
+    const changed = [...next.keys()].filter((n) => old.has(n) && canonical(old.get(n)) !== canonical(next.get(n))).sort();
+    return { added, removed, changed };
+}
+function canonical(value) {
+    return JSON.stringify(value, (_key, v) => v !== null && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : v);
+}
+/** Redacts every secret value of this server (exact, every encoded and escaped form) plus token shapes. */
+export function redactForServer(text, values) {
+    const forms = withEscapedForms(values.flatMap(encodedForms)).sort((a, b) => b.length - a.length);
+    return redactTokenShapedValues(redactExactSecretValues(text, [...values, ...forms]));
+}
+/** The same error with its message redacted; an McpClientError keeps its code, any other keeps its name. */
+export function redactError(error, values) {
+    const message = redactForServer(error instanceof Error ? error.message : "The MCP server call failed.", values);
+    if (error instanceof McpClientError)
+        return new McpClientError(error.code, message);
+    if (error instanceof McpServerInputError)
+        return new McpServerInputError(message);
+    // Its message is fixed and carries no value: keep it (and its ids) as it is.
+    if (error instanceof McpCredentialsUnavailableError)
+        return error;
+    const out = new Error(message);
+    if (error instanceof Error)
+        out.name = error.name;
+    return out;
+}
+/**
+ * Loads the owner's secrets for the server; each must exist, be owned by ownerId, be brokered, and list
+ * the URL's host (McpServerInputError otherwise). A stored value that can't be decrypted throws
+ * McpCredentialsUnavailableError.
+ */
+export async function loadServerSecrets(db, cipher, server) {
+    const host = new URL(server.url).hostname.toLowerCase();
+    const entries = new Map();
+    const values = new Set();
+    for (const name of server.secretNames) {
+        const stored = await db.secret.findUnique({
+            where: { ownerId_name: { ownerId: server.ownerId, name } },
+            select: { ciphertext: true, broker: true },
+        });
+        if (!stored)
+            throw new McpServerInputError(`Secret "${name}" was not found among your secrets.`);
+        if (stored.broker === null || stored.broker === undefined)
+            throw new McpServerInputError(`Secret "${name}" is not brokered; set its broker config first (set_secret_broker).`);
+        let broker;
+        try {
+            broker = parseSecretBrokerConfig(stored.broker);
+        }
+        catch {
+            throw new McpServerInputError(`Secret "${name}" has a broker config that cannot be read; set it again.`);
+        }
+        if (!broker.hosts.includes(host))
+            throw new McpServerInputError(`Secret "${name}" is not brokered to host ${host}; add it to the secret's hosts.`);
+        let value;
+        try {
+            value = await cipher.decrypt(stored.ciphertext);
+        }
+        catch {
+            // The cipher's error is dropped: it is not an input problem, and its text is not ours to pass on.
+            throw new McpCredentialsUnavailableError(server.id, server.name, name);
+        }
+        const entry = { value, broker };
+        entries.set(name, entry);
+        for (const v of withEscapedForms(consoleRedactionValues(entry)))
+            values.add(v);
+    }
+    const accessor = {
+        get: async () => {
+            throw new Error("secret_brokered: this secret is brokered; it is never readable");
+        },
+        resolve: async (name) => entries.get(name),
+    };
+    return { accessor, values: [...values] };
+}
+/** The McpFetch for one server: brokeredFetch over safeFetch with the timeout and signal; text body, lower-case headers. */
+export function serverFetch(server, accessor, options) {
+    return async (request, signal) => {
+        const response = (await brokeredFetch({
+            url: server.url,
+            init: { method: request.method, headers: request.headers, body: request.body },
+            secretNames: server.secretNames,
+            secrets: accessor,
+            fetchImpl: options.fetchImpl ?? safeFetch,
+            policy: { timeoutMs: options.timeoutMs, signal },
+            redactFromConsole: () => { },
+        }));
+        return {
+            status: response.status,
+            headers: Object.fromEntries(Object.entries(response.headers).map(([k, v]) => [k.toLowerCase(), v])),
+            body: Buffer.from(response.bodyBase64, "base64").toString("utf8"),
+        };
+    };
+}
+/** initialize + listTools + close; the result is redacted (as JSON text) before it is returned. */
+export async function fetchSnapshot(server, deps) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const { accessor, values } = await loadServerSecrets(deps.db, deps.cipher, server);
+    const client = new McpHttpClient({
+        fetch: serverFetch(server, accessor, { timeoutMs, fetchImpl: deps.fetchImpl }),
+        signal: AbortSignal.timeout(timeoutMs * 3),
+    });
+    let raw;
+    try {
+        const serverInfo = await client.initialize();
+        raw = { serverInfo, tools: await client.listTools() };
+    }
+    catch (error) {
+        throw redactError(error, values);
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+    const redacted = redactForServer(JSON.stringify(raw), values);
+    try {
+        return JSON.parse(redacted);
+    }
+    catch {
+        throw new McpServerInputError("The MCP server's tool list could not be saved safely.");
+    }
+}
+/** For the secret delete guard: names of the owner's MCP servers whose secretNames include the secret. */
+export async function mcpServersUsingSecret(db, ownerId, secretName) {
+    const rows = await db.mcpServer.findMany({
+        where: { ownerId, secretNames: { has: secretName } },
+        select: { name: true },
+    });
+    return rows.map((r) => r.name).sort();
+}

package/dist/core/mcp-tools.d.ts

@@ -0,0 +1,108 @@
+/**
+ * A native run's remote MCP tools: the load step pins the agent's attached, allowed tools
+ * (loadMcpToolPins), the runner offers them as built-ins (mcpToolDefs), and every call runs on the
+ * control plane through handleMcpTool. The pin decides only which tools the model sees for this
+ * run; each call re-checks the live attachment, that the agent's owner may still use the server (owns
+ * it or holds use on it), and uses the live server row (URL, secrets). A pin carries no URL (a query
+ * string can carry a token), secret names or owner id: pins are saved in the run's step results.
+ *
+ * Secret values never leave: results and errors are redacted against the server's secrets (every
+ * encoded form) plus token shapes, the log line carries no arguments, bodies or URL, and
+ * mcpNamedSecretValues feeds the run's own redaction (secret-guard.ts loadAgentSecretValues).
+ */
+import type { PrismaClient } from "#prisma";
+import type { Logger } from "./logger.js";
+import type { LoadedTool } from "../providers/engine/types.js";
+import type { SecretCipher } from "../providers/secrets/types.js";
+import type { safeFetch } from "../sandbox/safe-fetch.js";
+/** One MCP tool as the load step pins it. */
+export interface McpToolPin {
+    /** The name the model sees: `<server name>__<tool name>`. */
+    exposedName: string;
+    /** The name the server knows. */
+    toolName: string;
+    serverId: string;
+    serverName: string;
+    /** Only when the attachment sets one. */
+    callTimeoutMs?: number;
+    definition: {
+        description: string;
+        inputSchema: Record<string, unknown>;
+    };
+}
+export declare const DEFAULT_MCP_CALL_TIMEOUT_MS = 30000;
+/** What a grantee's run sees when the server owner's credentials can't be loaded. */
+export declare const SHARED_CREDENTIALS_MESSAGE = "The MCP server's credentials can't be used; ask its owner to check it.";
+/**
+ * A Codex coding agent runs shell commands that can read the run's MCP token, so it may use only tools
+ * the server marks read-only (annotations.readOnlyHint === true in the saved tool list).
+ */
+export declare function isMarkedReadOnly(entry: {
+    annotations?: Record<string, unknown>;
+} | undefined): boolean;
+/**
+ * Whether a coding provider gets the Codex read-only rule. Fails closed: anything but exactly
+ * "claude-code" (Codex, an unknown value, or a coding agent with no profile) counts as Codex. A run
+ * is judged by the provider it was dispatched with (CodingRun.provider), never the agent's current
+ * profile, which can change between dispatch and launch.
+ */
+export declare function isCodexCoding(provider: string | null | undefined): boolean;
+type McpToolsDb = Pick<PrismaClient, "agentMcpServer" | "secret" | "resourceGrant">;
+/** Redaction reads attachments and secrets only: it covers every attached server, usable or not. */
+type McpSecretsDb = Pick<PrismaClient, "agentMcpServer" | "secret">;
+export interface McpToolPinOptions {
+    /**
+     * Pin only tools the server marks read-only: the caller sets it for a Codex coding run, from the
+     * provider the run was dispatched with (isCodexCoding(run.provider)). Native runs leave it unset.
+     */
+    readOnlyOnly?: boolean;
+}
+/**
+ * Builds pins for an agent's attachments: allowed tools present in the snapshot only, from servers the
+ * agent's owner may still use (owns, or holds use on); none when the mode is off.
+ */
+export declare function loadMcpToolPins(db: Pick<PrismaClient, "agentMcpServer" | "resourceGrant">, agentId: string, options?: McpToolPinOptions): Promise<McpToolPin[]>;
+/**
+ * The pins whose exposed name no other tool of the run uses. Attach refuses clashes; this covers a
+ * name that became a built-in (or an attached tool) later: the MCP tool is left out, with a warning.
+ */
+export declare function withoutClashingPins(pins: readonly McpToolPin[], otherNames: readonly string[], log: Pick<Logger, "warn">): McpToolPin[];
+export declare function mcpToolDefs(pins: readonly McpToolPin[]): LoadedTool[];
+export interface McpToolContext {
+    db: McpToolsDb;
+    cipher: Pick<SecretCipher, "decrypt">;
+    /** The agent whose attachment is re-checked on every call. */
+    agentId: string;
+    /** The run, for the per-call log line. */
+    runId: string;
+    /** The run's stop signal: aborting it stops a call in flight. */
+    signal: AbortSignal;
+    /** A sandboxed run's session deadline; the call's time limit never runs past it. */
+    deadlineAt?: Date;
+    /**
+     * Refuse any tool the live tool list doesn't mark read-only: set by the coding gateway for a Codex
+     * run, from the run's dispatched provider (isCodexCoding(codingRun.provider)). Native runs leave it unset.
+     */
+    readOnlyOnly?: boolean;
+    fetchImpl?: typeof safeFetch;
+    log: Pick<Logger, "info" | "warn">;
+}
+/**
+ * Never throws. Re-checks the live attachment, validates the arguments, runs initialize → tools/call →
+ * close under the time limit, and returns the redacted result text or a JSON error. One log line per call.
+ */
+export declare function handleMcpTool(pin: McpToolPin, argsJson: string, ctx: McpToolContext): Promise<string>;
+export interface NamedMcpSecretValues {
+    /** `mcp:<server name>/<secret name>`. */
+    name: string;
+    values: string[];
+}
+/**
+ * Every secret value of every server attached to the agent, named `mcp:<server>/<secret>`, in
+ * every form the server's own redaction looks for. A secret that no longer exists has no value to
+ * leak and is skipped; a read that fails rejects (callers fail closed).
+ */
+export declare function mcpNamedSecretValues(db: McpSecretsDb, cipher: Pick<SecretCipher, "decrypt">, agentId: string): Promise<NamedMcpSecretValues[]>;
+/** Secret values for every attached server of this agent (for run-text masking and gateway cause checks). */
+export declare function mcpSecretValuesForAgent(db: McpSecretsDb, cipher: Pick<SecretCipher, "decrypt">, agentId: string): Promise<string[]>;
+export {};