Introduction
KavachOS is an auth OS for AI agents. It handles identity, permissions, delegation, and audit for agentic systems.
What is KavachOS
KavachOS gives every AI agent a cryptographic identity, enforces least-privilege access control, and maintains an immutable record of everything it does. It ships as a TypeScript SDK (kavachos) with zero framework dependencies in the core, plus drop-in adapters for seven frameworks.
The central primitive is AgentIdentity, not a user session. Agents are first-class entities with their own tokens, permission sets, and audit trails. Human users own agents, but the auth model is built around agents from the ground up.
KavachOS does not replace your human auth provider. It runs alongside Clerk, Auth.js, better-auth, or whatever you already use. You bring the user ID from your existing auth system, and KavachOS handles everything that happens from there.
Why agent auth matters
Most MCP servers running today have no authentication at all. A tool that can write files, run shell commands, or push to GitHub is often wide open to any caller that knows the endpoint URL. As agentic systems become more capable, this is no longer acceptable.
KavachOS addresses three concrete problems:
Identity. An agent has no cryptographic identity it can present to a downstream service. There is no way to say "this action was taken by agent X, owned by user Y, acting under delegation Z."
Least privilege. Granting an agent broad access to get a task done, then hoping it stays in bounds, is not a security model. Permissions need to be declared, scoped, and enforced at call time.
Accountability. If an agent causes an incident, you need a tamper-evident record of what it did and why it was allowed to do it. Console logs are not enough.
Core features
Agent identity. Every agent gets a bearer token (kv_...) backed by a SHA-256 hash in the database. Rotation is atomic and instant — the old token is invalid the moment you rotate.
Permission engine. Resource-based access control with colon-separated hierarchies and wildcard matching. Permissions carry optional constraints: rate limits, time windows, IP allowlists, and human-in-the-loop approval gates.
Delegation chains. An orchestrator agent can delegate a strict subset of its permissions to a sub-agent, with configurable depth limits and expiry. The full chain is audited and revocable at any point.
Audit trail. Every authorization decision is written to an immutable log with a unique auditId. Export as JSON or CSV for compliance tooling.
MCP OAuth 2.1. A spec-compliant authorization server for the Model Context Protocol. Implements PKCE (S256), Protected Resource Metadata (RFC 9728), Resource Indicators (RFC 8707), and Dynamic Client Registration (RFC 7591).
Framework adapters. Drop-in middleware for Hono, Express, Next.js, Fastify, Nuxt, SvelteKit, and Astro.
Database support. SQLite for local development, Postgres or MySQL in production. All via Drizzle ORM with auto-migration.
Package structure
The core package has zero framework dependencies. It uses Web API Request/Response primitives. Adapters wrap it for their respective frameworks without touching the core logic.
Comparison with alternatives
| KavachOS | better-auth (agents plugin) | Casdoor | Auth0 Agents | Roll your own | |
|---|---|---|---|---|---|
| Agent-first data model | yes | no (humans first) | no | partial (beta) | depends |
| Wildcard permission matching | yes | no | yes | limited | depends |
| Delegation chains with depth limits | yes | no | no | no | rarely |
| MCP OAuth 2.1 compliant | yes | no | no | no | no |
| Immutable compliance-ready audit log | yes | partial | partial | yes | rarely |
| Token rotation | yes | no | yes | yes | rarely |
| TypeScript-native SDK | yes | yes | no (Go) | no (REST only) | yes |
| Framework-agnostic core | yes | yes | no | no | yes |
Casdoor is written in Go and requires a separate service. Auth0 Agents is in beta and tightly coupled to the Auth0 platform. Rolling your own means rebuilding delegation chains, wildcard permission matching, and audit integrity from scratch.
What KavachOS is not
KavachOS does not handle login flows, session cookies, OAuth social providers, or email verification. Those belong in your human auth layer. If you need all of that in one package, look at better-auth or Auth.js. KavachOS starts where those leave off: at the point where an authenticated human spins up an agent and hands it a set of capabilities.