@glinr/theauth 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,16 +1,16 @@
 export { and, eq, like } from 'drizzle-orm';
 export { createAgentModule } from './agent/index.js';
-import { D as Database, a as DatabaseConfig, K as KavachConfig, b as DelegateInput, P as Permission, c as DelegationChain, d as DidDocument, e as DidKeyPair, f as DidWebConfig, g as AgentDid, S as SignedPayload, V as VerificationResult, T as TheAuthConfig, C as CreateAgentInput, A as AgentIdentity, h as AgentFilter, U as UpdateAgentInput, i as AuthorizeRequest, R as RequestContext, j as AuthorizeResult, k as AuditFilter, l as AuditEntry, m as AuditExportOptions, M as McpServerInput, n as McpServer, o as ResolvedUser, p as SessionManager, q as ApprovalRequest, r as MagicLinkModule, E as EmailOtpModule, s as TotpModule, t as PasskeyModule, O as OrgModule, u as SsoModule, v as AdminModule, w as ApiKeyManagerModule, x as UsernameAuthModule, y as PasswordResetModule, z as EmailVerificationModule, B as OneTimeTokenModule, F as SessionFreshnessModule, G as PhoneAuthModule, H as CaptchaModule, W as WebhookModule$1, I as EvaluateInput, J as PolicyDecision, L as InvalidateScope, N as PolicyCacheStats, Q as PluginEndpoint, X as EndpointContext, Y as TheAuthPlugin, Z as SessionConfig, _ as Session } from './types-D1dTo8-m.js';
-export { $ as AdminConfig, a0 as AdminUser, a1 as AgentConfig, a2 as ApiKey, a3 as ApiKeyManagerConfig, a4 as ApprovalConfig, a5 as ApprovalModule, a6 as AuthAdapter, a7 as AuthConfig, a8 as AuthHooks, a9 as AuthInstance, aa as AuthPlugin, ab as CaptchaConfig, ac as CaptchaVerifyResult, ad as CreateTokenInput, ae as D1DatabaseBinding, af as EmailOtpConfig, ag as EmailVerificationConfig, ah as KavachHooks, ai as KavachInstance, aj as KavachPlugin, ak as MagicLinkConfig, al as McpMiddleware, am as OidcProvider, an as OneTimeTokenConfig, ao as OneTimeTokenPurpose, ap as OrgConfig, aq as OrgInvitation, ar as OrgMember, as as OrgRole, at as Organization, au as PasskeyConfig, av as PasskeyCredential, aw as PasswordResetConfig, ax as PermissionConstraints, ay as PhoneAuthConfig, az as PluginContext, aA as PluginInitResult, aB as RevokeTokensResult, aC as SSO_ERROR, aD as SamlProvider, aE as ServiceEndpoint, aF as SessionFreshnessConfig, aG as SsoAuditEvent, aH as SsoConfig, aI as SsoConnection, aJ as SsoError, aK as TheAuthHooks, aL as TheAuthInstance, aM as TokenValidationResult, aN as TotpConfig, aO as TotpSetup, aP as UsernameAuthConfig, aQ as ValidateTokenResult, aR as VerificationMethod, aS as agentCards, aT as agentDids, aU as agents, aV as apiKeysTable, aW as approvalRequests, aX as auditLogs, aY as budgetPolicies, aZ as classifyViolation, a_ as createAdminModule, a$ as createApiKeyManagerModule, b0 as createApprovalModule, b1 as createCaptchaModule, b2 as createDatabase, b3 as createDatabaseSync, b4 as createEmailOtpModule, b5 as createEmailVerificationModule, b6 as createMagicLinkModule, b7 as createOneTimeTokenModule, b8 as createOrgModule, b9 as createPasskeyModule, ba as createPasswordResetModule, bb as createPhoneAuthModule, bc as createSessionFreshnessModule, bd as createSessionManager, be as createSsoModule, bf as createTotpModule, bg as createUsernameAuthModule, bh as delegationChains, bi as emailOtps, bj as magicLinks, bk as mcpServers, bl as oauthAccessTokens, bm as oauthAuthorizationCodes, bn as oauthClients, bo as orgInvitations, bp as orgMembers, bq as orgRoles, br as organizations, bs as passkeyChallenges, bt as passkeyCredentials, bu as permissions, bv as rateLimits, bw as sessions, bx as ssoConnections, by as tenants, bz as totpRecords, bA as trustScores, bB as users } from './types-D1dTo8-m.js';
+import { D as Database, a as DatabaseConfig, T as TheAuthConfig, b as DelegateInput, P as Permission, c as DelegationChain, d as DidDocument, e as DidKeyPair, f as DidWebConfig, g as AgentDid, S as SignedPayload, V as VerificationResult, h as PluginEndpoint, E as EndpointContext, i as TheAuthPlugin, j as SessionManager, k as SessionConfig, l as Session, C as CreateAgentInput, A as AgentIdentity, m as AgentFilter, U as UpdateAgentInput, n as AuthorizeRequest, R as RequestContext, o as AuthorizeResult, p as AuditFilter, q as AuditEntry, r as AuditExportOptions, M as McpServerInput, s as McpServer, t as ResolvedUser, u as ApprovalRequest, v as MagicLinkModule, w as EmailOtpModule, x as TotpModule, y as PasskeyModule, O as OrgModule, z as SsoModule, B as AdminModule, F as ApiKeyManagerModule, G as UsernameAuthModule, H as PasswordResetModule, I as EmailVerificationModule, J as OneTimeTokenModule, K as SessionFreshnessModule, L as PhoneAuthModule, N as CaptchaModule, W as WebhookModule$1, Q as EvaluateInput, X as PolicyDecision, Y as InvalidateScope, Z as PolicyCacheStats } from './types-JOx1R8-Q.js';
+export { _ as AdminConfig, $ as AdminUser, a0 as AgentConfig, a1 as ApiKey, a2 as ApiKeyManagerConfig, a3 as ApprovalConfig, a4 as ApprovalModule, a5 as AuthAdapter, a6 as AuthConfig, a7 as AuthHooks, a8 as AuthInstance, a9 as AuthPlugin, aa as CaptchaConfig, ab as CaptchaVerifyResult, ac as CreateTokenInput, ad as D1DatabaseBinding, ae as EmailOtpConfig, af as EmailVerificationConfig, ag as MagicLinkConfig, ah as McpMiddleware, ai as OidcProvider, aj as OneTimeTokenConfig, ak as OneTimeTokenPurpose, al as OrgConfig, am as OrgInvitation, an as OrgMember, ao as OrgRole, ap as Organization, aq as PasskeyConfig, ar as PasskeyCredential, as as PasswordResetConfig, at as PermissionConstraints, au as PhoneAuthConfig, av as PluginContext, aw as PluginInitResult, ax as RevokeTokensResult, ay as SSO_ERROR, az as SamlProvider, aA as ServiceEndpoint, aB as SessionFreshnessConfig, aC as SsoAuditEvent, aD as SsoConfig, aE as SsoConnection, aF as SsoError, aG as TheAuthHooks, aH as TheAuthInstance, aI as TokenValidationResult, aJ as TotpConfig, aK as TotpSetup, aL as UsernameAuthConfig, aM as ValidateTokenResult, aN as VerificationMethod, aO as agentCards, aP as agentDids, aQ as agents, aR as apiKeysTable, aS as approvalRequests, aT as auditLogs, aU as budgetPolicies, aV as classifyViolation, aW as createAdminModule, aX as createApiKeyManagerModule, aY as createApprovalModule, aZ as createCaptchaModule, a_ as createDatabase, a$ as createDatabaseSync, b0 as createEmailOtpModule, b1 as createEmailVerificationModule, b2 as createMagicLinkModule, b3 as createOneTimeTokenModule, b4 as createOrgModule, b5 as createPasskeyModule, b6 as createPasswordResetModule, b7 as createPhoneAuthModule, b8 as createSessionFreshnessModule, b9 as createSessionManager, ba as createSsoModule, bb as createTotpModule, bc as createUsernameAuthModule, bd as delegationChains, be as emailOtps, bf as magicLinks, bg as mcpServers, bh as oauthAccessTokens, bi as oauthAuthorizationCodes, bj as oauthClients, bk as orgInvitations, bl as orgMembers, bm as orgRoles, bn as organizations, bo as passkeyChallenges, bp as passkeyCredentials, bq as permissions, br as rateLimits, bs as sessions, bt as ssoConnections, bu as tenants, bv as totpRecords, bw as trustScores, bx as users } from './types-JOx1R8-Q.js';
 export { createAuditModule } from './audit/index.js';
 export { AccessTokenClaims, AdditionalFieldsConfig, AdditionalFieldsModule, AnonymousAuthConfig, AnonymousAuthModule, AuthorizeParams, BearerAuthOptions, BudgetCheckResult, CheckParams, CheckResult, CheckoutOptions, CostAlert, CostAttributionConfig, CostAttributionModule, CostReport, CreateEphemeralSessionInput, CustomSessionConfig, CustomSessionModule, DEFAULT_ATLASSIAN_SCOPES, DEFAULT_DISCORD_SCOPES, DEFAULT_DROPBOX_SCOPES, DEFAULT_FIGMA_SCOPES, DEFAULT_NOTION_SCOPES, DEFAULT_REDDIT_SCOPES, DEFAULT_SLACK_SCOPES, DEFAULT_SPOTIFY_SCOPES, DEFAULT_TWITCH_SCOPES, DEFAULT_ZOOM_SCOPES, DeleteOptions, DeleteResult, DeviceAuthConfig, DeviceAuthModule, DeviceAuthStatus, DeviceCodeResponse, EVENT_TYPES, EndpointGroup, EndpointLimit, EphemeralSession, EphemeralSessionConfig, EphemeralSessionModule, EphemeralSessionValidateResult, EventStreamConfig, EventStreamModule, EventType, ExpandParams, FederatedAgent, FederationConfig, FederationModule, FederationToken, FederationWellKnown, FieldDefinition, GdprModule, GenericOIDCConfig, GetUserClaimsFn, GoogleUser, HeaderAuthOptions, HibpApiError, HibpBreachedError, HibpConfig, HibpModule, InstanceIdentity, IssueFederationTokenInput, JsonWebKeySet, JwtSessionConfig, JwtSessionModule, KVNamespace, KVStore, LastLoginConfig, LastLoginModule, ListObjectsParams, ListSubjectsParams, LoginEvent, LoginMethod, MemoryStore, OAuthAccount, OAuthCallbackResult, OAuthModule, OAuthModuleConfig, OAuthPluginConfig, OAuthProvider, OAuthProviderConfig, OAuthProxyConfig, OAuthProxyError, OAuthProxyModule, OAuthProxyPluginConfig, OAuthTokens, OAuthUserInfo, OidcClient, OidcDiscoveryDocument, OidcProviderConfig, OidcProviderModule, OneTapConfig, OneTapModule, OneTapVerifyError, OpenApiComponents, OpenApiConfig, OpenApiDocument, OpenApiInfo, OpenApiMediaType, OpenApiModule, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiServer, PermissionRuleSet, PolarConfig, PolarModule, PolarSubscription, ProxyTokens, RateLimitConfig, RateLimitMiddlewareOptions, RateLimitPluginConfig, RateLimitResult, RateLimitStore, RateLimiter, ReBACConfig, ReBACModule, RecordCostInput, RecordLoginInput, RegisterClientInput, Relationship, ResourceNode, ScimConfig, ScimGroup, ScimModule, ScimUser, SessionTokens, SessionUser, SiweConfig, SiweModule, SiweVerifyResult, StreamEvent, StripeConfig, StripeModule, SubscriptionInfo, TokenParams, TokenResponse, TrustLevel, TrustedDevice, TrustedDeviceConfig, TrustedDeviceModule, TrustedInstance, TwoFactorConfig, UserDataExport, UserInfoClaims, ValidationResult, VerifiedSession, additionalFields, admin, anonymousAuth, apiKeys, atlassianProvider, auth0Provider, bearerAuth, bitbucketProvider, cognitoProvider, coinbaseProvider, createAdditionalFieldsModule, createAnonymousAuthModule, createAppleProvider, createAtlassianProvider, createCostAttributionModule, createCustomSessionModule, createDeviceAuthModule, createDiscordProvider, createDropboxProvider, createEphemeralSessionModule, createEventStreamModule, createFederationModule, createFigmaProvider, createGdprModule, createGithubProvider, createGitlabProvider, createGoogleProvider, createHibpModule, createJwtSessionModule, createLastLoginModule, createLinkedInProvider, createMicrosoftProvider, createNotionProvider, createOAuthModule, createOAuthProxyModule, createOidcProviderModule, createOneTapModule, createOpenApiModule, createPolarModule, createRateLimiter, createReBACModule, createRedditProvider, createScimModule, createSiweModule, createSlackProvider, createSpotifyProvider, createStripeModule, createTrustedDeviceModule, createTwitchProvider, createTwitterProvider, createZoomProvider, customAuth, customSession, deviceAuth, deviceLabelFromRequest, dropboxProvider, emailOtp, facebookProvider, figmaProvider, gdpr, genericOIDC, headerAuth, huggingfaceProvider, kakaoProvider, kickProvider, kvStore, lineProvider, linearProvider, magicLink, naverProvider, normalizeAtlassianProfile, normalizeDiscordProfile, normalizeDropboxProfile, normalizeFigmaProfile, normalizeNotionProfile, normalizeRedditProfile, normalizeSlackProfile, normalizeSpotifyProfile, normalizeTwitchProfile, normalizeZoomProfile, notionProvider, oauth, oauthProxy, oktaProvider, oneTap, organization, passkey, paypalProvider, polar, polarProvider, railwayProvider, rateLimit, redditProvider, robloxProvider, salesforceProvider, scim, siwe, spotifyProvider, stripe, tiktokProvider, twitchProvider, twoFactor, vercelProvider, vkProvider, wechatProvider, withRateLimit, yahooProvider, zoomProvider } from './auth/index.js';
 export { constantTimeEqual, fromBase64Url, fromHex, generateId, hmacSha1Raw, hmacSha256, hmacSha256Raw, importHmacKey, pbkdf2Hash, pbkdf2Verify, randomBytes, randomBytesHex, sha1, sha256, sha256Raw, toBase64Url, toHex } from './crypto/index.js';
+export { PermissionTemplateName, createPermissionEngine, getPermissionTemplate, permissionTemplates } from './permission/index.js';
 import { RedirectChainManager } from './redirect/index.js';
 export { RedirectChainState, RedirectConfig, RedirectEntry, createRedirectChain } from './redirect/index.js';
