Registry / auth-security / kavachos

kavachos

JSON →
library0.1.0jsnpmunverified

Kavachos is a comprehensive authentication and authorization library designed for both human users and, uniquely, AI agents. It provides identity management, fine-grained permissions, delegation capabilities, and an immutable audit trail tailored for the 'agentic era'. The current stable version is 0.4.2, with rapid iterative releases addressing features and fixes, as seen by the frequent minor and patch updates between 0.3.0 and 0.4.2. A key differentiator is its dual focus on AI agent identity (cryptographic bearer tokens, wildcard permissions, delegation chains) alongside robust human authentication (14 methods, 27+ OAuth providers, passkeys, SSO). It also functions as a spec-compliant OAuth 2.1 authorization server for the Model Context Protocol (MCP) and is designed to be edge-compatible, running on platforms like Cloudflare Workers, Deno, Bun, and Node.js with a minimal runtime dependency footprint.

npm install kavachos
INSTALL
IMPORT
SIG · KAVACHOS
K
kavachos
auth-securityjavascriptv0.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createKavach
import { createKavach } from 'kavachos';
const createKavach = require('kavachos').createKavach;
Kavachos is primarily designed for ESM. While CJS might work with transpilers, direct 'require' is not the idiomatic approach.
emailPassword
import { emailPassword } from 'kavachos/auth';
import { emailPassword } from 'kavachos';
Authentication providers like emailPassword are exported from the 'kavachos/auth' subpath.
google
import { google } from 'kavachos/auth';
import { google } from 'kavachos/oauth';
OAuth providers were promoted to first-class named exports in v0.4.0 and are available from 'kavachos/auth' since v0.4.2.
KavachOptions
import type { KavachOptions } from 'kavachos';
TypeScript types are available and recommended for use with type imports.

This quickstart demonstrates initializing Kavachos with an SQLite database and email/password plugin, creating an AI agent with specific permissions, and then performing an authorization check for that agent.

import { createKavach } from "kavachos"; import { emailPassword } from "kavachos/auth"; async function runKavachExample() { const kavach = createKavach({ database: { provider: "sqlite", url: "kavach.db" }, plugins: [emailPassword()], }); // Ensure the database is initialized (implementation detail not in quickstart, but necessary for a runnable example) // In a real app, you'd likely have migrations or a setup script. // For this example, we'll assume the 'kavach.db' file exists or is created by the library. // Create an AI agent with scoped permissions const agent = await kavach.agent.create({ ownerId: "user-123", // This would typically be a human user's ID name: "github-reader", type: "autonomous", permissions: [ { resource: "mcp:github:*", actions: ["read"] }, { resource: "mcp:deploy:production", actions: ["execute"], constraints: { requireApproval: true } } ] }); console.log(`Created agent: ${agent.name} with ID ${agent.id}`); // Authorize and audit (< 1ms) const result = await kavach.authorize(agent.id, { action: "read", resource: "mcp:github:repos" }); console.log(`Authorization result for 'read mcp:github:repos':`, result); // Expected output: { allowed: true, auditId: "aud_..." } if permissions are correctly configured const unauthorizedResult = await kavach.authorize(agent.id, { action: "write", resource: "mcp:github:repos" }); console.log(`Authorization result for 'write mcp:github:repos':`, unauthorizedResult); // Expected output: { allowed: false, auditId: "aud_..." } } runKavachExample().catch(console.error);
Debug
Known issues
breakingUpgrading from v0.3.x to v0.4.x may require changes due to new features like agentic JWT claims and promotion of OAuth providers. Consult the migration guide for specific steps.
fix
Refer to the official 'first migration guide' mentioned in v0.4.0 release notes for details on necessary code adjustments and configuration changes.
affects: >=0.4.0
gotchaOAuth provider factories (e.g., `notion`, `google`) were missing from the top-level `kavachos/auth` barrel in v0.4.0 and v0.4.1, preventing direct import from that path.
fix
Ensure you are on v0.4.2 or higher to directly import OAuth providers from `kavachos/auth`. If stuck on older versions, you might need to import from a deeper path or temporarily use a different approach until upgrading.
affects: >=0.4.0 <0.4.2
gotchaKavachos uses peer dependencies for database drivers. You must install the appropriate driver (e.g., `@libsql/client`, `better-sqlite3`, `pg`, `mysql2`, `sql.js`) for your chosen database provider.
fix
Install the correct database client package based on your `database.provider` configuration, e.g., `npm install better-sqlite3` for SQLite.
affects: >=0.0.1
gotchaKavachos is designed with ESM in mind. While CommonJS compatibility might be achieved through transpilation, direct `require()` calls may lead to unexpected behavior or syntax errors.
fix
Configure your project to use ES Modules (e.g., `"type": "module"` in `package.json`) and use `import` statements. If pure CJS is required, investigate specific bundler configurations or alternative versions/wrappers if available.
affects: >=0.0.1
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'create') at Object.<anonymous> (file:///path/to/your/script.js:X:Y)
The `kavach` object was not correctly initialized or `createKavach` failed due to missing database configuration or a database driver.
fix
Ensure `createKavach` is called with valid `database` options and that the corresponding database peer dependency (e.g., `better-sqlite3` for `sqlite`) is installed.
ESM_IMPORT_SOURCE_EMPTY: Import source 'kavachos/auth' has no exports for named import 'notion'.
Attempting to import an OAuth provider (like `notion`) from `kavachos/auth` on `kavachos` versions prior to 0.4.2 where the barrel export was missing.
fix
Upgrade `kavachos` to version 0.4.2 or higher. If upgrading is not immediately possible, consult the release notes for 0.4.0 to see if an alternative import path for providers was available temporarily.
SyntaxError: Named export 'createKavach' not found. The requested module 'kavachos' is a CommonJS module, which may not support all module.exports as named exports.
Attempting to use ES module `import` syntax in a CommonJS environment, or trying to `require` a named export directly from an ESM-first package.
fix
Ensure your project is configured for ES Modules (add `"type": "module"` to `package.json`) or use dynamic `import()` for CJS environments, or `require()` the entire module and access properties: `const kavachos = require('kavachos'); const createKavach = kavachos.createKavach;`.
Upgrade
Version history
0.1.0latest on npm
Audit
Dependencies
@libsql/clientoptionalPeer dependency for LibSQL database integration.
better-sqlite3optionalPeer dependency for Better SQLite3 database integration.
mysql2optionalPeer dependency for MySQL database integration.
pgoptionalPeer dependency for PostgreSQL database integration.
sql.jsoptionalPeer dependency for SQL.js database integration (browser/WebAssembly).
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
kavachos — npm install kavachos · libregistry