kanoniv-auth

Sudo for AI agents. Cryptographic delegation tokens that scope-confine what AI agents can do. Ed25519 signatures. Hierarchical scopes. Full audit trail.

pip install kanoniv-auth

Three surfaces, one cryptographic core

1. wrap-mcp — Access control for any MCP server

One line. No code changes to the server. No SDK. Just a proxy.

# Before: any agent calls anything
npx my-mcp-server

# After: only delegated agents, only authorized tools
kanoniv-auth wrap-mcp --mode strict -- npx my-mcp-server

The proxy sits between Claude Code and the MCP server. On every tools/call:

• Reads the delegation token from ~/.kanoniv/session-token
• Checks that the token grants scope for the tool being called
• VERIFIED → forwards the call to the server
• DENIED → returns a JSON-RPC error. The server never sees the call.

$ resolve({name: "John"})     → VERIFIED (token has "resolve" scope) → forwarded
$ merge({entity_id: "123"})   → DENIED (token missing "merge" scope) → blocked

Tool name = required scope. No regex. No string parsing. Enforcement at the resource.

Modes:

• --mode strict — no valid token = reject (production)
• --mode warn — no valid token = log warning, forward anyway (rollout)
• --mode audit — log everything, verify nothing (observability)

2. Claude Code skills — Interactive sudo

/delegate  → choose scopes → every tool call verified → /audit
/scope     → change scopes mid-session (no restart)
/ttl       → extend session time
/status    → check delegation status
/audit     → view the audit trail

Install the skills:

kanoniv-auth install-skill

Then in Claude Code:

You:    /delegate
Claude: What scopes? → Read-only + test
Claude: Delegation active. Scopes: code.read, test.run

You:    Edit src/auth.rs
Claude: ✗ SCOPE DENIED: file editing requires code.edit scope

You:    /scope code.edit,test.run
Claude: Scopes updated.

You:    Edit src/auth.rs
Claude: ✓ (allowed)

3. GitHub Action — CI/CD pipelines

- uses: kanoniv/auth-action@v1
  with:
    root_key: ${{ secrets.KANONIV_ROOT_KEY }}
    scopes: deploy.staging
    ttl: 4h

Agent gets KANONIV_TOKEN. Can deploy to staging, cannot touch prod — cryptographically impossible.

How it works

Root Key (Ed25519)
  → signs Delegation Token
      → scopes: [resolve, search]
      → expires: 4h
      → agent: did:agent:43d8...

wrap-mcp proxy (every tools/call):
  → read token from ~/.kanoniv/session-token
  → tool "resolve" in scopes? → VERIFIED → forward
  → tool "merge" not in scopes? → DENIED → JSON-RPC error

Scopes are hierarchical: resolve grants resolve.entity, resolve.bulk, etc. Scopes can only narrow through delegation chains — never widen.

Quick start

# Install
pip install kanoniv-auth

# Generate a root key
kanoniv-auth init

# Issue a delegation token
kanoniv-auth delegate --scopes resolve,search --ttl 4h --name my-agent

# Wrap an MCP server
kanoniv-auth wrap-mcp --mode strict -- npx my-mcp-server

# Install Claude Code skills
kanoniv-auth install-skill

CLI reference

kanoniv-auth init                    Generate root key pair
kanoniv-auth delegate                Issue a delegation token
kanoniv-auth verify                  Verify a token against a scope
kanoniv-auth sign                    Sign an execution envelope
kanoniv-auth exec                    Verify → execute → sign (the sudo experience)
kanoniv-auth status                  Check token status
kanoniv-auth whoami                  Show identity behind a token
kanoniv-auth audit-log               View local audit log
kanoniv-auth tokens                  List saved tokens
kanoniv-auth revoke                  Revoke a token
kanoniv-auth agents list             List registered agents
kanoniv-auth agents show <name>      Show agent details
kanoniv-auth agents remove <name>    Remove an agent
kanoniv-auth install-skill           Install Claude Code skills
kanoniv-auth install-hook            Install git pre-push hook
kanoniv-auth wrap-mcp                Wrap MCP server with access control

Links

• auth-action — GitHub Action + Claude Code skill pack
• agent-auth — Full library (Rust + Python + TypeScript)
• kanoniv.com — Shared identity layer for AI agents

License

MIT