agentgate-governed-writefile-demo

# agentgate-governed-writefile-demo This repo is the smallest outsider-readable proof path through AgentGate + MCP Firewall for one governed `write_file` call. It proves one narrow thing: a governed `write_file` call can be bonded, forwarded, independently checked on disk, and resolved from observed effect instead of upstream self-report. It exists as a narrow entry point into the ecosystem: one concrete proof path you can read, run, and inspect quickly. It is not a framework, SDK, starter kit, or general-purpose demo. ## Start Here - Success run: `npm run demo:success` - Failure run: `npm run demo:failure` - Success file: `./demo/governed-root/success/hello-from-agentgate.txt` - Failure target that should stay missing: `./demo/governed-root/failure/expected-but-missing.txt` - Success audit JSON: `./demo/output/success-firewall-outcome.json` - Failure audit JSON: `./demo/output/failure-firewall-outcome.json` Each command starts AgentGate, the upstream, and MCP Firewall for that run, then shuts them down afterward. You do not start those services by hand. ## Why This Repo Exists This repo exists to be the smallest concrete proof path through AgentGate + MCP Firewall for governed `write_file`. The success run proves the file really appears on disk and resolves `success`. The failure run proves an upstream can report success, the target can still stay missing, and the firewall will resolve `failed` from the missing on-disk effect. ## What You Can Verify Quickly - `npm run demo:success` produces the expected file and resolves `success`. - `npm run demo:failure` leaves the target path missing and resolves `failed`. - The firewall decision comes from the observed file effect on disk, not upstream-reported success alone. - Each run prints one raw `FIREWALL_OUTCOME {...}` line and saves parsed audit JSON under `./demo/output/`. - The demo starts what it needs automatically for the run and shuts it down afterward. ## Quick Proof After Setup Watch the real proof video: [assets/governed-writefile-proof-demo.mp4](assets/governed-writefile-proof-demo.mp4) The video shows the success run, the real file appearing on disk, the success audit JSON, the failure run, the target file staying missing, and the failure audit JSON. - success file appears - success audit resolves `success` / `verified` - failure target file stays missing - failure audit resolves `failed` / `target_missing` ## Agent-readable UI surface: buttons for humans, manifests for agents, proof for both A normal UI button tells a human what action is available. An agent-readable manifest tells an agent what action exists, what authority is required, what scope is allowed, and what counts as success. This repo includes a small example manifest at `./demo/ui-surface-manifest.example.json` for the existing notes `write_file` demo surface. It does not introduce a new protocol or UI framework. The manifest is only a presentation layer for the existing governed `write_file` proof. This does not add a new proof surface. It re-expresses the existing governed `write_file` proof as an agent-readable action manifest. Why this matters: future agent-native interfaces should not only expose actions; they should expose authority boundaries and verifiable success conditions. In this repo, the actual proof remains MCP Firewall's independent filesystem verification and AgentGate settlement. ## What This Is Not This is not a framework, starter kit, SDK, deployment story, or multi-tool demo. It is one governed `write_file` proof path, kept narrow on purpose. This does not prove general MCP security. It does not prove general agent safety. This does not verify arbitrary tools. This does not make upstream servers trustworthy. ## Inspect The Proof - Success target file: `./demo/governed-root/success/hello-from-agentgate.txt` - Failure target path that should remain missing: `./demo/governed-root/failure/expected-but-missing.txt` - Saved parsed audit JSON files: `./demo/output/success-firewall-outcome.json`, `./demo/output/failure-firewall-outcome.json` - Raw audit line: `FIREWALL_OUTCOME {...}` in stdout during each run ## Prerequisites - Node.js 20+ - A local checkout of `agentgate` - A local checkout of `agentgate-mcp-firewall` - `npm install` run in all three repos By default the three repos sit next to each other: ```text parent-directory/ agentgate/ agentgate-mcp-firewall/ agentgate-governed-writefile-demo/ ``` If your checkouts live elsewhere, set `AGENTGATE_REPO_PATH` and `MCP_FIREWALL_REPO_PATH` in `.env`. ## First Run Initial setup takes longer because you need sibling repo checkouts and `npm install` in all three repos. The proof run itself is the quick part. Install dependencies: ```bash cd ../agentgate && npm install cd ../agentgate-mcp-firewall && npm install cd ../agentgate-governed-writefile-demo && npm install ``` If your repo paths or ports differ from the defaults: ```bash cp .env.example .env ``` Run the proof: ```bash npm run demo:success npm run demo:failure ``` ## Success Demo ```bash npm run demo:success ``` Expected result: - one raw `FIREWALL_OUTCOME` line in stdout - `verification.status: verified` - `finalResolution: success` - a real file at `./demo/governed-root/success/hello-from-agentgate.txt` - a saved parsed audit JSON file at `./demo/output/success-firewall-outcome.json` What the run does: - starts a dedicated local AgentGate instance - creates or loads demo identities from `./demo/output/identities/` - locks demo bonds - starts the real filesystem-backed upstream - starts MCP Firewall with a `write_file`-only policy and one governed root - authenticates, performs one governed `write_file` call, verifies the file on disk, writes the audit JSON, and shuts everything down ## Failure Demo ```bash npm run demo:failure ``` Expected result: - one raw `FIREWALL_OUTCOME` line in stdout - `verification.status: failed` - `reasonCode: target_missing` - `finalResolution: failed` - no file at `./demo/governed-root/failure/expected-but-missing.txt` - a saved parsed audit JSON file at `./demo/output/failure-firewall-outcome.json` What the run does: - reuses the same local AgentGate DB and identities if they already exist - locks fresh demo bonds - starts the compromised upstream fixture in `noop` mode - lets the firewall startup canary succeed - makes one governed `write_file` call that upstream reports as successful - observes that the target file never appears on disk, resolves `failed`, writes the audit JSON, and shuts everything down ## Architecture ```mermaid flowchart LR CLI["This demo CLI"] --> AG["AgentGate<br/>repo-local DB"] CLI --> FW["MCP Firewall"] FW --> UP["Upstream write_file server"] UP --> ROOT["./demo/governed-root"] FW --> AUDIT["FIREWALL_OUTCOME<br/>stdout + saved JSON"] ``` ## Local State All generated state stays inside `./demo/`: - AgentGate DB: `./demo/output/agentgate.sqlite` - identity files: `./demo/output/identities/` - success audit JSON: `./demo/output/success-firewall-outcome.json` - failure audit JSON: `./demo/output/failure-firewall-outcome.json` - governed file output: `./demo/governed-root/` ## If You Want Implementation Depth, Then Read MCP Firewall And AgentGate This repo only wires one proof path together. For the independent `write_file` effect verification, read `agentgate-mcp-firewall` next. For the underlying identity, bond, execute, resolve, and authentication logic, read `agentgate` after that. ## License MIT