# context-firewall

**A local MCP server that answers agents' questions about you — through a policy.**

Share your allergies with the restaurant-booking agent. Refuse your salary
to everyone by default. Every request logged, every grant revocable,
nothing in the cloud.

```bash
npx context-firewall init
npx context-firewall enroll "claude-code"
# paste the printed token into claude-code's MCP config env — see docs/clients/claude-code.md
npx context-firewall serve
```

See it work without any client at all:

```bash
git clone https://github.com/ketriumlabs/context-firewall.git && cd context-firewall
pnpm install && pnpm build
node examples/demo/restaurant-agent.mjs
```

That script is the whole pitch in ~30 lines of console output: an agent
asks for allergies, gets refused until a human approves a single-use
grant, reads it once, gets refused again on the second attempt (grant
consumed), then asks for salary and is refused throughout — no scenario in
the demo ever grants that. Self-verifying — it exits non-zero if the
behavior ever drifts from this description.

## Why

Portable AI-context projects (`open-context`, `personal-context-manager`,
Stanford Digital Economy Lab's Human Context Protocol work) are converging
on "give agents a file about you" — but none of them do field-level
privacy. This does: a deny-by-default policy engine between your context
and every agent that asks about it, so "share diet preferences" and
"share salary" are two different, separately-revocable decisions, not one
all-or-nothing file handoff.

## The two files

- **`context.yaml`** — your data, namespaced (`identity`, `preferences`,
  `health`, `finance`, ...). Human-editable, diffable, safe to back up in
  a private git repo.
- **`policy.yaml`** — who gets what. Per-client, per-field grants with
  expiry (`once` / a TTL date / `never`). `cat` it any time to see exactly
  who can see what.

Neither file is a database. Both are plain YAML you can read yourself —
full field reference in [`docs/format.md`](docs/format.md), with editor
autocomplete via the published JSON Schemas in [`schemas/`](schemas).

## Threat model — read this before trusting it

See [`docs/threat-model.md`](docs/threat-model.md). Short version: this is
a **consent and organization tool, not a sandbox**. It does not protect
against local malware with filesystem access, a client that lies about
its own identity (a bearer token, not a cryptographic proof, is what
establishes identity in v0.1), or — yet — data at rest without your OS's
own disk encryption. It does give you a real audit trail, revocable
per-field grants, and policy files you can read yourself instead of
trusting a vendor's opaque memory feature.

## Importing existing memory

```bash
context-firewall import chatgpt path/to/export.json
context-firewall import claude path/to/memory-export.json
```

Both write a `*-imported-draft.yaml` file — extracted text snippets under
an `imported` namespace with instructions to sort them into real
namespaces by hand. Deliberately not "smart": guessing that a memory
string is `health` vs. `finance` and getting it wrong silently would be
worse than not guessing.

## CLI reference

| Command | What |
|---|---|
| `init` | Create `context.yaml` + `policy.yaml` |
| `enroll <name>` | Register an MCP client, print its one-time token |
| `serve` | Start the MCP server (reads `CONTEXT_FIREWALL_TOKEN` from env) |
| `status` | Show pending requests and current grants |
| `approve <id> [--once \| --ttl-days N]` | Approve a pending request |
| `deny <id>` | Deny a pending request (remembered — never re-asked) |
| `import <chatgpt\|claude> <file>` | Draft `context.yaml` from an export |

All commands accept `--dir <path>` to use a data directory other than
`~/.context-firewall`.

## Citations

Namespace layout and field taxonomy adapted from the Stanford Digital
Economy Lab's Human Context Protocol work and the `open-context` project's
field categories — see [`docs/format.md`](docs/format.md) for the mapping.
This project doesn't invent a new standard; if one of these converges into
something real, context-firewall converges with it.

## Roadmap

See [`docs/roadmap.md`](docs/roadmap.md) — OS-keychain encryption at rest
is the tracked v0.2 flagship.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Policy/consent changes get extra
scrutiny — see [SECURITY.md](SECURITY.md).

## License

[Apache-2.0](LICENSE)