latchkey

Capability-token gate for AI agents. Mint time-boxed, scope-limited grants ("latchkeys") that authorize specific tool calls. Agents present a key; the gate verifies TTL, scopes, audience, and spend limits before allowing the call.

Full MCP surface for mint / revoke / introspect / authorize — plus CLI and a hash-chained audit log.

Why

Agent tool access is often all-or-nothing. Latchkey lets you hand an agent a narrow, expiring, use-capped credential instead of ambient authority — including delegation chains (A mints a tighter key for B) and an emergency kill-switch.

Features

• HMAC-signed tokens (lk1.…) via LATCHKEY_SECRET — no external KMS required
• Scopes: tool:http_request, tool:file_write:path=/tmp/**, risk:irreversible
• Use-once keys (maxUses: 1) and spend limits
• Delegation with narrow-only MintPolicy
• Revocation list + revoke-all kill-switch
• Hash-chained audit log + Mermaid grant-graph export
• MCP tools + CLI

Packages

Package	Role
@latchkey/core	LatchKey, KeyStore, MintPolicy, Authorizer, RevocationList, AuditLog
@latchkey/mcp-server	Stdio MCP server
@latchkey/cli	latchkey CLI

Quick start

git clone https://github.com/SanjoyDat1/latchkey.git
cd latchkey
npm install
cp .env.example .env   # set LATCHKEY_SECRET
export LATCHKEY_SECRET="$(openssl rand -hex 32)"
npm run build
npm test
npm run typecheck

CLI

export LATCHKEY_SECRET="$(openssl rand -hex 32)"

npx latchkey mint \
  --audience coding-agent \
  --scope 'tool:file_write:path=/tmp/**' \
  --scope 'tool:http_request' \
  --ttl-ms 3600000 \
  --max-uses 20

npx latchkey authorize --token "$TOKEN" --tool file_write --param path=/tmp/out.txt --audience coding-agent
npx latchkey export --format mermaid
npx latchkey revoke --all   # emergency kill-switch

Use LATCHKEY_STORE_PATH so mint/authorize share state across CLI processes.

Cursor MCP config

Add to your Cursor MCP settings (stdio; logs go to stderr only):

{
  "mcpServers": {
    "latchkey": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/latchkey/packages/mcp-server/dist/index.js"],
      "env": {
        "LATCHKEY_SECRET": "replace-with-long-random-secret-32chars-min",
        "LATCHKEY_ADMIN_TOKEN": "replace-with-admin-token-16chars-min",
        "LATCHKEY_STORE_PATH": "/ABSOLUTE/PATH/TO/latchkey/.latchkey/store.json",
        "LATCHKEY_AUDIT_PATH": "/ABSOLUTE/PATH/TO/latchkey/.latchkey/audit.json"
      }
    }
  }
}

Admin tools (lk_mint, lk_revoke, lk_list_active, lk_audit_query, lk_export) require adminToken matching LATCHKEY_ADMIN_TOKEN. lk_authorize / lk_introspect only need a latchkey token (authorize also requires audience).

MCP tools

Tool	Purpose
lk_mint	Mint a latchkey (optional parentToken for delegation)
lk_revoke	Revoke by id/token, or all kill-switch
lk_introspect	Status without consuming a use
lk_authorize	Gate a tool call (consumes a use on allow)
lk_list_active	List live keys
lk_audit_query	Query hash-chained audit events
lk_export	Mermaid grant graph or JSON snapshot

Token format

lk1.<base64url(payload)>.<base64url(hmac_sha256)>

Signed with HMAC-SHA256(LATCHKEY_SECRET, "lk1." + payload). Verification uses constant-time comparison.

Secret: set LATCHKEY_SECRET (min 32 characters). Set LATCHKEY_ADMIN_TOKEN for MCP admin tools. Never commit secrets. Rotate by minting new keys and revoking old ones.

Architecture

See docs/ARCHITECTURE.md and docs/PLAN.md.

flowchart LR
  Host[Agent Host] -->|MCP| Server[latchkey-mcp]
  Server --> Core[Authorizer / MintPolicy]
  Core --> Store[KeyStore]
  Core --> Rev[RevocationList]
  Core --> Audit[AuditLog]

License

MIT