Kanoniv Auth

Kanoniv Auth replaces API keys with cryptographic delegation tokens. Three functions make up the entire API: delegate() issues scoped, time-bounded authority. verify() checks it offline. sign() proves what happened. Everything else - Claude Code skills, MCP proxies, CI/CD actions, git hooks - is built on these three primitives.

Ed25519 keypairs generate did:agent: identifiers on the spot. No registry, no server. Delegation tokens use macaroon-style attenuation - caveats can only narrow authority, never widen it. Verification walks the full chain offline, checking every signature and every caveat. Nothing phones home.

The Core API

Python

from kanoniv_auth import delegate, verify, sign

# Issue scoped authority
token = delegate(scopes=["deploy.staging", "test.run"], ttl="4h", name="ci-agent")

# Check authorization (offline - no server calls)
verify(action="deploy.staging", token=token)  # ok
verify(action="deploy.prod", token=token)     # raises ScopeViolation

# Prove what happened
envelope = sign(action="deploy.staging", token=token, target="app-v2.3.1")

Rust

use kanoniv_agent_auth::{AgentKeyPair, Delegation, Caveat, Invocation, verify_invocation};

let root = AgentKeyPair::generate();
let agent = AgentKeyPair::generate();

let delegation = Delegation::create_root(&root, &agent.identity().did, vec![
    Caveat::ActionScope(vec!["deploy.staging".into()]),
    Caveat::ExpiresAt("2026-04-01T00:00:00Z".into()),
]).unwrap();

let invocation = Invocation::create(
    &agent, "deploy.staging", serde_json::json!({"target": "app-v2"}), delegation
).unwrap();

verify_invocation(&invocation, &agent.identity(), &root.identity()).unwrap();

TypeScript

import { generateKeyPair, createRootDelegation, createInvocation, verifyInvocation } from "@kanoniv/agent-auth";

const root = generateKeyPair();
const agent = generateKeyPair();

const delegation = createRootDelegation(root, agent.identity.did, [
  { type: "action_scope", value: ["deploy.staging"] },
  { type: "expires_at", value: "2026-04-01T00:00:00Z" },
]);

const invocation = createInvocation(agent, "deploy.staging", { target: "app-v2" }, delegation);
verifyInvocation(invocation, agent.identity, root.identity);

Three functions. The rest of this page covers the seven surfaces where those functions run.

Seven Integration Surfaces

The same delegation tokens work across every surface. Pick the integration points that match your stack.

Surface	What it does	Install
Python SDK	Core library. delegate, verify, sign.	pip install kanoniv-auth
Rust Crate	Native performance. Same API.	cargo add kanoniv-agent-auth
TypeScript SDK	Browser and Node.js.	npm install @kanoniv/agent-auth
Claude Code Skills	5 skills with PreToolUse enforcement.	kanoniv-auth install-skill
wrap-mcp	Auth proxy for any MCP server.	kanoniv-auth wrap-mcp --mode strict -- <cmd>
GitHub Action	CI/CD delegation with OIDC support.	uses: kanoniv/auth-action@v1
Git Hook	Pre-push scope enforcement.	kanoniv-auth install-hook

Claude Code Skills

Five slash commands give Claude Code agents scoped, time-bounded authority with full audit logging.

Skill	Purpose
/delegate	Issue a delegation token with scopes and TTL
/scope	Show current active scopes
/ttl	Show time remaining on the active delegation
/status	Check delegation status, agent identity, and active constraints
/audit	View the local audit trail

How enforcement works. PreToolUse hooks intercept every tool call (Bash, Edit, Write) before execution. The hook maps the operation to a scope string, then verifies the active delegation token against that scope. If the scope is not granted, the tool call is blocked. PostToolUse hooks log every action - allowed or denied - to ~/.kanoniv/audit.log.

Example:

/delegate --scope code.edit,test.run --ttl 2h --name my-agent

Scope mapping:

Operation	Scope
git push origin main	git.push.{repo}.main
git commit	git.commit.{repo}
File edits	code.edit
Test runs	test.run
File reads	Always allowed

INFO

File reads are always allowed regardless of delegation scope. Reads do not mutate state.

wrap-mcp

wrap-mcp sits between Claude Code and any MCP server. It intercepts JSON-RPC tool calls and verifies delegation tokens before forwarding them to the downstream server.

kanoniv-auth wrap-mcp --mode strict --root-key ~/.kanoniv/root.key -- npx my-mcp-server

Three modes control enforcement behavior:

Mode	Behavior
strict	No valid token = reject with JSON-RPC error
warn	No valid token = log warning, forward anyway
audit	Log everything, verify nothing

Verification priority:

1. _proof field in tool arguments - cryptographic MCP proof embedded in the call
2. Session token file at ~/.kanoniv/session-token - set by /delegate or kanoniv-auth delegate
3. Reject, warn, or pass through based on mode

WARNING

In strict mode, every tool call without a valid proof or session token returns a JSON-RPC error. Make sure the agent has an active delegation before starting work.

GitHub Action

Add delegation and audit to any CI/CD pipeline.

