{"id":16837,"library":"kavachos","title":"Kavachos: Agent and Human Authentication OS","description":"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.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/kavachos/kavachos","tags":["javascript","auth","agent","mcp","ai","identity","authentication","authorization","oauth","typescript"],"install":[{"cmd":"npm install kavachos","lang":"bash","label":"npm"},{"cmd":"yarn add kavachos","lang":"bash","label":"yarn"},{"cmd":"pnpm add kavachos","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for LibSQL database integration.","package":"@libsql/client","optional":true},{"reason":"Peer dependency for Better SQLite3 database integration.","package":"better-sqlite3","optional":true},{"reason":"Peer dependency for MySQL database integration.","package":"mysql2","optional":true},{"reason":"Peer dependency for PostgreSQL database integration.","package":"pg","optional":true},{"reason":"Peer dependency for SQL.js database integration (browser/WebAssembly).","package":"sql.js","optional":true}],"imports":[{"note":"Kavachos is primarily designed for ESM. While CJS might work with transpilers, direct 'require' is not the idiomatic approach.","wrong":"const createKavach = require('kavachos').createKavach;","symbol":"createKavach","correct":"import { createKavach } from 'kavachos';"},{"note":"Authentication providers like emailPassword are exported from the 'kavachos/auth' subpath.","wrong":"import { emailPassword } from 'kavachos';","symbol":"emailPassword","correct":"import { emailPassword } from 'kavachos/auth';"},{"note":"OAuth providers were promoted to first-class named exports in v0.4.0 and are available from 'kavachos/auth' since v0.4.2.","wrong":"import { google } from 'kavachos/oauth';","symbol":"google","correct":"import { google } from 'kavachos/auth';"},{"note":"TypeScript types are available and recommended for use with type imports.","symbol":"KavachOptions","correct":"import type { KavachOptions } from 'kavachos';"}],"quickstart":{"code":"import { createKavach } from \"kavachos\";\nimport { emailPassword } from \"kavachos/auth\";\n\nasync function runKavachExample() {\n  const kavach = createKavach({\n    database: { provider: \"sqlite\", url: \"kavach.db\" },\n    plugins: [emailPassword()],\n  });\n\n  // Ensure the database is initialized (implementation detail not in quickstart, but necessary for a runnable example)\n  // In a real app, you'd likely have migrations or a setup script.\n  // For this example, we'll assume the 'kavach.db' file exists or is created by the library.\n\n  // Create an AI agent with scoped permissions\n  const agent = await kavach.agent.create({\n    ownerId: \"user-123\", // This would typically be a human user's ID\n    name: \"github-reader\",\n    type: \"autonomous\",\n    permissions: [\n      { resource: \"mcp:github:*\", actions: [\"read\"] },\n      { resource: \"mcp:deploy:production\", actions: [\"execute\"],\n        constraints: { requireApproval: true } }\n    ]\n  });\n\n  console.log(`Created agent: ${agent.name} with ID ${agent.id}`);\n\n  // Authorize and audit (< 1ms)\n  const result = await kavach.authorize(agent.id, {\n    action: \"read\",\n    resource: \"mcp:github:repos\"\n  });\n\n  console.log(`Authorization result for 'read mcp:github:repos':`, result);\n  // Expected output: { allowed: true, auditId: \"aud_...\" } if permissions are correctly configured\n\n  const unauthorizedResult = await kavach.authorize(agent.id, {\n    action: \"write\",\n    resource: \"mcp:github:repos\"\n  });\n  console.log(`Authorization result for 'write mcp:github:repos':`, unauthorizedResult);\n  // Expected output: { allowed: false, auditId: \"aud_...\" }\n}\n\nrunKavachExample().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the official 'first migration guide' mentioned in v0.4.0 release notes for details on necessary code adjustments and configuration changes.","message":"Upgrading 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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"OAuth 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.","severity":"gotcha","affected_versions":">=0.4.0 <0.4.2"},{"fix":"Install the correct database client package based on your `database.provider` configuration, e.g., `npm install better-sqlite3` for SQLite.","message":"Kavachos 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"Kavachos 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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `createKavach` is called with valid `database` options and that the corresponding database peer dependency (e.g., `better-sqlite3` for `sqlite`) is installed.","cause":"The `kavach` object was not correctly initialized or `createKavach` failed due to missing database configuration or a database driver.","error":"TypeError: Cannot read properties of undefined (reading 'create') at Object.<anonymous> (file:///path/to/your/script.js:X:Y)"},{"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.","cause":"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.","error":"ESM_IMPORT_SOURCE_EMPTY: Import source 'kavachos/auth' has no exports for named import 'notion'."},{"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;`.","cause":"Attempting to use ES module `import` syntax in a CommonJS environment, or trying to `require` a named export directly from an ESM-first package.","error":"SyntaxError: Named export 'createKavach' not found. The requested module 'kavachos' is a CommonJS module, which may not support all module.exports as named exports."}],"ecosystem":"npm","meta_description":null}