Kavachos: Agent and Human Authentication OS

Common errors

• TypeError: Cannot read properties of undefined (reading 'create') at Object.<anonymous> (file:///path/to/your/script.js:X:Y)

  cause 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'.

  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.
  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.

  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.
  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;`.

Warnings

• breaking 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.
  Fix: Refer to the official 'first migration guide' mentioned in v0.4.0 release notes for details on necessary code adjustments and configuration changes.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Install the correct database client package based on your `database.provider` configuration, e.g., `npm install better-sqlite3` for SQLite.
• gotcha 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.
  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.

Install

• npm install kavachos npm
• yarn add kavachos yarn
• pnpm add kavachos pnpm

Imports

• createKavach
  wrong:

  const createKavach = require('kavachos').createKavach;

  correct:

  import { createKavach } from 'kavachos';

  Kavachos is primarily designed for ESM. While CJS might work with transpilers, direct 'require' is not the idiomatic approach.
• emailPassword
  wrong:

  import { emailPassword } from 'kavachos';

  correct:

  import { emailPassword } from 'kavachos/auth';

  Authentication providers like emailPassword are exported from the 'kavachos/auth' subpath.
• google
  wrong:

  import { google } from 'kavachos/oauth';

  correct:

  import { google } from 'kavachos/auth';

  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.

Quickstart

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);