@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/deploy/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Deployment guides for non-coder "bring-your-own-host" protection flow.
+ *
+ * Shipped as part of the [FREE] tool surface — no Shield account needed to
+ * read these. Claude can walk a novice user through setting up a single
+ * DigitalOcean Droplet running both their app and a hardened Blacksands
+ * Receiver that proxies traffic through Shield's zero-trust controls.
+ *
+ * New deploy targets (Railway, Render, Fly, EC2) can be added by:
+ *   1. Extending the DeployTarget union
+ *   2. Implementing a guide function in this file
+ *   3. Dispatching from getDeploymentGuide()
+ */
+export type DeployTarget = "digitalocean-droplet" | "local-docker-development";
+/** Architecture-overview shape — returned when no target is specified. */
+export interface DeploymentArchitectureOverview {
+    kind: "architecture-overview";
+    authoritativeNote: string;
+    blacksandsArchitecture: {
+        receiverIsPublicIpEdgeProxy: string;
+        inbound: string;
+        outbound: string;
+        controlPlaneChannels: string;
+        falseModelsToReject: string[];
+    };
+    pickATarget: Array<{
+        target: DeployTarget;
+        description: string;
+        recommended: string;
+    }>;
+}
+export interface DeploymentGuide {
+    kind: "guide";
+    target: DeployTarget;
+    summary: string;
+    estimatedCost: string;
+    estimatedTimeMinutes: number;
+    prerequisites: string[];
+    walkthroughMarkdown: string;
+    dockerCompose: string;
+    verificationSteps: string[];
+    securityControls: Array<{
+        control: string;
+        effect: string;
+    }>;
+    honestTamperingNote: string;
+}
+export interface DeploymentGuideOpts {
+    /** Docker image tag for the user's app (e.g. "myapp:latest"). Defaults to a placeholder. */
+    appImage?: string;
+    /** Port the user's app listens on inside its container. Default: 8080. */
+    appPort?: number;
+    /** Short slug for the app — used in container/host names. Default: "my-app". */
+    appName?: string;
+    /** Receiver setup token from receiver_initialize. Can be omitted and pasted later. */
+    receiverSetupToken?: string;
+    /** DigitalOcean region slug (e.g. "nyc3", "sfo3"). Default: "nyc3". */
+    region?: string;
+    /** DigitalOcean droplet size slug (e.g. "s-1vcpu-2gb"). Default: "s-1vcpu-2gb". */
+    dropletSize?: string;
+}
+/**
+ * The single entry point. Pass a target to get a target-specific walkthrough.
+ * Pass undefined / no target to get an architecture overview that any caller
+ * MUST read before producing their own walkthrough — this prevents LLMs from
+ * confidently improvising wrong deployment models from training data.
+ */
+export declare function getDeploymentGuide(target: DeployTarget | undefined | null, opts?: DeploymentGuideOpts): DeploymentGuide | DeploymentArchitectureOverview;
+//# sourceMappingURL=index.d.ts.map

package/build/shield/deploy/index.js

