@blacksandscyber/mcp-server-bursar 0.5.0

package/README.md

@@ -0,0 +1,230 @@
+# @blacksandscyber/mcp-server-bursar
+
+Zero-trust security operations for AI agents. **45 tools** for codebase analysis, application provisioning, mTLS certificate management, compliance reporting, and Receiver proxy lifecycle — exposed through the Model Context Protocol so Claude (or any MCP client) can drive Blacksands Bursar directly.
+
+Two install paths, depending on which Claude surface you use:
+
+| Surface | Install | Effort |
+|---|---|---|
+| **Claude Code** | `claude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar` | One command |
+| **Claude Desktop** | Drag-and-drop the signed `.dxt` bundle | One drag |
+
+**Nine tools work without any Blacksands account.** Codebase scanning, framework detection, PII discovery, deployment guidance — installed and ready immediately. Sign up at [bursar.blacksandscyber.online](https://bursar.blacksandscyber.online) to unlock the remaining 36 tools (provisioning, compliance, Receiver management).
+
+---
+
+## Claude Code — one-line install
+
+The fastest path. Works in any directory — Claude Code launches the MCP server when needed.
+
+```bash
+# Local-only mode — 9 [FREE] tools work immediately, no account needed
+claude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar
+
+# Verify
+claude mcp list
+# bursar: npx -y @blacksandscyber/mcp-server-bursar - ✓ Connected
+```
+
+Then, in any Claude Code session:
+
+```
+> Scan my project at ~/some-app for security risks
+[Claude calls bursar_scan_codebase, returns the security manifest]
+
+> What's the Blacksands deployment architecture?
+[Claude calls bursar_guide_deployment, returns the authoritative overview]
+```
+
+### Bring your own credentials (full Bursar API access)
+
+To unlock all 45 tools, pass your existing cert bundle (issued through Overwatch / SysAdmin / a setup token):
+
+```bash
+claude mcp add bursar \
+  --env BURSAR_AUTHORIZER_URL=https://mauth-beta.blacksandscyber.online \
+  --env BURSAR_CLIENT_CERT=$HOME/.blacksands/mcp-certs/test-mcp9.crt \
+  --env BURSAR_CLIENT_KEY=$HOME/.blacksands/mcp-certs/test-mcp9.key \
+  --env BURSAR_AUTH_PASSWORD=$(cat $HOME/.blacksands/mcp-certs/.auth-password) \
+  --env BURSAR_ORG_ID=blacksands \
+  -- npx -y @blacksandscyber/mcp-server-bursar
+```
+
+Or, for a one-time bootstrap with a setup token from your Blacksands admin:
+
+```bash
+claude mcp add bursar \
+  --env BURSAR_SETUP_TOKEN=bss_xxxxxxxxxxxx \
+  -- npx -y @blacksandscyber/mcp-server-bursar
+```
+
+The MCP server redeems the token on first launch, persists the cert bundle to `~/.blacksands/mcp-certs/`, and uses it for every subsequent run.
+
+---
+
+## Claude Desktop — drag-and-drop the .dxt
+
+1. Build (or download) `blacksands-bursar-x.y.z.dxt`:
+   ```bash
+   cd mcp-server-blacksands-bursar
+   MANIFEST=manifest-v2.json npm run build:dxt
+   # outputs build/blacksands-bursar-x.y.z.dxt
+   ```
+2. Drag the `.dxt` onto the Claude Desktop app icon.
+3. Confirm install. Send a chat message — the MCP server starts on first tool call.
+
+For the non-coder onboarding flow (admin issues a setup token, user clicks the install email), see [bursar.blacksandscyber.online/docs/install](https://bursar.blacksandscyber.online/docs/install).
+
+---
+
+## What you get
+
+### 9 [FREE] tools — no account needed
+
+Run on any local project. No network calls except for `bursar_guide_deployment`'s overview text (which is bundled).
+
+| Tool | What it does |
+|---|---|
+| `bursar_scan_codebase` | Composite scan — framework, endpoints, PII, services, datastores, manifest |
+| `bursar_detect_framework` | Express, Flask, Rails, Next.js, Django, etc. |
+| `bursar_scan_endpoints` | Extract HTTP/API routes with method + auth detection |
+| `bursar_detect_pii` | SSN, credit card, health data, DOB; produces compliance hints |
+| `bursar_detect_external_services` | Stripe, OpenAI, AWS, Firebase, Twilio, etc. |
+| `bursar_detect_data_stores` | PostgreSQL, MongoDB, Redis, ORMs |
+| `bursar_generate_manifest` | Assemble detection results into a Security Manifest JSON |
+| `bursar_get_protection_requirements` | Plain-English checklist of what's needed to protect this app |
+| `bursar_guide_deployment` | Authoritative deployment walkthrough — DigitalOcean Droplet, local-docker dev, etc. |
+
+### 36 tools requiring a Blacksands account
+
+Provisioning (`bursar_create_org`, `bursar_create_app`, `bursar_provision_app`, `bursar_install_agent_remotely`), compliance (`bursar_compliance_report`, `bursar_compliance_controls`), certs (`bursar_list_certs`, `bursar_revoke_cert`, `bursar_rotate_cert`), Receiver lifecycle (`receiver_initialize`, `receiver_activate`, `receiver_onboard_service`, `receiver_health`), sessions (`bursar_list_sessions`, `bursar_revoke_session`), and emergency controls (`bursar_emergency_lockdown`, `bursar_lift_lockdown`).
+
+Calling any of these in local-only mode returns a friendly setup-token prompt instead of a stack trace.
+
+---
+
+## Configuration
+
+All env vars are optional except where noted. Sensible defaults are baked in so the MCP server starts in local-only mode with zero configuration.
+
+| Var | Default | Required for | Description |
+|---|---|---|---|
+| `MCP_TRANSPORT` | `stdio` | — | Set to `local-only` to skip all auth and run only the 9 [FREE] tools |
+| `BURSAR_AUTHORIZER_URL` | `https://mauth-beta.blacksandscyber.online` | broker mode | Where the MCP client authenticates to Bursar |
+| `BURSAR_SETUP_URL` | `https://onboard.beta.blacksandscyber.online` | token bootstrap | Where setup tokens are redeemed |
+| `BURSAR_SETUP_TOKEN` | (none) | first-time bootstrap | One-time `bss_…` token from a Blacksands admin |
+| `BURSAR_CLIENT_CERT` | (none) | broker mode | Path to mTLS client cert PEM file |
+| `BURSAR_CLIENT_KEY` | (none) | broker mode | Path to mTLS client key PEM file |
+| `BURSAR_AUTH_PASSWORD` | (none) | broker mode | Cert bundle's auth password |
+| `BURSAR_ORG_ID` | (none) | broker mode | Your organization id |
+| `BURSAR_CA_CERT` | bundled | optional | Path to Blacksands CA cert (override the bundled one) |
+| `LOG_LEVEL` | `info` | — | `debug`, `info`, `warn`, `error` |
+
+Persisted state lives in `~/.blacksands/mcp-certs/`:
+- `<client-name>.crt`, `<client-name>.key` — your mTLS bundle
+- `.auth-password`, `.client-name`, `.org-id`, `.last-token-prefix` — bookkeeping
+- `blacksands-ca.crt` — the Blacksands CA chain
+
+To rotate credentials: `rm -rf ~/.blacksands/mcp-certs/`, then start the MCP server with a fresh `BURSAR_SETUP_TOKEN`.
+
+---
+
+## Accessing protected services
+
+Once your agent has a valid mTLS cert (issued by Blacksands), reaching a protected service is **NOT** a single mTLS call. The auth chain is **bisected**: agent does mTLS to the **Authorizer** (which returns a list of services it's allowed to reach), then a SECOND independently-verified mTLS handshake to the **Receiver** (a public-IP edge proxy that forwards to the actual backend service).
+
+**For LLM-generated client code:** ask Claude to call **`broker_get_protocol_walkthrough`** before generating anything. That tool returns the authoritative protocol description plus copy-paste examples in Node.js, Python, and curl. Don't let Claude improvise the auth chain from training-data assumptions about mTLS — Blacksands is unusual: cert at TWO independent stages, backend service URL never reachable directly.
+
+```
+                  INTERNET
+                     │
+                     │  443 (mTLS, mandatory)
+                     ▼
+         ┌────────────────────┐
+         │     Authorizer     │  ← step 1: agent mTLS handshake
+         │  (mauth-…)         │  ← step 2: returns service-list with Receiver URLs
+         └────────────────────┘
+                     │
+                     │  agent picks service, builds URL with sessionToken
+                     ▼
+         ┌────────────────────┐
+         │     Receiver       │  ← step 4: SECOND mTLS handshake (same cert,
+         │  (public IP edge)  │            re-verified independently)
+         └─────────┬──────────┘
+                   │ private network
+                   ▼
+              backend service
+              (never reachable directly)
+```
+
+The MCP server's `broker_get_protocol_walkthrough` tool is the canonical reference — fetched lazily when an LLM needs it. Same content is also surfaced as the `blacksands://broker-protocol` MCP resource for clients (like Claude Desktop) that prime context at session start.
+
+A minimal Node.js sketch:
+
+```js
+const agent = new https.Agent({ cert, key, ca });
+
+// STEP 1+2: mTLS to Authorizer, get service URL + token
+const auth = await axios.post(
+  'https://mauth-beta.blacksandscyber.online/api/agent/auth',
+  { password, serviceId: 'bursar-api' },
+  { httpsAgent: agent }
+);
+const receiverUrl = auth.data.service.serviceUrl;  // points at the Receiver, not the service
+const [base, qs] = receiverUrl.split('?');
+const token = new URLSearchParams(qs).get('token');
+
+// STEP 3+4+5+6: SAME agent reused for the second mTLS handshake
+const api = axios.create({
+  baseURL: `${base}/v1`,
+  httpsAgent: agent,        // same cert presented again, Receiver re-verifies independently
+  params: { token },
+});
+const orgs = await api.get('/orgs');
+```
+
+Full Node.js, Python, and curl examples — plus the anti-patterns to avoid — are in the tool's output.
+
+---
+
+## Verifying the install
+
+```bash
+# Should show "bursar: ... ✓ Connected"
+claude mcp list
+
+# Quickest check — call a [FREE] tool that doesn't need Bursar API
+claude --print "What is the Blacksands deployment architecture? Use bursar_guide_deployment."
+```
+
+The MCP server logs to stderr (stdout is reserved for the MCP wire protocol). On macOS look in `~/Library/Logs/Claude/mcp-server-Bursar.log` (Claude Desktop) or run with `claude --mcp-debug` (Claude Code).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/b0bmarl3y/Blacksands_2_0.git
+cd Blacksands_2_0/mcp-server-blacksands-bursar
+npm install
+npm run lint && npm test          # 137 tests, ~4s
+npm run build                     # tsc → build/
+node dxt/scripts/setup.js         # boot the server directly
+```
+
+Test harness layout:
+
+| Tier | Location | What it covers | Cadence |
+|---|---|---|---|
+| 1 | `tests/manifest.test.ts`, `tests/dxt-package.test.ts`, `tests/bursar/deploy/*`, `tests/config.test.ts`, `tests/server-tags.test.ts` | DXT manifest spec, content invariants on tool output, mode dispatch, [FREE] tag discipline | Every commit |
+| 2 | `tests/harness/*` | MCP wire-protocol harness — spawns the compiled server and exercises tools/list + tools/call against a fixture project | Every PR |
+| 3 | `tests/integration/live-broker.test.ts` (gated) | Live broker chain canary against the real Bursar API | Release / on-demand (`RUN_LIVE_INTEGRATION=1`) |
+| 4 | (manual checklist) | Drag-install validation + LLM behavior + destructive-tool exercise | Release prep |
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+For commercial support, custom integrations, or enterprise deployments (cryptographic remote attestation, HSM-backed cert storage, on-prem control plane), contact [support@blacksands.io](mailto:support@blacksands.io).

package/build/config.d.ts

@@ -0,0 +1,45 @@
+export type DeploymentMode = "stdio" | "http-service" | "local-only";
+export interface MtlsConfig {
+    /** PEM-encoded client certificate (required in stdio / broker mode) */
+    clientCert: string;
+    /** PEM-encoded client private key (required in stdio / broker mode) */
+    clientKey: string;
+    /** Optional PEM-encoded CA bundle for server certificate pinning */
+    caCert: string | null;
+}
+export interface BrokerConfig {
+    /** URL of the Blacksands Authorizer (e.g. https://auth.blacksands.io) */
+    authorizerUrl: string;
+    /** Service ID to request from the Authorizer (default: "shield-api") */
+    serviceId: string;
+    /** Unique password issued alongside the mTLS cert for Authorizer session auth */
+    authPassword: string;
+}
+export interface ServiceMtlsConfig {
+    /** Shield API base URL (service discovery URL inside the VPC) */
+    apiUrl: string;
+    /** PEM-encoded service client cert */
+    clientCert: string;
+    /** PEM-encoded service client key */
+    clientKey: string;
+    /** Optional CA bundle */
+    caCert: string | null;
+}
+export interface Config {
+    mode: DeploymentMode;
+    shield: {
+        orgId: string;
+        /** Present in stdio mode; null when running as an http-service without broker */
+        broker: BrokerConfig | null;
+        /** Present in stdio mode; null when running as an http-service */
+        mtls: MtlsConfig | null;
+        /** Present in http-service mode when a service cert is configured */
+        service: ServiceMtlsConfig | null;
+    };
+    aws: {
+        region: string;
+        profile?: string;
+    };
+}
+export declare function loadConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/build/config.js

@@ -0,0 +1,177 @@
+"use strict";
+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.loadConfig = loadConfig;
+/**
+ * Configuration loaded from environment variables.
+ *
+ * The Shield MCP Server runs in one of two deployment modes:
+ *
+ *   - stdio (default): the server runs on the agent's machine and connects
+ *     to Shield through the full Broker handshake. The agent's mTLS cert is
+ *     issued by a human administrator through Overwatch or SysAdmin.
+ *
+ *   - http-service: the server runs as an HTTP service behind a Blacksands
+ *     Receiver. The Receiver authenticates the incoming agent and forwards
+ *     identity headers. The MCP server itself authenticates to Shield API
+ *     using a service-level mTLS certificate (not broker).
+ *
+ *   - local-only: the server starts without any Shield credentials. Only
+ *     local codebase-scan tools (bursar_scan_codebase, bursar_flag_pii_candidates,
+ *     etc.) are available. Shield-dependent tools fail gracefully at call
+ *     time with a user-friendly message pointing to the signup flow.
+ *     setup.js sets MCP_TRANSPORT=local-only when neither a cert bundle
+ *     nor a setup token is present, enabling the "free analyze" experience
+ *     without any account required.
+ *
+ * Set MCP_TRANSPORT=http to select http-service mode. The stdio entrypoint
+ * (src/index.ts) never sets that var, so stdio deployments always require
+ * the full broker configuration.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+/** Resolve ~ in file paths to the actual home directory. */
+function resolvePath(p) {
+    if (!p)
+        return null;
+    return p.startsWith("~") ? p.replace("~", os.homedir()) : p;
+}
+function readPem(inlineEnv, pathEnv) {
+    if (inlineEnv && inlineEnv.includes("-----BEGIN"))
+        return inlineEnv;
+    const path = resolvePath(pathEnv);
+    if (!path)
+        return null;
+    try {
+        return fs.readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function missingStdioConfigError(missing) {
+    return new Error([
+        "Shield MCP Server (stdio mode) cannot start: required broker configuration is missing.",
+        "",
+        "Missing: " + missing.join(", "),
+        "",
+        "The stdio MCP server operates in Broker mode. An mTLS client certificate",
+        "and auth password must be issued by a human administrator through Overwatch",
+        "or SysAdmin, then supplied to this Agent as config.",
+        "",
+        "Required environment variables:",
+        "  SHIELD_AUTHORIZER_URL, SHIELD_AUTH_PASSWORD, SHIELD_CLIENT_CERT,",
+        "  SHIELD_CLIENT_KEY, SHIELD_ORG_ID",
+        "",
+        "If you intended to run the server in http-service mode (behind a Receiver),",
+        "set MCP_TRANSPORT=http.",
+        "",
+        "If you only need local codebase scanning tools (no Shield account),",
+        "set MCP_TRANSPORT=local-only.",
+    ].join("\n"));
+}
+function loadConfig() {
+    const mode = process.env.MCP_TRANSPORT === "http" ? "http-service" :
+        process.env.MCP_TRANSPORT === "local-only" ? "local-only" :
+            "stdio";
+    const orgId = process.env.SHIELD_ORG_ID || "";
+    // ── local-only mode ─────────────────────────────────────────────────
+    // No credentials required. Local codebase-scan tools work; Shield API
+    // tools fail gracefully at call time with a signup prompt.
+    if (mode === "local-only") {
+        return {
+            mode,
+            shield: { orgId, broker: null, mtls: null, service: null },
+            aws: { region: process.env.AWS_REGION || "us-east-1", profile: process.env.AWS_PROFILE },
+        };
+    }
+    if (mode === "stdio") {
+        const clientCertPem = readPem(process.env.SHIELD_CLIENT_CERT_PEM, process.env.SHIELD_CLIENT_CERT);
+        const clientKeyPem = readPem(process.env.SHIELD_CLIENT_KEY_PEM, process.env.SHIELD_CLIENT_KEY);
+        const caCertPem = readPem(process.env.SHIELD_CA_CERT_PEM, process.env.SHIELD_CA_CERT);
+        const authorizerUrl = process.env.SHIELD_AUTHORIZER_URL || "";
+        const serviceId = process.env.SHIELD_SERVICE_ID || "shield-api";
+        const authPassword = process.env.SHIELD_AUTH_PASSWORD || "";
+        const missing = [];
+        if (!authorizerUrl)
+            missing.push("SHIELD_AUTHORIZER_URL");
+        if (!authPassword)
+            missing.push("SHIELD_AUTH_PASSWORD");
+        if (!clientCertPem)
+            missing.push("SHIELD_CLIENT_CERT");
+        if (!clientKeyPem)
+            missing.push("SHIELD_CLIENT_KEY");
+        if (!orgId)
+            missing.push("SHIELD_ORG_ID");
+        if (missing.length > 0)
+            throw missingStdioConfigError(missing);
+        return {
+            mode,
+            shield: {
+                orgId,
+                mtls: { clientCert: clientCertPem, clientKey: clientKeyPem, caCert: caCertPem },
+                broker: { authorizerUrl, serviceId, authPassword },
+                service: null,
+            },
+            aws: { region: process.env.AWS_REGION || "us-east-1", profile: process.env.AWS_PROFILE },
+        };
+    }
+    // ── http-service mode ───────────────────────────────────────────────
+    //
+    // The MCP server is reached through a Blacksands Receiver, which has
+    // already authenticated the calling agent and forwards identity headers.
+    // The MCP server itself may optionally talk to Shield API using a
+    // service-level mTLS certificate. If that cert is absent, Shield-dependent
+    // tools will fail at call time, but local tools (codebase discovery) and
+    // the MCP protocol surface stay fully functional.
+    const apiUrl = process.env.SHIELD_API_URL || "";
+    const serviceCert = readPem(process.env.SHIELD_SERVICE_CERT_PEM, process.env.SHIELD_SERVICE_CERT);
+    const serviceKey = readPem(process.env.SHIELD_SERVICE_KEY_PEM, process.env.SHIELD_SERVICE_KEY);
+    const serviceCa = readPem(process.env.SHIELD_SERVICE_CA_PEM, process.env.SHIELD_SERVICE_CA);
+    const service = (apiUrl && serviceCert && serviceKey)
+        ? { apiUrl, clientCert: serviceCert, clientKey: serviceKey, caCert: serviceCa }
+        : null;
+    return {
+        mode,
+        shield: {
+            orgId,
+            broker: null,
+            mtls: null,
+            service,
+        },
+        aws: { region: process.env.AWS_REGION || "us-east-1", profile: process.env.AWS_PROFILE },
+    };
+}
+//# sourceMappingURL=config.js.map

package/build/http-transport.d.ts

@@ -0,0 +1,16 @@
+/**
+ * HTTP + SSE Transport for Blacksands Bursar MCP Server.
+ *
+ * Runs the MCP server as a network service (instead of stdio) so it can be
+ * deployed behind a Blacksands Receiver and accessed by authenticated AI agents.
+ *
+ * Supports the MCP Streamable HTTP transport:
+ *   POST /mcp   — JSON-RPC request/response (and server→client notifications via SSE)
+ *   GET  /mcp   — SSE stream for server-initiated messages
+ *   DELETE /mcp  — Session termination
+ *
+ * Identity headers injected by the Receiver are used for authorization:
+ *   X-User-DN, X-User-CN, X-Authenticated-User, X-Blacksands-Session
+ */
+export {};
+//# sourceMappingURL=http-transport.d.ts.map

package/build/http-transport.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * HTTP + SSE Transport for Blacksands Bursar MCP Server.
+ *
+ * Runs the MCP server as a network service (instead of stdio) so it can be
+ * deployed behind a Blacksands Receiver and accessed by authenticated AI agents.
+ *
+ * Supports the MCP Streamable HTTP transport:
+ *   POST /mcp   — JSON-RPC request/response (and server→client notifications via SSE)
+ *   GET  /mcp   — SSE stream for server-initiated messages
+ *   DELETE /mcp  — Session termination
+ *
+ * Identity headers injected by the Receiver are used for authorization:
+ *   X-User-DN, X-User-CN, X-Authenticated-User, X-Blacksands-Session
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Signal to the rest of the server that we're running as an HTTP service.
+// Must be set BEFORE importing config/server, which read it at module load.
+process.env.MCP_TRANSPORT = "http";
+const http_1 = __importDefault(require("http"));
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const server_1 = require("./server");
+const logger_1 = require("./shared/logger");
+const PORT = parseInt(process.env.MCP_HTTP_PORT || "3100", 10);
+const HOST = process.env.MCP_HTTP_HOST || "0.0.0.0";
+/**
+ * Session store: maps Mcp-Session-Id → transport instance.
+ * Each AI agent connection gets its own transport + server pair.
+ */
+const sessions = new Map();
+/** Extract Blacksands identity from Receiver-injected headers. */
+function extractIdentity(req) {
+    return {
+        userDN: req.headers["x-user-dn"],
+        userCN: req.headers["x-user-cn"],
+        authenticatedUser: req.headers["x-authenticated-user"],
+        sessionId: req.headers["x-blacksands-session"],
+        certFingerprint: req.headers["x-client-cert-fingerprint"],
+        receiverBackend: req.headers["x-receiver-backend"],
+    };
+}
+/** Validate that the request came through an authenticated Receiver. */
+function isAuthenticated(req) {
+    const identity = extractIdentity(req);
+    // In production (behind Receiver), identity headers are always present.
+    // In local dev mode, allow unauthenticated access.
+    if (process.env.MCP_REQUIRE_AUTH === "false")
+        return true;
+    return !!(identity.authenticatedUser && identity.sessionId);
+}
+async function handleMcpRequest(req, res) {
+    // CORS for browser-based MCP clients
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id");
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+    if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    // Auth check
+    if (!isAuthenticated(req)) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Unauthorized", message: "Missing Blacksands identity headers" }));
+        return;
+    }
+    const sessionId = req.headers["mcp-session-id"];
+    if (req.method === "POST") {
+        // If no session exists for this ID, create a new one
+        if (!sessionId || !sessions.has(sessionId)) {
+            const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                sessionIdGenerator: () => crypto.randomUUID(),
+                onsessioninitialized: (newSessionId) => {
+                    const entry = sessions.get("_pending");
+                    if (entry) {
+                        sessions.delete("_pending");
+                        sessions.set(newSessionId, entry);
+                    }
+                    const identity = extractIdentity(req);
+                    logger_1.logger.info("MCP session initialized", {
+                        mcpSessionId: newSessionId,
+                        user: identity.authenticatedUser,
+                        blacksandsSession: identity.sessionId,
+                    });
+                },
+            });
+            const server = (0, server_1.createServer)();
+            await server.connect(transport);
+            sessions.set("_pending", { transport, server });
+            await transport.handleRequest(req, res);
+            return;
+        }
+        // Existing session
+        const entry = sessions.get(sessionId);
+        if (entry) {
+            await entry.transport.handleRequest(req, res);
+        }
+        else {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Session not found" }));
+        }
+        return;
+    }
+    if (req.method === "GET") {
+        // SSE stream for server-initiated messages
+        if (!sessionId || !sessions.has(sessionId)) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Missing or invalid Mcp-Session-Id" }));
+            return;
+        }
+        const entry = sessions.get(sessionId);
+        if (entry) {
+            await entry.transport.handleRequest(req, res);
+        }
+        return;
+    }
+    if (req.method === "DELETE") {
+        // Session termination
+        if (sessionId && sessions.has(sessionId)) {
+            const entry = sessions.get(sessionId);
+            if (entry) {
+                await entry.transport.handleRequest(req, res);
+                await entry.server.close();
+                sessions.delete(sessionId);
+                logger_1.logger.info("MCP session terminated", { mcpSessionId: sessionId });
+            }
+        }
+        else {
+            res.writeHead(204);
+            res.end();
+        }
+        return;
+    }
+    res.writeHead(405, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Method not allowed" }));
+}
+function handleHealthCheck(_req, res) {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        status: "healthy",
+        service: "blacksands-shield-mcp",
+        version: "0.1.0",
+        activeSessions: sessions.size,
+        uptime: process.uptime(),
+    }));
+}
+function startHttpServer() {
+    const server = http_1.default.createServer((req, res) => {
+        const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+        if (url.pathname === "/health") {
+            handleHealthCheck(req, res);
+        }
+        else if (url.pathname === "/mcp") {
+            handleMcpRequest(req, res).catch((err) => {
+                logger_1.logger.error("MCP request handler error", { error: err.message });
+                if (!res.headersSent) {
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Internal server error" }));
+                }
+            });
+        }
+        else {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not found", endpoints: ["/mcp", "/health"] }));
+        }
+    });
+    server.listen(PORT, HOST, () => {
+        logger_1.logger.info(`MCP HTTP server listening on ${HOST}:${PORT}`);
+        logger_1.logger.info("Endpoints: POST/GET/DELETE /mcp, GET /health");
+    });
+    // Graceful shutdown
+    const shutdown = async () => {
+        logger_1.logger.info("Shutting down MCP HTTP server...");
+        for (const [id, entry] of sessions) {
+            await entry.server.close();
+            sessions.delete(id);
+        }
+        server.close(() => {
+            logger_1.logger.info("MCP HTTP server stopped");
+            process.exit(0);
+        });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+startHttpServer();
+//# sourceMappingURL=http-transport.js.map

package/build/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @blacksandscyber/mcp-server-bursar
+ *
+ * Blacksands Bursar MCP Server.
+ * 39 tools exposing the human-admin surface via the Blacksands Broker.
+ *
+ * Usage:
+ *   node build/index.js                 # Start via stdio transport
+ *   npx -y @blacksandscyber/mcp-server-bursar  # Run via npx
+ *
+ * Credentials are issued by a human administrator through Overwatch or
+ * SysAdmin and provided here as configuration. See README.md for details.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map