@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/install/configMerge.d.ts

@@ -0,0 +1,91 @@
+/**
+ * MCP config-file merge for `bursar_install_agent_remotely`.
+ *
+ * Responsibilities (from SHIELD-INSTALL-AGENT-REMOTELY-REQUIREMENTS.md §FR-5):
+ *   - Resolve the default config path for an agentType on a given platform.
+ *   - Merge a "blacksands-shield" MCP server stanza into an existing JSON
+ *     config, never clobbering unrelated keys.
+ *   - Abort when the target file parses as something we don't recognize.
+ *   - Never silently set SHIELD_API_KEY; explicitly remove it if present.
+ *   - Produce an atomic write plan: compute the new content and a .bak of
+ *     the old content so the orchestrator can roll back.
+ *
+ * This module is PURE: it does not touch the filesystem. It takes the
+ * current file content (string | null) as input and returns the new
+ * content, the backup, and a structured diff. The orchestrator handles
+ * the actual reads/writes — keeps this unit-testable without mocks.
+ */
+export type AgentType = "claude-desktop" | "mcp-server" | "openclaw" | "custom";
+export type Platform = "darwin" | "win32" | "linux";
+export interface ConfigEnv {
+    SHIELD_CONNECTION_MODE: "broker";
+    SHIELD_AUTHORIZER_URL: string;
+    SHIELD_SERVICE_ID: string;
+    SHIELD_AUTH_PASSWORD: string;
+    SHIELD_CLIENT_CERT: string;
+    SHIELD_CLIENT_KEY: string;
+    SHIELD_CA_CERT?: string;
+}
+export interface MergeInput {
+    agentType: AgentType;
+    /** Current file content; null if the file does not exist. */
+    current: string | null;
+    /** Name to use as the JSON key under mcpServers. */
+    serverKey: string;
+    /** Env vars to inject into the server stanza. */
+    env: ConfigEnv;
+    /** Absolute path to the MCP server binary on the target (or command invocation). */
+    command: string;
+    args?: string[];
+}
+export interface MergeResult {
+    /** The new file content that should be written atomically. */
+    nextContent: string;
+    /** The previous content (null if file didn't exist) — used for .bak. */
+    previousContent: string | null;
+    /** Per-key summary of what changed, for human-readable dry-run output. */
+    diff: {
+        action: "create-file" | "insert-server" | "overwrite-server" | "noop";
+        serverKey: string;
+        removedKeys: string[];
+        notes: string[];
+    };
+}
+/**
+ * Resolves the default config-file path for an (agentType, platform) pair.
+ * Uses a provided home directory so this function is pure and testable.
+ * The `custom` agentType has no default — callers MUST pass an explicit path.
+ */
+export declare function defaultConfigPath(agentType: AgentType, platform: Platform, homeDir: string, appDataDir?: string): string | null;
+/** Convenience: resolve config path from runtime context with current-process fallbacks. */
+export declare function resolveConfigPath(agentType: AgentType, explicit?: string): string;
+/**
+ * Merge the blacksands-shield server stanza into a JSON config file.
+ *
+ * Merge semantics:
+ *   - If file doesn't exist → create `{ "mcpServers": { [serverKey]: <stanza> } }`.
+ *   - If file exists and parses as JSON object → preserve every existing key
+ *     except `mcpServers[serverKey]`, which we replace. If the existing stanza
+ *     had a SHIELD_API_KEY env var, we drop it (reported in diff.removedKeys).
+ *   - If file exists but isn't parseable JSON → abort with InstallError(phase: apply-config).
+ *   - If `mcpServers` exists but isn't an object → abort; same reasoning.
+ */
+export declare function mergeJsonConfig(input: MergeInput, filePath: string): MergeResult;
+/**
+ * YAML merge for OpenClaw's config.yaml. Same invariants as JSON:
+ *   - preserve every existing key
+ *   - strip legacy SHIELD_API_KEY if present
+ *   - abort on unparseable YAML or non-object root
+ *
+ * OpenClaw's schema expects an `mcp_servers:` map (snake_case) at the root.
+ * We write/replace the "blacksands-shield" entry inside it; all sibling
+ * entries are left untouched.
+ */
+export declare function mergeYamlConfig(input: MergeInput, filePath: string): MergeResult;
+/**
+ * Merge dispatcher: picks the right format based on agentType.
+ *   - openclaw → YAML (mcp_servers: …)
+ *   - everything else → JSON (mcpServers: …)
+ */
+export declare function mergeConfig(input: MergeInput, filePath: string): MergeResult;
+//# sourceMappingURL=configMerge.d.ts.map

