@blacksandscyber/mcp-server-bursar 0.5.0

package/build/server.js

@@ -0,0 +1,902 @@
+"use strict";
+/**
+ * Blacksands Bursar MCP Server — 52 tools across 8 categories.
+ *
+ * The Shield MCP Server exposes the same operational surface a human
+ * administrator reaches through Overwatch or SysAdmin. Every call is
+ * authenticated and proxied through the full Broker handshake — there is
+ * no direct Shield API access, no API-key bootstrap, and no internal
+ * system access (Kafka, LDAP, AWS SDK, iptables, Route 53 are all internal
+ * to Blacksands and never touched by the Agent).
+ */
+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.buildAnonymizedScanSummary = buildAnonymizedScanSummary;
+exports.createServer = createServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const config_1 = require("./config");
+const client_1 = require("./shield/client");
+const logger_1 = require("./shared/logger");
+const errors_1 = require("./shared/errors");
+// Local codebase analysis (no Blacksands access required)
+const frameworkDetector_1 = require("./shield/discovery/frameworkDetector");
+const endpointScanner_1 = require("./shield/discovery/endpointScanner");
+const piiDetector_1 = require("./shield/discovery/piiDetector");
+const externalServiceDetector_1 = require("./shield/discovery/externalServiceDetector");
+const dataStoreDetector_1 = require("./shield/discovery/dataStoreDetector");
+const manifestGenerator_1 = require("./shield/discovery/manifestGenerator");
+const severity_1 = require("./shield/discovery/severity");
+const environmentScanner_1 = require("./shield/discovery/environmentScanner");
+const dockerScanner_1 = require("./shield/discovery/dockerScanner");
+const topologyNormalizer_1 = require("./shield/discovery/topologyNormalizer");
+const postureReporter_1 = require("./shield/verify/postureReporter");
+const orchestrator_1 = require("./shield/install/orchestrator");
+const deploy_1 = require("./shield/deploy");
+const protocol_walkthrough_1 = require("./shield/protocol-walkthrough");
+const identity_1 = require("./shield/identity");
+const bootRole_1 = require("./shield/bootRole");
+const linkBuilder_1 = require("./shared/linkBuilder");
+/** Helper to wrap tool handlers with error formatting. */
+function safeHandler(fn) {
+    return fn()
+        .then(result => ({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }))
+        .catch(err => ({ content: [{ type: "text", text: (0, errors_1.formatError)(err) }] }));
+}
+/**
+ * Like safeHandler, but appends an optional one-line markdown footer (Shield
+ * Portal deep link, U1) after the JSON payload. `footerFn` receives the
+ * successful result; if it returns null or throws, the result is returned
+ * unchanged — deep links must never break a tool.
+ */
+function safeHandlerWithFooter(fn, footerFn) {
+    return fn()
+        .then(async (result) => {
+        let footer = null;
+        try {
+            footer = await footerFn(result);
+        }
+        catch {
+            footer = null; // degrade gracefully — no link, no error
+        }
+        const text = JSON.stringify(result, null, 2);
+        return {
+            content: [{ type: "text", text: footer ? `${text}\n\n${footer}` : text }],
+        };
+    })
+        .catch(err => ({ content: [{ type: "text", text: (0, errors_1.formatError)(err) }] }));
+}
+/**
+ * Build the ANONYMIZED claim summary for a free local scan. Deliberately
+ * contains NO paths, hostnames, snippets, or service names — the Shield API
+ * rejects payloads that fail its anonymization schema, so we only ever send
+ * derived counts/severities and generic finding titles.
+ */
+function buildAnonymizedScanSummary(scan) {
+    const score = (0, linkBuilder_1.previewScoreFromSeverity)(scan.bySeverity);
+    const findings = [];
+    for (const e of scan.endpoints ?? []) {
+        if (findings.length >= 5)
+            break;
+        if (e.auth_method === "unknown" || e.auth_method === "public") {
+            findings.push({
+                title: `${(e.method || "unknown").toUpperCase()} endpoint with no detectable authentication`,
+                severity: e.severity || "medium",
+                category: "auth",
+                recommendation: "Add authentication middleware or document why this route is public",
+            });
+        }
+    }
+    for (const p of scan.piiFields ?? []) {
+        if (findings.length >= 5)
+            break;
+        findings.push({
+            title: `Possible ${p.type || "PII"} field detected`,
+            severity: p.severity || "medium",
+            category: "pii",
+            recommendation: "Confirm the field and ensure encryption at rest and in transit",
+        });
+    }
+    return {
+        score,
+        highestSeverity: scan.highestSeverity,
+        bySeverity: scan.bySeverity,
+        framework: scan.framework
+            ? {
+                name: scan.framework.name,
+                language: scan.framework.language,
+                packageManager: scan.framework.packageManager,
+            }
+            : undefined,
+        counts: {
+            endpoints: scan.endpoints?.length ?? 0,
+            piiFields: scan.piiFields?.length ?? 0,
+            externalServices: scan.externalServices?.length ?? 0,
+            dataStores: scan.dataStores?.length ?? 0,
+        },
+        findings,
+        source: "mcp-scan",
+    };
+}
+function createServer() {
+    const config = (0, config_1.loadConfig)();
+    const server = new mcp_js_1.McpServer({
+        name: "blacksands-bursar",
+        version: "0.5.0",
+    });
+    // Resolve the cert's role at boot — drives which tools we register below.
+    // Synchronous on purpose: an async API call to /v1/mcp/identity would
+    // require the broker handshake to complete (~2-6s) before tool/list could
+    // respond, and Claude Desktop's initialize timeout is ~4-8s. So we resolve
+    // from a fast local source (env var → ~/.blacksands/mcp-certs/.role →
+    // mode-derived default) and rely on Shield API's requireMcpRole middleware
+    // for the authoritative defense-in-depth check at call time. A wrong
+    // answer here at worst shows the LLM extra tools; it can never grant
+    // extra capability because the API enforces independently.
+    const bootRole = (0, bootRole_1.resolveBootRole)(config.mode);
+    const canMaster = bootRole.role === "master";
+    logger_1.logger.info("MCP role resolved at boot", {
+        role: bootRole.role,
+        source: bootRole.source,
+        rationale: bootRole.rationale,
+    });
+    let shieldClient = null;
+    let shieldConnected = false;
+    async function getShield() {
+        if (!shieldClient) {
+            if (config.mode === "stdio") {
+                shieldClient = new client_1.ShieldClient({
+                    clientCert: config.shield.mtls.clientCert,
+                    clientKey: config.shield.mtls.clientKey,
+                    caCert: config.shield.mtls.caCert ?? undefined,
+                    broker: {
+                        authorizerUrl: config.shield.broker.authorizerUrl,
+                        serviceId: config.shield.broker.serviceId,
+                        authPassword: config.shield.broker.authPassword,
+                    },
+                });
+            }
+            else if (config.shield.service) {
+                shieldClient = new client_1.ShieldClient({
+                    clientCert: config.shield.service.clientCert,
+                    clientKey: config.shield.service.clientKey,
+                    caCert: config.shield.service.caCert ?? undefined,
+                    directUrl: config.shield.service.apiUrl,
+                });
+            }
+            else if (config.mode === "local-only") {
+                throw new Error("Shield API tools require a Blacksands account.\n\n" +
+                    "You're running in local-only mode — these 12 tools work right now without an account:\n" +
+                    "  bursar_scan_codebase, bursar_scan_environment, bursar_detect_framework, bursar_scan_endpoints,\n" +
+                    "  bursar_flag_pii_candidates, bursar_detect_external_services, bursar_detect_data_stores,\n" +
+                    "  bursar_generate_manifest, bursar_get_protection_requirements,\n" +
+                    "  bursar_guide_deployment, broker_get_protocol_walkthrough,\n" +
+                    "  broker_get_my_identity\n\n" +
+                    "To unlock provisioning, compliance, and Receiver tools, create a free account at:\n" +
+                    "  https://shield.blacksandscyber.online\n" +
+                    "Your administrator can also issue you a setup token through Overwatch or Architect.");
+            }
+            else {
+                throw new Error("Shield API is not reachable from this MCP server instance. " +
+                    "This server is running in http-service mode without a service mTLS certificate. " +
+                    "To enable Shield-dependent tools, set SHIELD_API_URL, SHIELD_SERVICE_CERT, and SHIELD_SERVICE_KEY. " +
+                    "Local codebase-scan tools (bursar_scan_codebase, bursar_flag_pii_candidates, etc.) work without Shield access.");
+            }
+        }
+        if (!shieldConnected) {
+            await shieldClient.connect();
+            shieldConnected = true;
+        }
+        return shieldClient;
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // CATEGORY A: Shield Discovery (7 tools) — local codebase analysis
+    // ═══════════════════════════════════════════════════════════════════════
+    server.tool("bursar_scan_codebase", "[FREE] Full codebase security scan: detect framework, endpoints, PII, external services, data stores, and generate a security manifest — works on any local project, no Blacksands account needed", { projectPath: zod_1.z.string().describe("Absolute path to the project directory to scan") }, async ({ projectPath }) => safeHandlerWithFooter(async () => {
+        logger_1.logger.info("Scanning codebase", { projectPath });
+        const framework = await (0, frameworkDetector_1.detectFramework)(projectPath);
+        const endpoints = (0, severity_1.tagEndpoints)(await (0, endpointScanner_1.scanEndpoints)(projectPath, framework));
+        const piiFields = (0, severity_1.tagPiiFields)(await (0, piiDetector_1.detectPii)(projectPath));
+        const externalServices = await (0, externalServiceDetector_1.detectExternalServices)(projectPath);
+        const dataStores = await (0, dataStoreDetector_1.detectDataStores)(projectPath);
+        const manifest = (0, manifestGenerator_1.generateManifest)({ framework, endpoints, externalServices, dataStores, piiFields, projectPath });
+        const allFindings = [...endpoints, ...piiFields];
+        return {
+            bySeverity: (0, severity_1.summarizeBySeverity)(allFindings),
+            highestSeverity: (0, severity_1.topSeverity)(allFindings),
+            framework, endpoints, piiFields, externalServices, dataStores, manifest,
+        };
+    }, 
+    // U1 golden path: with no account, POST the anonymized summary to the
+    // public claim endpoint and link the Glass preview report. Org-bound
+    // installs deep-link to the Posture Home instead. Both degrade to "no
+    // footer" when offline/unreachable.
+    async (scan) => {
+        const summary = buildAnonymizedScanSummary(scan);
+        if (config.mode === "local-only") {
+            return (0, linkBuilder_1.buildClaimLine)(summary); // no account → claim URL (or null offline)
+        }
+        return (0, linkBuilder_1.portalHomeLine)(summary.score); // org-bound → Posture Home
+    }));
+    server.tool("bursar_scan_environment", "[FREE] Scan the local environment and return a normalized topology JSON (schemaVersion 1.0) for the visualization app. Phase 1 inspects the macOS host READ-ONLY: Apple Containerization `container` CLI (containers/networks/volumes), listening TCP ports, and host facts → the `infra` plane. The `zt` (zero-trust) plane is built ONLY from live Shield Broker state (receivers/sessions/endpoints) when an account is reachable — otherwise it is empty and metadata.trust.authoritative=false. No mutation; observe only.", {
+        provider: zod_1.z.enum(["macos", "docker", "aws", "azure"]).default("macos")
+            .describe("Environment provider to scan. 'macos' (Apple Containerization) and 'docker' (local Docker daemon, READ-ONLY) are implemented; aws/azure return an empty infra plane with a 'not yet implemented' note."),
+        planes: zod_1.z.array(zod_1.z.enum(["infra", "zt"])).default(["infra", "zt"])
+            .describe("Which planes to assemble: 'infra' (host/network/container/volume/service) and/or 'zt' (zero-trust control/data plane)."),
+        appId: zod_1.z.string().optional()
+            .describe("Optional Shield app id to scope ZT-plane enrichment (sessions/endpoints) to a single application."),
+    }, async ({ provider, planes, appId }) => safeHandler(async () => {
+        logger_1.logger.info("Scanning environment topology", { provider, planes, appId });
+        // ── infra plane ──────────────────────────────────────────────────────
+        let env = null;
+        const extraNotes = [];
+        if (provider === "macos") {
+            // Always inspect the host: it supplies the metadata.host name even when
+            // only the zt plane is requested, and the scan is cheap + read-only.
+            env = await (0, environmentScanner_1.scanMacEnvironment)();
+        }
+        else if (provider === "docker") {
+            // Phase 2: READ-ONLY Docker daemon inspection → same RawEnvironment shape,
+            // folded into the infra plane through the identical normalization path.
+            env = await (0, dockerScanner_1.scanDockerEnvironment)();
+        }
+        else {
+            // aws/azure: not yet implemented — empty infra plane + note (no throw).
+            extraNotes.push(`provider not yet implemented: ${provider}`);
+        }
+        // ── zt plane (live Broker state only) ─────────────────────────────────
+        let zt = null;
+        if (planes.includes("zt")) {
+            // Obtain a ZtSource adapter over the Shield client. If Shield access is
+            // not configured/reachable, degrade to an empty, non-authoritative
+            // plane — never throw, never fabricate trust.
+            let src = null;
+            try {
+                const client = await getShield();
+                src = {
+                    orgId: config.shield.orgId,
+                    listReceivers: (f) => client.listReceivers(f),
+                    listApps: (orgId) => client.listApps(orgId),
+                    listSessions: (id) => client.listSessions(id),
+                    listEndpoints: (id) => client.listEndpoints(id),
+                };
+            }
+            catch (err) {
+                logger_1.logger.info("bursar_scan_environment: Shield client unavailable — ZT plane will be empty", { err: String(err) });
+                src = null;
+            }
+            zt = await (0, topologyNormalizer_1.buildZtPlane)(src, appId);
+        }
+        return (0, topologyNormalizer_1.assembleEnvelope)({ provider, planes, env, zt, extraNotes });
+    }));
+    server.tool("bursar_detect_framework", "[FREE] Detect application framework, runtime, and package manager from project files — no account needed", { projectPath: zod_1.z.string().describe("Path to project directory") }, async ({ projectPath }) => safeHandler(() => (0, frameworkDetector_1.detectFramework)(projectPath)));
+    server.tool("bursar_scan_endpoints", "[FREE] Scan source code for HTTP/API endpoints. Reports per-route HTTP method (never silently defaulted to GET), auth_method classification (public/session/jwt/signature/scheduler/token/api_key/oauth/unknown), file:line, and a 'routes with no detectable authentication' section — no account needed", { projectPath: zod_1.z.string().describe("Path to project directory") }, async ({ projectPath }) => safeHandler(async () => {
+        const fw = await (0, frameworkDetector_1.detectFramework)(projectPath);
+        const endpoints = (0, severity_1.tagEndpoints)(await (0, endpointScanner_1.scanEndpoints)(projectPath, fw));
+        const byMethod = {};
+        const byAuth = {};
+        for (const e of endpoints) {
+            byMethod[e.method] = (byMethod[e.method] ?? 0) + 1;
+            byAuth[e.auth_method] = (byAuth[e.auth_method] ?? 0) + 1;
+        }
+        const unauthenticated = endpoints.filter(e => e.auth_method === "unknown" || e.auth_method === "public");
+        const undeterminedMethod = endpoints.filter(e => e.method === "unknown");
+        return {
+            bySeverity: (0, severity_1.summarizeBySeverity)(endpoints),
+            highestSeverity: (0, severity_1.topSeverity)(endpoints),
+            endpoints,
+            summary: {
+                total: endpoints.length,
+                byMethod,
+                byAuth,
+                unauthenticated_or_unknown: unauthenticated.length,
+                method_undetermined: undeterminedMethod.length,
+            },
+            routes_with_no_detectable_authentication: unauthenticated.map(e => ({
+                method: e.method, path: e.path, file: e.file, line: e.line,
+                severity: e.severity, severity_rationale: e.severity_rationale,
+            })),
+        };
+    }));
+    server.tool("bursar_flag_pii_candidates", "[FREE] Scan source code and flag candidate PII fields (SSN, credit card, health data, etc.) for human review, with file:line, code snippet, confidence, severity, and remediation per finding. Comment/prose-only matches are filtered out to reduce false positives. Findings are candidates — not confirmed PII — and should be reviewed. Infers compliance requirements — no account needed", { projectPath: zod_1.z.string().describe("Path to project directory") }, async ({ projectPath }) => safeHandler(async () => {
+        const fields = (0, severity_1.tagPiiFields)(await (0, piiDetector_1.detectPii)(projectPath));
+        const { getSensitivityLevel, getComplianceHints } = await Promise.resolve().then(() => __importStar(require("./shield/discovery/piiDetector")));
+        const byConfidence = { high: 0, medium: 0, low: 0 };
+        const bySensitivity = { critical: 0, high: 0, medium: 0, low: 0 };
+        for (const f of fields) {
+            if (f.confidence)
+                byConfidence[f.confidence]++;
+            bySensitivity[f.sensitivity]++;
+        }
+        return {
+            bySeverity: (0, severity_1.summarizeBySeverity)(fields),
+            highestSeverity: (0, severity_1.topSeverity)(fields),
+            fields,
+            summary: {
+                total: fields.length,
+                byConfidence,
+                bySensitivity,
+                types: [...new Set(fields.map(f => f.type))],
+            },
+            sensitivityLevel: getSensitivityLevel(fields),
+            complianceHints: getComplianceHints(fields),
+        };
+    }));
+    server.tool("bursar_detect_external_services", "[FREE] Detect third-party service integrations (Stripe, OpenAI, AWS, Firebase, etc.) from dependencies and source code — no account needed", { projectPath: zod_1.z.string().describe("Path to project directory") }, async ({ projectPath }) => safeHandler(() => (0, externalServiceDetector_1.detectExternalServices)(projectPath)));
+    server.tool("bursar_detect_data_stores", "[FREE] Detect database connections (PostgreSQL, MongoDB, Redis, etc.) from dependencies, env vars, and Docker config — no account needed", { projectPath: zod_1.z.string().describe("Path to project directory") }, async ({ projectPath }) => safeHandler(() => (0, dataStoreDetector_1.detectDataStores)(projectPath)));
+    server.tool("bursar_generate_manifest", "[FREE] Generate a security manifest from discovery scan results or by scanning a project path — no account needed", { projectPath: zod_1.z.string().describe("Path to project directory") }, async ({ projectPath }) => safeHandler(async () => {
+        const framework = await (0, frameworkDetector_1.detectFramework)(projectPath);
+        const endpoints = await (0, endpointScanner_1.scanEndpoints)(projectPath, framework);
+        const piiFields = await (0, piiDetector_1.detectPii)(projectPath);
+        const externalServices = await (0, externalServiceDetector_1.detectExternalServices)(projectPath);
+        const dataStores = await (0, dataStoreDetector_1.detectDataStores)(projectPath);
+        return (0, manifestGenerator_1.generateManifest)({ framework, endpoints, externalServices, dataStores, piiFields, projectPath });
+    }));
+    // ─────────────────────────────────────────────────────────────────────────
+    // MASTER-ROLE-GATED TOOLS (Categories B–H, ~36 tools)
+    //
+    // Wrapped in `if (canMaster)` so a Consumer cert sees only the [FREE]
+    // tools registered above + Category I registered below. The block ends
+    // before "CATEGORY I: Local guidance" — that category contains [FREE]
+    // tools that consumers also get.
+    //
+    // Defense-in-depth: even if the boot role resolves wrong (env override,
+    // stale role hint file), the Shield API's requireMcpRole middleware
+    // independently 403s. Tool filtering here is a UX optimization (cleaner
+    // tools/list for the LLM); the API is the security boundary.
+    // ─────────────────────────────────────────────────────────────────────────
+    if (canMaster) {
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY B: Shield Provisioning (7 tools)
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("bursar_create_org", "Create a new organization in Blacksands Bursar", { name: zod_1.z.string(), plan: zod_1.z.string().optional() }, async ({ name, plan }) => safeHandler(async () => (await getShield()).createOrg(name, plan)));
+        server.tool("bursar_list_orgs", "List organizations in Blacksands Bursar", { page: zod_1.z.number().optional(), pageSize: zod_1.z.number().optional() }, async ({ page, pageSize }) => safeHandler(async () => (await getShield()).listOrgs(page, pageSize)));
+        server.tool("bursar_create_app", "Register a new application with an organization", {
+            orgId: zod_1.z.string(),
+            name: zod_1.z.string(),
+            // `type` is REQUIRED by the Shield API (POST /orgs/:orgId/apps validates
+            // body('type').isIn([...])). Default to 'web' so the common case works
+            // without the caller having to know the contract; override as needed.
+            type: zod_1.z.enum(["web", "mobile", "api", "iot", "service"]).default("web"),
+            framework: zod_1.z.string().optional(),
+            runtime: zod_1.z.string().optional(),
+            environment: zod_1.z.enum(["development", "staging", "production"]).optional(),
+            domain: zod_1.z.string().optional(),
+        }, async ({ orgId, name, type, framework, runtime, environment, domain }) => safeHandler(async () => (await getShield()).createApp(orgId, name, { type, framework, runtime, environment, domain })));
+        server.tool("bursar_list_apps", "List applications for an organization", { orgId: zod_1.z.string() }, async ({ orgId }) => safeHandler(async () => (await getShield()).listApps(orgId)));
+        server.tool("bursar_submit_manifest", "Submit a security manifest to Shield API for validation and provisioning", { manifest: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).describe("Security manifest JSON object"), orgId: zod_1.z.string() }, async ({ manifest, orgId }) => safeHandler(async () => (await getShield()).submitManifest(manifest, orgId)));
+        server.tool("bursar_provision_app", "Provision the full security stack (certs, DNS, policies, endpoints) from a submitted manifest", { manifestId: zod_1.z.string() }, async ({ manifestId }) => safeHandlerWithFooter(async () => {
+            const { operationId } = await (await getShield()).provisionManifest(manifestId);
+            const result = await (await getShield()).pollOperation(operationId);
+            return { manifestId, operationId, ...result };
+        }, 
+        // U1: deep link to live progress on the Posture Home.
+        () => (0, linkBuilder_1.portalHomeLine)(null)));
+        server.tool("bursar_poll_operation", "Check the status of an async Shield API operation", { operationId: zod_1.z.string() }, async ({ operationId }) => safeHandler(async () => (await getShield()).pollOperation(operationId)));
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY C: mTLS Identity (2 tools — list + revoke, read-only surface)
+        // Issuance is performed by a human administrator through Overwatch or
+        // SysAdmin. The Agent can inventory and revoke, not create.
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("bursar_list_mcp_certs", "List all active mTLS client certificates issued for this organization's MCP instances", {}, async () => safeHandler(async () => (await getShield()).listMcpCerts()));
+        server.tool("bursar_revoke_mcp_cert", "Revoke an mTLS client certificate by client name. Use this when decommissioning an MCP install or rotating credentials. To issue a new certificate, use Overwatch or SysAdmin.", { clientName: zod_1.z.string().describe("The client name used when the cert was issued") }, async ({ clientName }) => safeHandler(async () => (await getShield()).revokeMcpCert(clientName)));
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY D: Verification & Compliance (4 tools)
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("bursar_verify_posture", "Run a security posture verification scan on an application", {
+            appId: zod_1.z.string(),
+            // `scanType` is REQUIRED by the Shield API (POST /verify validates
+            // body('scanType').isIn([...])). Default to 'full' so the tool works
+            // without the caller knowing the contract; override for a lighter scan.
+            scanType: zod_1.z.enum(["full", "quick", "compliance", "penetration"]).default("full"),
+        }, async ({ appId, scanType }) => safeHandler(async () => {
+            const { operationId } = await (await getShield()).triggerVerify(appId, scanType);
+            const op = await (await getShield()).pollOperation(operationId);
+            return (0, postureReporter_1.formatPosture)(op.result);
+        }));
+        server.tool("bursar_get_posture", "Get the latest security posture score, grade, and recommendations for an application", { appId: zod_1.z.string() }, async ({ appId }) => safeHandlerWithFooter(async () => {
+            const result = await (await getShield()).getLatestPosture(appId);
+            return (0, postureReporter_1.formatPosture)(result);
+        }, 
+        // U1: append "Posture preview: NN/100 — view full report → portal".
+        (posture) => {
+            const score = typeof posture?.score === "number" ? posture.score
+                : typeof posture?.posture?.score === "number" ? posture.posture.score
+                    : null;
+            return (0, linkBuilder_1.portalHomeLine)(score);
+        }));
+        server.tool("bursar_compliance_report", "Generate a compliance report (SOC2, HIPAA, PCI-DSS, ISO27001) for an application", { appId: zod_1.z.string(), framework: zod_1.z.enum(["SOC2", "HIPAA", "PCI-DSS", "ISO27001"]) }, async ({ appId, framework }) => safeHandlerWithFooter(async () => (await getShield()).getComplianceReport(appId, framework), 
+        // U1: compliance reports render richer in the portal — deep link it.
+        () => (0, linkBuilder_1.portalHomeLine)(null)));
+        server.tool("bursar_compliance_controls", "List all compliance controls for a given framework", { framework: zod_1.z.enum(["SOC2", "HIPAA", "PCI-DSS", "ISO27001"]) }, async ({ framework }) => safeHandler(async () => (await getShield()).getComplianceControls(framework)));
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY E: Security Operations (10 tools)
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("bursar_emergency_lockdown", "Emergency lockdown: immediately revoke all certificates and sessions for an application", { appId: zod_1.z.string(), reason: zod_1.z.string() }, async ({ appId, reason }) => safeHandler(async () => (await getShield()).emergencyLockdown(appId, reason)));
+        server.tool("bursar_lift_lockdown", "Lift an emergency lockdown on an application", { appId: zod_1.z.string() }, async ({ appId }) => safeHandler(async () => (await getShield()).liftLockdown(appId)));
+        server.tool("bursar_list_certs", "List all certificates for an application", { appId: zod_1.z.string() }, async ({ appId }) => safeHandler(async () => (await getShield()).listCerts(appId)));
+        server.tool("bursar_rotate_cert", "Rotate a specific certificate", { appId: zod_1.z.string(), certId: zod_1.z.string() }, async ({ appId, certId }) => safeHandler(async () => (await getShield()).rotateCert(appId, certId)));
+        server.tool("bursar_revoke_cert", "Revoke a specific certificate", { appId: zod_1.z.string(), certId: zod_1.z.string(), reason: zod_1.z.string().optional() }, async ({ appId, certId, reason }) => safeHandler(async () => (await getShield()).revokeCert(appId, certId, reason)));
+        server.tool("bursar_list_policies", "List security policies for an application", { appId: zod_1.z.string() }, async ({ appId }) => safeHandler(async () => (await getShield()).listPolicies(appId)));
+        server.tool("bursar_create_policy", "Create a security policy (network, DNS, access, or compliance) for an application", { appId: zod_1.z.string(), name: zod_1.z.string(), type: zod_1.z.string(), rules: zod_1.z.array(zod_1.z.object({ action: zod_1.z.enum(["allow", "deny", "log"]), target: zod_1.z.string() })) }, async ({ appId, name, type, rules }) => safeHandler(async () => (await getShield()).createPolicy(appId, name, type, rules)));
+        server.tool("bursar_update_dns_rules", "Add or remove application-level DNS allow/block rules (not Receiver DNS, which is auto-managed)", { appId: zod_1.z.string(), rules: zod_1.z.array(zod_1.z.object({ domain: zod_1.z.string(), action: zod_1.z.enum(["allow", "block"]), reason: zod_1.z.string().optional() })) }, async ({ appId, rules }) => safeHandler(async () => (await getShield()).updateDnsRules(appId, rules)));
+        server.tool("bursar_list_sessions", "List active sessions for an application", { appId: zod_1.z.string() }, async ({ appId }) => safeHandler(async () => (await getShield()).listSessions(appId)));
+        server.tool("bursar_revoke_session", "Revoke a specific session", { appId: zod_1.z.string(), sessionId: zod_1.z.string() }, async ({ appId, sessionId }) => safeHandler(async () => (await getShield()).revokeSession(appId, sessionId)));
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY F: Receiver Lifecycle (13 tools — initialization + services + service lifecycle + monitoring)
+        // Networking inputs only. DNS is auto-assigned by Blacksands during
+        // Receiver registration and is read-only from the Agent's perspective.
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("receiver_initialize", "Start Receiver initialization: creates the Receiver record and sends installation credentials to the installer email. IMPORTANT: This requires a Linux server where you can run Docker (e.g., an EC2 instance, VPS, or cloud VM). If the user does not have a server yet, help them deploy one first (Railway Pro, Render, DigitalOcean, or AWS EC2).", { installerEmail: zod_1.z.string(), organizationId: zod_1.z.string(), notes: zod_1.z.string().optional() }, async ({ installerEmail, organizationId, notes }) => safeHandler(async () => (await getShield()).initializeReceiver(installerEmail, organizationId, notes)));
+        server.tool("receiver_init_status", "Check the initialization status of a Receiver (awaiting, in_progress, completed, failed)", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => (await getShield()).getReceiverStatus(receiverUID)));
+        server.tool("receiver_activate", "Activate a Receiver after initialization completes", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => (await getShield()).activateReceiver(receiverUID)));
+        server.tool("receiver_resend_email", "Resend installation credentials email for a pending Receiver initialization", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => (await getShield()).resendReceiverEmail(receiverUID)));
+        server.tool("receiver_cancel_init", "Cancel a pending Receiver initialization", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => (await getShield()).cancelReceiverInit(receiverUID)));
+        server.tool("receiver_onboard_service", "Add a service to be proxied by the Receiver. Supply networking inputs only: name, backend host, port, and protocol. Blacksands handles the proxy wiring, certificates, and firewall internally.", {
+            receiverUID: zod_1.z.string(),
+            name: zod_1.z.string().describe("Service name"),
+            host: zod_1.z.string().describe("Backend host or IP"),
+            port: zod_1.z.number().describe("Backend port"),
+            protocol: zod_1.z.enum(["http", "https", "ssh", "rdp"]),
+            path: zod_1.z.string().optional(),
+        }, async (params) => safeHandler(async () => (await getShield()).onboardReceiverService(params.receiverUID, {
+            name: params.name, host: params.host, port: params.port, protocol: params.protocol, path: params.path,
+        })));
+        server.tool("receiver_remove_service", "Remove a proxied service from a Receiver", { receiverUID: zod_1.z.string(), serviceName: zod_1.z.string() }, async ({ receiverUID, serviceName }) => safeHandler(async () => (await getShield()).removeReceiverService(receiverUID, serviceName)));
+        server.tool("receiver_list_services", "List all services currently proxied by a Receiver", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => (await getShield()).listReceiverServices(receiverUID)));
+        // ── Service lifecycle (F4.12) ───────────────────────────────────────────
+        // Control a proxied service's protection state without deleting it.
+        // pause = reversible stop (new connections denied, registration kept);
+        // resume = paused→active; disable = stronger off-state requiring admin
+        // re-enable; status = current state + health. To delete a service entirely,
+        // use receiver_remove_service instead.
+        server.tool("bursar_service_pause", "Pause a proxied service: temporarily stop accepting new connections while keeping its registration. Reversible with bursar_service_resume. Use this for maintenance windows or to quickly cut off a service without removing it.", { receiverUID: zod_1.z.string(), serviceName: zod_1.z.string().describe("Service name as shown by receiver_list_services") }, async ({ receiverUID, serviceName }) => safeHandler(async () => (await getShield()).pauseService(receiverUID, serviceName)));
+        server.tool("bursar_service_resume", "Resume a paused service, returning it to active so it accepts connections again.", { receiverUID: zod_1.z.string(), serviceName: zod_1.z.string().describe("Service name as shown by receiver_list_services") }, async ({ receiverUID, serviceName }) => safeHandler(async () => (await getShield()).resumeService(receiverUID, serviceName)));
+        server.tool("bursar_service_disable", "Disable a proxied service: take it offline in a state that requires an explicit re-enable (stronger than pause). The registration is kept — use receiver_remove_service to delete it entirely.", { receiverUID: zod_1.z.string(), serviceName: zod_1.z.string().describe("Service name as shown by receiver_list_services") }, async ({ receiverUID, serviceName }) => safeHandler(async () => (await getShield()).disableService(receiverUID, serviceName)));
+        server.tool("bursar_service_status", "Get the current protection state (active / paused / disabled) and health of a proxied service.", { receiverUID: zod_1.z.string(), serviceName: zod_1.z.string().describe("Service name as shown by receiver_list_services") }, async ({ receiverUID, serviceName }) => safeHandler(async () => (await getShield()).getServiceStatus(receiverUID, serviceName)));
+        server.tool("receiver_get_dns", "View the DNS name(s) automatically assigned to a Receiver by Blacksands. Read-only — DNS is provisioned during Receiver registration and cannot be modified by the Agent.", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => {
+            const record = await (await getShield()).getReceiver(receiverUID);
+            return {
+                receiverUID,
+                dnsName: record.dnsName ?? null,
+                wildcardDomain: record.wildcardDomain ?? null,
+                publicIP: record.publicIP ?? null,
+                note: "DNS records are auto-provisioned by Blacksands during Receiver registration. To change them, the Receiver must be re-registered with new networking inputs.",
+            };
+        }));
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY G: Receiver Monitoring (3 tools)
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("receiver_health", "Get the health status of a specific Receiver", { receiverUID: zod_1.z.string() }, async ({ receiverUID }) => safeHandler(async () => (await getShield()).getReceiverStatus(receiverUID)));
+        server.tool("receiver_list", "List all Receivers with optional status and organization filters", { organizationId: zod_1.z.string().optional(), status: zod_1.z.string().optional() }, async ({ organizationId, status }) => safeHandler(async () => (await getShield()).listReceivers({ organizationId, status })));
+        server.tool("receiver_statistics", "Get Receiver initialization and deployment statistics", {}, async () => safeHandler(async () => (await getShield()).getReceiverStatistics()));
+        // ═══════════════════════════════════════════════════════════════════════
+        // CATEGORY H: Composite provisioning (1 tool)
+        // `bursar_install_agent_remotely` issues a new MCP identity, delivers it
+        // to the target via the chosen transport, writes the agent config, and
+        // verifies the broker handshake — closing the "manual copy-files" seam
+        // in multi-agent provisioning. See SHIELD-INSTALL-AGENT-REMOTELY-
+        // REQUIREMENTS.md for the full contract.
+        //
+        // Phase A.1: bootstrap-token transport only; SSH and aws-ssm stub-and-
+        // throw. Config-merge supports claude-desktop + mcp-server JSON.
+        // ═══════════════════════════════════════════════════════════════════════
+        server.tool("bursar_install_agent_remotely", "Provision and install a new Blacksands Bursar AI-agent identity on a remote host. " +
+            "Issues an mTLS client certificate tied to `clientName`, delivers the credential bundle " +
+            "to the target via the selected transport, writes the agent's MCP config, and verifies " +
+            "the agent completes the Authorizer → Receiver broker handshake before returning. " +
+            "Intended as the one-call replacement for the manual cert-issue → copy-files → " +
+            "edit-config → restart workflow. Phase A.1 supports transport.type='bootstrap-token' " +
+            "fully; 'ssh' and 'aws-ssm' are stubs that will throw a 'not-implemented' InstallError.", {
+            // Identity
+            clientName: zod_1.z.string()
+                .regex(/^[a-z0-9][a-z0-9-]{1,62}$/, "must be 2-63 chars, lowercase alphanumeric + hyphens, not starting with a hyphen")
+                .describe("Unique name for the new agent instance — becomes the cert CN."),
+            orgId: zod_1.z.string()
+                .describe("Organization the new identity will belong to."),
+            // Agent runtime on target
+            agentType: zod_1.z.enum(["claude-desktop", "mcp-server", "openclaw", "custom"])
+                .describe("Which MCP agent runtime the target will use. Determines config path + restart command."),
+            configPath: zod_1.z.string().optional()
+                .describe("Absolute path on target for MCP config. Required when agentType=custom; defaulted for known types."),
+            restartCmd: zod_1.z.string().optional()
+                .describe("Shell command to restart the agent on the target. Defaults are inferred from agentType where possible."),
+            // Delivery transport (discriminated union)
+            transport: zod_1.z.discriminatedUnion("type", [
+                zod_1.z.object({
+                    type: zod_1.z.literal("ssh"),
+                    host: zod_1.z.string(),
+                    port: zod_1.z.number().int().min(1).max(65535).default(22),
+                    username: zod_1.z.string(),
+                    authMethod: zod_1.z.enum(["private-key", "ssh-agent", "password"]),
+                    privateKeyPath: zod_1.z.string().optional(),
+                    knownHostsPath: zod_1.z.string().optional(),
+                    hostKeyFingerprint: zod_1.z.string().optional()
+                        .describe("Expected SSH host-key SHA256 fingerprint (strict check). RECOMMENDED."),
+                    sudo: zod_1.z.boolean().default(false),
+                }),
+                zod_1.z.object({
+                    type: zod_1.z.literal("bootstrap-token"),
+                    ttlSeconds: zod_1.z.number().int().min(60).max(3600).default(900)
+                        .describe("How long the setup token remains valid, in seconds. Max 1 hour."),
+                    allowedCidr: zod_1.z.string().optional()
+                        .describe("If set, redemption is restricted to this CIDR (NOT YET ENFORCED — Phase B)."),
+                    oneShot: zod_1.z.boolean().default(true)
+                        .describe("Token is single-use. Currently always true."),
+                    deliverVia: zod_1.z.enum(["return", "email"]).default("return"),
+                    email: zod_1.z.string().email().optional(),
+                }),
+                zod_1.z.object({
+                    type: zod_1.z.literal("aws-ssm"),
+                    instanceId: zod_1.z.string(),
+                    region: zod_1.z.string().optional(),
+                }),
+            ]),
+            // Broker config on target
+            serviceId: zod_1.z.string().default("shield-api")
+                .describe("Shield service ID the target will connect to through the Broker."),
+            authorizerUrl: zod_1.z.string().url().optional()
+                .describe("Defaults to the Authorizer configured on this MCP server."),
+            // RBAC role for the new cert. 'master' = full 47-tool surface (default,
+            // backward compat). 'consumer' = restricted 11-tool [FREE]-only surface;
+            // appropriate for developer/CI agents that need to call protected
+            // services through the Broker but should NOT be able to manage Shield
+            // itself. Enforced at TWO layers: Shield API requireMcpRole middleware
+            // (per-route 403 on admin endpoints) AND MCP-server-side resolveBootRole
+            // (filters tool registration so the LLM doesn't even see admin tools).
+            role: zod_1.z.enum(["master", "consumer"]).optional()
+                .describe("RBAC role. Defaults to 'master' for backward compat. Use 'consumer' for least-privilege agents that only need [FREE] tools + broker access to protected services."),
+            // Behavior
+            dryRun: zod_1.z.boolean().default(false)
+                .describe("Plan the install without touching the target or issuing credentials."),
+            waitForHandshake: zod_1.z.boolean().default(true)
+                .describe("Poll for the target's first broker handshake before returning. Phase A.1 no-ops this — endpoint not yet deployed."),
+            handshakeTimeoutMs: zod_1.z.number().int().min(5000).max(300_000).default(60_000),
+            rollbackOnFailure: zod_1.z.boolean().default(true)
+                .describe("Revoke credentials and undo file writes if any post-issue phase fails."),
+        }, async (params) => safeHandler(async () => {
+            const input = {
+                clientName: params.clientName,
+                orgId: params.orgId,
+                agentType: params.agentType,
+                configPath: params.configPath,
+                restartCmd: params.restartCmd,
+                transport: params.transport,
+                serviceId: params.serviceId,
+                authorizerUrl: params.authorizerUrl,
+                role: params.role,
+                dryRun: params.dryRun,
+                waitForHandshake: params.waitForHandshake,
+                handshakeTimeoutMs: params.handshakeTimeoutMs,
+                rollbackOnFailure: params.rollbackOnFailure,
+            };
+            return (0, orchestrator_1.runInstallWithRollback)(input, {
+                shield: await getShield(),
+                defaultAuthorizerUrl: config.mode === "stdio" ? config.shield.broker?.authorizerUrl : undefined,
+            });
+        }));
+    } // end if (canMaster) — Categories B–H gated to master role only
+    // ═══════════════════════════════════════════════════════════════════════
+    // CATEGORY I: Local guidance ([FREE] — both roles)
+    // ═══════════════════════════════════════════════════════════════════════
+    server.tool("bursar_get_protection_requirements", "[FREE] Given a security manifest (or a project path to scan), explain in plain English what is needed to protect this app with Blacksands Bursar — including what infrastructure the user must set up first. No account needed.", {
+        manifest: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional()
+            .describe("Security manifest JSON from bursar_generate_manifest. If omitted, provide projectPath instead."),
+        projectPath: zod_1.z.string().optional()
+            .describe("Path to the project directory to scan. Used when manifest is not yet generated."),
+    }, async ({ manifest, projectPath }) => safeHandler(async () => {
+        let m = manifest ?? {};
+        // If no manifest provided, generate one on the fly
+        if (!manifest && projectPath) {
+            const fw = await (0, frameworkDetector_1.detectFramework)(projectPath);
+            const ep = await (0, endpointScanner_1.scanEndpoints)(projectPath, fw);
+            const pii = await (0, piiDetector_1.detectPii)(projectPath);
+            const ext = await (0, externalServiceDetector_1.detectExternalServices)(projectPath);
+            const ds = await (0, dataStoreDetector_1.detectDataStores)(projectPath);
+            m = (0, manifestGenerator_1.generateManifest)({ framework: fw, endpoints: ep, externalServices: ext, dataStores: ds, piiFields: pii, projectPath });
+        }
+        const requirements = [];
+        // 1. Deployed backend — needed if there are API endpoints to protect
+        const endpoints = m.endpoints ?? [];
+        if (endpoints.length > 0) {
+            requirements.push({
+                status: "required_before_receiver",
+                item: "Deployed backend server with Blacksands Receiver alongside",
+                description: `Your app has ${endpoints.length} API endpoint(s). The simplest path for non-coders: ` +
+                    "a single DigitalOcean Droplet running both your app and a hardened Blacksands Receiver " +
+                    "via docker-compose. One VPS, about $6/month, ~20 minutes to a protected endpoint. " +
+                    "Call the bursar_guide_deployment tool with target='digitalocean-droplet' to get a " +
+                    "step-by-step walkthrough plus a ready-to-paste docker-compose.yml. " +
+                    "Advanced users can also deploy the app separately (Railway/Render/EC2) and run the " +
+                    "Receiver on their own infrastructure.",
+                helpLink: "https://shield.blacksandscyber.online/docs/deploy",
+            });
+        }
+        // 2. Blacksands account — needed for all provisioning tools
+        requirements.push({
+            status: "required_for_shield_tools",
+            item: "Blacksands Bursar account",
+            description: "Create a free account at shield.blacksandscyber.online. Your administrator will " +
+                "generate a one-click install link that adds your Shield identity to Claude Desktop. " +
+                "Once installed, you can provision your app with bursar_create_app and bursar_provision_app.",
+            helpLink: "https://shield.blacksandscyber.online",
+        });
+        // 3. Compliance note for PII-heavy apps
+        const piiFields = m.piiFields ?? [];
+        if (piiFields.length > 0) {
+            requirements.push({
+                status: "recommended",
+                item: "Compliance framework review",
+                description: `Your app handles ${piiFields.length} PII field type(s). After provisioning, ` +
+                    "use bursar_compliance_report to generate a SOC 2 or HIPAA report. " +
+                    "This is optional but recommended before going to production.",
+            });
+        }
+        const nextStep = endpoints.length > 0
+            ? "Deploy your app first (ask Claude to help), then create a Blacksands account to protect it."
+            : "Create a free Blacksands account at shield.blacksandscyber.online to start provisioning.";
+        return {
+            summary: "What you need before protecting this app with Blacksands Bursar",
+            requirements,
+            nextStep,
+            localToolsAvailable: [
+                "bursar_scan_codebase", "bursar_detect_framework", "bursar_scan_endpoints",
+                "bursar_flag_pii_candidates", "bursar_detect_external_services", "bursar_detect_data_stores",
+                "bursar_generate_manifest",
+            ],
+            note: "The tools listed above work right now, no account required. Provisioning and protection tools unlock after you create an account.",
+        };
+    }));
+    server.tool("bursar_guide_deployment", "[FREE] **CALL THIS BEFORE ANSWERING ANY QUESTION ABOUT DEPLOYING / HOSTING / RUNNING AN APP WITH BLACKSANDS.** " +
+        "This is the AUTHORITATIVE source for Blacksands Bursar's deployment architecture. " +
+        "Do not improvise from general zero-trust or proxy knowledge — Blacksands is NOT like " +
+        "Cloudflare Tunnel, Tailscale Funnel, ngrok, or any outbound-tunneling agent. The Blacksands " +
+        "Receiver is a public-IP edge proxy that requires inbound TCP 443 and consumes Kafka messages " +
+        "from the Manager (no HTTP to the Authorizer). Call this tool with no `target` first to get " +
+        "the architecture overview + a list of supported targets, then call it again with a specific " +
+        "target for copy-paste steps. Available targets: " +
+        "'digitalocean-droplet' (single-VPS production, ~$6/mo, ~20 min) | " +
+        "'local-docker-development' (LAPTOP DEV ONLY — no Receiver; laptops can't host one). " +
+        "No Blacksands account needed to read the output.", {
+        target: zod_1.z.enum(["digitalocean-droplet", "local-docker-development"]).optional().describe("Deployment target. **Omit on first call** to get an architecture overview + target list. " +
+            "Then call again with the chosen target for copy-paste steps. " +
+            "'digitalocean-droplet' = production-ready single-VPS with hardened Receiver. " +
+            "'local-docker-development' = laptop dev only, no Receiver (laptops lack the public IP a Receiver requires)."),
+        appImage: zod_1.z.string().optional().describe("Docker image tag for the user's app (e.g. 'myapp:latest'). If omitted, the " +
+            "walkthrough uses a placeholder the user fills in."),
+        appPort: zod_1.z.number().optional().describe("Port the app listens on inside its container. Default: 8080."),
+        appName: zod_1.z.string().optional().describe("Short slug for the app — used in container and host names. Default: 'my-app'."),
+        receiverSetupToken: zod_1.z.string().optional().describe("Setup token from receiver_initialize. Can be omitted; the walkthrough will " +
+            "instruct the user to paste it later."),
+        region: zod_1.z.string().optional().describe("DigitalOcean region slug (e.g. 'nyc3', 'sfo3'). Default: 'nyc3'. Only relevant for digitalocean-droplet."),
+        dropletSize: zod_1.z.string().optional().describe("DigitalOcean droplet size slug (e.g. 's-1vcpu-2gb'). Default: 's-1vcpu-2gb'. Only relevant for digitalocean-droplet."),
+    }, async (params) => safeHandler(async () => (0, deploy_1.getDeploymentGuide)(params.target ?? null, params)));
+    server.tool("broker_get_protocol_walkthrough", "[FREE] **CALL THIS BEFORE WRITING ANY CODE OR INSTRUCTIONS FOR ACCESSING A BLACKSANDS-PROTECTED SERVICE.** " +
+        "This is the AUTHORITATIVE description of the bisected Blacksands broker auth protocol: agent → Authorizer (mTLS) → service-list → " +
+        "Receiver (mTLS again, independently re-verified) → backend service. Do NOT improvise from general mTLS or zero-trust knowledge — " +
+        "this protocol is unusual: the cert is presented at TWO independent stages with the same identity, and the backend service URL is " +
+        "NEVER reachable directly. Returns: bisectedFlow steps, falseModelsToReject (anti-patterns to NOT generate), copy-paste code examples " +
+        "in Node.js/Python/curl, and common pitfalls with fixes. Optionally pass language='node'|'python'|'curl' to scope the examples. " +
+        "No Blacksands account needed to read the output.", {
+        language: zod_1.z.enum(["node", "python", "curl", "all"]).optional().describe("Filter code examples to a specific language. Default: 'all' (returns Node, Python, and curl)."),
+    }, async (params) => safeHandler(async () => (0, protocol_walkthrough_1.getProtocolWalkthrough)({ language: params.language })));
+    server.tool("broker_get_my_identity", "[FREE] Returns the calling MCP cert's identity: CN, RBAC role (master | consumer), org id, " +
+        "client name, and tier. Useful for the LLM to introspect 'who am I, what role do I have, what " +
+        "org am I authorized for' before generating code that talks to Blacksands-protected services. " +
+        "In local-only mode (no Shield account) returns a synthetic { role: 'consumer' } identity. " +
+        "Includes a protocol_hint pointing at broker_get_protocol_walkthrough — agents calling this " +
+        "naturally encounter the next breadcrumb to learn the bisected auth flow.", {}, async () => safeHandler(async () => {
+        let identity;
+        if (config.mode === "stdio") {
+            try {
+                const shield = await getShield();
+                identity = await (0, identity_1.fetchClientIdentity)(shield);
+            }
+            catch (err) {
+                // Don't propagate broker failures from this introspection tool —
+                // surface them as part of the response so the LLM can reason about
+                // them rather than seeing a generic error.
+                identity = {
+                    ...(0, identity_1.localOnlyIdentity)(),
+                    cn: null,
+                    role: "consumer",
+                };
+                return {
+                    ...identity,
+                    protocol_hint: "To make requests through your assigned services, call broker_get_protocol_walkthrough " +
+                        "first for the protocol details (Authorizer mTLS → service-list → Receiver mTLS → backend).",
+                    warning: `Could not fetch identity from Shield API: ${err.message}. ` +
+                        `Falling back to consumer-mode synthetic identity.`,
+                };
+            }
+        }
+        else {
+            identity = (0, identity_1.localOnlyIdentity)();
+        }
+        return {
+            ...identity,
+            protocol_hint: "To make requests through your assigned services, call broker_get_protocol_walkthrough " +
+                "first for the protocol details (Authorizer mTLS → service-list → Receiver mTLS → backend).",
+        };
+    }));
+    // ═══════════════════════════════════════════════════════════════════════
+    // Welcome resource — surfaced by Claude Desktop when the extension is active
+    // ═══════════════════════════════════════════════════════════════════════
+    server.resource?.("shield-getting-started", "blacksands://getting-started", { mimeType: "text/markdown" }, async () => ({
+        contents: [{
+                uri: "blacksands://getting-started",
+                mimeType: "text/markdown",
+                text: [
+                    "# Blacksands Bursar — Start Here",
+                    "",
+                    "## You Can Start Right Now (No Account Needed)",
+                    "",
+                    "Seven tools work on any local codebase without a Blacksands account:",
+                    "",
+                    "| Tool | What it does |",
+                    "|---|---|",
+                    "| `bursar_scan_codebase` | Full scan in one call — runs all 6 tools below |",
+                    "| `bursar_detect_framework` | Identifies framework, runtime, and package manager |",
+                    "| `bursar_scan_endpoints` | Finds all API routes and their auth methods |",
+                    "| `bursar_flag_pii_candidates` | Flags candidate sensitive fields (SSN, credit card, health data) for review |",
+                    "| `bursar_detect_external_services` | Detects Stripe, OpenAI, AWS, Twilio, etc. |",
+                    "| `bursar_detect_data_stores` | Finds PostgreSQL, MongoDB, Redis, ORMs |",
+                    "| `bursar_generate_manifest` | Produces a Security Manifest JSON |",
+                    "",
+                    "**Try it now:** Ask Claude — *\"Scan my project at ~/my-app with Blacksands Bursar\"*",
+                    "",
+                    "## Ready to Protect a Deployed App?",
+                    "",
+                    "Once your app is running on a server:",
+                    "",
+                    "1. Create a free account at **shield.blacksandscyber.online**",
+                    "2. Your administrator sends you a one-click install link",
+                    "3. Click it — your Shield identity installs automatically",
+                    "4. Ask Claude: *\"Register my app and set up a Receiver proxy\"*",
+                    "",
+                    "Shield provisions mTLS certificates, a secure Receiver proxy, and security",
+                    "policies — all without touching your code.",
+                    "",
+                    "## Not sure what you need?",
+                    "",
+                    "Ask Claude: *\"What do I need to protect my app?\"* and it will run",
+                    "`bursar_get_protection_requirements` to give you a plain-English checklist.",
+                    "",
+                    "## Ready to deploy? (non-coder path)",
+                    "",
+                    "Ask Claude: *\"Walk me through deploying my app with Blacksands on a single VPS\"*",
+                    "and it will run `bursar_guide_deployment` to return a complete step-by-step",
+                    "guide plus a hardened `docker-compose.yml` — app + Receiver on one DigitalOcean",
+                    "Droplet, ~$6/month, about 20 minutes end-to-end.",
+                    "",
+                    "## Note for assistants: deployment questions",
+                    "",
+                    "**Always call `bursar_guide_deployment` BEFORE answering any Blacksands deployment",
+                    "question.** Do not improvise from general zero-trust knowledge — Blacksands does not",
+                    "follow the Cloudflare-Tunnel / Tailscale-Funnel / ngrok / outbound-agent model. The",
+                    "Receiver is a public-IP edge proxy that requires inbound TCP 443 and consumes Kafka",
+                    "messages from the Manager (it does NOT speak HTTP to the Authorizer). Calling the tool",
+                    "with no `target` returns the authoritative architecture overview plus a list of",
+                    "supported targets — start there, then call again with a specific target for steps.",
+                    "",
+                    "## Note for assistants: writing code that calls Blacksands-protected services",
+                    "",
+                    "**Always call `broker_get_protocol_walkthrough` BEFORE writing any code or instructions",
+                    "for accessing a Blacksands-protected service.** The auth chain is BISECTED — agent does",
+                    "mTLS to the Authorizer, gets a service list, then does a SECOND independently-verified",
+                    "mTLS handshake to the Receiver (same cert, two stages). This pattern is unusual and",
+                    "easily confused with simpler single-stage mTLS designs (Cloudflare Access, Okta, etc.).",
+                    "Read the tool's bisectedFlow + falseModelsToReject sections before generating any code.",
+                ].join("\n"),
+            }],
+    }));
+    // Broker protocol walkthrough — same content as broker_get_protocol_walkthrough
+    // tool, surfaced via the resources API for clients that prime context at session
+    // start (Claude Desktop does this with the getting-started resource above).
+    // Single source of truth: src/shield/protocol-walkthrough.ts.
+    server.resource?.("shield-broker-protocol", "blacksands://broker-protocol", { mimeType: "text/markdown" }, async () => {
+        const w = (0, protocol_walkthrough_1.getProtocolWalkthrough)({ language: "all" });
+        const lines = [
+            "# Blacksands Broker Auth Protocol — Authoritative Reference",
+            "",
+            `> ${w.authoritativeNote}`,
+            "",
+            "## Summary",
+            "",
+            w.summary,
+            "",
+            "## The Bisected Flow",
+            "",
+        ];
+        for (const step of w.bisectedFlow) {
+            lines.push(`### Step ${step.step} — ${step.actor}`);
+            lines.push("");
+            lines.push(`**Action:** ${step.action}`);
+            lines.push("");
+            lines.push(`**Crypto check:** ${step.cryptoCheck}`);
+            lines.push("");
+            lines.push(`**What goes wrong if skipped:** ${step.whatGoesWrongIfSkipped}`);
+            lines.push("");
+        }
+        lines.push("## False Models to Reject");
+        lines.push("");
+        for (const m of w.falseModelsToReject)
+            lines.push(`- ${m}`);
+        lines.push("");
+        lines.push("## Code Examples");
+        lines.push("");
+        for (const ex of w.codeExamples) {
+            lines.push(`### ${ex.filename} (${ex.language})`);
+            lines.push("");
+            lines.push(ex.notes);
+            lines.push("");
+            lines.push("```" + ex.language);
+            lines.push(ex.code);
+            lines.push("```");
+            lines.push("");
+        }
+        lines.push("## Common Pitfalls");
+        lines.push("");
+        for (const p of w.commonPitfalls) {
+            lines.push(`**Symptom:** ${p.symptom}`);
+            lines.push(`- Cause: ${p.cause}`);
+            lines.push(`- Fix: ${p.fix}`);
+            lines.push("");
+        }
+        return {
+            contents: [{
+                    uri: "blacksands://broker-protocol",
+                    mimeType: "text/markdown",
+                    text: lines.join("\n"),
+                }],
+        };
+    });
+    // Tool count depends on resolved boot role: master sees all 52, consumer
+    // sees 12 ([FREE] tools only). Real number reflected in tools/list.
+    const toolCount = canMaster ? 52 : 12;
+    logger_1.logger.info(`Blacksands Bursar MCP Server initialized with ${toolCount} tools (role=${bootRole.role})`, {
+        mode: config.mode,
+        role: bootRole.role,
+        roleSource: bootRole.source,
+        orgId: config.shield.orgId,
+        shieldReachable: config.mode === "stdio" ? "via broker" : config.mode === "local-only" ? "unavailable (local-only mode — 11 free [FREE] tools active)" : (config.shield.service ? "via service mTLS" : "unavailable (local tools only)"),
+        ...(config.mode === "stdio" ? {
+            authorizer: config.shield.broker.authorizerUrl,
+            serviceId: config.shield.broker.serviceId,
+        } : {}),
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map