-export { PermissionTemplateName, createPermissionEngine, getPermissionTemplate, permissionTemplates } from './permission/index.js';
-export { AUTH_AGENT_CREDENTIAL, AUTH_DELEGATION_CREDENTIAL, AUTH_PERMISSION_CREDENTIAL, AuditCredentialSubject, AuditExportResult, AuditRecord, CredentialFormat, CredentialStatus, CredentialStatusSchema, CredentialSubject, CredentialSubjectSchema, DelegationLink, ExportAuditOptions, ExtractedPermissions, IssueAgentCredentialInput, IssueDelegationCredentialInput, IssuePermissionCredentialInput, KAVACH_AGENT_CREDENTIAL, KAVACH_DELEGATION_CREDENTIAL, KAVACH_PERMISSION_CREDENTIAL, Proof, ProofSchema, THEAUTH_AGENT_CREDENTIAL, THEAUTH_AUDIT_CONTEXT, THEAUTH_AUDIT_CREDENTIAL, THEAUTH_DELEGATION_CREDENTIAL, THEAUTH_PERMISSION_CREDENTIAL, VCIssuer, VCIssuerConfig, VCJwtPayload, VCVerifier, VCVerifierConfig, VC_CONTEXT_V1, VC_CONTEXT_V2, VC_TYPE_CREDENTIAL, VC_TYPE_PRESENTATION, VerifiableCredential, VerifiableCredentialSchema, VerifiablePresentation, VerifiablePresentationSchema, VerifiedCredential, VerifiedPresentation, createVCIssuer, createVCVerifier, exportAuditAsVC, listAuditRecords } from './vc/index.js';
+export { AUTH_AGENT_CREDENTIAL, AUTH_DELEGATION_CREDENTIAL, AUTH_PERMISSION_CREDENTIAL, AuditCredentialSubject, AuditExportResult, AuditRecord, CredentialFormat, CredentialStatus, CredentialStatusSchema, CredentialSubject, CredentialSubjectSchema, DelegationLink, ExportAuditOptions, ExtractedPermissions, IssueAgentCredentialInput, IssueDelegationCredentialInput, IssuePermissionCredentialInput, Proof, ProofSchema, THEAUTH_AGENT_CREDENTIAL, THEAUTH_AUDIT_CONTEXT, THEAUTH_AUDIT_CREDENTIAL, THEAUTH_DELEGATION_CREDENTIAL, THEAUTH_PERMISSION_CREDENTIAL, VCIssuer, VCIssuerConfig, VCJwtPayload, VCVerifier, VCVerifierConfig, VC_CONTEXT_V1, VC_CONTEXT_V2, VC_TYPE_CREDENTIAL, VC_TYPE_PRESENTATION, VerifiableCredential, VerifiableCredentialSchema, VerifiablePresentation, VerifiablePresentationSchema, VerifiedCredential, VerifiedPresentation, createVCIssuer, createVCVerifier, exportAuditAsVC, listAuditRecords } from './vc/index.js';
 import 'drizzle-orm/sqlite-core';
-import './types-IkWVkOVv.js';
+import './types-XoCxTUZj.js';
 import 'zod';
 import './standards/index.js';
 import 'jose';
@@ -60,32 +60,20 @@ declare function createPrivilegeAnalyzer(db: Database): {
 };
 type PrivilegeAnalyzer = ReturnType<typeof createPrivilegeAnalyzer>;
 
-/**
- * Create TheAuth tables if they do not already exist.
- *
- * Uses `CREATE TABLE IF NOT EXISTS` so it is safe to call on every startup.
- * Tables are created in dependency order (no forward-reference FK issues).
- *
- * When `config` is provided, only tables required by the configured features
- * are created. When omitted, all tables are created (backward-compatible
- * behaviour for callers that do not pass a config).
- *
- * @param db       Drizzle database instance returned by `createDatabase()`.
- * @param provider The database provider used to build the correct DDL syntax.
- * @param config   Optional KavachConfig used to determine which feature tables
- *                 to create. When absent, all tables are created.
- *
- * @example
- * ```typescript
- * const db = await createDatabase({ provider: 'postgres', url: process.env.DATABASE_URL });
- * await createTables(db, 'postgres');
- * ```
- */
-declare function createTables(db: Database, provider: DatabaseConfig["provider"], config?: KavachConfig): Promise<void>;
+declare function createTables(db: Database, provider: DatabaseConfig["provider"], config?: TheAuthConfig): Promise<void>;
 
 interface DelegationModuleConfig {
     db: Database;
 }
+type DelegationErrorCode = "DELEGATION_PERMISSION_SUBSET" | "DELEGATION_DEPTH_EXCEEDED";
+/**
+ * Typed error for delegation requests that are invalid by caller input.
+ * Adapters map it to HTTP 400 using `code`.
+ */
+declare class DelegationError extends Error {
+    readonly code: DelegationErrorCode;
+    constructor(code: DelegationErrorCode, message: string);
+}
 /**
  * Create the delegation module.
  * Handles agent-to-agent permission delegation with chain tracking.
@@ -294,1350 +282,1342 @@ declare const ja: TranslationKeys;
 declare const zh: TranslationKeys;
 
 /**
- * Create a TheAuth instance.
- *
- * The factory is **async** so it can open database connections for Postgres
- * and MySQL (which require async driver initialisation) and optionally run
- * `CREATE TABLE IF NOT EXISTS` for all schema tables.
- *
- * @example SQLite (simplest)
- * ```typescript
- * import { createTheAuth } from '@glinr/theauth';
- *
- * const auth = await createTheAuth({
- *   database: { provider: 'sqlite', url: 'theauth.db' },
- * });
- * ```
- *
- * @example Postgres
- * ```typescript
- * const auth = await createTheAuth({
- *   database: { provider: 'postgres', url: process.env.DATABASE_URL },
- * });
- * ```
+ * OpenAPI 3.1 specification generator for TheAuth REST API.
  *
- * @example MySQL - skip auto-migration (tables managed externally)
- * ```typescript
- * const auth = await createTheAuth({
- *   database: {
- *     provider: 'mysql',
- *     url: process.env.DATABASE_URL,
- *     skipMigrations: true,
- *   },
- * });
- * ```
+ * This generates the spec that enables auto-generated SDKs
+ * for Python, Go, Java, Rust, etc. via OpenAPI codegen tools.
  */
