Building Kavachos: Auth for AI Agents and Humans

The Problem Nobody Was Talking About

When I started building AI-powered apps in earnest, I kept hitting the same wall. I needed to authenticate users -- that part was solved. But I also needed my AI agents to authenticate against external APIs, delegate permissions to sub-agents, and leave an audit trail for every action taken on a user's behalf.

Every auth library I tried was built for humans logging into apps. That mental model breaks down fast when your "user" is an autonomous agent running a multi-step workflow at 3am.

The question nobody was asking loudly enough: who authenticates the agent?

Why Existing Solutions Fall Short

Auth0, Clerk, and NextAuth are all excellent for what they do. I have used all of them, and I have no complaints about their core human-facing flows. The problem is architectural -- they were designed around a session-per-human model.

Agent-to-agent delegation is a completely different shape. Imagine a user grants your app permission to manage their calendar. Your app spins up a scheduling agent, which in turn calls a contact-enrichment agent, which calls a third-party CRM API. Each hop in that chain needs scoped, auditable credentials. The original user's OAuth token cannot just be passed around -- that is a security disaster waiting to happen.

Existing solutions do not model delegation chains. They do not issue scoped tokens for sub-agents. They do not track which agent in a chain performed which action. I could bolt all of this on top of an existing library, but I would be fighting the abstractions the whole way.

So I built Kavachos instead.

What Kavachos Does

Kavachos is an auth system built for the AI-native era. It handles the human-facing stuff you expect -- OAuth with 27+ providers, SAML, OIDC -- but it also ships a first-class MCP 2.1 auth server for agent authentication.

The core features:

• OAuth 27+ providers -- GitHub, Google, Linear, Notion, Slack, and many more, all with consistent token handling
• SAML/OIDC -- enterprise SSO support out of the box
• MCP 2.1 auth server -- issue and verify tokens for Model Context Protocol agents
• Scoped permissions -- define granular permission sets and issue tokens that only cover what a given agent actually needs
• Delegation chains -- track how credentials flow from user to agent to sub-agent, with a full chain-of-custody record
• Audit trails -- every authentication event, token issuance, and permission check is logged with enough context to reconstruct what happened

The delegation chain model is what I am most proud of. When a user grants your app a permission, Kavachos issues a root credential. When your app delegates to an agent, it issues a derived credential scoped to a subset of that permission. Derived credentials cannot exceed the scope of their parent -- that constraint is enforced cryptographically, not just by convention.

import { kavachos } from "kavachos";
 
const auth = kavachos({
  providers: ["github", "google", "slack"],
  mcp: {
    enabled: true,
    version: "2.1",
  },
});
 
// Issue a delegated token for an agent
const agentToken = await auth.delegate({
  parentToken: userCredential,
  scopes: ["calendar:read", "contacts:read"],
  subject: "scheduling-agent",
  expiresIn: "1h",
});

The agent gets a token with exactly the permissions it needs for exactly as long as it needs them. No more, no less.

Edge Runtime Support

One constraint I had from the start: Kavachos had to work everywhere. Cloudflare Workers, Deno Deploy, Bun -- not just Node.js.

This meant no native Node.js dependencies in the core library. Every crypto operation uses the Web Crypto API. JWTs are handled by Jose, which is runtime-agnostic. Validation uses Zod, which runs anywhere JavaScript runs.

The result is a library that deploys to the edge without polyfills or workarounds. Your auth logic runs close to your users, not in a single region.

The npm Ecosystem

Kavachos ships as a suite of packages so you only pull in what you need:

• kavachos -- the core library, runtime-agnostic
• @kavachos/react -- hooks and context providers for React apps
• @kavachos/nextjs -- Next.js App Router integration with middleware support
• @kavachos/client -- lightweight client for browser environments

The Next.js package is where most people start. It wires up route protection, session management, and the OAuth callback handlers with minimal configuration.

// app/api/auth/[...kavachos]/route.ts
import { KavaachosHandler } from "@kavachos/nextjs";
import { auth } from "@/lib/auth";
 
export const { GET, POST } = KavaachosHandler(auth);

Full docs live at docs.kavachos.com.

Architecture Decisions

A few choices I want to explain because they were deliberate.

Drizzle ORM for the database layer. I looked at Prisma and Kysely seriously. Drizzle won because it generates SQL you can actually read, has a small runtime footprint, and works without a query engine binary -- which matters a lot for edge deployments.

Jose for JWTs. The jsonwebtoken package is Node.js only. Jose implements the same JOSE standards (JWS, JWE, JWK, JWT) using the Web Crypto API. It is well-maintained and has no peer dependencies.

Zod for validation. Every token, every provider config, every delegation request is validated with Zod schemas. I considered io-ts and Valibot, but Zod's error messages and ecosystem maturity made it the obvious call.

The MCP auth server implements the 2.1 spec, which introduced proper client authentication and improved token introspection. If you are building tools that plug into Claude, GPT, or any other MCP-compatible host, Kavachos handles the auth handshake for you.

What Is Next

The open source packages are stable and in active use. The next milestone is Kavachos Cloud -- a managed SaaS at app.kavachos.com that handles the infrastructure so you do not have to.

With Kavachos Cloud, you get a hosted auth server, a dashboard for managing providers and permissions, real-time audit log streaming, and usage analytics. No self-hosting required.

I am also expanding the provider list, improving the MCP tooling as the spec continues to evolve, and adding a policy engine for more expressive permission rules.

If you are building anything in the AI agent space and hitting the same auth walls I was, check out kavachos.com or open an issue on GitHub. This is a problem worth solving properly, and I would rather solve it with the community than alone.