Two-Key

Two-Key

Two independent keys must turn before an AI agent can act. No human needed.

AI agent authorization and MCP gateway with dual-path authorization. Deterministic bytecode policy combined with AI judge approval, single-use capability tokens, and an encrypted ledger.

🎯 The Problem

AI agents can be given permission to use a tool without being given authority to perform every consequential action that tool can perform.

Traditional tool permissions answer:

"Can this agent call this tool?"

Two-Key asks a different question:

"Is this specific action authorized to execute?"

Two-Key is an authorization layer for AI agents that use tools. Before a consequential tool call executes, Two-Key requires independent authorization through a deterministic policy path and an independent judge path:

• The policy key (Path A). The rules you sign compile to bytecode. A small deterministic VM checks every call against fields read from the call's own arguments: the tool, the amount, the counterparty, the data class, and fields you define. It reads no prose, so no prompt can talk it out of a rule.
• The judgment key (Path B). One or more AI judges, each with its own credential, review the call against your written constitution. Two-Key refuses to start with a judge that holds the agent's own credential.

Only when both keys turn does Two-Key issue a single-use token, bound to the exact arguments, the signed constitution, and the ledger state. The gateway runs the tool only with that token, and every decision, allowed or denied, is written to an encrypted, hash-chained ledger with a signed head.

What you get:

• Works with the agent you have. Grok, ChatGPT, Claude, Gemini, or a local model (i.e. Ollama) proposes the call as data; Two-Key decides.
• Judges you choose. xAI, OpenAI, Anthropic, Gemini, or a local model. One judge is enough to start; the high_assurance profile asks for judges from two makers and a yes from a local one.
• In front of any MCP server (0.5.0). two-key mcp-proxy shows the agent only the tools you signed and runs every call through both keys.
• Facts from your systems, not from the agent (0.5.0). A field such as "this invoice matches its purchase order" comes from your own lookup, and is looked up again just before the tool runs.
• An audit trail you can check. AES-256-GCM at rest, a hash chain, a head signed by the principal and a witness key, and two-key audit.
• A copy in your SIEM (0.7.0). Every decision can go to syslog or an HTTPS webhook as it is written, in Two-Key's own schema, ECS, or OCSF, with reason codes and digests but no argument values. A collector that is down never blocks a decision.
• Keys you can recover. Passphrase backup of every key, in three bundles.
• Small on purpose. Python 3.10 to 3.14, one required dependency (cryptography), Apache-2.0.

Status: beta. 0.9.0 is the current release, the last beta before 1.0: every signature is hybrid Ed25519 + ML-DSA-65 (quantum-resistant), a 0.8.0 deployment's keys are upgraded once at the first start, a tool behind the proxy can check its own calls (the tool check), a tool error spends its token, and two-key setup --window sets up in a window. 0.8.0 added a summary of recent decisions for the judges, each judge's ballot in the ledger, one proxy per agent, a read-only ledger audit window (two-key ledger-view) and a constitution editor. 0.7.3 added two-key setup and two-key config set, get, undo and check for setting up and changing a deployment, a signed serial so a ledger never goes back to older rules, and start-up checks for the upstream server's files behind a launcher. 0.7.0 added the SIEM export, a start-up check that refuses to run when the monitored agent is Two-Key's own account, and a count of the tokens the gateway refuses. Maintainer-reviewed and tested with live LLM agents and judges. Read Known limits and docs/FIT.md before you rely on it.

Contents

• Quick start
• Put Two-Key in front of an MCP server
• Documentation
• Components
• Dual-path authorization
• Architecture
• What this repo leaves out
• Known limits
• Roadmap
• Install and versions
• Layout
• History and license

Quick start

Install 0.9.0 from PyPI (docs/PYPI.md):

pip install "two-key[yaml]==0.9.0"

Tag v0.9.0 on main is the same code.

Or run the offline demo from a clone. It uses test-double judges, so it needs no API keys:

python3 -m venv .venv

. .venv/bin/activate pip install -e ".[yaml]" python -m two_key demo python -m two_key authorize --help

For a ten-minute walkthrough from install to an allowed and a refused call with a local judge, on the command line or in the setup and ledger windows, see docs/QUICKSTART.md.

Real judges are configured in examples/judges.yaml. The operator guide is docs/HOWTO.md. Before a real agent runs, close every way around Two-Key: docs/CONNECTING.md.

Put Two-Key in front of an MCP server

New in 0.5.0 (#2):

pip install "two-key[mcp]==0.9.0"

An MCP client (a desktop assistant, an IDE, an agent framework) normally starts an MCP server and calls its tools directly. With Two-Key, the client starts two-key mcp-proxy instead. The proxy starts the real server itself, shows the agent only the tools you signed, and runs every call through both keys before the server sees it. Facts such as a purchase-order match come from your own hook, never from the agent. A refused call comes back to the agent as a tool error with a reason code.

flowchart TD

host["Agent host MCP client"] -- "tools/list and tools/call, stdio" --> tk subgraph proxy["two-key mcp-proxy, its own OS user"] hooks["Fact hooks your code"] -- "facts" --> tk["Two-Key checks policy, asks judges"] tk -- "token" --> gw["Gateway same process"] end tk -. "normalized record" .-> judges["Judges"] gw -- "projected args, stdio" --> up["Upstream MCP server child process, third OS user"] up --> sor["System of record"] hooks -. "look facts up" .-> sor

two-key setup writes a first deployment; two-key config set, get, and undo change one setting at a time, checked and recorded in the ledger, and config key-passphrase encrypts the principal key (SETUP). two-key config check --config proxy.yaml says whether the proxy would start, and config show prints the settings it resolves to; both are read-only (HOWTO "Look at a config without starting the proxy"). two-key mcp-draft-specs drafts the tool specs from the server's own schemas for you to review and sign. The walkthrough, with a worked example, is HOWTO "Put Two-Key in front of an MCP server". Run the proxy and the upstream server as separate OS users, so neither the agent nor the server can reach the proxy's keys (HOWTO "Key custody"). The proxy speaks stdio only and does not listen on the network; an agent on another machine starts it over SSH with a forced command (CONNECTING), a route that still needs live testing. From 0.7.0 the proxy refuses to start when the account that started it is Two-Key's own, is root, or can change Two-Key's files (on_agent_access).

Documentation

| [docs/THREAT_MODEL.md](docs/THREAT_M