telekey-mcp

See it stop an attack (30 seconds)

An agent is told to "clean up my old files, then email me a summary." You approve once. The orchestrator hands the cleanup to a helper — with a narrowed key that drops sendEmail. Then the helper gets prompt-injected into emailing an attacker:

npm install
node demo.js    # the attack, against the passport API directly
node drive.js   # the same attack, over real stdio JSON-RPC against src/server.js

(Recording above is assets/demo.gif; the raw asciinema capture is assets/demo.cast.)

The injection still happened. It just had nowhere to go — sendEmail was never in the helper's key, and the key could not be widened to add it. That last line is the whole point: a wider key doesn't get refused, it cannot be built.

Related MCP server: Outfit

The system, at a glance

Green is authorized, red is blocked, amber is the narrowed sub-agent key, cyan is identity. The animated version is inlined as SVG on the live demo; source in assets/telekey-diagram.html.

Install into Claude Code (one command)

This repo is a plugin marketplace. Point Claude Code at it and install — no clone, no build:

/plugin marketplace add stefans71/telekey-mcp
/plugin install telekey

The PreToolUse hook now enforces the key on every tool call. The same hook contract works on Codex and DeepSeek's bridge. To try the mechanics without installing anything, use node demo.js above.

The one rule that does the work

In the code this key is a signed capability passport; "key" and "passport" are the same thing throughout. Everything else — the engine, the policy layer, the plugin — exists to enforce that one rule at every hop.

What it stops

Twenty-five fixtures, each turning a documented 2026 agent-security failure mode into a pass/fail assertion. Every line below is backed by a passing test in test/ — run npm test to see them go green. The suite runs 29 tests in total: these 25 plus four build-integrity guards that keep the playground's parity vectors and standalone build from drifting from the engine.

1..29
# tests 29
# pass 29
# fail 0

Quick start

npm install
node demo.js    # the attack above, running against the real API
npm test        # 29 tests — 25 failure-mode fixtures + 4 build-integrity guards
npm run server  # boots the real MCP server (official SDK) over stdio

Open the server in the official MCP Inspector:

npx @modelcontextprotocol/inspector node src/server.js

Call delete_file with a passport argument and watch the engine allow it — or request an ungranted capability and watch it return isError with a CAP_NOT_GRANTED code.

How it works

Every tool call routes through a governance engine — a local trusted computing base — that does four things:

Two entry points share this one engine:

• The MCP server (src/server.js) gates each tool with engine.authorizeCall() before the tool body runs — the demonstrable, end-to-end path.

• The Claude Code plugin (plugin/) enforces the same rule at the harness boundary via a PreToolUse hook, so a call that exceeds the key is blocked before it runs — regardless of what the model intended. The same hook contract works on Codex and DeepSeek's bridge.

Why the delegation part matters

Permissions creep. In today's MCP setups an agent's access tends to widen as work moves — each new tool, each sub-agent, each hop quietly adds reach, and nothing forces it back down. The delegation primitive the MCP spec now leans on (RFC 8693 token exchange) has three documented gaps that let this happen: no holder-side scope attenuation, no portable provenance across hops, and no cross-domain verification without pre-arranged federation.

The first — the holder can't hand out a smaller key on its own — is exactly the property a 1994 language called Telescript enforced with its Permit model. TeleKey demonstrates that missing property as a signed key plus one verification rule, on top of standards everyone already ships.

1. You approve once. Root key P0: caps = {listRepo, deleteFile:repoX, sendEmail:you}, budget = {ttl:120s, spend:$0.50, calls:40, spawns:2}.

2. The orchestrator spawns a cleanup helper. The engine mints P1 ⊆ P0 with sendEmail dropped — the helper has no business emailing.

3. The helper deletes files; each call is checked against P1.caps, budget ticks down, and a token scoped only to repoX is exchanged per call. The root token is never passed through.

4. Control returns; the orchestrator sends the summary under P0 (the helper never could).

If step 2's helper is prompt-injected into sendEmail:attacker, verification fails at step 1 — that capability was never in P1, and P1 could not have been widened to add it. The injection still happened; it just had nowhere to go.

Why the name

In 1992, a startup called General Magic — the team that later seeded the iPhone, Android, eBay, and WebKit — built a language named Telescript for mobile software agents. Its core idea was a Permit: an unforgeable credential that travelled with an agent and, crucially, could only be narrowed as the agent moved between machines. The company folded; the idea was thirty years early.

The 2026 agent stack is now reinventing exactly that permit, badly, under names like "delegation token." TeleKey picks the idea back up — a key that shrinks as it's passed along, carrying its lineage in the name. Old idea, finally on time.

What's in here

src/          passport core: passport.js · engine.js · policy.js · publisher.js · server.js
plugin/       Claude Code plugin — PreToolUse hook enforcing the passport (also works on Codex/DeepSeek)
test/         conformance + policy + plugin-persistence + build guards (29 tests)
docs/         wizards (START-HERE, INSTALL-PLUGIN) + ROADMAP + NAMING
assets/       banner + architecture diagram (SVG), demo recording (gif + asciinema cast)
demo.js       the confused-deputy attack, failing, in 40 lines
playground/   the same attack as a live page (real engine via Web Crypto, parity-checked)
drive.js      scripted JSON-RPC driver: a valid call + a denied injected call, over stdio
passport-policy.json   user-adjustable permission settings

The plugin lives in plugin/ and imports the shared core from src/, so it can be extracted to its own repo later without a rewrite.

Status & caveats

Lineage & sources

Telescript Language Reference and Safety & Security whitepapers (General Magic, 1995) · MCP authorization spec (2025–2026) · RFC 8693 / 8707 / 9068 / 9207 · NSA/CISA MCP Security Design Considerations (2026) · OWASP MCP Top 10.

Project docs

License

MIT.