@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/install/orchestrator.js

@@ -0,0 +1,404 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInstall = runInstall;
+exports.runInstallWithRollback = runInstallWithRollback;
+const crypto_1 = require("crypto");
+const bootstrapToken_1 = require("./transports/bootstrapToken");
+const ssh_1 = require("./transports/ssh");
+const awsSsm_1 = require("./transports/awsSsm");
+const configMerge_1 = require("./configMerge");
+const errors_1 = require("../../shared/errors");
+const logger_1 = require("../../shared/logger");
+// ──────────────────────────────────────────────────────────────────────────
+// Transport factory
+// ──────────────────────────────────────────────────────────────────────────
+function buildTransport(shield, spec) {
+    switch (spec.type) {
+        case "bootstrap-token": return new bootstrapToken_1.BootstrapTokenTransport(shield, spec);
+        case "ssh": return new ssh_1.SshTransport(shield, spec);
+        case "aws-ssm": return new awsSsm_1.AwsSsmTransport(shield, spec);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Target redaction — strip anything remotely sensitive before echoing
+// the transport spec in the tool response (§5 output contract)
+// ──────────────────────────────────────────────────────────────────────────
+function redactTarget(spec) {
+    switch (spec.type) {
+        case "ssh":
+            return {
+                type: spec.type,
+                host: spec.host,
+                port: spec.port,
+                username: spec.username,
+                authMethod: spec.authMethod,
+                sudo: spec.sudo,
+                hasHostKeyFingerprint: !!spec.hostKeyFingerprint,
+            };
+        case "bootstrap-token":
+            return {
+                type: spec.type,
+                ttlSeconds: spec.ttlSeconds,
+                deliverVia: spec.deliverVia,
+                oneShot: spec.oneShot,
+                hasAllowedCidr: !!spec.allowedCidr,
+                hasEmail: !!spec.email,
+            };
+        case "aws-ssm":
+            return {
+                type: spec.type,
+                instanceId: spec.instanceId,
+                region: spec.region || null,
+            };
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Idempotency precheck (§FR-10)
+// ──────────────────────────────────────────────────────────────────────────
+async function precheckExisting(shield, clientName) {
+    try {
+        const resp = await shield.listMcpCerts();
+        const existing = (resp.data || []).find(c => c.name === clientName);
+        if (existing) {
+            return { conflict: true, existing };
+        }
+        return { conflict: false };
+    }
+    catch (err) {
+        // If we can't list, fall through rather than blocking the install;
+        // the Shield API will reject a duplicate on issue-cert anyway.
+        logger_1.logger.warn("install precheck: could not list MCP certs, proceeding", {
+            error: err.message,
+        });
+        return { conflict: false };
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Default restart command suggestions (§FR-6)
+// ──────────────────────────────────────────────────────────────────────────
+function defaultRestartCommand(agentType, clientName) {
+    switch (agentType) {
+        case "claude-desktop":
+            // §10.3: don't automate quit-and-reopen; instruct user to restart.
+            return null;
+        case "mcp-server":
+            return `systemctl --user restart blacksands-${clientName}`;
+        case "openclaw":
+            return `systemctl --user restart openclaw-${clientName}`;
+        case "custom":
+            return null;
+    }
+}
+async function runInstall(input, deps) {
+    const auditId = (0, crypto_1.randomUUID)();
+    const startedAt = Date.now();
+    const authorizerUrl = input.authorizerUrl || deps.defaultAuthorizerUrl;
+    if (!authorizerUrl) {
+        throw new errors_1.InstallError("authorizerUrl was not provided and this MCP server does not have a default Authorizer configured (http-service mode without SHIELD_AUTHORIZER_URL)", {
+            phase: "precheck",
+            clientName: input.clientName,
+            next_steps: [
+                "Provide `authorizerUrl` explicitly, e.g. 'https://auth.beta.blacksandscyber.online'.",
+            ],
+        }, 400);
+    }
+    const configPath = (0, configMerge_1.resolveConfigPath)(input.agentType, input.configPath);
+    const redactedTarget = redactTarget(input.transport);
+    const revokeHint = `bursar_revoke_mcp_cert({ clientName: "${input.clientName}" })`;
+    logger_1.logger.info("install: start", {
+        auditId,
+        clientName: input.clientName,
+        orgId: input.orgId,
+        agentType: input.agentType,
+        transport: input.transport.type,
+        dryRun: input.dryRun,
+    });
+    // ── Dry-run short-circuit (§FR-9) ──────────────────────────────────────
+    if (input.dryRun) {
+        const plannedRestart = input.restartCmd || defaultRestartCommand(input.agentType, input.clientName) || "(none — manual restart)";
+        return {
+            status: "dry-run",
+            clientName: input.clientName,
+            clientId: `dry-run:${auditId}`,
+            transport: input.transport.type,
+            target: redactedTarget,
+            installedFiles: [],
+            configPath,
+            handshake: { verified: false, reason: "dry-run" },
+            auditId,
+            revokeHint,
+            next_steps: [
+                `(dry-run) Would mint/issue credentials for clientName="${input.clientName}" in orgId="${input.orgId}".`,
+                `(dry-run) Would write cert bundle + merge config at ${configPath}.`,
+                `(dry-run) Would issue restart: ${plannedRestart}`,
+                `(dry-run) Would verify handshake through ${authorizerUrl}.`,
+                "Remove `dryRun: true` to actually perform the install.",
+            ],
+            warnings: input.transport.type === "ssh" || input.transport.type === "aws-ssm"
+                ? [
+                    `${input.transport.type} transport is a Phase A.2/B stub — dry-run reports as if it would work, but live execution will throw InstallError('transport-not-implemented').`,
+                ]
+                : undefined,
+        };
+    }
+    // ── Precheck: duplicate clientName? (§FR-10) ───────────────────────────
+    const precheck = await precheckExisting(deps.shield, input.clientName);
+    if (precheck.conflict) {
+        throw new errors_1.InstallError(`ALREADY_INSTALLED: a cert for clientName="${input.clientName}" already exists`, {
+            phase: "precheck",
+            clientName: input.clientName,
+            next_steps: [
+                `Existing cert: CN=${precheck.existing.cn}, fingerprint=${precheck.existing.fingerprint.slice(0, 16)}…, expires=${precheck.existing.expires}`,
+                `To re-issue, revoke the existing cert first: ${revokeHint}`,
+                "Or pick a different clientName.",
+            ],
+        }, 409);
+    }
+    // ── Transport.deliver ───────────────────────────────────────────────────
+    const transport = buildTransport(deps.shield, input.transport);
+    let delivery;
+    try {
+        delivery = await transport.deliver({
+            clientName: input.clientName,
+            orgId: input.orgId,
+            agentType: input.agentType,
+            configPath,
+            serviceId: input.serviceId,
+            authorizerUrl,
+            role: input.role,
+        });
+    }
+    catch (err) {
+        // Delivery failures haven't mutated anything yet — nothing to roll back,
+        // but we still re-throw as an InstallError for consistent error shape.
+        if (err instanceof errors_1.InstallError)
+            throw err;
+        throw new errors_1.InstallError(`Transport '${input.transport.type}' failed to deliver: ${err.message}`, {
+            phase: "connect-transport",
+            transport: input.transport.type,
+            clientName: input.clientName,
+            cause: { name: err.name, message: err.message },
+        }, 502);
+    }
+    // ── Handshake verification (§FR-7) ─────────────────────────────────────
+    // bootstrap-token deliveries return status: "bootstrap-pending" — nothing
+    // to verify yet, because the target hasn't redeemed the token.
+    // For synchronous transports (ssh), poll the Shield API until the
+    // newly-issued cert authenticates or we time out.
+    let handshake;
+    if (input.waitForHandshake && delivery.status === "installed") {
+        handshake = await pollHandshake(deps.shield, input.clientName, input.handshakeTimeoutMs, startedAt);
+    }
+    else {
+        handshake = buildHandshakeResult(input, delivery.status, Date.now() - startedAt);
+    }
+    const next_steps = [...delivery.next_steps];
+    if (delivery.status === "bootstrap-pending") {
+        next_steps.push("After the target completes installation, run bursar_list_mcp_certs to confirm the new identity is registered.", "Once the agent is up, run receiver_onboard_service to grant it access to specific backend services (governance default is deny-all — §FR-12).");
+    }
+    // ── Compose result (§5 output contract) ────────────────────────────────
+    return {
+        status: delivery.status,
+        clientName: input.clientName,
+        clientId: delivery.clientId,
+        fingerprint: delivery.fingerprint,
+        expires: delivery.expires,
+        transport: input.transport.type,
+        target: redactedTarget,
+        installedFiles: delivery.installedFiles,
+        configPath,
+        bootstrapUrl: delivery.bootstrapUrl,
+        bootstrapExpiresAt: delivery.bootstrapExpiresAt,
+        handshake,
+        auditId,
+        revokeHint,
+        next_steps,
+        warnings: delivery.warnings,
+    };
+}
+function buildHandshakeResult(input, status, waitedMs) {
+    if (status === "bootstrap-pending") {
+        return {
+            verified: false,
+            waitedMs: 0,
+            reason: "awaiting-redemption — target has not yet consumed the setup token",
+        };
+    }
+    return {
+        verified: false,
+        waitedMs,
+        reason: input.waitForHandshake
+            ? "skipped"
+            : "waitForHandshake=false",
+    };
+}
+/**
+ * Poll GET /mcp/certs/:clientName/handshake with exponential backoff
+ * until the cert has its first broker handshake or we hit timeoutMs.
+ * Delays: 1s, 2s, 4s, 8s, capped at 15s.
+ */
+async function pollHandshake(shield, clientName, timeoutMs, startedAt) {
+    const deadline = startedAt + timeoutMs;
+    let delay = 1000;
+    while (Date.now() < deadline) {
+        try {
+            const h = await shield.getHandshakeStatus(clientName);
+            if (h.verified) {
+                return {
+                    verified: true,
+                    verifiedAt: h.first_handshake_at || new Date().toISOString(),
+                    receiverUrl: h.receiver_url || undefined,
+                    waitedMs: Date.now() - startedAt,
+                };
+            }
+        }
+        catch (err) {
+            // 404 is expected right after issuance in some deployments — keep
+            // polling. Other errors we log but don't fatal out; the caller can
+            // re-run with waitForHandshake=false if Shield API is broken.
+            logger_1.logger.debug("install: handshake poll transient error", {
+                clientName, error: err.message,
+            });
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise(r => setTimeout(r, Math.min(delay, remaining)));
+        delay = Math.min(delay * 2, 15_000);
+    }
+    return {
+        verified: false,
+        waitedMs: Date.now() - startedAt,
+        reason: `timeout after ${timeoutMs}ms — cert exists but has not yet completed a broker handshake`,
+    };
+}
+/**
+ * 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.
+ */
+async function runInstallWithRollback(input, deps) {
+    const auditId = (0, crypto_1.randomUUID)();
+    let lockAcquired = false;
+    // ── 1. Acquire advisory lock (§7 Concurrency) ─────────────────────────
+    // Non-fatal if the endpoint is unavailable — log and proceed. Fatal only
+    // if Shield reports 409 (another owner holds it).
+    try {
+        await deps.shield.acquireInstallLock(input.clientName, {
+            ttlSeconds: Math.min(Math.max(Math.floor(input.handshakeTimeoutMs / 1000) + 120, 300), 3600),
+            auditId,
+        });
+        lockAcquired = true;
+    }
+    catch (err) {
+        const message = err.message || "";
+        if (/409|Conflict|Lock held/i.test(message)) {
+            throw new errors_1.InstallError(`Install lock for clientName="${input.clientName}" is held by another operator — wait for them to finish or pick a different clientName.`, { phase: "precheck", clientName: input.clientName, cause: { name: err.name, message } }, 409);
+        }
+        logger_1.logger.warn("install: lock acquire failed (non-fatal, proceeding)", {
+            clientName: input.clientName, error: message,
+        });
+    }
+    // ── 2. Audit: install-started ─────────────────────────────────────────
+    void writeAudit(deps.shield, {
+        auditId,
+        clientName: input.clientName,
+        transportType: input.transport.type,
+        agentType: input.agentType,
+        status: "started",
+        phase: "precheck",
+        dryRun: input.dryRun,
+        target: redactTarget(input.transport),
+    });
+    let result;
+    try {
+        result = await runInstall({ ...input }, deps);
+        // Override auditId so the tool response matches the audit ledger.
+        result.auditId = auditId;
+    }
+    catch (err) {
+        // Audit failure, then re-throw (transport has already rolled back its
+        // own state inside deliver()).
+        const phase = err instanceof errors_1.InstallError ? err.phase : "precheck";
+        void writeAudit(deps.shield, {
+            auditId,
+            clientName: input.clientName,
+            transportType: input.transport.type,
+            agentType: input.agentType,
+            status: "failed",
+            phase,
+            dryRun: input.dryRun,
+            target: redactTarget(input.transport),
+            errorMessage: err.message,
+        });
+        if (lockAcquired) {
+            deps.shield.releaseInstallLock(input.clientName).catch((e) => {
+                logger_1.logger.warn("install: lock release after failure errored", {
+                    clientName: input.clientName, error: e.message,
+                });
+            });
+        }
+        if (!input.rollbackOnFailure || !(err instanceof errors_1.InstallError))
+            throw err;
+        if (err.phase === "precheck" || err.phase === "issue-cert" || err.phase === "mint-token") {
+            throw err;
+        }
+        // The transport has already performed rollback inside its deliver()
+        // catch block; we just re-throw unchanged so the caller sees the
+        // attached rollback:{performed:true, steps:[...]} block.
+        throw err;
+    }
+    // ── 3. Audit: install completed (or bootstrap-pending) ────────────────
+    void writeAudit(deps.shield, {
+        auditId,
+        clientName: input.clientName,
+        transportType: input.transport.type,
+        agentType: input.agentType,
+        status: result.status,
+        phase: result.handshake.verified ? "verify-handshake" : "apply-config",
+        dryRun: input.dryRun,
+        target: redactTarget(input.transport),
+    });
+    // ── 4. Release lock ────────────────────────────────────────────────────
+    if (lockAcquired) {
+        deps.shield.releaseInstallLock(input.clientName).catch((e) => {
+            logger_1.logger.warn("install: lock release errored", {
+                clientName: input.clientName, error: e.message,
+            });
+        });
+    }
+    return result;
+}
+/**
+ * Fire-and-forget audit writer — never throws; audit failures are
+ * logged but must not break the install flow.
+ */
+async function writeAudit(shield, row) {
+    try {
+        await shield.recordInstallAudit(row);
+    }
+    catch (err) {
+        logger_1.logger.warn("install: audit write failed", {
+            auditId: row.auditId, error: err.message,
+        });
+    }
+}
+//# sourceMappingURL=orchestrator.js.map

package/build/shield/install/transports/awsSsm.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AWS Systems Manager (SSM) transport.
+ *
+ * Delivers a Shield MCP identity to an SSM-managed EC2 instance without
+ * opening inbound ports. Per SHIELD-INSTALL-AGENT-REMOTELY-REQUIREMENTS.md
+ * §FR-4, we NEVER embed raw private-key material in the SSM command
+ * document. Instead:
+ *
+ *   1. Mint a short-lived setup token via Shield API.
+ *   2. Send an AWS-RunShellScript command to the target that curls the
+ *      bootstrap URL, writes the bundle to ~/.blacksands/mcp-certs/
+ *      with correct modes, and (optionally) triggers a restart.
+ *   3. Poll GetCommandInvocation for terminal state.
+ *   4. On success, return bootstrap-pending-style status; the target's
+ *      curl invocation is what actually redeems.
+ *
+ * Private-key transit path: Shield API → target (direct HTTPS). The MCP
+ * host never sees the key_pem.
+ *
+ * @aws-sdk/client-ssm is loaded lazily so bootstrap-token-only users
+ * don't pay the SDK cost.
+ */
+import type { ShieldClient } from "../../client";
+import type { Transport, TransportDeliveryResult, AwsSsmTransportSpec, AgentType } from "../types";
+export declare class AwsSsmTransport implements Transport {
+    private readonly shield;
+    private readonly spec;
+    readonly type: "aws-ssm";
+    constructor(shield: ShieldClient, spec: AwsSsmTransportSpec);
+    deliver(args: {
+        clientName: string;
+        orgId: string;
+        agentType: AgentType;
+        configPath: string;
+        serviceId: string;
+        authorizerUrl: string;
+    }): Promise<TransportDeliveryResult>;
+    rollback(delivery: TransportDeliveryResult): Promise<{
+        steps: string[];
+        errors: string[];
+    }>;
+}
+//# sourceMappingURL=awsSsm.d.ts.map