- uses: kanoniv/auth-action@v1
  with:
    oidc: true
    api_key: ${{ secrets.KANONIV_API_KEY }}
    scopes: deploy.staging,test.run
    ttl: 4h
    post_audit: true

Inputs:

Input	Required	Default	Description
oidc	No	false	Use GitHub OIDC for identity instead of a static key
api_key	Yes	-	Kanoniv Auth API key
scopes	Yes	-	Comma-separated scope list
ttl	No	1h	Delegation time-to-live
post_audit	No	false	Upload audit log as job artifact on completion

Outputs:

Output	Description
token	The delegation token (use in subsequent steps)
did	The agent DID for this workflow run
expires_at	RFC 3339 expiry timestamp

Delegation Model

Authority flows through signed delegation chains. Each delegation is a cryptographic statement: "I (issuer) authorize you (delegate) to perform actions X, subject to constraints Y." Constraints are called caveats. Caveats can only narrow authority, never widen it.

Any token holder can sub-delegate to another agent, adding further restrictions. The chain forms a directed path from root authority to leaf agent. Verification walks the entire chain, checking every signature and every caveat at each step. Chain depth is capped at 32.

Six caveat types:

Caveat	Purpose	Example
ActionScope	Restrict to specific actions	["resolve", "search"]
ExpiresAt	Token expiry (RFC 3339)	"2026-04-01T00:00:00Z"
MaxCost	Spend limit per invocation	5.0
Resource	Glob pattern on target resource	"entity:customer:*"
Context	Key-value match on invocation context	{"key": "environment", "value": "staging"}
Custom	Arbitrary key-value constraint	{"key": "department", "value": "sales"}

Caveats accumulate through the chain. If the root grants ActionScope: [resolve, search, merge] and a middle agent adds ActionScope: [resolve], the leaf can only resolve. The intersection of all caveats at each depth determines the effective authority.

INFO

See the Delegation Quickstart for complete runnable examples of chains, sub-delegation, and caveat enforcement in all three languages.

Observatory

The hosted control plane at auth.kanoniv.com. Five capabilities:

• Agent Registry - Agents with did:agent: identifiers, capabilities, status (online/idle/offline), and reputation scores. Register via SDK, CLI, or the UI.
• Delegation Management - Grant, revoke, and modify scoped delegations. View active chains with full caveat details and expiry.
• Provenance Trail - Chronological timeline of every action. Each entry shows agent name, action type, entity IDs, metadata, and ALLOWED/BLOCKED status.
• Reputation Scoring - Deterministic scores from 0 to 100, recomputed after every provenance entry and feedback submission.
• Enforcement Engine - Scope + caveat checking on every action recorded through the Observatory API. Blocked actions are still logged with reason codes.

Reputation signals:

Signal	Weight	Calculation
Activity	30%	log2(total_actions + 1) * 15, capped at 100
Success Rate	25%	successes / (successes + failures) * 100
Reward Signal	20%	Average feedback score (-1 to 1), normalized to 0-100
Tenure	15%	days_registered / 90 * 100, capped at 100
Action Diversity	10%	distinct_action_types / 7 * 100

WARNING

Reputation scores below 20 trigger a warning in the dashboard. This does not block actions automatically, but operators can configure delegation policies that require minimum reputation thresholds.

Plans:

Plan	Agents	Actions/month	Delegations
Free	3	100	5
Team	25	10,000	100
Enterprise	Unlimited	Unlimited	Unlimited

CLI Reference

The kanoniv-auth command provides access to all operations from the terminal.

Command	Purpose
kanoniv-auth init	Generate root keypair and write to ~/.kanoniv/
kanoniv-auth delegate --scopes X --ttl 4h	Issue a delegation token
kanoniv-auth verify --scope X --token T	Check authorization offline
kanoniv-auth sign --action X --token T	Sign an execution proof
kanoniv-auth exec --scope X -- cmd	Verify scope, execute command, sign result
kanoniv-auth status	Show active delegation, scopes, and TTL
kanoniv-auth audit	View local audit trail
kanoniv-auth wrap-mcp --mode M -- cmd	Run MCP auth proxy
kanoniv-auth install-skill	Install Claude Code skills
kanoniv-auth install-hook	Install git pre-push hook
kanoniv-auth serve	Run the delegation service

INFO

kanoniv-auth exec combines verify + execute + sign in one step. If verification fails, the command never runs. If it succeeds, the output is signed automatically.

Packages

Package	Registry	Version	Language
kanoniv-auth	PyPI	0.4.0	Python
kanoniv-agent-auth	crates.io	0.3.1	Rust
@kanoniv/agent-auth	npm	latest	TypeScript
kanoniv/auth-action	GitHub	v1	YAML

All three language implementations produce byte-identical DIDs, signatures, and content hashes for the same inputs. A delegation issued in Python can be verified in Rust or TypeScript.

Next Steps

• Agent Identity - Keypair generation, DIDs, message signing
• Delegation Quickstart - Chains, caveats, sub-delegation with runnable code
• MCP Server Auth - Proof-based authentication for MCP tool calls
• Audit Trail - Provenance entries and entity lifecycle events
• Memory - Persistent, entity-linked agent knowledge
• Getting Started - Installation and first resolution