# 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.

```bash
# 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:

```bash
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

```yaml
- 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

```bash
# 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](https://github.com/kanoniv/auth-action) — GitHub Action + Claude Code skill pack
- [agent-auth](https://github.com/kanoniv/agent-auth) — Full library (Rust + Python + TypeScript)
- [kanoniv.com](https://kanoniv.com) — Shared identity layer for AI agents

## License

MIT
