Name: KavachOS
Author: KavachOS

kavachExpress(kavach, options?) returns an Express Router with all KavachOS routes pre-mounted. Use app.use to attach it at your chosen path.

Install

pnpm add kavachos @kavachos/express express
pnpm add -D @types/express

Setup

Create the kavach instance

// lib/kavach.ts
import { createKavach, createMcpModule } from 'kavachos';

export const kavach = createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.env.AUTH_BASE_URL!,
  mcp: {
    issuer: process.env.AUTH_BASE_URL!,
    audience: process.env.MCP_BASE_URL!,
  },
});

export const mcp = createMcpModule(kavach);

Mount the adapter

// src/index.ts
import express from 'express';
import { kavachExpress } from '@kavachos/express';
import { kavach, mcp } from './lib/kavach.js';

const app = express();

// Required: parse JSON and URL-encoded bodies before the adapter
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Mount all KavachOS routes
app.use('/api/kavach', kavachExpress(kavach, { mcp }));

app.listen(3000);

Call express.json() and express.urlencoded() before mounting the adapter. The adapter reads req.body which requires those parsers to be in place.

MCP endpoints

Pass mcp to enable the MCP OAuth 2.1 authorization server. All MCP endpoints are registered on the same router alongside the REST API:

app.use('/api/kavach', kavachExpress(kavach, { mcp }));
// registers:
// GET  /api/kavach/.well-known/oauth-authorization-server
// GET  /api/kavach/.well-known/oauth-protected-resource
// POST /api/kavach/mcp/register
// GET  /api/kavach/mcp/authorize
// POST /api/kavach/mcp/token

Endpoint reference

Method	Path	Description
`POST`	`/agents`	Create an agent
`GET`	`/agents`	List agents
`GET`	`/agents/:id`	Get an agent
`PATCH`	`/agents/:id`	Update an agent
`DELETE`	`/agents/:id`	Revoke an agent
`POST`	`/agents/:id/rotate`	Rotate token
`POST`	`/authorize`	Authorize by agent ID
`POST`	`/authorize/token`	Authorize by bearer token
`POST`	`/delegations`	Create delegation
`GET`	`/delegations/:agentId`	List delegation chains
`DELETE`	`/delegations/:id`	Revoke delegation
`GET`	`/audit`	Query audit logs
`GET`	`/audit/export`	Export audit logs

Full example

import express from 'express';
import { createKavach, createMcpModule } from 'kavachos';
import { kavachExpress } from '@kavachos/express';

const kavach = createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.env.AUTH_BASE_URL!,
  mcp: {
    issuer: process.env.AUTH_BASE_URL!,
    audience: process.env.MCP_BASE_URL!,
  },
});

const mcp = createMcpModule(kavach);

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.use('/api/kavach', kavachExpress(kavach, { mcp }));

app.get('/health', (_req, res) => res.json({ ok: true }));

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Express