io.github.Delego-Dev/delego

delego

Website: delegohq.com · Docs: delegohq.com/docs · Spec: Delego-Dev/specification

Intent-bound action authorization for AI agents. It sits between an agent and whatever credential broker holds the user's secrets, and it answers the one question brokers don't: is this specific action the thing the human actually asked for?

   agent  ──propose──▶  delego  ──if allowed──▶  credential broker  ──▶  service
   (LLM)               (policy +                (Agent Vault /         (bank,
                        approval +               OneCLI /               SaaS,
                        audit)                   Browser Use…)          API)
                           │
                           └── needs_approval ──▶  human (CLI)

📜 Protocol: delego implements protocol 0.3 of the open delego wire specification — canonicalization, the policy schema, intent/fingerprint binding including the §4.2 query-fold, and the signed audit chain. The authorization token (spec §9) is an optional profile, not yet implemented.

Why this exists

The "agent gets its own scoped credential, and never holds the user's secret directly" pattern is now a crowded, converging space — Infisical's Agent Vault, OneCLI, Browser Use, Nango, and others all do credential brokering.

The harder problem sits one level up — the confused deputy: the agent holds a valid credential, a prompt injection redirects it, the scope covers the action, so the broker happily injects the secret and the action goes through. The credential is the wrong place to catch this — it's valid. OAuth tokens carry no commitment to the original instruction.

Authorising the action (not just the credential) is an active area — see deterministic policy engines (OPA/Cedar, Permit), human-in-the-loop approval (HumanLayer), MCP gateways/firewalls, and the "pre-action authorization" line of research. delego is a small, deterministic, local, Apache-2.0 reference for it: no LLM in the decision path, no credential custody, approvals bound to the exact action fingerprint, and a signed, hash-chained audit trail — riding the existing broker layer rather than competing with it.

What it is / isn't

• Is a decision-and-audit layer. Deterministic policy, human approval for sensitive actions, signed append-only audit ledger.
• Isn't a credential vault or a proxy. It delegates execution to a broker through a thin BrokerAdapter interface — you ride the existing layer instead of rebuilding it.
• Authorisation is pure Python, no LLM in the loop. A model can advise upstream; the decision that gates a credential is made outside the stochastic loop, so an injection can't talk its way past it.

Key properties

1. Intent binding — every action carries a hash of the original human instruction, recorded in the audit ledger and re-checked at resolve time, so an approval cannot be re-pointed at a different claimed instruction.
2. Action-bound, single-use approval — a human "yes" is bound to one exact action fingerprint. An agent that gets approval for action A cannot reuse it to run action B (the confused-deputy guard), and cannot replay the same approval to run action A twice — an approval releases its action exactly once.
3. Tamper-evident audit — receipts form an Ed25519-signed hash chain. Editing, reordering, removing a receipt, or dropping a field breaks verification, which reports the fault rather than trusting the ledger. Caveats (be precise): hash-chaining does not catch truncation of the most recent receipts (a tail-truncated prefix verifies clean), and the local signing key protects nothing against a host compromise. For rollback detection, anchor the head externally and pass it to verify(expected_head=…); for key safety, use an HSM/KMS. See SECURITY.md.

Quickstart

pip install delego          # the `delego` library + CLI
# pip install "delego[mcp]" # add the `delego-mcp` server (MCP is an optional extra)
delego init               # creates ~/.delego with signing keys and an example policy
delego policy             # inspect the active policy

To run the full loop end-to-end from a clone — an allowed read, a forbidden deny, an over-cap deny, an approval flow, the confused-deputy guard refusing a substituted action, and audit-chain tamper detection (no agent or live service needed):

git clone https://github.com/Delego-Dev/delego && cd delego
pip install -e ".[dev]"
python examples/demo.py
pytest

Human side (CLI)

delego policy            # show the active policy
delego pending           # list actions awaiting approval
delego approve apr_xxxx  # release a parked action (or: delego deny apr_xxxx)
delego log -n 20         # read recent receipts
delego verify            # check the audit chain (hashes, linkage, signatures)

Agent side (MCP) — wiring into Claude Code

delego ships an MCP server (delego_mcp) over stdio — install it with the mcp extra: pip install "delego[mcp]". Register it in your MCP config (for Claude Code, .mcp.json at the project root) so the agent can propose actions. Set DELEGO_HOME to keep the policy, signing keys, and ledger project-scoped under .claude/.delego:

