Name: KavachOS
Author: KavachOS

Setup

import { createKavach } from 'kavachos';

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  apiKeys: { 
    prefix: 'kos_',          // default
    defaultExpiryDays: 90,   // default: 365
  }, 
});

Creating a key

const { key, apiKey } = await kavach.apiKeys.create({
  userId: 'user_abc',
  name: 'CI deploy token',
  permissions: ['agents:read', 'agents:create'], 
  expiresAt: new Date('2026-01-01'),  // optional, falls back to defaultExpiryDays
});

// key = 'kos_a3f8c2e1...' — the full secret, returned once only
// apiKey.id, apiKey.prefix, apiKey.permissions, apiKey.expiresAt

The full key is never stored. Show it to the user immediately after creation — it cannot be recovered later. Only a SHA-256 hash is kept in the database.

Validating a key

const result = await kavach.apiKeys.validate('kos_a3f8c2e1...');
if (result) {
  // result.userId, result.permissions, result.keyId
}

Validation updates lastUsedAt asynchronously without blocking the response.

Listing and revoking

// All keys for a user (no secrets exposed)
const keys = await kavach.apiKeys.list('user_abc');

// Revoke by key ID
await kavach.apiKeys.revoke('key_...');

Rotating a key

Rotation revokes the existing key and creates a new one with the same name and permissions:

const { key, apiKey } = await kavach.apiKeys.rotate('key_...');
// key = new full secret — store it now

Endpoints

Method	Path	Description
POST	`/auth/api-keys`	Create API key
GET	`/auth/api-keys/:userId`	List keys for user
DELETE	`/auth/api-keys/:keyId`	Revoke key
POST	`/auth/api-keys/:keyId/rotate`	Rotate key

API keys