@blacksandscyber/mcp-server-bursar 0.5.0

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

@@ -0,0 +1,139 @@
+/**
+ * Shared types for bursar_install_agent_remotely.
+ *
+ * The Zod schema in src/server.ts is the source of truth for input shape.
+ * The runtime types below are carefully kept in sync — and are what the
+ * orchestrator, transports, and config merger pass around.
+ */
+export type AgentType = "claude-desktop" | "mcp-server" | "openclaw" | "custom";
+export type TransportType = "ssh" | "bootstrap-token" | "aws-ssm";
+export interface SshTransportSpec {
+    type: "ssh";
+    host: string;
+    port: number;
+    username: string;
+    authMethod: "private-key" | "ssh-agent" | "password";
+    privateKeyPath?: string;
+    knownHostsPath?: string;
+    hostKeyFingerprint?: string;
+    sudo: boolean;
+}
+export interface BootstrapTokenTransportSpec {
+    type: "bootstrap-token";
+    ttlSeconds: number;
+    allowedCidr?: string;
+    oneShot: boolean;
+    deliverVia: "return" | "email";
+    email?: string;
+}
+export interface AwsSsmTransportSpec {
+    type: "aws-ssm";
+    instanceId: string;
+    region?: string;
+}
+export type TransportSpec = SshTransportSpec | BootstrapTokenTransportSpec | AwsSsmTransportSpec;
+export interface InstallInput {
+    clientName: string;
+    orgId: string;
+    agentType: AgentType;
+    configPath?: string;
+    restartCmd?: string;
+    transport: TransportSpec;
+    serviceId: string;
+    authorizerUrl?: string;
+    dryRun: boolean;
+    waitForHandshake: boolean;
+    handshakeTimeoutMs: number;
+    rollbackOnFailure: boolean;
+    /**
+     * RBAC role for the issued cert. 'master' grants the full 47-tool MCP
+     * surface; 'consumer' restricts the agent to the 11 [FREE] tools and
+     * is enforced both at the Shield API (requireMcpRole middleware) AND
+     * at the MCP server (boot-time tool filtering via .role hint file
+     * written by setup.js). Defaults to 'master' when omitted, matching
+     * bursar_mcp_clients.role's backward-compat default.
+     */
+    role?: "master" | "consumer";
+}
+export interface InstalledFileRecord {
+    path: string;
+    mode: string;
+    sha256: string;
+}
+export interface InstallResult {
+    status: "installed" | "bootstrap-pending" | "dry-run";
+    clientName: string;
+    clientId: string;
+    fingerprint?: string;
+    expires?: string;
+    transport: TransportType;
+    target: Record<string, unknown>;
+    installedFiles: InstalledFileRecord[];
+    configPath: string;
+    bootstrapUrl?: string;
+    bootstrapExpiresAt?: string;
+    handshake: {
+        verified: boolean;
+        verifiedAt?: string;
+        receiverUrl?: string;
+        waitedMs?: number;
+        reason?: string;
+    };
+    auditId: string;
+    revokeHint: string;
+    next_steps: string[];
+    rollback?: {
+        performed: boolean;
+        steps: string[];
+        errors?: string[];
+    };
+    warnings?: string[];
+}
+/**
+ * Transport interface. Phase A.1 implements BootstrapToken only;
+ * SSH and SSM stubs throw to keep the discriminated union complete.
+ */
+export interface Transport {
+    readonly type: TransportType;
+    /**
+     * Deliver the credential bundle to the target and write files.
+     * For bootstrap-token, this means minting the token — no target-side
+     * action is performed by this MCP; the target will redeem later.
+     */
+    deliver(args: {
+        clientName: string;
+        orgId: string;
+        agentType: AgentType;
+        configPath: string;
+        serviceId: string;
+        authorizerUrl: string;
+        /** RBAC role for the issued cert (master | consumer). Optional; defaults
+         *  to 'master' on the Shield API side when omitted. */
+        role?: "master" | "consumer";
+    }): Promise<TransportDeliveryResult>;
+    /**
+     * Roll back any mutations this transport made on the target. Must be
+     * idempotent; called with the delivery result from a successful deliver().
+     */
+    rollback(delivery: TransportDeliveryResult): Promise<{
+        steps: string[];
+        errors: string[];
+    }>;
+}
+export interface TransportDeliveryResult {
+    /** status to surface to caller (maps to InstallResult.status) */
+    status: "installed" | "bootstrap-pending";
+    clientId: string;
+    fingerprint?: string;
+    expires?: string;
+    installedFiles: InstalledFileRecord[];
+    bootstrapUrl?: string;
+    bootstrapExpiresAt?: string;
+    /** If the target will redeem a token later, we don't yet know the config path. */
+    appliedConfig: boolean;
+    /** Arbitrary per-transport state the rollback step needs. */
+    rollbackState?: unknown;
+    warnings?: string[];
+    next_steps: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/build/shield/install/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared types for bursar_install_agent_remotely.
+ *
+ * The Zod schema in src/server.ts is the source of truth for input shape.
+ * The runtime types below are carefully kept in sync — and are what the
+ * orchestrator, transports, and config merger pass around.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/build/shield/protocol-walkthrough.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Authoritative description of the Blacksands broker auth protocol.
+ *
+ * Why this module exists:
+ *   The auth chain is BISECTED:
+ *     1. Agent does mTLS with the Authorizer
+ *     2. Authorizer returns the list of services the agent is authorized for
+ *     3. Agent picks one
+ *     4. The selected URL points at a Receiver (NOT the backend service)
+ *     5. Receiver re-verifies mTLS independently
+ *     6. Receiver proxies to the actual backend service
+ *
+ *   LLMs that don't know this protocol improvise from training data —
+ *   typically attempting `curl https://internal-service.acme.com/...`
+ *   directly and presenting the cert to the wrong endpoint. This module
+ *   is the SINGLE SOURCE OF TRUTH the LLM should consult before writing
+ *   any code that talks to a Blacksands-protected service.
+ *
+ *   Same authoritative-mode pattern as src/shield/deploy/index.ts (the
+ *   bursar_guide_deployment tool) — proven to override training-data
+ *   improvisation when the description is strong enough.
+ *
+ * Surfaced through THREE channels — single source of truth, three reach paths:
+ *   - The MCP tool `broker_get_protocol_walkthrough` (LLM-driven look-up)
+ *   - The MCP resource `blacksands://broker-protocol` (client-driven priming)
+ *   - The README "Accessing protected services" section (human + crawler)
+ */
+export type CodeLanguage = "node" | "python" | "curl" | "all";
+export interface CodeExample {
+    language: "node" | "python" | "curl";
+    filename: string;
+    code: string;
+    notes: string;
+}
+export interface FlowStep {
+    step: number;
+    actor: "agent" | "authorizer" | "receiver" | "service";
+    action: string;
+    cryptoCheck: string;
+    whatGoesWrongIfSkipped: string;
+}
+export interface ProtocolWalkthrough {
+    kind: "protocol-walkthrough";
+    authoritativeNote: string;
+    summary: string;
+    bisectedFlow: FlowStep[];
+    falseModelsToReject: string[];
+    codeExamples: CodeExample[];
+    commonPitfalls: Array<{
+        symptom: string;
+        cause: string;
+        fix: string;
+    }>;
+    furtherReading: {
+        receiverDocs: string;
+        authorizerDocs: string;
+        mcpServerInstall: string;
+    };
+}
+export interface WalkthroughOpts {
+    /** Filter code examples to a specific language. Default: all. */
+    language?: CodeLanguage;
+}
+export declare function getProtocolWalkthrough(opts?: WalkthroughOpts): ProtocolWalkthrough;
+//# sourceMappingURL=protocol-walkthrough.d.ts.map

package/build/shield/protocol-walkthrough.js

@@ -0,0 +1,392 @@
+"use strict";
+/**
+ * Authoritative description of the Blacksands broker auth protocol.
+ *
+ * Why this module exists:
+ *   The auth chain is BISECTED:
+ *     1. Agent does mTLS with the Authorizer
+ *     2. Authorizer returns the list of services the agent is authorized for
+ *     3. Agent picks one
+ *     4. The selected URL points at a Receiver (NOT the backend service)
+ *     5. Receiver re-verifies mTLS independently
+ *     6. Receiver proxies to the actual backend service
+ *
+ *   LLMs that don't know this protocol improvise from training data —
+ *   typically attempting `curl https://internal-service.acme.com/...`
+ *   directly and presenting the cert to the wrong endpoint. This module
+ *   is the SINGLE SOURCE OF TRUTH the LLM should consult before writing
+ *   any code that talks to a Blacksands-protected service.
+ *
+ *   Same authoritative-mode pattern as src/shield/deploy/index.ts (the
+ *   bursar_guide_deployment tool) — proven to override training-data
+ *   improvisation when the description is strong enough.
+ *
+ * Surfaced through THREE channels — single source of truth, three reach paths:
+ *   - The MCP tool `broker_get_protocol_walkthrough` (LLM-driven look-up)
+ *   - The MCP resource `blacksands://broker-protocol` (client-driven priming)
+ *   - The README "Accessing protected services" section (human + crawler)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProtocolWalkthrough = getProtocolWalkthrough;
+function getProtocolWalkthrough(opts = {}) {
+    const language = opts.language ?? "all";
+    return {
+        kind: "protocol-walkthrough",
+        authoritativeNote: "This is the AUTHORITATIVE description of the Blacksands broker auth protocol. " +
+            "Do NOT improvise from general mTLS or zero-trust knowledge — the protocol is BISECTED " +
+            "(Authorizer first, then a separately-verified Receiver), which is unusual and easily " +
+            "confused with simpler single-stage mTLS designs. Read the bisectedFlow + " +
+            "falseModelsToReject sections before writing any code or instructions for accessing " +
+            "a Blacksands-protected service.",
+        summary: "To call any Blacksands-protected service, your agent makes TWO mTLS handshakes in " +
+            "sequence with the same client cert: one to the Authorizer (which discovers what " +
+            "services you're allowed to reach and where they live), and one to the Receiver (a " +
+            "public-IP edge proxy that verifies your cert chain a second time and only then " +
+            "forwards to the backend). The Receiver address is returned by the Authorizer in " +
+            "the service-list response — never hardcoded by the agent. The backend service " +
+            "URL is NEVER reachable directly from the agent.",
+        bisectedFlow: [
+            {
+                step: 1,
+                actor: "agent",
+                action: "Agent opens an HTTPS connection to the Authorizer (e.g. mauth-beta.blacksandscyber.online) " +
+                    "and presents its mTLS client certificate during the TLS handshake. Cert + auth password " +
+                    "are POSTed to /api/agent/auth.",
+                cryptoCheck: "Authorizer validates: (a) the cert chain against the org CA, (b) the cert isn't revoked, " +
+                    "(c) the auth password matches the bundle's stored credential.",
+                whatGoesWrongIfSkipped: "If the agent skips this step and tries to talk to a service URL directly, no service " +
+                    "URL is reachable from the public internet — only the Receiver's edge IP is, and it will " +
+                    "reject any TLS handshake whose SNI doesn't match a known service.",
+            },
+            {
+                step: 2,
+                actor: "authorizer",
+                action: "On success, Authorizer returns a sessionToken plus a list of services { serviceId, serviceUrl, " +
+                    "serviceType }. The serviceUrl points at the RECEIVER's public address, not at the backend " +
+                    "service. The token is stamped with the agent's identity for downstream Receiver verification.",
+                cryptoCheck: "Authorizer signs the sessionToken; the Receiver verifies the signature in step 4.",
+                whatGoesWrongIfSkipped: "Without the service-list response, the agent has no way to know (a) which Receiver to " +
+                    "contact for which backend, (b) which backend services this cert is even authorized for. " +
+                    "The set of allowed services is per-cert, not per-URL — guessing service URLs cannot work.",
+            },
+            {
+                step: 3,
+                actor: "agent",
+                action: "Agent picks the service it wants from the list (matching by serviceId or serviceType), then " +
+                    "appends the sessionToken to the serviceUrl as a query parameter (?token=…) and uses that as " +
+                    "the base URL for all subsequent requests.",
+                cryptoCheck: "Token-in-URL is bound to the cert's identity by the Authorizer; binding is checked by the " +
+                    "Receiver in step 4 before any request bytes are forwarded.",
+                whatGoesWrongIfSkipped: "Agents that hardcode a serviceUrl (skipping the discovery in step 2) get a stale Receiver " +
+                    "address; if the Receiver moves, every cached client breaks.",
+            },
+            {
+                step: 4,
+                actor: "receiver",
+                action: "Agent opens a SECOND mTLS handshake — this time to the Receiver — and presents the SAME " +
+                    "client cert. The Receiver listens on TCP 443 only; mTLS is mandatory.",
+                cryptoCheck: "Receiver INDEPENDENTLY validates the cert chain against the org CA on every new connection. " +
+                    "It does not trust forwarded headers or the fact that the Authorizer already validated. " +
+                    "This is the second 'bisected' check that distinguishes the protocol from single-stage mTLS.",
+                whatGoesWrongIfSkipped: "If the agent presents a different cert (or no cert) to the Receiver, the TLS handshake fails " +
+                    "and no bytes are forwarded. The cert on Receiver-side is the SAME cert that authenticated to " +
+                    "the Authorizer — never a session-derived ephemeral one.",
+            },
+            {
+                step: 5,
+                actor: "receiver",
+                action: "Receiver looks up the request's sessionToken (?token=…) in its Redis-cached service-authorization " +
+                    "table populated by the Manager via Kafka. If the token + cert + serviceId combination is valid, " +
+                    "the request is forwarded to the backend service.",
+                cryptoCheck: "Token + cert fingerprint + serviceId are checked together; mismatched combinations are 403'd.",
+                whatGoesWrongIfSkipped: "Without the token, the Receiver may still accept the cert at the TLS layer but reject the " +
+                    "request at the application layer — symptoms include 401/403 with no clear cause.",
+            },
+            {
+                step: 6,
+                actor: "service",
+                action: "Backend service (Shield API, your internal app, etc.) receives the request from the Receiver. " +
+                    "The Receiver may have added X-Client-Cert-CN / X-Client-Cert-Valid headers so the service " +
+                    "knows the verified identity (used by Shield API for the per-MCP-client RBAC table).",
+                cryptoCheck: "The backend service trusts the Receiver's identity assertion (since the Receiver did the heavy " +
+                    "lifting). It does not re-verify the agent's cert; it relies on the headers.",
+                whatGoesWrongIfSkipped: "If the agent attempts to reach the backend service directly (bypassing the Receiver), no " +
+                    "X-Client-Cert headers are present, and the service rejects the request — that's the entire " +
+                    "point of the architecture.",
+            },
+        ],
+        falseModelsToReject: [
+            "WRONG: 'Agent talks directly to the backend service URL.' " +
+                "There is no public path to the backend service. Only the Receiver's public IP is reachable.",
+            "WRONG: 'The cert is presented to the backend service.' " +
+                "The cert is only ever presented to the Authorizer (step 1) and the Receiver (step 4). The " +
+                "service receives forwarded headers, not the cert itself.",
+            "WRONG: 'After getting the serviceUrl, skip the Receiver — it's just a transparent proxy.' " +
+                "The Receiver is a SEPARATE security boundary that re-verifies the cert chain. Skipping it " +
+                "is impossible (the URL points at it; there's no backend URL to skip TO).",
+            "WRONG: 'The Authorizer hands out time-limited service certs the agent uses for the backend.' " +
+                "No. The agent uses ITS OWN cert for both stages. The Authorizer hands out a sessionToken " +
+                "(in the URL), not a derived certificate.",
+            "WRONG: 'Once authenticated, cache the serviceUrl forever — re-discovery is unnecessary.' " +
+                "Wrong. Service URLs can change (Receiver migrations, new Receivers added/removed); " +
+                "sessionTokens have a TTL (~30 minutes). The agent should re-call /api/agent/auth when " +
+                "either expires or fails. The MCP server's BrokerConnector handles this transparently if " +
+                "you use it; from-scratch implementations need to handle 401/403 → reconnect.",
+            "WRONG: 'Like Cloudflare Access — the agent sees a JWT, the proxy verifies, done.' " +
+                "Different model. Blacksands uses end-to-end mTLS (cert presented at BOTH stages) plus a " +
+                "URL-bound sessionToken. There is no JWT; there is no SSO bounce; the protocol is fully " +
+                "machine-to-machine.",
+            "WRONG: 'I can use any HTTP client; mTLS is just a TLS option.' " +
+                "Practically true, but the client must (a) present the cert to BOTH endpoints, (b) handle " +
+                "the URL+token construction from step 2's response, (c) reconnect on 401/403. Most off-the-" +
+                "shelf clients require explicit configuration for all three.",
+        ],
+        codeExamples: filterExamples([
+            {
+                language: "node",
+                filename: "broker-call.js",
+                notes: "Node.js with axios + https.Agent. Reuses the same agent (and cert) for BOTH the Authorizer call " +
+                    "and the Receiver call — that's the bisected handshake in code form.",
+                code: NODE_EXAMPLE,
+            },
+            {
+                language: "python",
+                filename: "broker_call.py",
+                notes: "Python with `requests`. The cert= and verify= kwargs cover the mTLS for both stages. " +
+                    "The same cert+key pair is passed to both calls.",
+                code: PYTHON_EXAMPLE,
+            },
+            {
+                language: "curl",
+                filename: "broker-call.sh",
+                notes: "curl one-liner showing the full chain: first auth, then service call. Useful for debugging " +
+                    "and for validating cert/token state from the shell.",
+                code: CURL_EXAMPLE,
+            },
+        ], language),
+        commonPitfalls: [
+            {
+                symptom: "401 from the Authorizer on /api/agent/auth",
+                cause: "Either (a) the cert is not presented (httpsAgent missing or misconfigured), or (b) the auth password is wrong, or (c) the cert was revoked.",
+                fix: "Verify httpsAgent is passed to the request; verify the auth password matches what's in ~/.blacksands/mcp-certs/.auth-password; if revoked, request a new cert from your Shield admin.",
+            },
+            {
+                symptom: "200 from /api/agent/auth but service.serviceUrl is empty or null",
+                cause: "Infrastructure regression — the Manager couldn't resolve the requested serviceId from LDAP, or the service_authorization Kafka message hasn't propagated yet, or the Receiver-side Redis cache is stale.",
+                fix: "Re-attempt with a small backoff. If it persists, the cert isn't authorized for that serviceId — check via bursar_list_services or your Shield admin dashboard.",
+            },
+            {
+                symptom: "TLS handshake error when calling the serviceUrl",
+                cause: "The agent is connecting WITHOUT the client cert. This is by far the most common bug — many HTTP clients require explicit per-call cert config for the second handshake even if the first one worked.",
+                fix: "Pass the SAME httpsAgent / cert / key to the second call as the first. In axios: reuse `httpsAgent`. In Python requests: pass `cert=` to BOTH `auth_response = requests.post(...)` AND `service_response = requests.get(...)`.",
+            },
+            {
+                symptom: "401/403 from the Receiver despite a valid cert",
+                cause: "The sessionToken from step 2 wasn't included in the request URL, OR the token expired (~30 minute TTL), OR the cert presented to the Receiver is different from the one used for the Authorizer.",
+                fix: "Append `?token=<sessionToken>` to every request through the Receiver. On 401/403 with a previously-working session, re-call /api/agent/auth and use the new token.",
+            },
+            {
+                symptom: "Connection refused when bypassing the Receiver",
+                cause: "Working as designed. The backend service is not reachable from the public internet. Only the Receiver is.",
+                fix: "Always go through the Receiver URL returned by the Authorizer. Never hardcode the backend service URL.",
+            },
+        ],
+        furtherReading: {
+            receiverDocs: "https://shield.blacksandscyber.online/docs/receiver",
+            authorizerDocs: "https://shield.blacksandscyber.online/docs/authorizer",
+            mcpServerInstall: "claude mcp add shield -- npx -y @blacksandscyber/mcp-server-bursar",
+        },
+    };
+}
+function filterExamples(all, lang) {
+    if (lang === "all")
+        return all;
+    return all.filter((e) => e.language === lang);
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Code examples — kept as separate constants for readability and so the
+// content tests can grep them.
+// ──────────────────────────────────────────────────────────────────────────
+const NODE_EXAMPLE = `// broker-call.js — Node.js / axios + https.Agent
+//
+// Demonstrates the BISECTED Blacksands auth flow:
+//   1. mTLS to Authorizer  → get session token + service URLs
+//   2. mTLS to Receiver    → make the actual service call
+//
+// Both calls reuse the SAME httpsAgent (so the SAME cert is presented
+// to both endpoints). This is the linchpin — the agent's identity is
+// verified independently at both stages.
+
+const fs = require("fs");
+const https = require("https");
+const axios = require("axios");
+
+const AUTHORIZER_URL = "https://mauth-beta.blacksandscyber.online";
+const SERVICE_ID = "shield-api";  // or your org's app id
+const CERT_PATH = process.env.SHIELD_CLIENT_CERT;
+const KEY_PATH  = process.env.SHIELD_CLIENT_KEY;
+const CA_PATH   = process.env.SHIELD_CA_CERT;
+const AUTH_PASSWORD = process.env.SHIELD_AUTH_PASSWORD;
+
+// ONE httpsAgent reused for BOTH handshakes. This is the bisected protocol
+// in code form — same cert, two independent verifications.
+const agent = new https.Agent({
+  cert: fs.readFileSync(CERT_PATH),
+  key:  fs.readFileSync(KEY_PATH),
+  ca:   fs.readFileSync(CA_PATH),
+  rejectUnauthorized: true,
+});
+
+async function callBlacksandsService() {
+  // ── STEP 1+2: Authorize and discover the service URL ────────────────
+  const authRes = await axios.post(
+    \`\${AUTHORIZER_URL}/api/agent/auth\`,
+    { password: AUTH_PASSWORD, serviceId: SERVICE_ID },
+    { httpsAgent: agent, timeout: 30_000 }
+  );
+
+  if (!authRes.data.success || !authRes.data.service?.serviceUrl) {
+    throw new Error("Authorizer did not return a service URL — cert may not be authorized for " + SERVICE_ID);
+  }
+
+  // The service URL points at the RECEIVER (NOT at the backend service).
+  // It includes a sessionToken bound to this cert's identity.
+  const receiverUrl = authRes.data.service.serviceUrl;
+
+  // Strip ?token=… so we can use the URL as a base; pass the token as a
+  // query param on every call instead. (Path concat with ? in the URL
+  // breaks: \`https://host?token=X/v1/foo\` is malformed.)
+  const [base, qs] = receiverUrl.split("?");
+  const token = qs ? new URLSearchParams(qs).get("token") : null;
+
+  // ── STEP 3+4+5+6: Call the backend through the Receiver ─────────────
+  // The same httpsAgent is reused — Receiver does its OWN mTLS handshake
+  // and re-verifies the cert chain. Token goes as a query param.
+  const apiClient = axios.create({
+    baseURL: \`\${base.replace(/\\/$/, "")}/v1\`,
+    httpsAgent: agent,
+    timeout: 30_000,
+    params: token ? { token } : {},
+  });
+
+  // Now make any number of calls — apiClient handles the mTLS + token
+  // for each one.
+  const orgs = await apiClient.get("/orgs");
+  return orgs.data;
+}
+
+callBlacksandsService()
+  .then((data) => console.log(JSON.stringify(data, null, 2)))
+  .catch((err) => {
+    console.error("Failed:", err.response?.data || err.message);
+    process.exit(1);
+  });
+`;
+const PYTHON_EXAMPLE = `# broker_call.py — Python / requests
+#
+# Demonstrates the BISECTED Blacksands auth flow:
+#   1. mTLS to Authorizer  -> get session token + service URLs
+#   2. mTLS to Receiver    -> make the actual service call
+#
+# Both calls pass the SAME (cert, key) tuple via cert=, so the SAME cert
+# is presented to both endpoints. Don't try to re-use a session object
+# without the cert= kwarg — requests will silently drop the client cert
+# from the second connection.
+
+import os
+from urllib.parse import urlsplit, parse_qs
+import requests
+
+AUTHORIZER_URL = "https://mauth-beta.blacksandscyber.online"
+SERVICE_ID = "shield-api"  # or your org's app id
+
+CERT = os.environ["SHIELD_CLIENT_CERT"]
+KEY  = os.environ["SHIELD_CLIENT_KEY"]
+CA   = os.environ["SHIELD_CA_CERT"]
+AUTH_PASSWORD = os.environ["SHIELD_AUTH_PASSWORD"]
+
+# (cert_path, key_path) tuple reused on both calls. cert= covers the mTLS
+# client cert; verify= covers the server cert chain (so the agent verifies
+# the Authorizer's and Receiver's certs against the Blacksands CA).
+mtls_cert = (CERT, KEY)
+
+def call_blacksands_service():
+    # ── STEP 1+2: Authorize and discover the service URL ────────────────
+    auth_res = requests.post(
+        f"{AUTHORIZER_URL}/api/agent/auth",
+        json={"password": AUTH_PASSWORD, "serviceId": SERVICE_ID},
+        cert=mtls_cert,
+        verify=CA,
+        timeout=30,
+    )
+    auth_res.raise_for_status()
+    auth_data = auth_res.json()
+
+    if not auth_data.get("success") or not auth_data.get("service", {}).get("serviceUrl"):
+        raise RuntimeError(
+            f"Authorizer did not return a service URL "
+            f"— cert may not be authorized for {SERVICE_ID}"
+        )
+
+    # The service URL points at the RECEIVER (NOT at the backend service).
+    # Includes a sessionToken bound to this cert's identity.
+    receiver_url = auth_data["service"]["serviceUrl"]
+    parts = urlsplit(receiver_url)
+    base = f"{parts.scheme}://{parts.netloc}{parts.path.rstrip('/')}"
+    token = parse_qs(parts.query).get("token", [None])[0]
+
+    # ── STEP 3+4+5+6: Call the backend through the Receiver ────────────
+    # Same cert= reused — Receiver does its OWN mTLS handshake.
+    # Token goes as a query param on every call.
+    params = {"token": token} if token else {}
+
+    orgs_res = requests.get(
+        f"{base}/v1/orgs",
+        cert=mtls_cert,
+        verify=CA,
+        params=params,
+        timeout=30,
+    )
+    orgs_res.raise_for_status()
+    return orgs_res.json()
+
+if __name__ == "__main__":
+    import json, sys
+    try:
+        print(json.dumps(call_blacksands_service(), indent=2))
+    except Exception as e:
+        print(f"Failed: {e}", file=sys.stderr)
+        sys.exit(1)
+`;
+const CURL_EXAMPLE = `# broker-call.sh — full chain in shell
+#
+# Useful for: debugging, validating that your cert bundle works end-to-end,
+# and prototyping before writing real client code.
+
+set -euo pipefail
+
+AUTHORIZER_URL="https://mauth-beta.blacksandscyber.online"
+SERVICE_ID="shield-api"
+CERT="\${SHIELD_CLIENT_CERT:?env not set}"
+KEY="\${SHIELD_CLIENT_KEY:?env not set}"
+CA="\${SHIELD_CA_CERT:?env not set}"
+AUTH_PASSWORD="\${SHIELD_AUTH_PASSWORD:?env not set}"
+
+# ── STEP 1+2: mTLS to Authorizer, get the service list ────────────────
+AUTH_RESPONSE=$(curl -sf \\
+  --cert "$CERT" --key "$KEY" --cacert "$CA" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"password\\":\\"$AUTH_PASSWORD\\",\\"serviceId\\":\\"$SERVICE_ID\\"}" \\
+  "$AUTHORIZER_URL/api/agent/auth")
+
+# Extract the Receiver URL + token (jq makes this readable; use python -c if jq isn't installed)
+RECEIVER_URL=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); u=d['service']['serviceUrl']; print(u.split('?')[0].rstrip('/'))")
+TOKEN=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); u=d['service']['serviceUrl']; print(u.split('token=')[1] if 'token=' in u else '')")
+
+# ── STEP 3+4+5+6: Call the backend through the Receiver ──────────────
+# SAME cert reused — Receiver does its own mTLS. Token goes as a query param.
+curl -sf \\
+  --cert "$CERT" --key "$KEY" --cacert "$CA" \\
+  "$RECEIVER_URL/v1/orgs?token=$TOKEN" | python3 -m json.tool
+`;
+//# sourceMappingURL=protocol-walkthrough.js.map

package/build/shield/provision/appProvisioner.d.ts

@@ -0,0 +1,15 @@
+/** Orchestrate app provisioning via Shield API. */
+import { ShieldClient } from "../client";
+export interface ProvisionResult {
+    appId: string;
+    manifestId: string;
+    operationId: string;
+    status: string;
+    steps: Array<{
+        step: string;
+        timestamp: string;
+        result?: unknown;
+    }>;
+}
+export declare function provisionApp(client: ShieldClient, orgId: string, manifest: unknown, appName: string): Promise<ProvisionResult>;
+//# sourceMappingURL=appProvisioner.d.ts.map

package/build/shield/provision/appProvisioner.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provisionApp = provisionApp;
+const logger_1 = require("../../shared/logger");
+async function provisionApp(client, orgId, manifest, appName) {
+    const steps = [];
+    // Step 1: Register app
+    logger_1.logger.info("Step 1: Registering application", { appName, orgId });
+    const app = await client.createApp(orgId, appName);
+    steps.push({ step: "register_app", timestamp: new Date().toISOString(), result: { appId: app.id } });
+    // Step 2: Submit manifest
+    logger_1.logger.info("Step 2: Submitting security manifest", { appId: app.id });
+    const mf = await client.submitManifest(manifest, orgId);
+    steps.push({ step: "submit_manifest", timestamp: new Date().toISOString(), result: { manifestId: mf.id } });
+    // Step 3: Provision from manifest
+    logger_1.logger.info("Step 3: Provisioning security stack", { manifestId: mf.id });
+    const { operationId } = await client.provisionManifest(mf.id);
+    steps.push({ step: "provision_initiated", timestamp: new Date().toISOString(), result: { operationId } });
+    // Step 4: Poll until complete
+    logger_1.logger.info("Step 4: Polling operation", { operationId });
+    const op = await client.pollOperation(operationId);
+    steps.push({ step: "provision_completed", timestamp: new Date().toISOString(), result: op.result });
+    return { appId: app.id, manifestId: mf.id, operationId, status: op.status, steps };
+}
+//# sourceMappingURL=appProvisioner.js.map