{
  "mcpServers": {
    "delego": {
      "command": "delego-mcp",
      "env": { "DELEGO_HOME": "/abs/path/to/project/.claude/.delego" }
    }
  }
}

Initialise that home and approve from the same one (the CLI and MCP server must share a home):

delego --home .claude/.delego init       # keys, example policy, and a .gitignore
delego --home .claude/.delego pending    # ...then: delego --home .claude/.delego approve apr_xxxx

If DELEGO_HOME is unset, the CLI also auto-uses ./.claude/.delego when run from the project root, falling back to ~/.delego. (Use an absolute path in the MCP env, since the server's launch directory isn't guaranteed.)

Tools exposed:

Approving and denying are deliberately not exposed over MCP — the agent that proposed an action must never be able to approve it; a human decides out-of-band.

Typical flow: the agent calls delego_propose_action. If it comes back needs_approval with an approval_id, a human runs delego approve <id>, then the agent calls delego_resolve_action with the identical action to complete it.

Policy format

A rule matches on method / host / path (glob) / path_contains, decides allow or needs_approval, and can attach constraints. Order is forbidden (hard deny) → rules (first match wins) → default. A matched rule whose constraints fail becomes a deny (fail-closed). See policy.example.yaml.

rules:
  - name: place-order
    decision: needs_approval
    match: { method: POST, host: api.example.com, path: /orders }
    constraints:
      amount:     { field: amount, max: 5000, currency: USD }
      allow_list: { field: destination, in: [internal] }

Supported constraints: amount (cap + currency), allow_list (field-in-set), rate_limit (max per minute/hour/day, counted from the ledger).

Build on delego

Three ways to use it, lowest friction first:

• As an MCP server — delego init, add the delego-mcp server to your MCP config, and your agent proposes actions instead of executing them. No code.
• As a library — pip install delego, write a policy + a BrokerAdapter, and call fw.propose(...) in your tool-call path.
• Behind a service — wrap the Firewall in an HTTP API so many agents share one decision point and one audit chain.

The one extension point is the broker — where your credential lives and the authorised action actually runs. delego never holds the secret:

• NullBroker (default) — simulates execution; for demos and tests.
• HTTPProxyBroker(gateway_url) — forwards the authorised action to an external credential gateway (OneCLI / vault / proxy) that injects the secret upstream.
• Your own — implement execute(action) -> dict against the BrokerAdapter protocol in delego/brokers.py.

▶ Delego-Dev/sample-app — a FastAPI service built on the published package, with the full propose → approve → resolve loop and a copy-paste curl walkthrough. The best starting point for building your own.

See ROADMAP.md for where delego is going and where to help.

Status

• Implemented (protocol 0.3): the policy engine, intent hashing, action fingerprinting with the URL query folded into the fingerprint (spec §4.2 — /orders?to=me and /orders?to=attacker are different actions), the confused-deputy guard, intent-bound + single-use human approvals, the signed, hash-chained audit ledger with verification and an external head-anchor check (delego verify --expected-head), and the §9 authorization token (optional profile) — a short-lived, EdDSA-signed JWS a separated broker verifies before injecting a credential (build_firewall(..., mint_tokens=True); verify_token / require_fingerprint).
• Single-writer daemon (delego daemon): one long-running process owns the ledger, so every client routes through it and rate_limit is exact across all of them — not just one host's file lock. The CLI's approve/deny/pending auto-route to a running daemon. Optional: with no daemon, everything works file-backed as before.
• Brokers: the default NullBroker holds no credentials and makes no real request — it records what would be sent (for demos and tests). HTTPProxyBroker forwards an authorised action — and its authorization token — to an external credential gateway; or write your own against the BrokerAdapter protocol in delego/brokers.py.
• Not yet: the MCP agent surface auto-routing to the daemon (it still talks to the firewall directly — wiring it is the next step), a TCP/cross-host daemon transport (it's a local Unix socket today), and a non-MCP HTTP surface.
• Known limitations: without the daemon, concurrent writes to the file-backed ledger and approval store are serialised with an OS file lock (corruption-safe), and a rate_limit is exact only among processes sharing one home on one host. Run delego daemon for exact rate limits across all clients (one writer). The daemon serializes one action in flight at a time (a reserve-then-execute throughput optimization, and a TCP transport for other hosts, are future work). Path globbing is coarse (** and * collapse).

License

Licensed under the Apache License 2.0.