package/build/shield/install/configMerge.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * MCP config-file merge for `bursar_install_agent_remotely`.
+ *
+ * Responsibilities (from SHIELD-INSTALL-AGENT-REMOTELY-REQUIREMENTS.md §FR-5):
+ *   - Resolve the default config path for an agentType on a given platform.
+ *   - Merge a "blacksands-shield" MCP server stanza into an existing JSON
+ *     config, never clobbering unrelated keys.
+ *   - Abort when the target file parses as something we don't recognize.
+ *   - Never silently set SHIELD_API_KEY; explicitly remove it if present.
+ *   - Produce an atomic write plan: compute the new content and a .bak of
+ *     the old content so the orchestrator can roll back.
+ *
+ * This module is PURE: it does not touch the filesystem. It takes the
+ * current file content (string | null) as input and returns the new
+ * content, the backup, and a structured diff. The orchestrator handles
+ * the actual reads/writes — keeps this unit-testable without mocks.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfigPath = defaultConfigPath;
+exports.resolveConfigPath = resolveConfigPath;
+exports.mergeJsonConfig = mergeJsonConfig;
+exports.mergeYamlConfig = mergeYamlConfig;
+exports.mergeConfig = mergeConfig;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const yaml = __importStar(require("js-yaml"));
+const errors_1 = require("../../shared/errors");
+// ──────────────────────────────────────────────────────────────────────────
+// Default config paths per agentType + platform
+// ──────────────────────────────────────────────────────────────────────────
+/**
+ * Resolves the default config-file path for an (agentType, platform) pair.
+ * Uses a provided home directory so this function is pure and testable.
+ * The `custom` agentType has no default — callers MUST pass an explicit path.
+ */
+function defaultConfigPath(agentType, platform, homeDir, appDataDir) {
+    if (agentType === "claude-desktop") {
+        if (platform === "darwin") {
+            return path.join(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        }
+        if (platform === "win32") {
+            const appData = appDataDir || path.join(homeDir, "AppData", "Roaming");
+            return path.join(appData, "Claude", "claude_desktop_config.json");
+        }
+        // Linux — Anthropic doesn't officially ship Claude Desktop for Linux, but
+        // the documented XDG path is the one third-party builds use.
+        return path.join(homeDir, ".config", "Claude", "claude_desktop_config.json");
+    }
+    if (agentType === "mcp-server") {
+        return path.join(homeDir, ".config", "blacksands", ".mcp.json");
+    }
+    if (agentType === "openclaw") {
+        return path.join(homeDir, ".openclaw", "config.yaml");
+    }
+    return null;
+}
+/** Convenience: resolve config path from runtime context with current-process fallbacks. */
+function resolveConfigPath(agentType, explicit) {
+    if (explicit)
+        return explicit;
+    const platform = process.platform;
+    const home = os.homedir();
+    const appData = process.env.APPDATA;
+    const resolved = defaultConfigPath(agentType, platform, home, appData);
+    if (!resolved) {
+        throw new errors_1.InstallError(`agentType "${agentType}" has no default config path; pass configPath explicitly`, { phase: "apply-config", next_steps: ['Pass a `configPath` value in the tool input.'] }, 400);
+    }
+    return resolved;
+}
+// ──────────────────────────────────────────────────────────────────────────
+// JSON config merge (claude-desktop, mcp-server)
+// ──────────────────────────────────────────────────────────────────────────
+/**
+ * Build the MCP server stanza that gets inserted under `mcpServers[serverKey]`.
+ * Returns a plain object; the caller serializes it as part of the full file.
+ *
+ * The env block explicitly OMITS SHIELD_API_KEY. If the existing stanza had
+ * one, we strip it (reported back in diff.removedKeys).
+ */
+function buildServerStanza(command, args, env) {
+    const envOut = {
+        SHIELD_CONNECTION_MODE: env.SHIELD_CONNECTION_MODE,
+        SHIELD_AUTHORIZER_URL: env.SHIELD_AUTHORIZER_URL,
+        SHIELD_SERVICE_ID: env.SHIELD_SERVICE_ID,
+        SHIELD_AUTH_PASSWORD: env.SHIELD_AUTH_PASSWORD,
+        SHIELD_CLIENT_CERT: env.SHIELD_CLIENT_CERT,
+        SHIELD_CLIENT_KEY: env.SHIELD_CLIENT_KEY,
+    };
+    if (env.SHIELD_CA_CERT)
+        envOut.SHIELD_CA_CERT = env.SHIELD_CA_CERT;
+    return {
+        command,
+        args: args || [],
+        env: envOut,
+    };
+}
+/**
+ * Parse JSON with a precise error — we want to tell the operator which file
+ * failed to parse, not just hand them "Unexpected token {".
+ */
+function safeParseJson(raw, filePath) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new errors_1.InstallError(`Config file at ${filePath} is not a JSON object — refusing to modify`, {
+                phase: "apply-config",
+                next_steps: [
+                    `Inspect ${filePath}. If it was intentionally customized, back it up and delete it, then retry.`,
+                ],
+            }, 409);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof errors_1.InstallError)
+            throw err;
+        throw new errors_1.InstallError(`Config file at ${filePath} is not valid JSON: ${err.message}`, {
+            phase: "apply-config",
+            next_steps: [
+                `Fix or remove ${filePath} before retrying. The tool refuses to overwrite unparseable files to avoid data loss.`,
+            ],
+        }, 409);
+    }
+}
+/**
+ * Merge the blacksands-shield server stanza into a JSON config file.
+ *
+ * Merge semantics:
+ *   - If file doesn't exist → create `{ "mcpServers": { [serverKey]: <stanza> } }`.
+ *   - If file exists and parses as JSON object → preserve every existing key
+ *     except `mcpServers[serverKey]`, which we replace. If the existing stanza
+ *     had a SHIELD_API_KEY env var, we drop it (reported in diff.removedKeys).
+ *   - If file exists but isn't parseable JSON → abort with InstallError(phase: apply-config).
+ *   - If `mcpServers` exists but isn't an object → abort; same reasoning.
+ */
+function mergeJsonConfig(input, filePath) {
+    const notes = [];
+    const removedKeys = [];
+    const stanza = buildServerStanza(input.command, input.args, input.env);
+    if (input.current === null || input.current.trim() === "") {
+        const nextObj = { mcpServers: { [input.serverKey]: stanza } };
+        notes.push(`Created new config file at ${filePath}.`);
+        return {
+            nextContent: JSON.stringify(nextObj, null, 2) + "\n",
+            previousContent: null,
+            diff: { action: "create-file", serverKey: input.serverKey, removedKeys, notes },
+        };
+    }
+    const parsed = safeParseJson(input.current, filePath);
+    let action = "insert-server";
+    // mcpServers must be an object (or absent). Arrays/primitives → abort.
+    let mcpServers = parsed.mcpServers;
+    if (mcpServers === undefined) {
+        mcpServers = {};
+    }
+    else if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+        throw new errors_1.InstallError(`Config file at ${filePath} has a non-object "mcpServers" key — refusing to modify`, {
+            phase: "apply-config",
+            next_steps: [`Fix the "mcpServers" key in ${filePath} to be a JSON object, then retry.`],
+        }, 409);
+    }
+    const mcpServersObj = mcpServers;
+    const existing = mcpServersObj[input.serverKey];
+    if (existing !== undefined) {
+        action = "overwrite-server";
+        notes.push(`Overwriting existing "${input.serverKey}" server stanza.`);
+        // Detect stripped SHIELD_API_KEY for reporting
+        if (existing !== null &&
+            typeof existing === "object" &&
+            !Array.isArray(existing) &&
+            "env" in existing &&
+            existing.env !== null &&
+            typeof existing.env === "object") {
+            const existingEnv = existing.env;
+            if ("SHIELD_API_KEY" in existingEnv) {
+                removedKeys.push(`mcpServers.${input.serverKey}.env.SHIELD_API_KEY`);
+                notes.push("Removed legacy SHIELD_API_KEY from existing stanza — broker mode requires mTLS + auth password only.");
+            }
+        }
+    }
+    const nextObj = {
+        ...parsed,
+        mcpServers: {
+            ...mcpServersObj,
+            [input.serverKey]: stanza,
+        },
+    };
+    // Preserve insertion order as closely as possible: if mcpServers wasn't
+    // originally in the parsed object, it will show up at the end, which
+    // matches what `JSON.stringify` does by default on spread.
+    return {
+        nextContent: JSON.stringify(nextObj, null, 2) + "\n",
+        previousContent: input.current,
+        diff: { action, serverKey: input.serverKey, removedKeys, notes },
+    };
+}
+// ──────────────────────────────────────────────────────────────────────────
+// YAML config merge (openclaw)
+// ──────────────────────────────────────────────────────────────────────────
+/**
+ * YAML merge for OpenClaw's config.yaml. Same invariants as JSON:
+ *   - preserve every existing key
+ *   - strip legacy SHIELD_API_KEY if present
+ *   - abort on unparseable YAML or non-object root
+ *
+ * OpenClaw's schema expects an `mcp_servers:` map (snake_case) at the root.
+ * We write/replace the "blacksands-shield" entry inside it; all sibling
+ * entries are left untouched.
+ */
+function mergeYamlConfig(input, filePath) {
+    const notes = [];
+    const removedKeys = [];
+    const stanza = buildServerStanza(input.command, input.args, input.env);
+    if (input.current === null || input.current.trim() === "") {
+        const nextObj = { mcp_servers: { [input.serverKey]: stanza } };
+        notes.push(`Created new YAML config at ${filePath}.`);
+        return {
+            nextContent: yaml.dump(nextObj, { lineWidth: 120, noRefs: true }),
+            previousContent: null,
+            diff: { action: "create-file", serverKey: input.serverKey, removedKeys, notes },
+        };
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(input.current);
+    }
+    catch (err) {
+        throw new errors_1.InstallError(`Config file at ${filePath} is not valid YAML: ${err.message}`, {
+            phase: "apply-config",
+            next_steps: [`Fix or remove ${filePath}. The tool refuses to overwrite unparseable files.`],
+        }, 409);
+    }
+    if (parsed === null || parsed === undefined) {
+        parsed = {};
+    }
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new errors_1.InstallError(`Config file at ${filePath} root is not a YAML mapping — refusing to modify`, { phase: "apply-config" }, 409);
+    }
+    const root = parsed;
+    let action = "insert-server";
+    let mcpServers = root.mcp_servers;
+    if (mcpServers === undefined) {
+        mcpServers = {};
+    }
+    else if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+        throw new errors_1.InstallError(`Config file at ${filePath} has a non-mapping "mcp_servers" key — refusing to modify`, { phase: "apply-config" }, 409);
+    }
+    const mcpServersObj = mcpServers;
+    const existing = mcpServersObj[input.serverKey];
+    if (existing !== undefined) {
+        action = "overwrite-server";
+        notes.push(`Overwriting existing "${input.serverKey}" entry.`);
+        if (existing !== null &&
+            typeof existing === "object" &&
+            !Array.isArray(existing) &&
+            "env" in existing &&
+            typeof existing.env === "object" &&
+            existing.env !== null) {
+            const existingEnv = existing.env;
+            if ("SHIELD_API_KEY" in existingEnv) {
+                removedKeys.push(`mcp_servers.${input.serverKey}.env.SHIELD_API_KEY`);
+                notes.push("Removed legacy SHIELD_API_KEY from existing entry — broker mode uses mTLS + auth password only.");
+            }
+        }
+    }
+    const nextObj = {
+        ...root,
+        mcp_servers: {
+            ...mcpServersObj,
+            [input.serverKey]: stanza,
+        },
+    };
+    return {
+        nextContent: yaml.dump(nextObj, { lineWidth: 120, noRefs: true }),
+        previousContent: input.current,
+        diff: { action, serverKey: input.serverKey, removedKeys, notes },
+    };
+}
+/**
+ * Merge dispatcher: picks the right format based on agentType.
+ *   - openclaw → YAML (mcp_servers: …)
+ *   - everything else → JSON (mcpServers: …)
+ */
+function mergeConfig(input, filePath) {
+    if (input.agentType === "openclaw") {
+        return mergeYamlConfig(input, filePath);
+    }
+    return mergeJsonConfig(input, filePath);
+}
+//# sourceMappingURL=configMerge.js.map