@@ -0,0 +1,569 @@
+"use strict";
+/**
+ * Deployment guides for non-coder "bring-your-own-host" protection flow.
+ *
+ * Shipped as part of the [FREE] tool surface — no Shield account needed to
+ * read these. Claude can walk a novice user through setting up a single
+ * DigitalOcean Droplet running both their app and a hardened Blacksands
+ * Receiver that proxies traffic through Shield's zero-trust controls.
+ *
+ * New deploy targets (Railway, Render, Fly, EC2) can be added by:
+ *   1. Extending the DeployTarget union
+ *   2. Implementing a guide function in this file
+ *   3. Dispatching from getDeploymentGuide()
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeploymentGuide = getDeploymentGuide;
+/**
+ * The single entry point. Pass a target to get a target-specific walkthrough.
+ * Pass undefined / no target to get an architecture overview that any caller
+ * MUST read before producing their own walkthrough — this prevents LLMs from
+ * confidently improvising wrong deployment models from training data.
+ */
+function getDeploymentGuide(target, opts = {}) {
+    if (!target) {
+        return buildArchitectureOverview();
+    }
+    switch (target) {
+        case "digitalocean-droplet":
+            return buildDigitalOceanDropletGuide(opts);
+        case "local-docker-development":
+            return buildLocalDockerDevelopmentGuide(opts);
+        default:
+            throw new Error(`Unsupported deployment target: ${target}`);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Architecture overview — returned when target is unspecified.
+// ──────────────────────────────────────────────────────────────────────────
+function buildArchitectureOverview() {
+    return {
+        kind: "architecture-overview",
+        authoritativeNote: "This is the AUTHORITATIVE description of how a Blacksands Bursar deployment is shaped. " +
+            "Do NOT answer Blacksands deployment questions from general zero-trust knowledge — " +
+            "Blacksands does not match the Cloudflare-Tunnel / Tailscale-Funnel / Twingate model. " +
+            "Read this overview, then call bursar_guide_deployment again with a specific target " +
+            "for copy-paste steps.",
+        blacksandsArchitecture: {
+            receiverIsPublicIpEdgeProxy: "The Blacksands Receiver is a PUBLIC-IP EDGE PROXY. It is NOT an outbound " +
+                "tunneling client. It runs on a host with a stable public IP and accepts " +
+                "incoming TLS connections directly from the internet on TCP 443.",
+            inbound: "TCP 443 ONLY, mTLS mandatory. The Receiver terminates TLS and independently " +
+                "verifies the client certificate chain against the org CA on every new connection. " +
+                "There is no plaintext HTTP path; port 80 is not exposed.",
+            outbound: "TLS to the Blacksands Kafka cluster. The Receiver consumes service_authorization " +
+                "messages from the Manager via Kafka — that is its only control-plane channel.",
+            controlPlaneChannels: "Receiver ↔ Manager via Kafka (TLS). The Receiver does NOT speak HTTP to the " +
+                "Authorizer; the Authorizer is the MCP-client side of the system. MCP clients " +
+                "(Claude Desktop) talk to the Authorizer to discover the Receiver's URL.",
+            falseModelsToReject: [
+                "WRONG: 'The Receiver dials out to the Blacksands control plane' — no, it is a public-IP proxy.",
+                "WRONG: 'No inbound ports needed' — inbound TCP 443 is required.",
+                "WRONG: 'Like Cloudflare Tunnel / Tailscale Funnel / ngrok' — different model entirely.",
+                "WRONG: 'Receiver authenticates to the Authorizer' — Receiver only consumes Kafka from the Manager.",
+                "WRONG: 'No public IP needed' — Receivers REQUIRE a stable public IP for SNI routing.",
+                "WRONG: 'Plaintext HTTP supported' — TLS+mTLS only.",
+            ],
+        },
+        pickATarget: [
+            {
+                target: "digitalocean-droplet",
+                description: "Single-VPS production-ready bundle. App + hardened Receiver in one docker-compose " +
+                    "on a DigitalOcean Droplet (~$6/mo). ~20 minutes to a protected endpoint. " +
+                    "Recommended for non-coders and for the first end-to-end test of Blacksands.",
+                recommended: "Start here unless you have a specific reason to do something else.",
+            },
+            {
+                target: "local-docker-development",
+                description: "DEV ONLY: a docker-compose for running your app locally on a laptop, WITHOUT a real " +
+                    "Receiver. Use ngrok or cloudflared as a temporary public-IP shim if you want to " +
+                    "test against a remote Receiver. Not suitable for production — laptops do not have " +
+                    "the stable public IP a Blacksands Receiver requires.",
+                recommended: "Only for local iteration on the app itself. Move to digitalocean-droplet (or another " +
+                    "VPS target) before any real traffic.",
+            },
+        ],
+    };
+}
+// ──────────────────────────────────────────────────────────────────────────
+// DigitalOcean single-VPS bundle
+// ──────────────────────────────────────────────────────────────────────────
+function buildDigitalOceanDropletGuide(opts) {
+    const appImage = opts.appImage || "YOUR_APP_IMAGE:tag";
+    const appPort = opts.appPort || 8080;
+    const appName = opts.appName || "my-app";
+    const token = opts.receiverSetupToken || "<paste-receiver-setup-token-here>";
+    const region = opts.region || "nyc3";
+    const size = opts.dropletSize || "s-1vcpu-2gb";
+    const dockerCompose = buildDropletDockerCompose({ appImage, appPort, appName });
+    const walkthrough = buildDropletWalkthrough({ appImage, appPort, appName, token, region, size, dockerCompose });
+    return {
+        kind: "guide",
+        target: "digitalocean-droplet",
+        summary: "Deploy your app + a hardened Blacksands Receiver on one DigitalOcean Droplet. Single VPS, ~$6/month, about 20 minutes to a protected endpoint.",
+        estimatedCost: `~$6/month (${size} droplet) + DigitalOcean bandwidth. New accounts typically get $200 free credit.`,
+        estimatedTimeMinutes: 20,
+        prerequisites: [
+            "DigitalOcean account (free to sign up at digitalocean.com)",
+            "Your app packaged as a Docker image (ask Claude to help containerize if needed)",
+            "A Blacksands Bursar account at shield.blacksandscyber.online",
+            "SSH key pair on your computer (run `ssh-keygen -t ed25519` if you don't have one)",
+        ],
+        walkthroughMarkdown: walkthrough,
+        dockerCompose,
+        verificationSteps: [
+            "`docker compose logs receiver` shows 'Receiver: bootstrap complete' and 'authenticated with Authorizer'",
+            "The `receiver_health` MCP tool returns status=active for your Receiver",
+            "The `receiver_list_services` MCP tool lists your app",
+            "Your app is reachable at the Receiver's assigned DNS name (use `receiver_get_dns`)",
+        ],
+        securityControls: [
+            { control: "mTLS-only on TCP 443", effect: "Every inbound connection must present a valid client certificate; plaintext HTTP is not exposed (no port 80 binding)" },
+            { control: "Receiver re-verifies cert chain on every new connection", effect: "The Receiver independently validates each client's certificate chain against the org CA on inbound TLS handshake — it does not trust forwarded cert headers from any upstream component" },
+            { control: "read_only: true", effect: "Receiver container filesystem is immutable at runtime" },
+            { control: "tmpfs mount for /certs", effect: "mTLS keys live in memory only — never hit disk, wiped on restart" },
+            { control: "user: 1000:1000", effect: "Receiver runs as unprivileged user; no root inside container" },
+            { control: "cap_drop: ALL", effect: "All Linux capabilities stripped — cannot mount filesystems, load modules, etc." },
+            { control: "no-new-privileges", effect: "Prevents setuid-based privilege escalation inside the container" },
+            { control: "No Docker socket mounted", effect: "Container cannot control the host Docker daemon or escape to host" },
+            { control: "Image pulled from signed registry", effect: "Swapping in a tampered image requires defeating Docker Content Trust" },
+            { control: "Sessions established at the Authorizer, not the Receiver", effect: "A locally-modified Receiver cannot invent valid sessions — every session is minted at a separate Blacksands service" },
+            { control: "Per-tenant Kafka authorization scope", effect: "Receiver only receives service_authorization messages for its own organization — cannot read or affect other tenants" },
+        ],
+        honestTamperingNote: "You have root on your own VPS, so you could modify the Receiver locally. Modifications affect only your own traffic — you cannot forge identities for other tenants (the CA private key is held by Blacksands, not the Receiver), cannot read other tenants' traffic (Receivers only receive Kafka messages addressed to their own org), and cannot invent valid sessions (sessions are established at the Authorizer, a separate Blacksands service). For workloads requiring cryptographic proof of binary integrity (TPM-backed remote attestation, signed control-plane messages), ask about Shield Enterprise.",
+    };
+}
+function buildDropletDockerCompose(p) {
+    return `# Blacksands Bursar — single-VPS deployment (DigitalOcean Droplet)
+#
+# Network model:
+#   INBOUND  : TCP 443 ONLY from the public internet. mTLS is mandatory —
+#              the Receiver terminates TLS and independently verifies every
+#              client certificate chain on the inbound handshake. There is
+#              NO plaintext HTTP path; port 80 is not exposed. The Receiver
+#              IS a public-IP edge proxy doing SNI routing — it is NOT an
+#              outbound tunnel.
+#   OUTBOUND : TLS to the Blacksands Kafka cluster (the Receiver's only
+#              control-plane channel — it consumes service_authorization
+#              messages from the Manager via Kafka). It does NOT speak HTTP
+#              to the Authorizer; the Authorizer is the MCP-client side.
+#
+# Security hardening applied to the Receiver container:
+#   - read_only: true              (filesystem immutable at runtime)
+#   - tmpfs /certs                 (mTLS keys in memory only, never on disk)
+#   - user: 1000:1000              (non-root inside container)
+#   - cap_drop: ALL                (all Linux capabilities stripped)
+#   - no-new-privileges            (prevents setuid escalation)
+#   - no Docker socket mount       (cannot control host Docker daemon)
+#   - signed image from Blacksands registry
+
+services:
+  receiver:
+    image: blacksands/receiver:stable
+    container_name: blacksands-receiver
+    restart: unless-stopped
+    read_only: true
+    user: "1000:1000"
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      # Bootstrap: the setup token is single-use and tells the Receiver where
+      # the Blacksands onboarding edge lives, so it can fetch its mTLS cert
+      # bundle, RECEIVER_ID, ORGANIZATION_ID, and Kafka credentials.
+      # Generated by the receiver_initialize MCP tool.
+      RECEIVER_SETUP_TOKEN: \${RECEIVER_SETUP_TOKEN}
+      LOG_LEVEL: info
+      # Route traffic to the app container via Docker DNS.
+      UPSTREAM_HOST: ${p.appName}
+      UPSTREAM_PORT: ${p.appPort}
+    tmpfs:
+      - /tmp:size=64M,mode=1777
+      - /var/cache/nginx:size=128M,mode=0700,uid=1000,gid=1000
+      - /run:size=16M,mode=0700,uid=1000,gid=1000
+      - /certs:size=16M,mode=0700,uid=1000,gid=1000
+    ports:
+      # The Receiver listens ONLY on 443. All client traffic is mTLS — the
+      # Receiver terminates TLS and independently verifies every client
+      # certificate chain against the org CA on the inbound handshake.
+      # There is no port 80 binding because there is no plaintext path.
+      - "443:8443"
+    networks:
+      - shield-net
+    depends_on:
+      - app
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+
+  app:
+    image: ${p.appImage}
+    container_name: ${p.appName}
+    restart: unless-stopped
+    # Your app is NOT exposed to the public internet.
+    # Only the Receiver on the shield-net network can reach it.
+    expose:
+      - "${p.appPort}"
+    networks:
+      - shield-net
+
+networks:
+  shield-net:
+    driver: bridge
+`;
+}
+function buildDropletWalkthrough(p) {
+    return `# Deploy your app + Blacksands Bursar Receiver — DigitalOcean single-VPS
+
+**Time:** about 20 minutes. **Cost:** ~$6/month. **Result:** your app reachable from the internet only through Blacksands' zero-trust Receiver.
+
+> **Network model in one paragraph (read this first).** The Receiver is a public-IP edge proxy that listens on **TCP 443 only** — every connection is mTLS, and the Receiver independently verifies the client certificate chain against your org CA on each inbound handshake before any bytes from the client reach your app. There is **no plaintext HTTP path**; port 80 is not exposed. SNI on 443 selects the right backend service. Your Droplet **must** allow inbound TCP 443 from the internet, or no traffic ever reaches the Receiver — it is **not** an outbound tunneling client. The Receiver's only outbound control-plane channel is **TLS to the Blacksands Kafka cluster** (where it consumes \`service_authorization\` messages from the Manager). It does not speak HTTP to the Authorizer; that's the MCP-client side of the system. Your *MCP client* (Claude Desktop) talks to the Authorizer to discover this Receiver's URL — your Receiver does not.
+
+---
+
+## Step 1 — Get a Receiver setup token
+
+In this Claude chat, say: *"Initialize a Receiver for my app, email it to <your-email>"*.
+
+Claude runs \`receiver_initialize\` and returns a **setup token**. Copy it; you'll paste it in Step 6.
+
+---
+
+## Step 2 — Create a DigitalOcean Droplet
+
+**Easiest (web UI):**
+
+1. Go to https://cloud.digitalocean.com/droplets/new
+2. **Image:** *Marketplace → Docker on Ubuntu 22.04*
+3. **Size:** Basic → Regular → **$6/mo (${p.size})**
+4. **Region:** **${p.region}** (or the region closest to your users)
+5. **Authentication:** SSH key — upload your public key (usually \`~/.ssh/id_ed25519.pub\`)
+6. **Hostname:** \`${p.appName}-shield\`
+7. Click **Create Droplet** — ready in about 45 seconds
+
+**Or with the \`doctl\` CLI:**
+
+\`\`\`bash
+doctl compute droplet create ${p.appName}-shield \\
+  --image docker-20-04 \\
+  --size ${p.size} \\
+  --region ${p.region} \\
+  --ssh-keys $(doctl compute ssh-key list --format ID --no-header | head -1)
+\`\`\`
+
+**Copy the Droplet's public IPv4 address** from the DigitalOcean dashboard.
+
+> **Firewall reminder.** Your Droplet must accept **inbound TCP 443 only** from the public internet — the Receiver is a public-IP edge proxy that requires mTLS on every connection. **Do not open port 80**; there is no plaintext HTTP path. New DigitalOcean Droplets default to no Cloud Firewall (so all ports are open), but if you've attached a Cloud Firewall make sure it allows inbound TCP 443 and only 443. The Droplet also needs **outbound TLS** to reach the Blacksands Kafka cluster — that's egress, which DigitalOcean allows by default.
+
+---
+
+## Step 3 — SSH into the Droplet
+
+\`\`\`bash
+ssh root@<droplet-ip>
+\`\`\`
+
+The Marketplace image has Docker pre-installed. Verify:
+
+\`\`\`bash
+docker --version && docker compose version
+\`\`\`
+
+---
+
+## Step 4 — Create the deployment directory
+
+\`\`\`bash
+mkdir -p /opt/blacksands && cd /opt/blacksands
+\`\`\`
+
+---
+
+## Step 5 — Save this \`docker-compose.yml\`
+
+Paste the file below as \`/opt/blacksands/docker-compose.yml\`:
+
+\`\`\`yaml
+${p.dockerCompose}\`\`\`
+
+If your app image, port, or name differ from the defaults, edit the \`app\` service accordingly.
+
+---
+
+## Step 6 — Store your Receiver setup token
+
+\`\`\`bash
+cat > /opt/blacksands/.env <<EOF
+RECEIVER_SETUP_TOKEN=${p.token}
+EOF
+chmod 600 /opt/blacksands/.env
+\`\`\`
+
+---
+
+## Step 7 — Launch
+
+\`\`\`bash
+docker compose --env-file .env up -d
+\`\`\`
+
+Watch the Receiver come up:
+
+\`\`\`bash
+docker compose logs -f receiver
+\`\`\`
+
+Wait for:
+- \`Receiver: bootstrap complete\` — the setup token was redeemed and the cert bundle / RECEIVER_ID / ORGANIZATION_ID are in memory
+- \`Receiver: Kafka consumer ready\` — the control-plane channel to the Manager is open
+- \`Receiver: listening on :8443 (mTLS only)\` — public ingress is up; mTLS verification active
+
+Press **Ctrl-C** when you see those.
+
+---
+
+## Step 8 — Wire up DNS and services
+
+Back in this Claude chat:
+
+1. *"Add my app as a service on my Receiver"* → runs \`receiver_onboard_service\` with \`host=${p.appName}\`, \`port=${p.appPort}\`.
+2. *"What's my Receiver's DNS name?"* → runs \`receiver_get_dns\`.
+3. *"Check my Receiver's health"* → runs \`receiver_health\`.
+
+If you want your own domain instead of the auto-assigned one, create an A record at your DNS provider pointing to the Droplet's IP, then tell Claude the domain.
+
+---
+
+## Verification
+
+Your app is now reachable **only** through the Receiver. Test by asking Claude: *"List active sessions on my Receiver"* — you should see traffic flowing through once you hit the URL.
+
+---
+
+## How traffic flows (so the picture is clear)
+
+\`\`\`
+                     INTERNET
+                        │
+                        │  443 ONLY · mTLS mandatory
+                        ▼
+               ┌────────────────┐
+               │   Receiver     │◀──── (outbound only) Kafka TLS to Blacksands Manager
+               │  (this box)    │       — receives service_authorization messages,
+               │  public IP     │         publishes session audit events
+               │  · TLS termin. │
+               │  · mTLS verify │
+               │  · SNI routing │
+               └───────┬────────┘
+                       │ docker network only (encrypted at the edge,
+                       ▼  cleartext or app-level TLS to your container)
+                 ┌──────────┐
+                 │   Your   │
+                 │   App    │
+                 └──────────┘
+\`\`\`
+
+**Receiver inbound is TCP 443 only and every connection is mTLS.** On each new connection the Receiver terminates TLS and independently verifies the client certificate chain against your org's CA — it does not trust forwarded headers from any upstream component for cert identity. SNI on 443 selects the right backend service; the connection from the Receiver to your app rides the private Docker network. The Receiver does **not** speak HTTP to the Authorizer; Kafka to the Manager is its only control-plane channel. The Authorizer is what your MCP client (Claude Desktop) talks to to discover this Receiver's URL.
+
+## What's protecting you
+
+The \`docker-compose.yml\` applies these controls to the Receiver container:
+
+| Control | Why it matters |
+|---|---|
+| **mTLS-only on 443** | Every inbound connection requires a client certificate; plaintext HTTP is not exposed |
+| **Receiver re-verifies the cert chain on every new connection** | The Receiver does not trust any forwarded cert identity — it independently validates the client's chain against your org CA on the inbound TLS handshake |
+| \`read_only: true\` | Receiver binaries + config cannot be modified at runtime |
+| \`tmpfs /certs\` | mTLS keys live in RAM only — never written to disk, gone on restart |
+| \`user: 1000:1000\` | Container runs unprivileged; \`root\` is not available inside |
+| \`cap_drop: ALL\` | No Linux capabilities — can't mount filesystems, load kernel modules, etc. |
+| \`no-new-privileges\` | Prevents setuid-based privilege escalation |
+| No Docker socket | Container can't talk to the Docker daemon or escape to host |
+| Signed image from Blacksands registry | Casual image swapping is detected by Docker Content Trust |
+
+**Honest note on local tampering.** You have root on your own Droplet, so you *could* modify the Receiver locally. What that does and doesn't get you:
+
+- **It can** weaken protection of *your own* traffic — e.g. logging less, skipping policy checks. That hurts only you.
+- **It cannot** forge identities for other tenants (the Blacksands CA's private key is held by Blacksands, not in this Receiver).
+- **It cannot** read other tenants' traffic — your Receiver only gets Kafka authorization messages addressed to your organization.
+- **It cannot** invent valid sessions out of thin air — every session is established at the Authorizer (a different system Blacksands operates), not the Receiver.
+
+For workloads that need cryptographic proof the Receiver hasn't been modified (TPM-backed binary attestation, signed-message verification at the control plane), see **Shield Enterprise**.
+
+---
+
+## Updating
+
+**New Receiver release from Blacksands:**
+\`\`\`bash
+cd /opt/blacksands
+docker compose pull receiver
+docker compose up -d receiver
+\`\`\`
+
+**New version of your own app:** edit the image tag in \`docker-compose.yml\`, then:
+\`\`\`bash
+docker compose up -d app
+\`\`\`
+
+---
+
+## Troubleshooting
+
+- **Receiver won't bootstrap** → setup token likely expired (they're single-use, time-limited). Ask Claude to initialize a fresh one, paste into \`.env\`, \`docker compose up -d receiver\`.
+- **Receiver bootstraps but Kafka consumer never reports ready** → outbound TLS to the Blacksands Kafka cluster is being blocked. Check the Droplet's egress (DigitalOcean Cloud Firewall, host iptables) allows outbound to the Kafka broker host on its TLS port.
+- **App unreachable from outside** → the Droplet's *inbound* TCP 443 must be open (and only 443). The Receiver is a public-IP edge proxy, not a tunnel; if your firewall blocks 443, nothing reaches the Receiver. Check **Droplets → Networking → Firewalls**.
+- **Receiver keeps restarting** → health check failing. Run \`docker compose exec receiver wget -qO- http://localhost:8080/health\` to see the actual error.
+
+For anything else, ask Claude — it has tools to query Blacksands' control plane for Receiver status, session logs, and policy enforcement.
+`;
+}
+// ──────────────────────────────────────────────────────────────────────────
+// Local Docker development — laptop dev-only path
+// ──────────────────────────────────────────────────────────────────────────
+function buildLocalDockerDevelopmentGuide(opts) {
+    const appImage = opts.appImage || "YOUR_APP_IMAGE:tag";
+    const appPort = opts.appPort || 8080;
+    const appName = opts.appName || "my-app";
+    const dockerCompose = `# Blacksands Bursar — LOCAL DEV ONLY (no Receiver in this file)
+#
+# IMPORTANT: a Blacksands Receiver REQUIRES a stable public IP. Laptops do
+# not have one — they sleep, change networks, and live behind NAT. So this
+# compose file does NOT include the Receiver. It runs your app locally for
+# fast development iteration; once the app is ready you deploy the actual
+# Blacksands-protected version to a real VPS (see target='digitalocean-droplet').
+#
+# If you want to test against a remote Receiver while iterating on the app
+# locally, use a public-IP shim:
+#   - ngrok http ${appPort}      (gives you a public hostname pointing at this laptop)
+#   - cloudflared tunnel        (similar; needs a Cloudflare account)
+# These are DEV-ONLY; do not expose production data this way.
+
+services:
+  app:
+    image: ${appImage}
+    container_name: ${appName}
+    restart: unless-stopped
+    ports:
+      # Bound to localhost only — DO NOT expose to the LAN. Use ngrok/cloudflared
+      # if you need a public URL during development.
+      - "127.0.0.1:${appPort}:${appPort}"
+    networks:
+      - dev-net
+
+networks:
+  dev-net:
+    driver: bridge
+`;
+    const walkthroughMarkdown = `# Local Docker development — Blacksands Bursar
+
+> **DEV ONLY.** This walkthrough does NOT install a Blacksands Receiver. A real Receiver requires a stable public IP and listens on inbound TCP 443; laptops can't satisfy that requirement. Use this guide while iterating on your app, then move to a real VPS for any traffic that matters. The recommended production target is \`digitalocean-droplet\` (single-VPS, ~$6/mo).
+
+---
+
+## What this gets you
+
+A clean local Docker setup where your app:
+- Runs in a container that auto-restarts (\`restart: unless-stopped\`)
+- Binds to \`127.0.0.1\` only (does NOT expose to your LAN)
+- Sits on its own Docker network
+
+What it does NOT get you:
+- Any Blacksands protection
+- A way for external users / CI / phones to reach the app
+
+---
+
+## Step 1 — Save the dev compose file
+
+\`\`\`yaml
+${dockerCompose}\`\`\`
+
+---
+
+## Step 2 — Run
+
+\`\`\`bash
+docker compose up -d
+docker compose logs -f ${appName}
+curl http://127.0.0.1:${appPort}/healthz   # adjust to your healthcheck path
+\`\`\`
+
+---
+
+## Step 3 — (Optional) Remote test against a real Receiver
+
+If you want to test the **MCP-protected access path** while still iterating on the app locally, you have two reasonable options:
+
+**Option A — ngrok shim (fastest):**
+\`\`\`bash
+brew install ngrok
+ngrok config add-authtoken <your-token>
+ngrok http ${appPort}
+# Get a URL like https://abc123.ngrok-free.app — point your real (remote)
+# Receiver at this URL via receiver_onboard_service.
+\`\`\`
+Limitation: ngrok rotates URLs unless you pay; the cert chain is ngrok's, not yours.
+
+**Option B — Run a real Receiver on a $6 VPS, point it at your laptop's tunnel:**
+Use the \`digitalocean-droplet\` target to stand up an actual Receiver, then add a service whose upstream is your ngrok / cloudflared URL. This is closest to your eventual production setup.
+
+**Both options are dev-only.** Do not put real user traffic through ngrok-shimmed laptops.
+
+---
+
+## When to graduate
+
+Stop using this walkthrough when:
+1. Your app's behaviour is stable enough that you want it always-on
+2. You need other people, your phone, or CI to hit it
+3. You want to actually test Blacksands' Receiver-side controls (mTLS verification, policies)
+
+At that point, switch to \`bursar_guide_deployment\` with \`target='digitalocean-droplet'\` for a single-VPS production-ready deployment.
+
+---
+
+## Why a laptop can't host a Receiver
+
+For completeness, here's the architectural reason:
+
+| Receiver requires | Laptop has | Result |
+|---|---|---|
+| Stable public IP | Behind NAT, IP changes per network | Can't satisfy |
+| Inbound TCP 443 reachable from internet | Most home routers block inbound | Can't satisfy |
+| 24/7 uptime to consume Kafka control-plane messages | Sleeps when lid closes | Can't satisfy |
+| Reproducible environment for Docker Content Trust on the Receiver image | Personal machine | Possible but fragile |
+
+A $6/mo Droplet (or any VPS) satisfies all of these. The Blacksands deployment story optimizes for that target.
+`;
+    return {
+        kind: "guide",
+        target: "local-docker-development",
+        summary: "DEV ONLY: a local Docker setup for iterating on the app. Does NOT install a Receiver — a Receiver requires a public IP, which laptops do not have. Use this for app development; switch to digitalocean-droplet for any real traffic.",
+        estimatedCost: "Free.",
+        estimatedTimeMinutes: 5,
+        prerequisites: [
+            "Docker Desktop installed and running",
+            "Your app packaged as a Docker image (or a Dockerfile to build from)",
+            "(Optional) ngrok or cloudflared if you want a public URL for remote testing",
+        ],
+        walkthroughMarkdown,
+        dockerCompose,
+        verificationSteps: [
+            "`docker compose ps` shows the app container running",
+            "`curl http://127.0.0.1:<port>/healthz` returns 200 from the laptop",
+            "The container does NOT bind to 0.0.0.0 (LAN-exposed) — only 127.0.0.1",
+        ],
+        securityControls: [
+            { control: "127.0.0.1 binding only", effect: "App is reachable from the laptop only — not from the LAN, not from the internet" },
+            { control: "Restart policy unless-stopped", effect: "Container survives crashes during dev iteration" },
+            { control: "Dedicated Docker network (dev-net)", effect: "Isolated from other compose stacks on the laptop" },
+        ],
+        honestTamperingNote: "This setup has no Blacksands protection at all — the app is not behind a Receiver, there is no mTLS, no policy enforcement, no audit. It is a dev convenience for iterating on the app itself. Do NOT use it for any traffic that matters. For real protection, deploy the digitalocean-droplet target (or another VPS variant) where a real Receiver can run.",
+    };
+}
+//# sourceMappingURL=index.js.map

package/build/shield/discovery/dataStoreDetector.d.ts

@@ -0,0 +1,3 @@
+import type { DataStore } from "../types";
+export declare function detectDataStores(projectPath: string): Promise<DataStore[]>;
+//# sourceMappingURL=dataStoreDetector.d.ts.map