-declare function createTheAuth(config: TheAuthConfig): Promise<{
-    agent: {
-        create(input: CreateAgentInput): ReturnType<(input: CreateAgentInput) => Promise<AgentIdentity & {
-            token: string;
-        }>>;
-        revoke(agentId: string): ReturnType<(agentId: string) => Promise<void>>;
-        rotate(agentId: string): ReturnType<(agentId: string) => Promise<AgentIdentity & {
-            token: string;
-        }>>;
-        get: (agentId: string) => Promise<AgentIdentity | null>;
-        list: (filter?: AgentFilter) => Promise<AgentIdentity[]>;
-        update: (agentId: string, input: UpdateAgentInput) => Promise<AgentIdentity>;
-        validateToken: (token: string) => Promise<AgentIdentity | null>;
+interface OpenAPISpec {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
     };
-    authorize: (agentId: string, request: AuthorizeRequest, context?: RequestContext) => Promise<AuthorizeResult>;
-    authorizeByToken: (token: string, request: AuthorizeRequest, context?: RequestContext) => Promise<AuthorizeResult>;
-    delegate: (input: DelegateInput) => Promise<DelegationChain>;
-    delegation: {
-        revoke: (chainId: string) => Promise<void>;
-        getEffectivePermissions: (agentId: string) => Promise<Permission[]>;
-        listChains: (agentId: string) => Promise<DelegationChain[]>;
+    servers: Array<{
+        url: string;
+        description: string;
+    }>;
+    paths: Record<string, Record<string, PathOperation>>;
+    components: {
+        schemas: Record<string, SchemaObject>;
+        securitySchemes: Record<string, SecurityScheme>;
     };
-    audit: {
-        query: (filter: AuditFilter) => Promise<AuditEntry[]>;
-        export: (options: AuditExportOptions) => Promise<string>;
-        cleanup: (options: {
-            retentionDays: number;
-        }) => Promise<{
-            deleted: number;
+}
+interface PathOperation {
+    summary: string;
+    operationId: string;
+    tags: string[];
+    security?: Array<Record<string, string[]>>;
+    parameters?: ParameterObject[];
+    requestBody?: {
+        required: boolean;
+        content: Record<string, {
+            schema: SchemaRef;
+        }>;
+    };
+    responses: Record<string, {
+        description: string;
+        content?: Record<string, {
+            schema: SchemaRef;
         }>;
+    }>;
+}
+interface ParameterObject {
+    name: string;
+    in: "query" | "path" | "header";
+    required: boolean;
+    schema: SchemaRef;
+}
+interface SecurityScheme {
+    type: string;
+    scheme?: string;
+    bearerFormat?: string;
+}
+type SchemaRef = {
+    $ref: string;
+} | SchemaObject;
+interface SchemaObject {
+    type?: string;
+    properties?: Record<string, SchemaRef>;
+    required?: string[];
+    items?: SchemaRef;
+    enum?: string[];
+    description?: string;
+    format?: string;
+    nullable?: boolean;
+}
+/**
+ * Generate the full OpenAPI 3.1 specification for the TheAuth REST API.
+ */
+declare function generateOpenAPISpec(options?: {
+    baseUrl?: string;
+    version?: string;
+}): OpenAPISpec;
+
+/**
+ * Create a plugin router that matches requests to registered plugin endpoints.
+ *
+ * The router strips `basePath` from the request URL before matching so plugins
+ * register paths relative to the mount point (e.g. `/auth/sign-in` instead
+ * of `/api/theauth/auth/sign-in`).
+ */
+declare function createPluginRouter(endpoints: PluginEndpoint[]): {
+    /** Try to handle a request. Returns Response if matched, null if not. */
+    handle: (request: Request, basePath: string, endpointCtx: EndpointContext) => Promise<Response | null>;
+    /** Get all registered endpoints (for adapter mounting) */
+    getEndpoints: () => PluginEndpoint[];
+};
+
+interface PluginRegistry {
+    endpoints: PluginEndpoint[];
+    migrations: string[];
+    hooks: {
+        onRequest: Array<NonNullable<TheAuthPlugin["hooks"]>["onRequest"]>;
+        onAuthenticate: Array<NonNullable<TheAuthPlugin["hooks"]>["onAuthenticate"]>;
+        onSessionCreate: Array<NonNullable<TheAuthPlugin["hooks"]>["onSessionCreate"]>;
+        onSessionRevoke: Array<NonNullable<TheAuthPlugin["hooks"]>["onSessionRevoke"]>;
     };
+    pluginContext: Record<string, unknown>;
+}
+/**
+ * Initialize all plugins and collect their endpoints, migrations, and hooks
+ * into a single registry.
+ *
+ * Calls each plugin's `init()` in registration order.  Migrations collected
+ * during init are executed before the registry is returned so that any
+ * subsequent requests can immediately use plugin tables.
+ */
+declare function initializePlugins(plugins: TheAuthPlugin[], db: Database, config: TheAuthConfig, sessionManager: SessionManager | null): Promise<PluginRegistry>;
+
+interface BudgetPolicy {
+    id: string;
+    agentId?: string;
+    userId?: string;
+    tenantId?: string;
+    limits: BudgetLimits;
+    currentUsage: BudgetUsage;
+    action: "warn" | "throttle" | "block" | "revoke";
+    status: "active" | "triggered" | "disabled";
+    createdAt: Date;
+}
+interface BudgetLimits {
+    maxTokensCostPerDay?: number;
+    maxTokensCostPerMonth?: number;
+    maxCallsPerDay?: number;
+    maxCallsPerMonth?: number;
+}
+interface BudgetUsage {
+    tokensCostToday: number;
+    tokensCostThisMonth: number;
+    callsToday: number;
+    callsThisMonth: number;
+    lastUpdated: string;
+}
+interface CreatePolicyInput {
+    agentId?: string;
+    userId?: string;
+    tenantId?: string;
+    limits: BudgetLimits;
+    action: "warn" | "throttle" | "block" | "revoke";
+}
+interface PolicyFilters {
+    agentId?: string;
+    userId?: string;
+    tenantId?: string;
+}
+declare function createPolicyModule(db: Database): {
+    create: (input: CreatePolicyInput) => Promise<BudgetPolicy>;
+    get: (policyId: string) => Promise<BudgetPolicy | null>;
+    list: (filters?: PolicyFilters) => Promise<BudgetPolicy[]>;
+    update: (policyId: string, updates: Partial<BudgetPolicy>) => Promise<BudgetPolicy>;
+    remove: (policyId: string) => Promise<void>;
+    checkBudget: (agentId: string, tokensCost?: number) => Promise<{
+        allowed: boolean;
+        reason?: string;
+        policy?: BudgetPolicy;
+    }>;
+    recordUsage: (agentId: string, tokensCost?: number) => Promise<void>;
+    resetDaily: () => Promise<{
+        reset: number;
+    }>;
+    resetMonthly: () => Promise<{
+        reset: number;
+    }>;
+};
+
+/**
+ * Cookie serialization and parsing utilities for TheAuth.
+ *
+ * Pure functions that work with Web API `Request`/`Response` objects and
+ * raw header strings. No framework dependencies.
+ */
+type SameSite = "strict" | "lax" | "none";
+interface CookieOptions {
+    /** Prevents JavaScript access to the cookie. Default: true. */
+    httpOnly?: boolean;
     /**
-     * MCP server registration.
-     *
-     * Register and look up MCP tool servers. Uses the `kavach_mcp_servers`
-     * database table — no separate in-memory store needed.
+     * Restricts transmission to HTTPS. Default: true in production
+     * (when `NODE_ENV === 'production'`), false otherwise.
      */
-    mcp: {
-        /**
-         * Register a new MCP tool server.
-         *
-         * Persists the server entry to the `kavach_mcp_servers` table.
-         * The returned record includes the generated `id` and `createdAt`.
-         */
-        register(input: McpServerInput): Promise<McpServer>;
-        /**
-         * List all registered MCP servers (active and inactive).
-         */
-        list(): Promise<McpServer[]>;
-        /**
-         * Get a single MCP server by ID. Returns null when not found.
-         */
-        get(id: string): Promise<McpServer | null>;
-    };
-    /**
-     * Least-privilege analyzer.
-     *
-     * Compare agent permissions against actual audit log usage to surface
-     * wildcards, unused grants, and over-permissioned identities.
-     */
-    analyzer: {
-        analyzeAgent: (agentId: string, options?: {
-            since?: Date;
-        }) => Promise<PrivilegeAnalysis>;
-        analyzeAll: (options?: {
-            since?: Date;
-        }) => Promise<PrivilegeAnalysis[]>;
-        getSummary: () => Promise<PrivilegeSummary>;
-    };
-    /**
-     * Human auth integration.
-     *
-     * `resolveUser` extracts the authenticated human from an inbound HTTP
-     * request via the configured adapter.  `session` is a full session
-     * manager (create / validate / revoke) when `auth.session` was passed
-     * to `createTheAuth()`.
-     *
-     * @example
-     * ```typescript
-     * app.use(async (req, res, next) => {
-     *   const user = await kavach.auth.resolveUser(req);
-     *   if (!user) return res.status(401).json({ error: 'Unauthorized' });
-     *   req.user = user;
-     *   next();
-     * });
-     * ```
-     */
-    auth: {
-        resolveUser(request: Request): Promise<ResolvedUser | null>;
-        session: SessionManager | null;
-    };
-    /**
-     * Resolve a human user from an incoming HTTP request.
-     *
-     * @deprecated Use `kavach.auth.resolveUser(request)` instead.
-     */
-    resolveUser(request: Request): Promise<ResolvedUser | null>;
-    /** Direct database access for advanced usage */
-    db: Database;
-    /**
-     * Multi-tenant isolation.
-     *
-     * Create and manage tenants (organizations) that share a single
-     * TheAuth instance with full data isolation. Agents can be scoped
-     * to a tenant via `tenantId`.
-     */
-    tenant: {
-        create: (input: CreateTenantInput) => Promise<Tenant>;
-        get: (tenantId: string) => Promise<Tenant | null>;
-        getBySlug: (slug: string) => Promise<Tenant | null>;
-        list: () => Promise<Tenant[]>;
-        update: (tenantId: string, updates: Partial<CreateTenantInput>) => Promise<Tenant>;
-        suspend: (tenantId: string) => Promise<void>;
-        activate: (tenantId: string) => Promise<void>;
-    };
-    /**
-     * Agent execution budget policies.
-     *
-     * Set spending caps (token cost, call counts) per agent, user, or
-     * tenant. Exceeded policies trigger a configurable action: warn,
-     * throttle, block, or revoke.
-     */
-    policies: {
-        create: (input: CreatePolicyInput) => Promise<BudgetPolicy>;
-        get: (policyId: string) => Promise<BudgetPolicy | null>;
-        list: (filters?: PolicyFilters) => Promise<BudgetPolicy[]>;
-        update: (policyId: string, updates: Partial<BudgetPolicy>) => Promise<BudgetPolicy>;
-        remove: (policyId: string) => Promise<void>;
-        checkBudget: (agentId: string, tokensCost?: number) => Promise<{
-            allowed: boolean;
-            reason?: string;
-            policy?: BudgetPolicy;
-        }>;
-        recordUsage: (agentId: string, tokensCost?: number) => Promise<void>;
-        resetDaily: () => Promise<{
-            reset: number;
-        }>;
-        resetMonthly: () => Promise<{
-            reset: number;
-        }>;
-    };
-    /**
-     * CIBA-style async human approval flows.
-     *
-     * Create pending approval requests, notify humans via webhook or
-     * custom handler, and resolve them with approve / deny.
-     */
-    approval: {
-        request: (input: {
-            agentId: string;
-            userId: string;
-            action: string;
-            resource: string;
-            arguments?: Record<string, unknown>;
-        }) => Promise<ApprovalRequest>;
-        approve: (requestId: string, respondedBy?: string) => Promise<ApprovalRequest>;
-        deny: (requestId: string, respondedBy?: string) => Promise<ApprovalRequest>;
-        get: (requestId: string) => Promise<ApprovalRequest | null>;
-        listPending: (userId?: string) => Promise<ApprovalRequest[]>;
-        cleanup: () => Promise<{
-            expired: number;
-        }>;
-    };
-    /**
-     * Graduated autonomy trust scoring.
-     *
-     * Compute and persist 0-100 trust scores derived from audit history,
-     * mapped to five levels: untrusted, limited, standard, trusted, elevated.
-     */
-    trust: {
-        computeScore: (agentId: string) => Promise<TrustScore>;
-        getScore: (agentId: string) => Promise<TrustScore | null>;
-        computeAll: () => Promise<TrustScore[]>;
-        getScores: (filters?: {
-            level?: string;
-            minScore?: number;
-        }) => Promise<TrustScore[]>;
-    };
-    /**
-     * W3C Decentralized Identifiers (DID) for agents.
-     *
-     * Generate did:key or did:web identities, sign payloads, and verify
-     * signatures. Private keys are never stored — they are returned to
-     * the caller on generation and must be stored securely.
-     *
-     * @example
-     * ```typescript
-     * const { agentDid, privateKeyJwk } = await kavach.did.generateKey(agentId);
-     * const signed = await kavach.did.sign(agentId, { action: 'read' }, privateKeyJwk);
-     * const result = await kavach.did.verify(signed.jws, agentDid.did);
-     * ```
-     */
-    did: {
-        generateKey: (agentId: string) => Promise<{
-            agentDid: AgentDid;
-            privateKeyJwk: JsonWebKey;
-        }>;
-        generateWeb: (agentId: string) => Promise<{
-            agentDid: AgentDid;
-            privateKeyJwk: JsonWebKey;
-        }>;
-        resolve: (did: string) => Promise<DidDocument | null>;
-        getAgentDid: (agentId: string) => Promise<AgentDid | null>;
-        sign: (agentId: string, payload: Record<string, unknown>, privateKeyJwk: JsonWebKey) => Promise<SignedPayload>;
-        verify: (jws: string, did?: string) => Promise<VerificationResult>;
-        createPresentation: (options: {
-            agentId: string;
-            privateKeyJwk: JsonWebKey;
-            capabilities: string[];
-            audience?: string;
-            expiresIn?: number;
-        }) => Promise<string>;
-        verifyPresentation: (jwt: string) => Promise<VerificationResult & {
-            capabilities?: string[];
-        }>;
-    };
-    /**
-     * Magic link (passwordless email) authentication.
-     *
-     * Null when `magicLink` config was not provided or `auth.session` is not
-     * configured (sessions are required to issue tokens on verification).
-     *
-     * @example
-     * ```typescript
-     * // In your route handler
-     * const response = await kavach.magicLink?.handleRequest(request);
-     * if (response) return response;
-     * ```
-     */
-    magicLink: MagicLinkModule | null;
-    /**
-     * Email OTP (one-time password) authentication.
-     *
-     * Null when `emailOtp` config was not provided or `auth.session` is not
-     * configured.
-     *
-     * @example
-     * ```typescript
-     * const response = await kavach.emailOtp?.handleRequest(request);
-     * if (response) return response;
-     * ```
-     */
-    emailOtp: EmailOtpModule | null;
-    /**
-     * TOTP two-factor authentication.
-     *
-     * Null when `totp` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * // On setup (show QR code to user)
-     * const { secret, uri, backupCodes } = await kavach.totp.setup(userId);
-     *
-     * // After user scans QR and enters code
-     * const { enabled } = await kavach.totp.enable(userId, totpCode);
-     *
-     * // On login (after password check)
-     * const { valid } = await kavach.totp.verify(userId, totpCode);
-     * ```
-     */
-    totp: TotpModule | null;
-    /**
-     * Passkey / WebAuthn authentication.
-     *
-     * Null when `passkey` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * // Registration — step 1: get options, send to browser
-     * const options = await kavach.passkey.getRegistrationOptions(userId, userName);
-     *
-     * // Registration — step 2: verify browser response
-     * const { credential } = await kavach.passkey.verifyRegistration(userId, response);
-     *
-     * // Authentication — step 1: get options
-     * const options = await kavach.passkey.getAuthenticationOptions(userId);
-     *
-     * // Authentication — step 2: verify browser response
-     * const result = await kavach.passkey.verifyAuthentication(response);
-     * if (result) console.log('Authenticated user:', result.userId);
-     * ```
-     */
-    passkey: PasskeyModule | null;
-    /**
-     * Organizations + RBAC.
-     *
-     * Null when `org` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * const org = await kavach.org?.create({ name: 'Acme', slug: 'acme', ownerId: userId });
-     * const allowed = await kavach.org?.hasPermission(org.id, userId, 'agents:create');
-     * ```
-     */
-    org: OrgModule | null;
-    /**
-     * SSO (SAML 2.0 + OIDC) enterprise authentication.
-     *
-     * Null when `sso` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * const conn = await kavach.sso?.createConnection({ orgId, providerId: 'okta', type: 'saml', domain: 'acme.com' });
-     * const url = await kavach.sso?.getSamlAuthUrl(conn.id);
-     * ```
-     */
-    sso: SsoModule | null;
-    /**
-     * Admin module.
-     *
-     * Null when `admin` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * await kavach.admin?.banUser(userId, 'Spam');
-     * const { session } = await kavach.admin?.impersonate(adminId, userId);
-     * ```
-     */
-    admin: AdminModule | null;
-    /**
-     * API key management.
-     *
-     * Null when `apiKeys` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * const { key, apiKey } = await kavach.apiKeys?.create({ userId, name: 'CI', permissions: ['agents:read'] });
-     * const result = await kavach.apiKeys?.validate(key);
-     * ```
-     */
-    apiKeys: ApiKeyManagerModule | null;
-    /**
-     * Username + password authentication.
-     *
-     * Null when `username` config was not provided or `auth.session` is not
-     * configured (sessions are required to issue tokens on sign-in/up).
-     *
-     * @example
-     * ```typescript
-     * const response = await kavach.username?.handleRequest(request);
-     * if (response) return response;
-     * ```
-     */
-    username: UsernameAuthModule | null;
-    /**
-     * Password reset (forgot password + reset password).
-     *
-     * Null when `passwordReset` config was not provided or `auth.session`
-     * is not configured.
-     *
-     * @example
-     * ```typescript
-     * // In your route handler
-     * const response = await kavach.passwordReset?.handleRequest(request);
-     * if (response) return response;
-     *
-     * // Or programmatically
-     * await kavach.passwordReset?.requestReset('alice@example.com');
-     * await kavach.passwordReset?.resetPassword(token, 'new-password');
-     * ```
-     */
-    passwordReset: PasswordResetModule | null;
-    /**
-     * Email address verification.
-     *
-     * Null when `emailVerification` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * // Send a verification email after sign-up
-     * await kavach.emailVerification?.sendVerification(userId, email);
-     *
-     * // Confirm from the link in the email
-     * const result = await kavach.emailVerification?.verify(token);
-     *
-     * // Check status
-     * const verified = await kavach.emailVerification?.isVerified(userId);
-     * ```
-     */
-    emailVerification: EmailVerificationModule | null;
-    /**
-     * One-time tokens (email verify, password reset, invitations, custom).
-     *
-     * Always available. Used internally by password reset but exposed for
-     * custom flows (email verification, invitation links, etc.).
-     */
-    oneTimeTokens: OneTimeTokenModule;
-    /**
-     * Session freshness enforcement for sensitive operations.
-     *
-     * Use as middleware before password changes, passkey registration,
-     * billing updates, or any action that requires a recently-authenticated
-     * session rather than an auto-refreshed one.
-     *
-     * @example
-     * ```typescript
-     * const stale = kavach.sessionFreshness.guard(session);
-     * if (stale) return stale; // 403 SESSION_NOT_FRESH
-     * ```
-     */
-    sessionFreshness: SessionFreshnessModule;
-    /**
-     * Phone number (SMS OTP) authentication.
-     *
-     * Null when `phone` config was not provided or `auth.session` is not
-     * configured.
-     *
-     * @example
-     * ```typescript
-     * const response = await kavach.phone?.handleRequest(request);
-     * if (response) return response;
-     * ```
-     */
-    phone: PhoneAuthModule | null;
-    /**
-     * Captcha integration (reCAPTCHA, hCaptcha, Cloudflare Turnstile).
-     *
-     * Null when `captcha` config was not provided.
-     *
-     * @example
-     * ```typescript
-     * const result = await kavach.captcha?.verify(token, ip);
-     * if (!result?.success) return new Response('Captcha failed', { status: 403 });
-     * ```
-     */
-    captcha: CaptchaModule | null;
-    /**
-     * Webhook system.
-     *
-     * Null when `webhooks` config was not provided or the array is empty.
-     *
-     * @example
-     * ```typescript
-     * kavach.webhooks?.emit('user.created', { userId: user.id });
-     * ```
-     */
-    webhooks: WebhookModule$1 | null;
-    /**
-     * Redirect chain manager.
-     *
-     * Capture the user's original destination before auth redirects, push
-     * intermediate steps (onboarding, email verification), and pop them
-     * back in order. Cookie-based, works across page transitions and tabs.
-     *
-     * @example
-     * ```typescript
-     * // In auth middleware — save where the user was going
-     * const setCookie = kavach.redirects.capture(request);
-     * return new Response(null, { status: 302, headers: { Location: '/sign-in', 'Set-Cookie': setCookie } });
-     *
-     * // After sign-in — send user to their original destination
-     * const { url, clearCookie } = kavach.redirects.pop(request);
-     * const headers: Record<string, string> = { Location: url };
-     * if (clearCookie) headers['Set-Cookie'] = clearCookie;
-     * return new Response(null, { status: 302, headers });
-     * ```
-     */
-    redirects: RedirectChainManager;
-    /**
-     * Unified policy engine.
-     *
-     * Single decision point that combines RBAC role expansion, ABAC constraint
-     * evaluation, and ReBAC graph queries. Backed by a process-local LRU cache
-     * with deterministic invalidation.
-     *
-     * @example
-     * ```typescript
-     * const decision = await kavach.policy.evaluate({
-     *   subject: { agentId: 'agent-abc' },
-     *   action: 'read',
-     *   resource: 'tool:github:list_issues',
-     * });
-     * if (!decision.allowed) throw new Error(decision.reason);
-     *
-     * // Flush cached decisions after a permission change
-     * kavach.policy.invalidate({ agentId: 'agent-abc' });
-     *
-     * // Inspect cache health
-     * const { hits, misses, size, evictions } = kavach.policy.stats();
-     * ```
-     */
-    policy: {
-        evaluate: (input: EvaluateInput) => Promise<PolicyDecision>;
-        invalidate: (scope: InvalidateScope) => void;
-        stats: () => PolicyCacheStats;
-    };
-    /**
-     * Plugin system.
-     *
-     * Route incoming HTTP requests through plugin-registered endpoints,
-     * retrieve all endpoints for adapter mounting, or access plugin-provided
-     * context values.
-     *
-     * @example
-     * ```typescript
-     * // In a framework adapter
-     * app.all('/kavach/*', async (req) => {
-     *   const response = await kavach.plugins.handleRequest(req);
-     *   if (response) return response;
-     *   return new Response('Not Found', { status: 404 });
-     * });
-     * ```
-     */
-    plugins: {
-        /** Route a request through plugin endpoints. Returns null if no plugin handles it. */
-        handleRequest(request: Request, basePath?: string): Promise<Response | null>;
-        /** Get all endpoints registered by plugins (for framework adapter mounting). */
-        getEndpoints(): PluginEndpoint[];
-        /** Get the merged plugin context (values returned from plugin init). */
-        getContext(): Record<string, unknown>;
-        /** Access the raw plugin registry (hooks, migrations, etc.). */
-        registry: PluginRegistry;
-    };
-}>;
-type TheAuth = Awaited<ReturnType<typeof createTheAuth>>;
+    secure?: boolean;
+    /** Controls cross-site sending. Default: 'lax'. */
+    sameSite?: SameSite;
+    /** Cookie scope path. Default: '/'. */
+    path?: string;
+    /** Cookie scope domain (omitted when not set). */
+    domain?: string;
+    /** Lifetime in seconds from now. Sets both Max-Age and Expires. */
+    maxAge?: number;
+    /** Absolute expiry date (overridden by maxAge when both are set). */
+    expires?: Date;
+    /** Partitioned attribute (CHIPS). */
+    partitioned?: boolean;
+}
 /**
- * @deprecated Use `createTheAuth` instead. Will be removed in a future major version.
+ * Serialize a cookie name/value pair into a `Set-Cookie` header string.
+ *
+ * @param name    Cookie name. Must be a valid cookie-name token.
+ * @param value   Cookie value. Will be percent-encoded.
+ * @param options Cookie attributes. Defaults to `httpOnly=true`, `secure`
+ *                based on `NODE_ENV`, `sameSite=lax`, `path=/`.
  */
-declare const createAuth: typeof createTheAuth;
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
 /**
- * @deprecated Use `createTheAuth` instead. Will be removed in a future major version.
+ * Serialize a deletion cookie (zero Max-Age, past Expires) that will
+ * instruct browsers to remove the named cookie.
  */
-declare const createKavach: typeof createTheAuth;
+declare function serializeCookieDeletion(name: string, options?: Omit<CookieOptions, "maxAge" | "expires">): string;
 /**
- * @deprecated Use `TheAuth` instead. Will be removed in a future major version.
+ * Parse a `Cookie` request header string into a name → value map.
+ *
+ * Values are percent-decoded. Unknown or malformed pairs are skipped
+ * silently so that a single bad cookie does not break the entire request.
+ *
+ * @param header The raw value of the `Cookie` header (e.g. `"a=1; b=2"`).
  */
-type Auth = TheAuth;
+declare function parseCookies(header: string): Record<string, string>;
 /**
- * @deprecated Use `TheAuth` instead. Will be removed in a future major version.
+ * Extract a single cookie value from a `Cookie` header string.
+ *
+ * Returns `undefined` when the cookie is absent.
+ */
+declare function getCookie(header: string, name: string): string | undefined;
+/**
+ * Extract cookies from a Web API `Request` object.
  */
-type Kavach = TheAuth;
+declare function parseCookiesFromRequest(request: Request): Record<string, string>;
 
 /**
- * OpenAPI 3.1 specification generator for TheAuth REST API.
+ * CSRF protection utilities for TheAuth.
+ *
+ * Implements two complementary defences:
+ *
+ * 1. **Origin/Referer validation** — checks the inbound request's `Origin`
+ *    (or `Referer` as fallback) against a caller-supplied allowlist.  This
+ *    alone blocks the vast majority of CSRF attacks from browser clients.
+ *
+ * 2. **Double-submit cookie pattern** — a random token is stored in a cookie
+ *    AND submitted by the client as a request header (or body field). The
+ *    server verifies both values match using a timing-safe comparison.
+ *
+ * Use origin validation first; fall back to token comparison when the origin
+ * header is absent (e.g. same-origin requests on some browsers, server-side
+ * fetch).
+ *
+ * @example
+ * ```typescript
+ * import { generateCsrfToken, validateCsrfToken, validateOrigin } from './csrf.js';
+ *
+ * // On form render: store token in cookie, embed in hidden field.
+ * const token = await generateCsrfToken();
+ *
+ * // On form submit:
+ * const originOk = validateOrigin(request, ['https://app.example.com']);
+ * const tokenOk  = validateCsrfToken(submittedToken, cookieToken);
+ * if (!originOk && !tokenOk) throw new Error('CSRF check failed');
+ * ```
+ */
+interface CsrfValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Generate a cryptographically random CSRF token.
  *
- * This generates the spec that enables auto-generated SDKs
- * for Python, Go, Java, Rust, etc. via OpenAPI codegen tools.
+ * Uses `crypto.getRandomValues` (Web Crypto API) so it works in both
+ * Node.js ≥ 19 and browser/edge runtimes.
+ *
+ * Returns a URL-safe base64 string (~43 chars).
  */
-interface OpenAPISpec {
-    openapi: string;
-    info: {
-        title: string;
-        version: string;
-        description: string;
-    };
-    servers: Array<{
-        url: string;
-        description: string;
-    }>;
-    paths: Record<string, Record<string, PathOperation>>;
-    components: {
-        schemas: Record<string, SchemaObject>;
-        securitySchemes: Record<string, SecurityScheme>;
-    };
-}
-interface PathOperation {
-    summary: string;
-    operationId: string;
-    tags: string[];
-    security?: Array<Record<string, string[]>>;
-    parameters?: ParameterObject[];
-    requestBody?: {
-        required: boolean;
-        content: Record<string, {
-            schema: SchemaRef;
-        }>;
-    };
-    responses: Record<string, {
-        description: string;
-        content?: Record<string, {
-            schema: SchemaRef;
-        }>;
-    }>;
-}
-interface ParameterObject {
-    name: string;
-    in: "query" | "path" | "header";
-    required: boolean;
-    schema: SchemaRef;
-}
-interface SecurityScheme {
-    type: string;
-    scheme?: string;
-    bearerFormat?: string;
-}
-type SchemaRef = {
-    $ref: string;
-} | SchemaObject;
-interface SchemaObject {
-    type?: string;
-    properties?: Record<string, SchemaRef>;
-    required?: string[];
-    items?: SchemaRef;
-    enum?: string[];
-    description?: string;
-    format?: string;
-    nullable?: boolean;
-}
+declare function generateCsrfToken(): string;
 /**
- * Generate the full OpenAPI 3.1 specification for the TheAuth REST API.
+ * Validate a CSRF token from the request against the value stored in the
+ * cookie using a constant-time comparison to prevent timing attacks.
+ *
+ * Both `requestToken` and `cookieToken` must be non-empty strings produced
+ * by `generateCsrfToken()`. Any mismatch returns `{ valid: false }`.
+ *
+ * @param requestToken  Token submitted with the request (header / body).
+ * @param cookieToken   Token read from the CSRF cookie.
  */
-declare function generateOpenAPISpec(options?: {
-    baseUrl?: string;
-    version?: string;
-}): OpenAPISpec;
-
+declare function validateCsrfToken(requestToken: string, cookieToken: string): CsrfValidationResult;
 /**
- * Create a plugin router that matches requests to registered plugin endpoints.
+ * Validate the `Origin` (or `Referer` fallback) header of an incoming
+ * request against a list of trusted origins.
  *
- * The router strips `basePath` from the request URL before matching so plugins
- * register paths relative to the mount point (e.g. `/auth/sign-in` instead
- * of `/api/kavach/auth/sign-in`).
+ * Rules:
+ * - If `Origin` is present and matches a trusted origin → valid.
+ * - If `Origin` is `"null"` (opaque origin) → invalid.
+ * - If `Origin` is absent, falls back to the `Referer` header.
+ * - If neither header is present → result depends on `allowMissingOrigin`.
+ *
+ * @param request            Incoming Web API `Request`.
+ * @param trustedOrigins     Array of allowed origins, e.g. `['https://app.example.com']`.
+ *                           Trailing slashes are stripped before comparison.
+ * @param allowMissingOrigin When `true`, requests without an `Origin` or
+ *                           `Referer` header are considered valid (useful for
+ *                           server-to-server calls). Defaults to `false`.
  */
-declare function createPluginRouter(endpoints: PluginEndpoint[]): {
-    /** Try to handle a request. Returns Response if matched, null if not. */
-    handle: (request: Request, basePath: string, endpointCtx: EndpointContext) => Promise<Response | null>;
-    /** Get all registered endpoints (for adapter mounting) */
-    getEndpoints: () => PluginEndpoint[];
-};
+declare function validateOrigin(request: Request, trustedOrigins: string[], allowMissingOrigin?: boolean): CsrfValidationResult;
 
-interface PluginRegistry {
-    endpoints: PluginEndpoint[];
-    migrations: string[];
-    hooks: {
-        onRequest: Array<NonNullable<TheAuthPlugin["hooks"]>["onRequest"]>;
-        onAuthenticate: Array<NonNullable<TheAuthPlugin["hooks"]>["onAuthenticate"]>;
-        onSessionCreate: Array<NonNullable<TheAuthPlugin["hooks"]>["onSessionCreate"]>;
-        onSessionRevoke: Array<NonNullable<TheAuthPlugin["hooks"]>["onSessionRevoke"]>;
-    };
-    pluginContext: Record<string, unknown>;
-}
 /**
- * Initialize all plugins and collect their endpoints, migrations, and hooks
- * into a single registry.
+ * Cookie-aware session manager for TheAuth.
  *
- * Calls each plugin's `init()` in registration order.  Migrations collected
- * during init are executed before the registry is returned so that any
- * subsequent requests can immediately use plugin tables.
+ * Wraps the lower-level `createSessionManager` with cookie serialization and
+ * optional CSRF protection so callers work with `Request`/`Response` objects
+ * directly rather than managing raw tokens and headers themselves.
+ *
+ * @example
+ * ```typescript
+ * import { createCookieSessionManager } from './manager.js';
+ *
+ * const sessions = createCookieSessionManager(
+ *   { secret: process.env.SESSION_SECRET },
+ *   db,
+ * );
+ *
+ * // On login
+ * const { session, setCookieHeader } = await sessions.createSession(user.id);
+ * return new Response(null, {
+ *   status: 302,
+ *   headers: { Location: '/dashboard', 'Set-Cookie': setCookieHeader },
+ * });
+ *
+ * // On each request
+ * const session = await sessions.validateSession(request.headers.get('cookie') ?? '');
+ * if (!session) return new Response('Unauthorized', { status: 401 });
+ *
+ * // On logout
+ * const deleteCookie = sessions.buildLogoutCookie();
+ * return new Response(null, {
+ *   status: 302,
+ *   headers: { Location: '/login', 'Set-Cookie': deleteCookie },
+ * });
+ * ```
  */
-declare function initializePlugins(plugins: TheAuthPlugin[], db: Database, config: TheAuthConfig, sessionManager: SessionManager | null): Promise<PluginRegistry>;
 
-interface BudgetPolicy {
-    id: string;
-    agentId?: string;
-    userId?: string;
-    tenantId?: string;
-    limits: BudgetLimits;
-    currentUsage: BudgetUsage;
-    action: "warn" | "throttle" | "block" | "revoke";
-    status: "active" | "triggered" | "disabled";
-    createdAt: Date;
-}
-interface BudgetLimits {
-    maxTokensCostPerDay?: number;
-    maxTokensCostPerMonth?: number;
-    maxCallsPerDay?: number;
-    maxCallsPerMonth?: number;
-}
-interface BudgetUsage {
-    tokensCostToday: number;
-    tokensCostThisMonth: number;
-    callsToday: number;
-    callsThisMonth: number;
-    lastUpdated: string;
+interface CookieSessionConfig extends SessionConfig {
+    /**
+     * Name of the session cookie.
+     * Defaults to `"theauth_session"`.
+     */
+    sessionName?: string;
+    /**
+     * Additional cookie attributes applied when setting the session cookie.
+     * `maxAge` is derived from `SessionConfig.maxAge` when not explicitly set.
+     */
+    cookieOptions?: Omit<CookieOptions, "maxAge">;
+    /**
+     * When `true`, `validateSession` automatically refreshes the session
+     * expiry on every successful validation.  Defaults to `true`.
+     */
+    autoRefresh?: boolean;
 }
-interface CreatePolicyInput {
-    agentId?: string;
-    userId?: string;
-    tenantId?: string;
-    limits: BudgetLimits;
-    action: "warn" | "throttle" | "block" | "revoke";
+interface CreateSessionResult {
+    /** The persisted session record. */
+    session: Session;
+    /** Ready-to-use `Set-Cookie` header value. */
+    setCookieHeader: string;
 }
-interface PolicyFilters {
-    agentId?: string;
-    userId?: string;
-    tenantId?: string;
+interface ValidateSessionResult {
+    /** The valid session, or `null` when the cookie is absent/invalid/expired. */
+    session: Session | null;
+    /**
+     * When `autoRefresh` is enabled and the session was valid, the refreshed
+     * `Set-Cookie` header to forward to the client. `null` otherwise.
+     */
+    refreshCookieHeader: string | null;
 }
-declare function createPolicyModule(db: Database): {
-    create: (input: CreatePolicyInput) => Promise<BudgetPolicy>;
-    get: (policyId: string) => Promise<BudgetPolicy | null>;
-    list: (filters?: PolicyFilters) => Promise<BudgetPolicy[]>;
-    update: (policyId: string, updates: Partial<BudgetPolicy>) => Promise<BudgetPolicy>;
-    remove: (policyId: string) => Promise<void>;
-    checkBudget: (agentId: string, tokensCost?: number) => Promise<{
-        allowed: boolean;
-        reason?: string;
-        policy?: BudgetPolicy;
-    }>;
-    recordUsage: (agentId: string, tokensCost?: number) => Promise<void>;
-    resetDaily: () => Promise<{
-        reset: number;
+interface CookieSessionManager {
+    /**
+     * Create a new session for the given user and return the session record
+     * together with a `Set-Cookie` header string ready to attach to a response.
+     */
+    createSession(userId: string, metadata?: Record<string, unknown>): Promise<CreateSessionResult>;
+    /**
+     * Parse the `Cookie` header, look up the session in the database, and
+     * verify it has not expired.
+     *
+     * When `autoRefresh` is enabled the session is extended on each valid
+     * request and a new `Set-Cookie` header is returned for forwarding.
+     *
+     * @param cookieHeader Raw value of the `Cookie` request header.
+     */
+    validateSession(cookieHeader: string): Promise<ValidateSessionResult>;
+    /**
+     * Extend the session expiry to `now + maxAge`.
+     *
+     * Returns the updated session and a fresh `Set-Cookie` header.
+     * Returns `null` when the session does not exist.
+     */
+    refreshSession(sessionId: string): Promise<{
+        session: Session;
+        setCookieHeader: string;
+    } | null>;
+    /**
+     * Delete a session by ID (server-side) and return a deletion cookie that
+     * will clear the browser cookie on the next response.
+     */
+    revokeSession(sessionId: string): Promise<{
+        deleteCookieHeader: string;
     }>;
-    resetMonthly: () => Promise<{
-        reset: number;
+    /**
+     * Revoke all sessions for the given user.
+     *
+     * Returns a deletion cookie header for clearing the current browser cookie.
+     */
+    revokeAllSessions(userId: string): Promise<{
+        deleteCookieHeader: string;
     }>;
-};
-
-/**
- * Cookie serialization and parsing utilities for TheAuth.
- *
- * Pure functions that work with Web API `Request`/`Response` objects and
- * raw header strings. No framework dependencies.
- */
-type SameSite = "strict" | "lax" | "none";
-interface CookieOptions {
-    /** Prevents JavaScript access to the cookie. Default: true. */
-    httpOnly?: boolean;
     /**
-     * Restricts transmission to HTTPS. Default: true in production
-     * (when `NODE_ENV === 'production'`), false otherwise.
+     * List all non-expired sessions for a user, newest first.
      */
-    secure?: boolean;
-    /** Controls cross-site sending. Default: 'lax'. */
-    sameSite?: SameSite;
-    /** Cookie scope path. Default: '/'. */
-    path?: string;
-    /** Cookie scope domain (omitted when not set). */
-    domain?: string;
-    /** Lifetime in seconds from now. Sets both Max-Age and Expires. */
-    maxAge?: number;
-    /** Absolute expiry date (overridden by maxAge when both are set). */
-    expires?: Date;
-    /** Partitioned attribute (CHIPS). */
-    partitioned?: boolean;
+    listSessions(userId: string): Promise<Session[]>;
+    /**
+     * Build a `Set-Cookie` header that deletes the session cookie on the client
+     * without any database operation.  Useful in error paths.
+     */
+    buildLogoutCookie(): string;
+    /** Expose the underlying low-level session manager for advanced usage. */
+    raw: SessionManager;
 }
 /**
- * Serialize a cookie name/value pair into a `Set-Cookie` header string.
- *
- * @param name    Cookie name. Must be a valid cookie-name token.
- * @param value   Cookie value. Will be percent-encoded.
- * @param options Cookie attributes. Defaults to `httpOnly=true`, `secure`
- *                based on `NODE_ENV`, `sameSite=lax`, `path=/`.
- */
-declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
-/**
- * Serialize a deletion cookie (zero Max-Age, past Expires) that will
- * instruct browsers to remove the named cookie.
- */
-declare function serializeCookieDeletion(name: string, options?: Omit<CookieOptions, "maxAge" | "expires">): string;
-/**
- * Parse a `Cookie` request header string into a name → value map.
- *
- * Values are percent-decoded. Unknown or malformed pairs are skipped
- * silently so that a single bad cookie does not break the entire request.
+ * Create a cookie-aware session manager.
  *
- * @param header The raw value of the `Cookie` header (e.g. `"a=1; b=2"`).
- */
-declare function parseCookies(header: string): Record<string, string>;
-/**
- * Extract a single cookie value from a `Cookie` header string.
+ * Internally delegates all DB operations to `createSessionManager`.
  *
- * Returns `undefined` when the cookie is absent.
- */
-declare function getCookie(header: string, name: string): string | undefined;
-/**
- * Extract cookies from a Web API `Request` object.
+ * @param config Cookie-aware session configuration.
+ * @param db     Drizzle database instance from `createDatabase()`.
  */
-declare function parseCookiesFromRequest(request: Request): Record<string, string>;
+declare function createCookieSessionManager(config: CookieSessionConfig, db: Database): CookieSessionManager;
 
 /**
- * CSRF protection utilities for TheAuth.
- *
- * Implements two complementary defences:
- *
- * 1. **Origin/Referer validation** — checks the inbound request's `Origin`
- *    (or `Referer` as fallback) against a caller-supplied allowlist.  This
- *    alone blocks the vast majority of CSRF attacks from browser clients.
+ * Multi-session support for TheAuth.
  *
- * 2. **Double-submit cookie pattern** — a random token is stored in a cookie
- *    AND submitted by the client as a request header (or body field). The
- *    server verifies both values match using a timing-safe comparison.
+ * Allows users to maintain multiple concurrent sessions (phone, laptop, tablet)
+ * with optional per-user session caps. When the cap is reached, the oldest
+ * session is evicted automatically (configurable).
  *
- * Use origin validation first; fall back to token comparison when the origin
- * header is absent (e.g. same-origin requests on some browsers, server-side
- * fetch).
+ * Uses the existing `theauth_sessions` table — no additional schema required.
  *
  * @example
  * ```typescript
- * import { generateCsrfToken, validateCsrfToken, validateOrigin } from './csrf.js';
+ * const multiSession = createMultiSessionModule(
+ *   { maxSessions: 5, overflowStrategy: 'evict-oldest' },
+ *   db,
+ *   sessionManager,
+ * );
  *
- * // On form render: store token in cookie, embed in hidden field.
- * const token = await generateCsrfToken();
+ * // List all active sessions for a user
+ * const sessionList = await multiSession.listSessions(userId);
  *
- * // On form submit:
- * const originOk = validateOrigin(request, ['https://app.example.com']);
- * const tokenOk  = validateCsrfToken(submittedToken, cookieToken);
- * if (!originOk && !tokenOk) throw new Error('CSRF check failed');
+ * // Sign out everywhere except here
+ * const count = await multiSession.revokeOtherSessions(userId, currentSessionId);
  * ```
  */
-interface CsrfValidationResult {
-    valid: boolean;
-    reason?: string;
+
+interface MultiSessionConfig {
+    /** Max concurrent sessions per user (default: 10) */
+    maxSessions?: number;
+    /** Strategy when max is reached (default: 'evict-oldest') */
+    overflowStrategy?: "reject" | "evict-oldest";
+}
+interface SessionInfo {
+    id: string;
+    createdAt: Date;
+    expiresAt: Date;
+    metadata?: Record<string, unknown>;
+    /** Human-readable device string extracted from User-Agent, e.g. "Chrome on macOS" */
+    device?: string;
+    /** IP address recorded at session creation */
+    ip?: string;
+}
+interface MultiSessionModule {
+    /** List all non-expired sessions for a user, newest first. */
+    listSessions(userId: string): Promise<SessionInfo[]>;
+    /** Revoke a single session by ID. */
+    revokeSession(sessionId: string): Promise<void>;
+    /** Revoke every session except the given one. Returns the count revoked. */
+    revokeOtherSessions(userId: string, currentSessionId: string): Promise<number>;
+    /** Return the count of active (non-expired) sessions for a user. */
+    getSessionCount(userId: string): Promise<number>;
+    /**
+     * Enforce the session cap before creating a new session.
+     *
+     * Call this before `sessionManager.create()`. If the cap is reached:
+     * - `evict-oldest` deletes the oldest session and resolves.
+     * - `reject` throws a `MultiSessionLimitError`.
+     */
+    enforceSessionLimit(userId: string): Promise<void>;
+}
+declare class MultiSessionLimitError extends Error {
+    readonly code = "SESSION_LIMIT_REACHED";
+    constructor(userId: string, max: number);
 }
+declare function createMultiSessionModule(config: MultiSessionConfig, db: Database, sessionManager: SessionManager): MultiSessionModule;
 /**
- * Generate a cryptographically random CSRF token.
- *
- * Uses `crypto.getRandomValues` (Web Crypto API) so it works in both
- * Node.js ≥ 19 and browser/edge runtimes.
+ * Build metadata to pass to `sessionManager.create()` that includes
+ * device info extracted from the incoming request.
  *
- * Returns a URL-safe base64 string (~43 chars).
+ * @example
+ * ```typescript
+ * const meta = buildSessionMetadata(request, { role: 'admin' });
+ * const { token } = await sessionManager.create(userId, meta);
+ * ```
  */
-declare function generateCsrfToken(): string;
+declare function buildSessionMetadata(request: Request, extra?: Record<string, unknown>): Record<string, unknown>;
+
 /**
- * Validate a CSRF token from the request against the value stored in the
- * cookie using a constant-time comparison to prevent timing attacks.
+ * Token family tracking for refresh token reuse detection.
  *
- * Both `requestToken` and `cookieToken` must be non-empty strings produced
- * by `generateCsrfToken()`. Any mismatch returns `{ valid: false }`.
+ * Each refresh token belongs to a "family" — a chain of rotations that all
+ * originate from the same initial login.  When `reuseDetection` is enabled,
+ * presenting an already-used token from a family immediately revokes every
+ * token in that family, because reuse indicates the token was stolen.
  *
- * @param requestToken  Token submitted with the request (header / body).
- * @param cookieToken   Token read from the CSRF cookie.
+ * The database table `theauth_refresh_token_families` stores:
+ *   - family-level metadata (userId, absolute expiry, revocation status)
+ *
+ * Each individual refresh token row in `theauth_refresh_tokens` links back to
+ * its family via `familyId`.
+ *
+ * @example
+ * ```typescript
+ * const families = createTokenFamilyStore(db);
+ *
+ * // On login — create a new family and issue the first token
+ * const family = await families.createFamily(userId, absoluteExpiresAt);
+ * const token = await families.issueToken(family.id, refreshTokenTTL);
+ *
+ * // On refresh — consume the token (marks it used, issues a new one)
+ * const result = await families.consumeToken(rawToken);
+ * if (result.status === 'reuse') {
+ *   // Entire family revoked — force re-login
+ * }
+ * ```
  */
-declare function validateCsrfToken(requestToken: string, cookieToken: string): CsrfValidationResult;
+
+interface TokenFamily {
+    id: string;
+    userId: string;
+    /** Absolute expiry — no refresh can extend beyond this date. */
+    absoluteExpiresAt: Date;
+    revoked: boolean;
+    createdAt: Date;
+}
+type ConsumeTokenStatus = "ok" /** Token valid, successfully consumed. */ | "expired" /** Token has passed its TTL. */ | "revoked" /** Entire family has been revoked (stolen token detected). */ | "reuse" /** Token was already used — family has now been revoked. */ | "not_found"; /** Token does not exist in the database. */
+interface ConsumeTokenResult {
+    status: ConsumeTokenStatus;
+    /** Populated when status is `"ok"`. */
+    family?: TokenFamily;
+}
+interface TokenFamilyStore {
+    /**
+     * Create a new token family for a user.
+     * Call this once per login to anchor the refresh token chain.
+     */
+    createFamily(userId: string, absoluteExpiresAt: Date): Promise<TokenFamily>;
+    /**
+     * Issue a new opaque refresh token tied to the given family.
+     *
+     * Returns the raw token string (only returned once — never stored in the
+     * clear) and the token's individual expiry date.
+     */
+    issueToken(familyId: string, ttlMs: number): Promise<{
+        rawToken: string;
+        expiresAt: Date;
+    }>;
+    /**
+     * Consume a refresh token.
+     *
+     * - If the token is valid and unused, it is marked `used` and the caller
+     *   should immediately call `issueToken` to rotate.
+     * - If the token was already used, the **entire family is revoked** (reuse
+     *   detection — token theft assumed).
+     * - If the token has expired or is not found, returns the appropriate status.
+     */
+    consumeToken(rawToken: string): Promise<ConsumeTokenResult>;
+    /**
+     * Revoke all token families (and their tokens) for a user.
+     * Used on logout, password change, or explicit session termination.
+     */
+    revokeFamiliesForUser(userId: string): Promise<void>;
+    /**
+     * Revoke a specific family by ID and all its tokens.
+     */
+    revokeFamily(familyId: string): Promise<void>;
+    /**
+     * Check whether the absolute session timeout has been reached for a family.
+     * Returns `true` when the family is still within its absolute timeout.
+     */
+    isFamilyActive(family: TokenFamily): boolean;
+}
 /**
- * Validate the `Origin` (or `Referer` fallback) header of an incoming
- * request against a list of trusted origins.
- *
- * Rules:
- * - If `Origin` is present and matches a trusted origin → valid.
- * - If `Origin` is `"null"` (opaque origin) → invalid.
- * - If `Origin` is absent, falls back to the `Referer` header.
- * - If neither header is present → result depends on `allowMissingOrigin`.
- *
- * @param request            Incoming Web API `Request`.
- * @param trustedOrigins     Array of allowed origins, e.g. `['https://app.example.com']`.
- *                           Trailing slashes are stripped before comparison.
- * @param allowMissingOrigin When `true`, requests without an `Origin` or
- *                           `Referer` header are considered valid (useful for
- *                           server-to-server calls). Defaults to `false`.
+ * Create a `TokenFamilyStore` backed by the TheAuth database.
  */
-declare function validateOrigin(request: Request, trustedOrigins: string[], allowMissingOrigin?: boolean): CsrfValidationResult;
+declare function createTokenFamilyStore(db: Database): TokenFamilyStore;
 
 /**
- * Cookie-aware session manager for TheAuth.
+ * Session refresh endpoint handler for TheAuth.
  *
- * Wraps the lower-level `createSessionManager` with cookie serialization and
- * optional CSRF protection so callers work with `Request`/`Response` objects
- * directly rather than managing raw tokens and headers themselves.
+ * Implements `POST /auth/refresh`:
+ * 1. Extracts the refresh token from an httpOnly cookie or the request body.
+ * 2. Validates the token (TTL, reuse detection, absolute timeout).
+ * 3. Issues a new short-lived access token (signed JWT).
+ * 4. Rotates the refresh token (one-time use — the old one is consumed).
+ * 5. Records the rotation in the audit log.
+ *
+ * Token family tracking (via `createTokenFamilyStore`) provides reuse
+ * detection: if an attacker uses a stolen refresh token after the legitimate
+ * user has already rotated it, the entire family is revoked and both parties
+ * are forced to re-authenticate.
  *
  * @example
  * ```typescript
- * import { createCookieSessionManager } from './manager.js';
- *
- * const sessions = createCookieSessionManager(
- *   { secret: process.env.SESSION_SECRET },
+ * const refresher = createSessionRefresher({
+ *   secret: process.env.SESSION_SECRET,
+ *   session: {
+ *     accessTokenTTL:    "15m",
+ *     refreshTokenTTL:   "30d",
+ *     absoluteTimeout:   "90d",
+ *     rotateRefreshTokens: true,
+ *     reuseDetection:    true,
+ *   },
  *   db,
- * );
- *
- * // On login
- * const { session, setCookieHeader } = await sessions.createSession(user.id);
- * return new Response(null, {
- *   status: 302,
- *   headers: { Location: '/dashboard', 'Set-Cookie': setCookieHeader },
  * });
  *
- * // On each request
- * const session = await sessions.validateSession(request.headers.get('cookie') ?? '');
- * if (!session) return new Response('Unauthorized', { status: 401 });
- *
- * // On logout
- * const deleteCookie = sessions.buildLogoutCookie();
- * return new Response(null, {
- *   status: 302,
- *   headers: { Location: '/login', 'Set-Cookie': deleteCookie },
+ * // In your Hono / Express router:
+ * app.post('/auth/refresh', async (ctx) => {
+ *   const result = await refresher.handleRequest(ctx.req.raw);
+ *   return result.response;
  * });
  * ```
  */
 
-interface CookieSessionConfig extends SessionConfig {
+interface RefreshSessionConfig {
     /**
-     * Name of the session cookie.
-     * Defaults to `"kavach_session"`.
+     * Short-lived access token lifetime.
+     * Parsed duration string, e.g. `"15m"`.
+     * Defaults to `"15m"`.
      */
-    sessionName?: string;
+    accessTokenTTL?: string;
     /**
-     * Additional cookie attributes applied when setting the session cookie.
-     * `maxAge` is derived from `SessionConfig.maxAge` when not explicitly set.
+     * Long-lived refresh token lifetime.
+     * Parsed duration string, e.g. `"30d"`.
+     * Defaults to `"30d"`.
      */
-    cookieOptions?: Omit<CookieOptions, "maxAge">;
+    refreshTokenTTL?: string;
     /**
-     * When `true`, `validateSession` automatically refreshes the session
-     * expiry on every successful validation.  Defaults to `true`.
+     * When `true` (default), each use of a refresh token rotates it: the old
+     * token is invalidated and a new one is issued.
      */
-    autoRefresh?: boolean;
+    rotateRefreshTokens?: boolean;
+    /**
+     * Maximum session lifetime regardless of how many times the token is
+     * refreshed.  Parsed duration string, e.g. `"90d"`.
+     * Defaults to `"90d"`.
+     */
+    absoluteTimeout?: string;
+    /**
+     * When `true` (default), presenting an already-used refresh token triggers
+     * reuse detection and revokes the entire token family.
+     */
+    reuseDetection?: boolean;
+    /**
+     * Name of the httpOnly cookie that carries the refresh token.
+     * Defaults to `"theauth_refresh"`.
+     */
+    refreshCookieName?: string;
+    /**
+     * Name of the httpOnly cookie that carries the access token (when cookie
+     * transport is used for the access token too).
+     * Defaults to `"theauth_access"`.
+     */
+    accessCookieName?: string;
 }
-interface CreateSessionResult {
-    /** The persisted session record. */
-    session: Session;
-    /** Ready-to-use `Set-Cookie` header value. */
-    setCookieHeader: string;
+interface SessionRefresherConfig {
+    /** Signing secret — at least 32 characters. */
+    secret: string;
+    /** Refresh / rotation settings. */
+    session?: RefreshSessionConfig;
+    /** Drizzle database instance. */
+    db: Database;
 }
-interface ValidateSessionResult {
-    /** The valid session, or `null` when the cookie is absent/invalid/expired. */
-    session: Session | null;
+/** The payload embedded in the short-lived access token JWT. */
+interface AccessTokenPayload {
+    /** User ID. */
+    sub: string;
+    /** Token family ID — used for server-side token binding. */
+    familyId: string;
+    /** Token type discriminator. */
+    type: "access";
+}
+interface RefreshResult {
+    /** Signed access token JWT. */
+    accessToken: string;
+    /** Raw opaque refresh token (only returned once — store in httpOnly cookie). */
+    refreshToken: string;
+    /** Expiry date of the new access token. */
+    accessTokenExpiresAt: Date;
+    /** Expiry date of the new refresh token. */
+    refreshTokenExpiresAt: Date;
+    /** The token family these tokens belong to. */
+    family: TokenFamily;
+}
+type RefreshError = "token_missing" | "token_not_found" | "token_expired" | "token_reuse" | "family_revoked" | "absolute_timeout";
+interface RefreshHandleResult {
+    /** HTTP Response ready to return to the caller. */
+    response: Response;
+    /** Populated on success. */
+    result?: RefreshResult;
+    /** Populated on failure. */
+    error?: RefreshError;
+}
+interface SessionRefresher {
+    /**
+     * Low-level refresh — takes a raw refresh token string directly.
+     *
+     * Returns `RefreshResult` on success or throws a `RefreshTokenError`.
+     */
+    refresh(rawRefreshToken: string): Promise<RefreshResult>;
+    /**
+     * High-level HTTP handler.
+     *
+     * Extracts the refresh token from the `Cookie` header (preferred) or the
+     * JSON request body, calls `refresh()`, and returns a `Response` with
+     * appropriate `Set-Cookie` headers.
+     */
+    handleRequest(request: Request): Promise<RefreshHandleResult>;
+    /**
+     * Issue an initial refresh token for a user (called once on login).
+     *
+     * Returns the access token, refresh token, and their expiry dates.
+     */
+    issueInitial(userId: string): Promise<RefreshResult>;
+    /**
+     * Revoke all refresh token families for a user (e.g. on logout or
+     * password change).
+     */
+    revokeAll(userId: string): Promise<void>;
+}
+/** Thrown by `SessionRefresher.refresh()` on validation failure. */
+declare class RefreshTokenError extends Error {
+    readonly code: RefreshError;
+    constructor(code: RefreshError, message: string);
+}
+/**
+ * Create a `SessionRefresher` backed by the TheAuth database.
+ */
+declare function createSessionRefresher(config: SessionRefresherConfig): SessionRefresher;
+
+interface Tenant {
+    id: string;
+    name: string;
+    slug: string;
+    settings: TenantSettings;
+    status: "active" | "suspended";
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface TenantSettings {
+    maxAgents?: number;
+    maxDelegationDepth?: number;
+    auditRetentionDays?: number;
+    allowedAgentTypes?: string[];
+}
+interface CreateTenantInput {
+    name: string;
+    slug: string;
+    settings?: Partial<TenantSettings>;
+}
+declare function createTenantModule(db: Database): {
+    create: (input: CreateTenantInput) => Promise<Tenant>;
+    get: (tenantId: string) => Promise<Tenant | null>;
+    getBySlug: (slug: string) => Promise<Tenant | null>;
+    list: () => Promise<Tenant[]>;
+    update: (tenantId: string, updates: Partial<CreateTenantInput>) => Promise<Tenant>;
+    suspend: (tenantId: string) => Promise<void>;
+    activate: (tenantId: string) => Promise<void>;
+};
+
+/**
+ * Create a TheAuth instance.
+ *
+ * The factory is **async** so it can open database connections for Postgres
+ * and MySQL (which require async driver initialisation) and optionally run
+ * `CREATE TABLE IF NOT EXISTS` for all schema tables.
+ *
+ * @example SQLite (simplest)
+ * ```typescript
+ * import { createTheAuth } from '@glinr/theauth';
+ *
+ * const auth = await createTheAuth({
+ *   database: { provider: 'sqlite', url: 'theauth.db' },
+ * });
+ * ```
+ *
+ * @example Postgres
+ * ```typescript
+ * const auth = await createTheAuth({
+ *   database: { provider: 'postgres', url: process.env.DATABASE_URL },
+ * });
+ * ```
+ *
+ * @example MySQL - skip auto-migration (tables managed externally)
+ * ```typescript
+ * const auth = await createTheAuth({
+ *   database: {
+ *     provider: 'mysql',
+ *     url: process.env.DATABASE_URL,
+ *     skipMigrations: true,
+ *   },
+ * });
+ * ```
+ */
+declare function createTheAuth(config: TheAuthConfig): Promise<{
+    agent: {
+        create(input: CreateAgentInput): ReturnType<(input: CreateAgentInput) => Promise<AgentIdentity & {
+            token: string;
+        }>>;
+        revoke(agentId: string): ReturnType<(agentId: string) => Promise<void>>;
+        rotate(agentId: string): ReturnType<(agentId: string) => Promise<AgentIdentity & {
+            token: string;
+        }>>;
+        get: (agentId: string) => Promise<AgentIdentity | null>;
+        list: (filter?: AgentFilter) => Promise<AgentIdentity[]>;
+        update: (agentId: string, input: UpdateAgentInput) => Promise<AgentIdentity>;
+        validateToken: (token: string) => Promise<AgentIdentity | null>;
+    };
+    authorize: (agentId: string, request: AuthorizeRequest, context?: RequestContext) => Promise<AuthorizeResult>;
+    authorizeByToken: (token: string, request: AuthorizeRequest, context?: RequestContext) => Promise<AuthorizeResult>;
+    delegate: (input: DelegateInput) => Promise<DelegationChain>;
+    delegation: {
+        revoke: (chainId: string) => Promise<void>;
+        getEffectivePermissions: (agentId: string) => Promise<Permission[]>;
+        listChains: (agentId: string) => Promise<DelegationChain[]>;
+    };
+    audit: {
+        query: (filter: AuditFilter) => Promise<AuditEntry[]>;
+        export: (options: AuditExportOptions) => Promise<string>;
+        cleanup: (options: {
+            retentionDays: number;
+        }) => Promise<{
+            deleted: number;
+        }>;
+    };
     /**
-     * When `autoRefresh` is enabled and the session was valid, the refreshed
-     * `Set-Cookie` header to forward to the client. `null` otherwise.
+     * MCP server registration.
+     *
+     * Register and look up MCP tool servers. Uses the `theauth_mcp_servers`
+     * database table — no separate in-memory store needed.
      */
-    refreshCookieHeader: string | null;
-}
-interface CookieSessionManager {
+    mcp: {
+        /**
+         * Register a new MCP tool server.
+         *
+         * Persists the server entry to the `theauth_mcp_servers` table.
+         * The returned record includes the generated `id` and `createdAt`.
+         */
+        register(input: McpServerInput): Promise<McpServer>;
+        /**
+         * List all registered MCP servers (active and inactive).
+         */
+        list(): Promise<McpServer[]>;
+        /**
+         * Get a single MCP server by ID. Returns null when not found.
+         */
+        get(id: string): Promise<McpServer | null>;
+    };
     /**
-     * Create a new session for the given user and return the session record
-     * together with a `Set-Cookie` header string ready to attach to a response.
+     * Least-privilege analyzer.
+     *
+     * Compare agent permissions against actual audit log usage to surface
+     * wildcards, unused grants, and over-permissioned identities.
      */
-    createSession(userId: string, metadata?: Record<string, unknown>): Promise<CreateSessionResult>;
+    analyzer: {
+        analyzeAgent: (agentId: string, options?: {
+            since?: Date;
+        }) => Promise<PrivilegeAnalysis>;
+        analyzeAll: (options?: {
+            since?: Date;
+        }) => Promise<PrivilegeAnalysis[]>;
+        getSummary: () => Promise<PrivilegeSummary>;
+    };
     /**
-     * Parse the `Cookie` header, look up the session in the database, and
-     * verify it has not expired.
+     * Human auth integration.
      *
-     * When `autoRefresh` is enabled the session is extended on each valid
-     * request and a new `Set-Cookie` header is returned for forwarding.
+     * `resolveUser` extracts the authenticated human from an inbound HTTP
+     * request via the configured adapter.  `session` is a full session
+     * manager (create / validate / revoke) when `auth.session` was passed
+     * to `createTheAuth()`.
      *
-     * @param cookieHeader Raw value of the `Cookie` request header.
+     * @example
+     * ```typescript
+     * app.use(async (req, res, next) => {
+     *   const user = await theauth.auth.resolveUser(req);
+     *   if (!user) return res.status(401).json({ error: 'Unauthorized' });
+     *   req.user = user;
+     *   next();
+     * });
+     * ```
      */
-    validateSession(cookieHeader: string): Promise<ValidateSessionResult>;
+    auth: {
+        resolveUser(request: Request): Promise<ResolvedUser | null>;
+        session: SessionManager | null;
+    };
     /**
-     * Extend the session expiry to `now + maxAge`.
+     * Resolve a human user from an incoming HTTP request.
      *
-     * Returns the updated session and a fresh `Set-Cookie` header.
-     * Returns `null` when the session does not exist.
+     * @deprecated Use `theauth.auth.resolveUser(request)` instead.
      */
-    refreshSession(sessionId: string): Promise<{
-        session: Session;
-        setCookieHeader: string;
-    } | null>;
+    resolveUser(request: Request): Promise<ResolvedUser | null>;
+    /** Direct database access for advanced usage */
+    db: Database;
     /**
-     * Delete a session by ID (server-side) and return a deletion cookie that
-     * will clear the browser cookie on the next response.
+     * Multi-tenant isolation.
+     *
+     * Create and manage tenants (organizations) that share a single
+     * TheAuth instance with full data isolation. Agents can be scoped
+     * to a tenant via `tenantId`.
      */
-    revokeSession(sessionId: string): Promise<{
-        deleteCookieHeader: string;
-    }>;
+    tenant: {
+        create: (input: CreateTenantInput) => Promise<Tenant>;
+        get: (tenantId: string) => Promise<Tenant | null>;
+        getBySlug: (slug: string) => Promise<Tenant | null>;
+        list: () => Promise<Tenant[]>;
+        update: (tenantId: string, updates: Partial<CreateTenantInput>) => Promise<Tenant>;
+        suspend: (tenantId: string) => Promise<void>;
+        activate: (tenantId: string) => Promise<void>;
+    };
     /**
-     * Revoke all sessions for the given user.
+     * Agent execution budget policies.
      *
-     * Returns a deletion cookie header for clearing the current browser cookie.
+     * Set spending caps (token cost, call counts) per agent, user, or
+     * tenant. Exceeded policies trigger a configurable action: warn,
+     * throttle, block, or revoke.
      */
-    revokeAllSessions(userId: string): Promise<{
-        deleteCookieHeader: string;
-    }>;
+    policies: {
+        create: (input: CreatePolicyInput) => Promise<BudgetPolicy>;
+        get: (policyId: string) => Promise<BudgetPolicy | null>;
+        list: (filters?: PolicyFilters) => Promise<BudgetPolicy[]>;
+        update: (policyId: string, updates: Partial<BudgetPolicy>) => Promise<BudgetPolicy>;
+        remove: (policyId: string) => Promise<void>;
+        checkBudget: (agentId: string, tokensCost?: number) => Promise<{
+            allowed: boolean;
+            reason?: string;
+            policy?: BudgetPolicy;
+        }>;
+        recordUsage: (agentId: string, tokensCost?: number) => Promise<void>;
+        resetDaily: () => Promise<{
+            reset: number;
+        }>;
+        resetMonthly: () => Promise<{
+            reset: number;
+        }>;
+    };
     /**
-     * List all non-expired sessions for a user, newest first.
+     * CIBA-style async human approval flows.
+     *
+     * Create pending approval requests, notify humans via webhook or
+     * custom handler, and resolve them with approve / deny.
      */
-    listSessions(userId: string): Promise<Session[]>;
+    approval: {
+        request: (input: {
+            agentId: string;
+            userId: string;
+            action: string;
+            resource: string;
+            arguments?: Record<string, unknown>;
+        }) => Promise<ApprovalRequest>;
+        approve: (requestId: string, respondedBy?: string) => Promise<ApprovalRequest>;
+        deny: (requestId: string, respondedBy?: string) => Promise<ApprovalRequest>;
+        get: (requestId: string) => Promise<ApprovalRequest | null>;
+        listPending: (userId?: string) => Promise<ApprovalRequest[]>;
+        cleanup: () => Promise<{
+            expired: number;
+        }>;
+    };
     /**
-     * Build a `Set-Cookie` header that deletes the session cookie on the client
-     * without any database operation.  Useful in error paths.
+     * Graduated autonomy trust scoring.
+     *
+     * Compute and persist 0-100 trust scores derived from audit history,
+     * mapped to five levels: untrusted, limited, standard, trusted, elevated.
      */
-    buildLogoutCookie(): string;
-    /** Expose the underlying low-level session manager for advanced usage. */
-    raw: SessionManager;
-}
-/**
- * Create a cookie-aware session manager.
- *
- * Internally delegates all DB operations to `createSessionManager`.
- *
- * @param config Cookie-aware session configuration.
- * @param db     Drizzle database instance from `createDatabase()`.
- */
-declare function createCookieSessionManager(config: CookieSessionConfig, db: Database): CookieSessionManager;
-
-/**
- * Multi-session support for TheAuth.
- *
- * Allows users to maintain multiple concurrent sessions (phone, laptop, tablet)
- * with optional per-user session caps. When the cap is reached, the oldest
- * session is evicted automatically (configurable).
- *
- * Uses the existing `kavach_sessions` table — no additional schema required.
- *
- * @example
- * ```typescript
- * const multiSession = createMultiSessionModule(
- *   { maxSessions: 5, overflowStrategy: 'evict-oldest' },
- *   db,
- *   sessionManager,
- * );
- *
- * // List all active sessions for a user
- * const sessionList = await multiSession.listSessions(userId);
- *
- * // Sign out everywhere except here
- * const count = await multiSession.revokeOtherSessions(userId, currentSessionId);
- * ```
- */
-
-interface MultiSessionConfig {
-    /** Max concurrent sessions per user (default: 10) */
-    maxSessions?: number;
-    /** Strategy when max is reached (default: 'evict-oldest') */
-    overflowStrategy?: "reject" | "evict-oldest";
-}
-interface SessionInfo {
-    id: string;
-    createdAt: Date;
-    expiresAt: Date;
-    metadata?: Record<string, unknown>;
-    /** Human-readable device string extracted from User-Agent, e.g. "Chrome on macOS" */
-    device?: string;
-    /** IP address recorded at session creation */
-    ip?: string;
-}
-interface MultiSessionModule {
-    /** List all non-expired sessions for a user, newest first. */
-    listSessions(userId: string): Promise<SessionInfo[]>;
-    /** Revoke a single session by ID. */
-    revokeSession(sessionId: string): Promise<void>;
-    /** Revoke every session except the given one. Returns the count revoked. */
-    revokeOtherSessions(userId: string, currentSessionId: string): Promise<number>;
-    /** Return the count of active (non-expired) sessions for a user. */
-    getSessionCount(userId: string): Promise<number>;
+    trust: {
+        computeScore: (agentId: string) => Promise<TrustScore>;
+        getScore: (agentId: string) => Promise<TrustScore | null>;
+        computeAll: () => Promise<TrustScore[]>;
+        getScores: (filters?: {
+            level?: string;
+            minScore?: number;
+        }) => Promise<TrustScore[]>;
+    };
+    /**
+     * W3C Decentralized Identifiers (DID) for agents.
+     *
+     * Generate did:key or did:web identities, sign payloads, and verify
+     * signatures. Private keys are never stored — they are returned to
+     * the caller on generation and must be stored securely.
+     *
+     * @example
+     * ```typescript
+     * const { agentDid, privateKeyJwk } = await theauth.did.generateKey(agentId);
+     * const signed = await theauth.did.sign(agentId, { action: 'read' }, privateKeyJwk);
+     * const result = await theauth.did.verify(signed.jws, agentDid.did);
+     * ```
+     */
+    did: {
+        generateKey: (agentId: string) => Promise<{
+            agentDid: AgentDid;
+            privateKeyJwk: JsonWebKey;
+        }>;
+        generateWeb: (agentId: string) => Promise<{
+            agentDid: AgentDid;
+            privateKeyJwk: JsonWebKey;
+        }>;
+        resolve: (did: string) => Promise<DidDocument | null>;
+        getAgentDid: (agentId: string) => Promise<AgentDid | null>;
+        sign: (agentId: string, payload: Record<string, unknown>, privateKeyJwk: JsonWebKey) => Promise<SignedPayload>;
+        verify: (jws: string, did?: string) => Promise<VerificationResult>;
+        createPresentation: (options: {
+            agentId: string;
+            privateKeyJwk: JsonWebKey;
+            capabilities: string[];
+            audience?: string;
+            expiresIn?: number;
+        }) => Promise<string>;
+        verifyPresentation: (jwt: string) => Promise<VerificationResult & {
+            capabilities?: string[];
+        }>;
+    };
     /**
-     * Enforce the session cap before creating a new session.
+     * Magic link (passwordless email) authentication.
      *
-     * Call this before `sessionManager.create()`. If the cap is reached:
-     * - `evict-oldest` deletes the oldest session and resolves.
-     * - `reject` throws a `MultiSessionLimitError`.
+     * Null when `magicLink` config was not provided or `auth.session` is not
+     * configured (sessions are required to issue tokens on verification).
+     *
+     * @example
+     * ```typescript
+     * // In your route handler
+     * const response = await theauth.magicLink?.handleRequest(request);
+     * if (response) return response;
+     * ```
      */
-    enforceSessionLimit(userId: string): Promise<void>;
-}
-declare class MultiSessionLimitError extends Error {
-    readonly code = "SESSION_LIMIT_REACHED";
-    constructor(userId: string, max: number);
-}
-declare function createMultiSessionModule(config: MultiSessionConfig, db: Database, sessionManager: SessionManager): MultiSessionModule;
-/**
- * Build metadata to pass to `sessionManager.create()` that includes
- * device info extracted from the incoming request.
- *
- * @example
- * ```typescript
- * const meta = buildSessionMetadata(request, { role: 'admin' });
- * const { token } = await sessionManager.create(userId, meta);
- * ```
- */
-declare function buildSessionMetadata(request: Request, extra?: Record<string, unknown>): Record<string, unknown>;
-
-/**
- * Token family tracking for refresh token reuse detection.
- *
- * Each refresh token belongs to a "family" — a chain of rotations that all
- * originate from the same initial login.  When `reuseDetection` is enabled,
- * presenting an already-used token from a family immediately revokes every
- * token in that family, because reuse indicates the token was stolen.
- *
- * The database table `kavach_refresh_token_families` stores:
- *   - family-level metadata (userId, absolute expiry, revocation status)
- *
- * Each individual refresh token row in `kavach_refresh_tokens` links back to
- * its family via `familyId`.
- *
- * @example
- * ```typescript
- * const families = createTokenFamilyStore(db);
- *
- * // On login — create a new family and issue the first token
- * const family = await families.createFamily(userId, absoluteExpiresAt);
- * const token = await families.issueToken(family.id, refreshTokenTTL);
- *
- * // On refresh — consume the token (marks it used, issues a new one)
- * const result = await families.consumeToken(rawToken);
- * if (result.status === 'reuse') {
- *   // Entire family revoked — force re-login
- * }
- * ```
- */
-
-interface TokenFamily {
-    id: string;
-    userId: string;
-    /** Absolute expiry — no refresh can extend beyond this date. */
-    absoluteExpiresAt: Date;
-    revoked: boolean;
-    createdAt: Date;
-}
-type ConsumeTokenStatus = "ok" /** Token valid, successfully consumed. */ | "expired" /** Token has passed its TTL. */ | "revoked" /** Entire family has been revoked (stolen token detected). */ | "reuse" /** Token was already used — family has now been revoked. */ | "not_found"; /** Token does not exist in the database. */
-interface ConsumeTokenResult {
-    status: ConsumeTokenStatus;
-    /** Populated when status is `"ok"`. */
-    family?: TokenFamily;
-}
-interface TokenFamilyStore {
+    magicLink: MagicLinkModule | null;
     /**
-     * Create a new token family for a user.
-     * Call this once per login to anchor the refresh token chain.
+     * Email OTP (one-time password) authentication.
+     *
+     * Null when `emailOtp` config was not provided or `auth.session` is not
+     * configured.
+     *
+     * @example
+     * ```typescript
+     * const response = await theauth.emailOtp?.handleRequest(request);
+     * if (response) return response;
+     * ```
      */
-    createFamily(userId: string, absoluteExpiresAt: Date): Promise<TokenFamily>;
+    emailOtp: EmailOtpModule | null;
     /**
-     * Issue a new opaque refresh token tied to the given family.
+     * TOTP two-factor authentication.
      *
-     * Returns the raw token string (only returned once — never stored in the
-     * clear) and the token's individual expiry date.
+     * Null when `totp` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * // On setup (show QR code to user)
+     * const { secret, uri, backupCodes } = await theauth.totp.setup(userId);
+     *
+     * // After user scans QR and enters code
+     * const { enabled } = await theauth.totp.enable(userId, totpCode);
+     *
+     * // On login (after password check)
+     * const { valid } = await theauth.totp.verify(userId, totpCode);
+     * ```
      */
-    issueToken(familyId: string, ttlMs: number): Promise<{
-        rawToken: string;
-        expiresAt: Date;
-    }>;
+    totp: TotpModule | null;
     /**
-     * Consume a refresh token.
+     * Passkey / WebAuthn authentication.
      *
-     * - If the token is valid and unused, it is marked `used` and the caller
-     *   should immediately call `issueToken` to rotate.
-     * - If the token was already used, the **entire family is revoked** (reuse
-     *   detection — token theft assumed).
-     * - If the token has expired or is not found, returns the appropriate status.
+     * Null when `passkey` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * // Registration — step 1: get options, send to browser
+     * const options = await theauth.passkey.getRegistrationOptions(userId, userName);
+     *
+     * // Registration — step 2: verify browser response
+     * const { credential } = await theauth.passkey.verifyRegistration(userId, response);
+     *
+     * // Authentication — step 1: get options
+     * const options = await theauth.passkey.getAuthenticationOptions(userId);
+     *
+     * // Authentication — step 2: verify browser response
+     * const result = await theauth.passkey.verifyAuthentication(response);
+     * if (result) console.log('Authenticated user:', result.userId);
+     * ```
      */
-    consumeToken(rawToken: string): Promise<ConsumeTokenResult>;
+    passkey: PasskeyModule | null;
     /**
-     * Revoke all token families (and their tokens) for a user.
-     * Used on logout, password change, or explicit session termination.
+     * Organizations + RBAC.
+     *
+     * Null when `org` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * const org = await theauth.org?.create({ name: 'Acme', slug: 'acme', ownerId: userId });
+     * const allowed = await theauth.org?.hasPermission(org.id, userId, 'agents:create');
+     * ```
      */
-    revokeFamiliesForUser(userId: string): Promise<void>;
+    org: OrgModule | null;
     /**
-     * Revoke a specific family by ID and all its tokens.
+     * SSO (SAML 2.0 + OIDC) enterprise authentication.
+     *
+     * Null when `sso` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * const conn = await theauth.sso?.createConnection({ orgId, providerId: 'okta', type: 'saml', domain: 'acme.com' });
+     * const url = await theauth.sso?.getSamlAuthUrl(conn.id);
+     * ```
      */
-    revokeFamily(familyId: string): Promise<void>;
+    sso: SsoModule | null;
     /**
-     * Check whether the absolute session timeout has been reached for a family.
-     * Returns `true` when the family is still within its absolute timeout.
+     * Admin module.
+     *
+     * Null when `admin` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * await theauth.admin?.banUser(userId, 'Spam');
+     * const { session } = await theauth.admin?.impersonate(adminId, userId);
+     * ```
      */
-    isFamilyActive(family: TokenFamily): boolean;
-}
-/**
- * Create a `TokenFamilyStore` backed by the TheAuth database.
- */
-declare function createTokenFamilyStore(db: Database): TokenFamilyStore;
-
-/**
- * Session refresh endpoint handler for TheAuth.
- *
- * Implements `POST /auth/refresh`:
- * 1. Extracts the refresh token from an httpOnly cookie or the request body.
- * 2. Validates the token (TTL, reuse detection, absolute timeout).
- * 3. Issues a new short-lived access token (signed JWT).
- * 4. Rotates the refresh token (one-time use — the old one is consumed).
- * 5. Records the rotation in the audit log.
- *
- * Token family tracking (via `createTokenFamilyStore`) provides reuse
- * detection: if an attacker uses a stolen refresh token after the legitimate
- * user has already rotated it, the entire family is revoked and both parties
- * are forced to re-authenticate.
- *
- * @example
- * ```typescript
- * const refresher = createSessionRefresher({
- *   secret: process.env.SESSION_SECRET,
- *   session: {
- *     accessTokenTTL:    "15m",
- *     refreshTokenTTL:   "30d",
- *     absoluteTimeout:   "90d",
- *     rotateRefreshTokens: true,
- *     reuseDetection:    true,
- *   },
- *   db,
- * });
- *
- * // In your Hono / Express router:
- * app.post('/auth/refresh', async (ctx) => {
- *   const result = await refresher.handleRequest(ctx.req.raw);
- *   return result.response;
- * });
- * ```
- */
-
-interface RefreshSessionConfig {
+    admin: AdminModule | null;
     /**
-     * Short-lived access token lifetime.
-     * Parsed duration string, e.g. `"15m"`.
-     * Defaults to `"15m"`.
+     * API key management.
+     *
+     * Null when `apiKeys` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * const { key, apiKey } = await theauth.apiKeys?.create({ userId, name: 'CI', permissions: ['agents:read'] });
+     * const result = await theauth.apiKeys?.validate(key);
+     * ```
+     */
+    apiKeys: ApiKeyManagerModule | null;
+    /**
+     * Username + password authentication.
+     *
+     * Null when `username` config was not provided or `auth.session` is not
+     * configured (sessions are required to issue tokens on sign-in/up).
+     *
+     * @example
+     * ```typescript
+     * const response = await theauth.username?.handleRequest(request);
+     * if (response) return response;
+     * ```
      */
-    accessTokenTTL?: string;
+    username: UsernameAuthModule | null;
     /**
-     * Long-lived refresh token lifetime.
-     * Parsed duration string, e.g. `"30d"`.
-     * Defaults to `"30d"`.
+     * Password reset (forgot password + reset password).
+     *
+     * Null when `passwordReset` config was not provided or `auth.session`
+     * is not configured.
+     *
+     * @example
+     * ```typescript
+     * // In your route handler
+     * const response = await theauth.passwordReset?.handleRequest(request);
+     * if (response) return response;
+     *
+     * // Or programmatically
+     * await theauth.passwordReset?.requestReset('alice@example.com');
+     * await theauth.passwordReset?.resetPassword(token, 'new-password');
+     * ```
      */
-    refreshTokenTTL?: string;
+    passwordReset: PasswordResetModule | null;
     /**
-     * When `true` (default), each use of a refresh token rotates it: the old
-     * token is invalidated and a new one is issued.
+     * Email address verification.
+     *
+     * Null when `emailVerification` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * // Send a verification email after sign-up
+     * await theauth.emailVerification?.sendVerification(userId, email);
+     *
+     * // Confirm from the link in the email
+     * const result = await theauth.emailVerification?.verify(token);
+     *
+     * // Check status
+     * const verified = await theauth.emailVerification?.isVerified(userId);
+     * ```
      */
-    rotateRefreshTokens?: boolean;
+    emailVerification: EmailVerificationModule | null;
     /**
-     * Maximum session lifetime regardless of how many times the token is
-     * refreshed.  Parsed duration string, e.g. `"90d"`.
-     * Defaults to `"90d"`.
+     * One-time tokens (email verify, password reset, invitations, custom).
+     *
+     * Always available. Used internally by password reset but exposed for
+     * custom flows (email verification, invitation links, etc.).
      */
-    absoluteTimeout?: string;
+    oneTimeTokens: OneTimeTokenModule;
     /**
-     * When `true` (default), presenting an already-used refresh token triggers
-     * reuse detection and revokes the entire token family.
+     * Session freshness enforcement for sensitive operations.
+     *
+     * Use as middleware before password changes, passkey registration,
+     * billing updates, or any action that requires a recently-authenticated
+     * session rather than an auto-refreshed one.
+     *
+     * @example
+     * ```typescript
+     * const stale = theauth.sessionFreshness.guard(session);
+     * if (stale) return stale; // 403 SESSION_NOT_FRESH
+     * ```
      */
-    reuseDetection?: boolean;
+    sessionFreshness: SessionFreshnessModule;
     /**
-     * Name of the httpOnly cookie that carries the refresh token.
-     * Defaults to `"kavach_refresh"`.
+     * Phone number (SMS OTP) authentication.
+     *
+     * Null when `phone` config was not provided or `auth.session` is not
+     * configured.
+     *
+     * @example
+     * ```typescript
+     * const response = await theauth.phone?.handleRequest(request);
+     * if (response) return response;
+     * ```
      */
-    refreshCookieName?: string;
+    phone: PhoneAuthModule | null;
     /**
-     * Name of the httpOnly cookie that carries the access token (when cookie
-     * transport is used for the access token too).
-     * Defaults to `"kavach_access"`.
+     * Captcha integration (reCAPTCHA, hCaptcha, Cloudflare Turnstile).
+     *
+     * Null when `captcha` config was not provided.
+     *
+     * @example
+     * ```typescript
+     * const result = await theauth.captcha?.verify(token, ip);
+     * if (!result?.success) return new Response('Captcha failed', { status: 403 });
+     * ```
      */
-    accessCookieName?: string;
-}
-interface SessionRefresherConfig {
-    /** Signing secret — at least 32 characters. */
-    secret: string;
-    /** Refresh / rotation settings. */
-    session?: RefreshSessionConfig;
-    /** Drizzle database instance. */
-    db: Database;
-}
-/** The payload embedded in the short-lived access token JWT. */
-interface AccessTokenPayload {
-    /** User ID. */
-    sub: string;
-    /** Token family ID — used for server-side token binding. */
-    familyId: string;
-    /** Token type discriminator. */
-    type: "access";
-}
-interface RefreshResult {
-    /** Signed access token JWT. */
-    accessToken: string;
-    /** Raw opaque refresh token (only returned once — store in httpOnly cookie). */
-    refreshToken: string;
-    /** Expiry date of the new access token. */
-    accessTokenExpiresAt: Date;
-    /** Expiry date of the new refresh token. */
-    refreshTokenExpiresAt: Date;
-    /** The token family these tokens belong to. */
-    family: TokenFamily;
-}
-type RefreshError = "token_missing" | "token_not_found" | "token_expired" | "token_reuse" | "family_revoked" | "absolute_timeout";
-interface RefreshHandleResult {
-    /** HTTP Response ready to return to the caller. */
-    response: Response;
-    /** Populated on success. */
-    result?: RefreshResult;
-    /** Populated on failure. */
-    error?: RefreshError;
-}
-interface SessionRefresher {
+    captcha: CaptchaModule | null;
     /**
-     * Low-level refresh — takes a raw refresh token string directly.
+     * Webhook system.
      *
-     * Returns `RefreshResult` on success or throws a `RefreshTokenError`.
+     * Null when `webhooks` config was not provided or the array is empty.
+     *
+     * @example
+     * ```typescript
+     * theauth.webhooks?.emit('user.created', { userId: user.id });
+     * ```
      */
-    refresh(rawRefreshToken: string): Promise<RefreshResult>;
+    webhooks: WebhookModule$1 | null;
     /**
-     * High-level HTTP handler.
+     * Redirect chain manager.
      *
-     * Extracts the refresh token from the `Cookie` header (preferred) or the
-     * JSON request body, calls `refresh()`, and returns a `Response` with
-     * appropriate `Set-Cookie` headers.
+     * Capture the user's original destination before auth redirects, push
+     * intermediate steps (onboarding, email verification), and pop them
+     * back in order. Cookie-based, works across page transitions and tabs.
+     *
+     * @example
+     * ```typescript
+     * // In auth middleware — save where the user was going
+     * const setCookie = theauth.redirects.capture(request);
+     * return new Response(null, { status: 302, headers: { Location: '/sign-in', 'Set-Cookie': setCookie } });
+     *
+     * // After sign-in — send user to their original destination
+     * const { url, clearCookie } = theauth.redirects.pop(request);
+     * const headers: Record<string, string> = { Location: url };
+     * if (clearCookie) headers['Set-Cookie'] = clearCookie;
+     * return new Response(null, { status: 302, headers });
+     * ```
      */
-    handleRequest(request: Request): Promise<RefreshHandleResult>;
+    redirects: RedirectChainManager;
     /**
-     * Issue an initial refresh token for a user (called once on login).
+     * Unified policy engine.
      *
-     * Returns the access token, refresh token, and their expiry dates.
+     * Single decision point that combines RBAC role expansion, ABAC constraint
+     * evaluation, and ReBAC graph queries. Backed by a process-local LRU cache
+     * with deterministic invalidation.
+     *
+     * @example
+     * ```typescript
+     * const decision = await theauth.policy.evaluate({
+     *   subject: { agentId: 'agent-abc' },
+     *   action: 'read',
+     *   resource: 'tool:github:list_issues',
+     * });
+     * if (!decision.allowed) throw new Error(decision.reason);
+     *
+     * // Flush cached decisions after a permission change
+     * theauth.policy.invalidate({ agentId: 'agent-abc' });
+     *
+     * // Inspect cache health
+     * const { hits, misses, size, evictions } = theauth.policy.stats();
+     * ```
      */
-    issueInitial(userId: string): Promise<RefreshResult>;
+    policy: {
+        evaluate: (input: EvaluateInput) => Promise<PolicyDecision>;
+        invalidate: (scope: InvalidateScope) => void;
+        stats: () => PolicyCacheStats;
+    };
     /**
-     * Revoke all refresh token families for a user (e.g. on logout or
-     * password change).
+     * Plugin system.
+     *
+     * Route incoming HTTP requests through plugin-registered endpoints,
+     * retrieve all endpoints for adapter mounting, or access plugin-provided
+     * context values.
+     *
+     * @example
+     * ```typescript
+     * // In a framework adapter
+     * app.all('/theauth/*', async (req) => {
+     *   const response = await theauth.plugins.handleRequest(req);
+     *   if (response) return response;
+     *   return new Response('Not Found', { status: 404 });
+     * });
+     * ```
      */
-    revokeAll(userId: string): Promise<void>;
-}
-/** Thrown by `SessionRefresher.refresh()` on validation failure. */
-declare class RefreshTokenError extends Error {
-    readonly code: RefreshError;
-    constructor(code: RefreshError, message: string);
-}
+    plugins: {
+        /** Route a request through plugin endpoints. Returns null if no plugin handles it. */
+        handleRequest(request: Request, basePath?: string): Promise<Response | null>;
+        /** Get all endpoints registered by plugins (for framework adapter mounting). */
+        getEndpoints(): PluginEndpoint[];
+        /** Get the merged plugin context (values returned from plugin init). */
+        getContext(): Record<string, unknown>;
+        /** Access the raw plugin registry (hooks, migrations, etc.). */
+        registry: PluginRegistry;
+    };
+}>;
+type TheAuth = Awaited<ReturnType<typeof createTheAuth>>;
 /**
- * Create a `SessionRefresher` backed by the TheAuth database.
+ * @deprecated Use `createTheAuth` instead. Will be removed in a future major version.
  */
-declare function createSessionRefresher(config: SessionRefresherConfig): SessionRefresher;
-
-interface Tenant {
-    id: string;
-    name: string;
-    slug: string;
-    settings: TenantSettings;
-    status: "active" | "suspended";
-    createdAt: Date;
-    updatedAt: Date;
-}
-interface TenantSettings {
-    maxAgents?: number;
-    maxDelegationDepth?: number;
-    auditRetentionDays?: number;
-    allowedAgentTypes?: string[];
-}
-interface CreateTenantInput {
-    name: string;
-    slug: string;
-    settings?: Partial<TenantSettings>;
-}
-declare function createTenantModule(db: Database): {
-    create: (input: CreateTenantInput) => Promise<Tenant>;
-    get: (tenantId: string) => Promise<Tenant | null>;
-    getBySlug: (slug: string) => Promise<Tenant | null>;
-    list: () => Promise<Tenant[]>;
-    update: (tenantId: string, updates: Partial<CreateTenantInput>) => Promise<Tenant>;
-    suspend: (tenantId: string) => Promise<void>;
-    activate: (tenantId: string) => Promise<void>;
-};
+declare const createAuth: typeof createTheAuth;
+/**
+ * @deprecated Use `TheAuth` instead. Will be removed in a future major version.
+ */
+type Auth = TheAuth;
 
 interface TrustScore {
     agentId: string;
@@ -1724,4 +1704,4 @@ declare function createWebhookModule(config: WebhookConfig): WebhookModule;
  */
 declare function verifyWebhookSignature(secret: string, rawBody: string, signature: string): Promise<boolean>;
 
-export { type AccessTokenPayload, AdminModule, AgentDid, AgentFilter, AgentIdentity, ApiKeyManagerModule, ApprovalRequest, AuditEntry, AuditExportOptions, AuditFilter, type Auth, AuthorizeRequest, AuthorizeResult, type BudgetLimits, type BudgetPolicy, type BudgetUsage, CaptchaModule, type ConsumeTokenResult, type ConsumeTokenStatus, type CookieOptions, type CookieSessionConfig, type CookieSessionManager, CreateAgentInput, type CreatePolicyInput, type CreateSessionResult, type CreateTenantInput, type CsrfValidationResult, Database, DatabaseConfig, DelegateInput, DelegationChain, DidDocument, DidKeyPair, type DidModule, DidWebConfig, EmailOtpModule, type EmailTemplate, type EmailTemplateConfig, type EmailTemplateName, type EmailTemplates, EmailVerificationModule, EndpointContext, type I18nConfig, type I18nModule, type Kavach, KavachConfig, MagicLinkModule, McpServer, McpServerInput, type MultiSessionConfig, MultiSessionLimitError, type MultiSessionModule, OneTimeTokenModule, OrgModule, PasskeyModule, PasswordResetModule, Permission, PhoneAuthModule, PluginEndpoint, type PluginRegistry, type PolicyFilters, type PrivilegeAnalysis, type PrivilegeAnalyzer, type PrivilegeFinding, type PrivilegeSummary, RedirectChainManager, type RefreshError, type RefreshHandleResult, type RefreshResult, type RefreshSessionConfig, RefreshTokenError, ResolvedUser, type SameSite, Session, SessionConfig, SessionFreshnessModule, type SessionInfo, SessionManager, type SessionRefresher, type SessionRefresherConfig, SignedPayload, SsoModule, type Tenant, type TenantSettings, type TheAuth, TheAuthConfig, TheAuthPlugin, type TokenFamily, type TokenFamilyStore, TotpModule, type TranslationKeys, type TrustConfig, type TrustModule, type TrustScore, UpdateAgentInput, UsernameAuthModule, type ValidateSessionResult, VerificationResult, type WebhookConfig, type WebhookEvent, type WebhookModule, type WebhookSubscription, buildDidDocument, buildSessionMetadata, createAuth, createCookieSessionManager, createDelegationModule, createDidModule, createEmailTemplates, createI18n, createKavach, createMultiSessionModule, createPluginRouter, createPolicyModule, createPresentation, createPrivilegeAnalyzer, createSessionRefresher, createTables, createTenantModule, createTheAuth, createTokenFamilyStore, createTrustModule, createWebhookModule, de, en, es, fr, generateCsrfToken, generateDidKey, generateDidWeb, generateOpenAPISpec, getCookie, getDidWebUrl, initializePlugins, ja, parseCookies, parseCookiesFromRequest, resolveDidKey, resolveDidWeb, serializeCookie, serializeCookieDeletion, signPayload, validateCsrfToken, validateOrigin, verifyPayload, verifyPresentation, verifyWebhookSignature, zh };
+export { type AccessTokenPayload, AdminModule, AgentDid, AgentFilter, AgentIdentity, ApiKeyManagerModule, ApprovalRequest, AuditEntry, AuditExportOptions, AuditFilter, type Auth, AuthorizeRequest, AuthorizeResult, type BudgetLimits, type BudgetPolicy, type BudgetUsage, CaptchaModule, type ConsumeTokenResult, type ConsumeTokenStatus, type CookieOptions, type CookieSessionConfig, type CookieSessionManager, CreateAgentInput, type CreatePolicyInput, type CreateSessionResult, type CreateTenantInput, type CsrfValidationResult, Database, DatabaseConfig, DelegateInput, DelegationChain, DelegationError, type DelegationErrorCode, DidDocument, DidKeyPair, type DidModule, DidWebConfig, EmailOtpModule, type EmailTemplate, type EmailTemplateConfig, type EmailTemplateName, type EmailTemplates, EmailVerificationModule, EndpointContext, type I18nConfig, type I18nModule, MagicLinkModule, McpServer, McpServerInput, type MultiSessionConfig, MultiSessionLimitError, type MultiSessionModule, OneTimeTokenModule, OrgModule, PasskeyModule, PasswordResetModule, Permission, PhoneAuthModule, PluginEndpoint, type PluginRegistry, type PolicyFilters, type PrivilegeAnalysis, type PrivilegeAnalyzer, type PrivilegeFinding, type PrivilegeSummary, RedirectChainManager, type RefreshError, type RefreshHandleResult, type RefreshResult, type RefreshSessionConfig, RefreshTokenError, ResolvedUser, type SameSite, Session, SessionConfig, SessionFreshnessModule, type SessionInfo, SessionManager, type SessionRefresher, type SessionRefresherConfig, SignedPayload, SsoModule, type Tenant, type TenantSettings, type TheAuth, TheAuthConfig, TheAuthPlugin, type TokenFamily, type TokenFamilyStore, TotpModule, type TranslationKeys, type TrustConfig, type TrustModule, type TrustScore, UpdateAgentInput, UsernameAuthModule, type ValidateSessionResult, VerificationResult, type WebhookConfig, type WebhookEvent, type WebhookModule, type WebhookSubscription, buildDidDocument, buildSessionMetadata, createAuth, createCookieSessionManager, createDelegationModule, createDidModule, createEmailTemplates, createI18n, createMultiSessionModule, createPluginRouter, createPolicyModule, createPresentation, createPrivilegeAnalyzer, createSessionRefresher, createTables, createTenantModule, createTheAuth, createTokenFamilyStore, createTrustModule, createWebhookModule, de, en, es, fr, generateCsrfToken, generateDidKey, generateDidWeb, generateOpenAPISpec, getCookie, getDidWebUrl, initializePlugins, ja, parseCookies, parseCookiesFromRequest, resolveDidKey, resolveDidWeb, serializeCookie, serializeCookieDeletion, signPayload, validateCsrfToken, validateOrigin, verifyPayload, verifyPresentation, verifyWebhookSignature, zh };