package/build/shield/install/keystore.d.ts

@@ -0,0 +1,25 @@
+export type KeystoreBackend = "keychain" | "libsecret" | "wincred" | "none";
+export type KeystoreMode = "off" | "auto" | "on";
+/** Service/label namespace under which secrets are filed in the OS store. */
+export declare const KEYSTORE_SERVICE = "blacksands-shield-mcp";
+/** The secret kinds we manage. */
+export type SecretKind = "key" | "password";
+/** Account name for a secret: "<clientName>.<kind>". */
+export declare function secretAccount(clientName: string, kind: SecretKind): string;
+/** Parse the BS_MCP_KEYSTORE gate. Default "off" (disk-only, no behavior change). */
+export declare function keystoreMode(env?: NodeJS.ProcessEnv): KeystoreMode;
+/** Which backend this platform can use (ignores the mode gate). */
+export declare function detectBackend(platform?: NodeJS.Platform): KeystoreBackend;
+/**
+ * Whether the keystore should be used right now: the mode is not "off" AND a
+ * backend is available. With mode "on" and no backend, we still report false
+ * (callers fall back to disk) but should surface a warning — see storeSecret.
+ */
+export declare function isKeystoreAvailable(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Store a secret. Returns true on success, false on any failure (caller falls back to disk). */
+export declare function storeSecret(account: string, secret: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Retrieve a secret. Returns the value, or null if absent / unavailable / on error. */
+export declare function retrieveSecret(account: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | null;
+/** Delete a secret. Best-effort; returns true if the backend reported success. */
+export declare function removeSecret(account: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+//# sourceMappingURL=keystore.d.ts.map

package/build/shield/install/keystore.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEYSTORE_SERVICE = void 0;
+exports.secretAccount = secretAccount;
+exports.keystoreMode = keystoreMode;
+exports.detectBackend = detectBackend;
+exports.isKeystoreAvailable = isKeystoreAvailable;
+exports.storeSecret = storeSecret;
+exports.retrieveSecret = retrieveSecret;
+exports.removeSecret = removeSecret;
+/** OS keystore storage for MCP installation secrets (F4.11, Gap #9 PR-G9-5).
+ *
+ * The installation-bound MCP private key and broker auth-password are the two
+ * sensitive items in ~/.blacksands/mcp-certs/. This module stores them in the
+ * platform secret store instead of (or in addition to) plain disk files:
+ *   - macOS   → Keychain   (`security` generic password)
+ *   - Linux   → libsecret  (`secret-tool`)
+ *   - Windows → not yet wired (falls back to disk; see GAP9 design doc)
+ *
+ * Design constraints:
+ *   - Every operation is best-effort and NEVER throws. A keystore miss or a
+ *     command failure returns false/null so the caller transparently falls
+ *     back to the existing disk path — credential handling must never make an
+ *     install worse than it is today.
+ *   - Gated by BS_MCP_KEYSTORE (off | auto | on); default "off" preserves the
+ *     current disk-only behavior byte-for-byte until a deployment opts in.
+ *   - The cert and CA are public and stay on disk; only the key + password are
+ *     candidates for the keystore.
+ *
+ * All shelling-out uses execFileSync (argv array, no shell) so a secret can
+ * never be interpreted by a shell.
+ */
+const child_process_1 = require("child_process");
+/** Service/label namespace under which secrets are filed in the OS store. */
+exports.KEYSTORE_SERVICE = "blacksands-shield-mcp";
+/** Account name for a secret: "<clientName>.<kind>". */
+function secretAccount(clientName, kind) {
+    return `${clientName}.${kind}`;
+}
+/** Parse the BS_MCP_KEYSTORE gate. Default "off" (disk-only, no behavior change). */
+function keystoreMode(env = process.env) {
+    const v = (env.BS_MCP_KEYSTORE || "").trim().toLowerCase();
+    if (v === "on" || v === "1" || v === "true" || v === "require")
+        return "on";
+    if (v === "auto")
+        return "auto";
+    return "off";
+}
+/** True if a command resolves on PATH (no output, no throw on success). */
+function commandExists(cmd, platform = process.platform) {
+    try {
+        (0, child_process_1.execFileSync)(platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Which backend this platform can use (ignores the mode gate). */
+function detectBackend(platform = process.platform) {
+    if (platform === "darwin")
+        return commandExists("security", platform) ? "keychain" : "none";
+    if (platform === "linux")
+        return commandExists("secret-tool", platform) ? "libsecret" : "none";
+    // win32: Credential Manager wiring is a follow-up (PR-G9-5b). Fall back to disk.
+    return "none";
+}
+/**
+ * Whether the keystore should be used right now: the mode is not "off" AND a
+ * backend is available. With mode "on" and no backend, we still report false
+ * (callers fall back to disk) but should surface a warning — see storeSecret.
+ */
+function isKeystoreAvailable(env = process.env, platform = process.platform) {
+    if (keystoreMode(env) === "off")
+        return false;
+    return detectBackend(platform) !== "none";
+}
+/** Store a secret. Returns true on success, false on any failure (caller falls back to disk). */
+function storeSecret(account, secret, env = process.env, platform = process.platform) {
+    if (keystoreMode(env) === "off")
+        return false;
+    const backend = detectBackend(platform);
+    try {
+        if (backend === "keychain") {
+            // -U updates an existing item without prompting; -w takes the secret value.
+            (0, child_process_1.execFileSync)("security", [
+                "add-generic-password", "-U",
+                "-a", account, "-s", exports.KEYSTORE_SERVICE, "-w", secret,
+            ], { stdio: "ignore" });
+            return true;
+        }
+        if (backend === "libsecret") {
+            // secret-tool reads the secret from stdin (not argv) — preferred.
+            (0, child_process_1.execFileSync)("secret-tool", [
+                "store", "--label", `${exports.KEYSTORE_SERVICE}:${account}`,
+                "service", exports.KEYSTORE_SERVICE, "account", account,
+            ], { input: secret, stdio: ["pipe", "ignore", "ignore"] });
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Retrieve a secret. Returns the value, or null if absent / unavailable / on error. */
+function retrieveSecret(account, env = process.env, platform = process.platform) {
+    if (keystoreMode(env) === "off")
+        return null;
+    const backend = detectBackend(platform);
+    try {
+        if (backend === "keychain") {
+            const out = (0, child_process_1.execFileSync)("security", [
+                "find-generic-password", "-a", account, "-s", exports.KEYSTORE_SERVICE, "-w",
+            ], { encoding: "utf8" });
+            // `security -w` emits the password followed by a trailing newline.
+            return out.length > 0 ? out.replace(/\r?\n$/, "") : null;
+        }
+        if (backend === "libsecret") {
+            const out = (0, child_process_1.execFileSync)("secret-tool", [
+                "lookup", "service", exports.KEYSTORE_SERVICE, "account", account,
+            ], { encoding: "utf8" });
+            return out.length > 0 ? out.replace(/\r?\n$/, "") : null;
+        }
+        return null;
+    }
+    catch {
+        // Non-zero exit (item not found) or command missing → caller uses disk.
+        return null;
+    }
+}
+/** Delete a secret. Best-effort; returns true if the backend reported success. */
+function removeSecret(account, env = process.env, platform = process.platform) {
+    if (keystoreMode(env) === "off")
+        return false;
+    const backend = detectBackend(platform);
+    try {
+        if (backend === "keychain") {
+            (0, child_process_1.execFileSync)("security", [
+                "delete-generic-password", "-a", account, "-s", exports.KEYSTORE_SERVICE,
+            ], { stdio: "ignore" });
+            return true;
+        }
+        if (backend === "libsecret") {
+            (0, child_process_1.execFileSync)("secret-tool", [
+                "clear", "service", exports.KEYSTORE_SERVICE, "account", account,
+            ], { stdio: "ignore" });
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=keystore.js.map

package/build/shield/install/orchestrator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Orchestrator for bursar_install_agent_remotely.
+ *
+ * Coordinates: precheck → transport.deliver → (config merge + restart are
+ * the target's job for bootstrap-token; handled by the transport itself
+ * for SSH/SSM in later phases) → handshake verification → rollback on
+ * failure.
+ *
+ * The orchestrator is intentionally thin. Transport-specific behavior
+ * lives in the Transport classes; config-file manipulation lives in
+ * configMerge. This file is just the state machine.
+ *
+ * See SHIELD-INSTALL-AGENT-REMOTELY-REQUIREMENTS.md §FR-1 through §FR-12.
+ */
+import type { ShieldClient } from "../client";
+import type { InstallInput, InstallResult } from "./types";
+export interface RunInstallDeps {
+    shield: ShieldClient;
+    /** Authorizer URL to fall back to when input.authorizerUrl is omitted. */
+    defaultAuthorizerUrl?: string;
+}
+export declare function runInstall(input: InstallInput, deps: RunInstallDeps): Promise<InstallResult>;
+/**
+ * Run install with full lifecycle: advisory lock → audit start →
+ * precheck → transport.deliver → handshake poll → audit finalize →
+ * lock release. On failure after precheck, the transport's rollback
+ * hook runs (SSH rolls back files + revokes the cert; bootstrap-token
+ * deletes the minted token).
+ *
+ * Exposed as the public entry point used by the tool handler in server.ts.
+ */
+export declare function runInstallWithRollback(input: InstallInput, deps: RunInstallDeps): Promise<InstallResult>;
+//# sourceMappingURL=orchestrator.d.ts.map