> ## Documentation Index > Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Reference for every `createKavach()` option in `KavachConfig`. Covers database providers, agent settings, MCP OAuth, session config, and anomaly detection. `createKavach()` accepts a `KavachConfig` object. The only required field is `database`. Everything else is optional and enables features incrementally. ```typescript theme={"system"} import { createKavach } from 'kavachos'; const kavach = await createKavach({ database: { provider: 'sqlite', url: 'kavach.db' }, }); ``` ## Common development setup A minimal config for local development with email/password auth and no email sending: ```typescript theme={"system"} import { createKavach } from 'kavachos'; import { emailPassword } from 'kavachos/auth'; const kavach = await createKavach({ database: { provider: 'sqlite', url: './kavach.db' }, plugins: [ emailPassword({ requireVerification: false, // skip in dev onSendVerification: async (email, token) => { console.log(`Verify: http://localhost:3000/verify?token=${token}`); }, }), ], }); ``` ## Top-level options Database connection config. Required. Agent identity settings. MCP OAuth 2.1 authorization server. Human auth adapter and session config. Anomaly detection thresholds. CIBA async approval flow config. Graduated autonomy trust scoring. OpenTelemetry integration via hooks. Lifecycle hooks for sandboxing and custom validation. Base URL for the auth server (e.g. [https://auth.example.com](https://auth.example.com)). Secret key used to sign tokens. Min 32 characters. ## Database config Database driver to use. File path for SQLite, connection string for Postgres/MySQL. Not used with D1. D1Database binding from the Worker environment. Required when provider is "d1". Skip automatic CREATE TABLE IF NOT EXISTS on init. Use when you manage migrations externally (Flyway, drizzle-kit push, etc.). Defaults to false. ```typescript theme={"system"} // Cloudflare D1 (edge) const kavach = await createKavach({ database: { provider: 'd1', binding: env.KAVACH_DB, // D1Database from Worker env }, }); // SQLite (Node.js) const kavach = await createKavach({ database: { provider: 'sqlite', url: './kavach.db' }, }); // PostgreSQL const kavach = await createKavach({ database: { provider: 'postgres', url: process.env.DATABASE_URL }, }); // MySQL database: { provider: 'mysql', url: process.env.DATABASE_URL } // In-memory SQLite (tests) database: { provider: 'sqlite', url: ':memory:' } ``` ## Agent config Controls the agent identity lifecycle. Enable agent identity management. Maximum number of agents a single user can create. Permission strings assigned to every new agent unless overridden. Write every agent action to the audit log regardless of permission outcome. Default token expiry duration string (e.g. "7d", "24h", "30m"). ```typescript theme={"system"} agents: { enabled: true, maxPerUser: 10, defaultPermissions: [], auditAll: true, tokenExpiry: '30d', }, ``` ## MCP config Enables the OAuth 2.1 authorization server for MCP-compliant tool access. Enable the MCP authorization server. Token issuer URL. Appears as the iss claim in JWTs. Base path for MCP endpoints. Secret used to sign JWTs. Min 32 characters. Defaults to the top-level secret. Access token lifetime in seconds. Defaults to 3600 (1 hour). Refresh token lifetime in seconds. Defaults to 604800 (7 days). Authorization code lifetime in seconds. Defaults to 600 (10 minutes). Reject all MCP requests without a valid Bearer token. Custom OAuth scopes supported by this server. Allowed resource URIs for RFC 8707 resource indicators. URL of your login page. Users are redirected here when unauthenticated. URL of your consent page. Users are redirected here to approve scopes. `}>OAuth clients registered at startup (first-party apps, CLIs, test fixtures). Promise>`}>Async function to add custom claims to issued tokens. ```typescript theme={"system"} mcp: { enabled: true, issuer: 'https://auth.example.com', baseUrl: 'https://auth.example.com', accessTokenTtl: 3600, refreshTokenTtl: 604800, enforceAuth: true, loginPage: 'https://example.com/login', consentPage: 'https://example.com/consent', }, ``` ## Auth config Connects KavachOS to your existing auth provider so it can resolve the human user behind incoming requests. ```typescript theme={"system"} auth: { adapter: betterAuthAdapter(auth), // resolves user from request session: { // optional: KavachOS-managed sessions secret: process.env.SESSION_SECRET, maxAge: 60 * 60 * 24 * 30, // 30 days in seconds }, }, ``` When `auth` is omitted, `kavach.auth.resolveUser()` always returns `null` (manual user management mode). See [Auth adapters](/guides/auth-adapters) for all adapter options. ## Session config Signing secret for session JWTs. Min 32 characters. Session lifetime in seconds. Name of the session cookie. ## Password reset config Requires `auth.session` to be configured. The caller provides an email-sending callback. Promise`} required>Callback to deliver the reset email. Receives email, raw token, and constructed URL. Base URL for the reset page. Token is appended as ?token=... Reset token lifetime in seconds. Revoke all sessions when the password is successfully reset. Minimum new password length. Maximum new password length. Always use an HTTPS URL for `resetUrl` in production. Reset tokens in plain HTTP links can be intercepted in transit or leaked via `Referer` headers. ```typescript theme={"system"} auth: { adapter: betterAuthAdapter(auth), session: { secret: process.env.SESSION_SECRET!, maxAge: 60 * 60 * 24 * 7, // 7 days }, passwordReset: { resetUrl: 'https://example.com/reset-password', tokenTtlSeconds: 3600, revokeSessionsOnReset: true, minPasswordLength: 10, sendResetEmail: async (email, token, url) => { await mailer.send({ to: email, subject: 'Reset your password', html: `Reset password`, }); }, }, }, ``` ## Session freshness config Controls when sessions are considered "fresh" for sensitive operations like password changes and passkey registration. Maximum session age in seconds to be considered fresh. ## Plugins KavachOS features are composable. Enable what you need: | Plugin | Import | What it does | | --------------- | --------------- | -------------------------------------------- | | `emailPassword` | `kavachos/auth` | Email + password with verification and reset | | `passkey` | `kavachos/auth` | WebAuthn/FIDO2 biometric auth | | `magicLink` | `kavachos/auth` | Passwordless email links | | `emailOtp` | `kavachos/auth` | One-time password codes via email | | `twoFactor` | `kavachos/auth` | TOTP 2FA with backup codes | | `multiSession` | `kavachos/auth` | Session limits and device management | | `organization` | `kavachos/auth` | Organizations with RBAC | | `apiKeys` | `kavachos/auth` | Static API key management | | `admin` | `kavachos/auth` | User management, banning, impersonation | | `stripe` | `kavachos/auth` | Stripe billing integration | | `polar` | `kavachos/auth` | Polar payment integration | ## Anomaly config Calls per agent per hour before flagging as high-frequency. Defaults to 500. Denial rate percentage that triggers an alert. Defaults to 50. Flag access outside these hours (0-23) as off-hours anomaly. Optional. ```typescript theme={"system"} anomaly: { highFrequencyThreshold: 200, highDenialRateThreshold: 30, expectedHours: { start: 8, end: 20 }, }, ``` ## Environment variables pattern Never hardcode secrets in config. Pass them through environment variables: ```typescript theme={"system"} const kavach = await createKavach({ database: { provider: 'postgres', url: process.env.DATABASE_URL!, }, secret: process.env.KAVACH_SECRET!, mcp: { enabled: true, issuer: process.env.KAVACH_ISSUER!, signingSecret: process.env.KAVACH_SIGNING_SECRET, }, }); ``` ## Dev vs production example ```typescript theme={"system"} // config/kavach.ts const isDev = process.env.NODE_ENV !== 'production'; export const kavach = await createKavach({ database: isDev ? { provider: 'sqlite', url: './kavach-dev.db' } : { provider: 'postgres', url: process.env.DATABASE_URL! }, secret: process.env.KAVACH_SECRET!, baseUrl: process.env.KAVACH_BASE_URL ?? 'http://localhost:3000', agents: { enabled: true, maxPerUser: isDev ? 100 : 25, auditAll: true, tokenExpiry: '30d', }, mcp: { enabled: true, issuer: process.env.KAVACH_BASE_URL ?? 'http://localhost:3000', accessTokenTtl: isDev ? 86400 : 3600, enforceAuth: !isDev, loginPage: '/login', consentPage: '/consent', }, anomaly: { highFrequencyThreshold: 500, highDenialRateThreshold: 50, }, }); ``` `secret` and `mcp.signingSecret` must be at least 32 characters. In production, generate them with `openssl rand -base64 32`. ## Next steps Switch from better-auth, Clerk, or other providers. SQLite, Postgres, or MySQL configuration. Mount KavachOS on your framework.