kavachos 0.0.2 → 0.0.3

package/dist/auth/index.d.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
-import { A as AuthAdapter, R as ResolvedUser } from '../types-_7hIICee.js';
+import { Z as AuthAdapter, o as ResolvedUser, F as KavachPlugin, D as Database, I as AdminConfig, p as SessionManager, Q as ApiKeyManagerConfig, a1 as EmailOtpConfig, a4 as MagicLinkConfig, a7 as OrgConfig, ac as PasskeyConfig, z as PluginEndpoint, aq as TotpConfig } from '../types-Xk83hv4O.js';
+export { u as AdminModule, J as AdminUser, N as ApiKey, v as ApiKeyManagerModule, _ as CaptchaConfig, y as CaptchaModule, $ as CaptchaVerifyResult, E as EmailOtpModule, r as MagicLinkModule, a6 as OidcProvider, a8 as OrgInvitation, a9 as OrgMember, O as OrgModule, aa as OrgRole, ab as Organization, ad as PasskeyCredential, s as PasskeyModule, af as PhoneAuthConfig, x as PhoneAuthModule, ai as SSO_ERROR, aj as SamlProvider, al as SsoAuditEvent, am as SsoConfig, an as SsoConnection, ao as SsoError, t as SsoModule, T as TotpModule, ar as TotpSetup, as as UsernameAuthConfig, w as UsernameAuthModule, ba as WebhookConfig, bb as WebhookEvent, W as WebhookModule, aC as createAdminModule, aD as createApiKeyManagerModule, aF as createCaptchaModule, aI as createEmailOtpModule, aJ as createMagicLinkModule, aK as createOrgModule, aL as createPasskeyModule, aM as createPhoneAuthModule, aO as createSsoModule, aP as createTotpModule, aQ as createUsernameAuthModule, bc as createWebhookModule } from '../types-Xk83hv4O.js';
+import { R as Result } from '../types-mwupB57A.js';
+import * as jose from 'jose';
+import 'drizzle-orm/better-sqlite3';
+import 'drizzle-orm/sqlite-core';
 
 /**
  * JWT bearer-token auth adapter.
@@ -140,4 +145,1716 @@ interface HeaderAuthOptions {
  */
 declare function headerAuth(options?: HeaderAuthOptions): AuthAdapter;
 
-export { AuthAdapter, type BearerAuthOptions, type HeaderAuthOptions, ResolvedUser, bearerAuth, customAuth, headerAuth };
+/**
+ * Additional user/session fields plugin for KavachOS.
+ *
+ * Lets callers extend the user and session schemas with typed custom fields
+ * without writing any database migrations.  Fields are stored in the existing
+ * `user.metadata` or `session.metadata` JSON columns.
+ *
+ * Field types: `string`, `number`, `boolean`, `json`.
+ * Required fields must be present when calling `setUserFields`.
+ * Fields not in the schema are rejected during `validate()`.
+ *
+ * @example
+ * ```typescript
+ * import { createKavach } from 'kavachos';
+ * import { additionalFields } from 'kavachos/auth';
+ *
+ * const kavach = await createKavach({
+ *   database: { provider: 'sqlite', url: 'kavach.db' },
+ *   plugins: [
+ *     additionalFields({
+ *       user: {
+ *         plan:    { type: 'string', required: false, defaultValue: 'free' },
+ *         credits: { type: 'number', required: false, defaultValue: 0 },
+ *       },
+ *     }),
+ *   ],
+ * });
+ *
+ * const mod = kavach.plugins.getContext().additionalFields as AdditionalFieldsModule;
+ * await mod.setUserFields(userId, { plan: 'pro', credits: 100 });
+ * const fields = await mod.getUserFields(userId);
+ * // => { plan: 'pro', credits: 100 }
+ * ```
+ */
+
+interface FieldDefinition {
+    type: "string" | "number" | "boolean" | "json";
+    required?: boolean;
+    defaultValue?: unknown;
+}
+interface AdditionalFieldsConfig {
+    /** Custom fields for users (stored in user.metadata). */
+    user?: Record<string, FieldDefinition>;
+    /** Custom fields for sessions (stored in session.metadata). */
+    session?: Record<string, FieldDefinition>;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+interface AdditionalFieldsModule {
+    /**
+     * Return the additional fields stored in `user.metadata` for the given user.
+     *
+     * Fields missing from the stored metadata are filled with their `defaultValue`
+     * (if one is defined in the schema).
+     */
+    getUserFields(userId: string): Promise<Record<string, unknown>>;
+    /**
+     * Write `fields` into `user.metadata`, merging with any already-stored values.
+     *
+     * Validates against the `user` schema before writing.
+     * Throws when the user does not exist or validation fails.
+     */
+    setUserFields(userId: string, fields: Record<string, unknown>): Promise<void>;
+    /**
+     * Return the additional fields stored in `session.metadata` for the given session.
+     */
+    getSessionFields(sessionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Write `fields` into `session.metadata`, merging with any already-stored values.
+     *
+     * Validates against the `session` schema before writing.
+     * Throws when the session does not exist or validation fails.
+     */
+    setSessionFields(sessionId: string, fields: Record<string, unknown>): Promise<void>;
+    /**
+     * Validate a field map against the "user" or "session" schema.
+     *
+     * Returns `{ valid: true }` on success or `{ valid: false, errors: [...] }` on
+     * failure.  Does not throw.
+     */
+    validate(fields: Record<string, unknown>, schema: "user" | "session"): ValidationResult;
+}
+declare function createAdditionalFieldsModule(config: AdditionalFieldsConfig, db: Database): AdditionalFieldsModule;
+declare function additionalFields(config?: AdditionalFieldsConfig): KavachPlugin;
+
+declare function admin(config?: AdminConfig): KavachPlugin;
+
+/**
+ * Anonymous authentication for KavachOS.
+ *
+ * Lets users start as guests without providing credentials. The anonymous
+ * user can later be upgraded to a real account by supplying an email.
+ *
+ * Anonymous users are stored in `kavach_users` with a synthetic placeholder
+ * email (`anon_<uuid>@kavachos.anonymous`) and a metadata flag
+ * `{ anonymous: true }`. This satisfies the NOT NULL UNIQUE constraint on
+ * the email column while keeping them easily identifiable.
+ *
+ * @example
+ * ```typescript
+ * const anon = createAnonymousAuthModule(config, db, sessionManager);
+ *
+ * // On first visit
+ * const { userId, sessionToken } = await anon.createAnonymousUser();
+ *
+ * // Later, when user signs up
+ * await anon.upgradeUser(userId, { email: 'alice@example.com', name: 'Alice' });
+ * ```
+ */
+
+interface AnonymousAuthConfig {
+    /** How long anonymous sessions last in seconds (default: 86400 = 24 hours) */
+    sessionTtlSeconds?: number;
+    /** Whether to allow anonymous users to create agents (default: false) */
+    allowAgentCreation?: boolean;
+}
+interface AnonymousAuthModule {
+    /** Create an anonymous user and a session. */
+    createAnonymousUser(): Promise<{
+        userId: string;
+        sessionToken: string;
+    }>;
+    /** Upgrade an anonymous user to a real account by setting their email. */
+    upgradeUser(anonymousUserId: string, upgrade: {
+        email: string;
+        name?: string;
+    }): Promise<void>;
+    /** Check if a user was created as anonymous and has not been upgraded. */
+    isAnonymous(userId: string): Promise<boolean>;
+    /**
+     * Delete anonymous users older than `maxAgeMs` and their sessions.
+     * Returns the number of users removed.
+     */
+    cleanup(maxAgeMs?: number): Promise<number>;
+}
+declare function createAnonymousAuthModule(config: AnonymousAuthConfig, db: Database, sessionManager: SessionManager): AnonymousAuthModule;
+
+declare function anonymousAuth(config?: AnonymousAuthConfig): KavachPlugin;
+
+declare function apiKeys(config?: ApiKeyManagerConfig): KavachPlugin;
+
+/**
+ * Custom session fields plugin for KavachOS.
+ *
+ * Lets callers attach arbitrary data to sessions at creation time and read or
+ * update that data later.  Everything is stored in the existing
+ * `session.metadata.custom` sub-key — no new database columns are required.
+ *
+ * Two integration points:
+ *
+ * 1. `defaultFields` — merged into every new session automatically.
+ * 2. `onSessionCreate` — async callback that receives the userId (and
+ *    optionally the originating Request) and returns additional fields to
+ *    merge.  Runs once per session, during the plugin's `onSessionCreate` hook.
+ *
+ * @example
+ * ```typescript
+ * import { createKavach } from 'kavachos';
+ * import { customSession } from 'kavachos/auth';
+ *
+ * const kavach = await createKavach({
+ *   database: { provider: 'sqlite', url: 'kavach.db' },
+ *   auth: { session: { secret: process.env.SESSION_SECRET } },
+ *   plugins: [
+ *     customSession({
+ *       defaultFields: { theme: 'dark' },
+ *       onSessionCreate: async (userId) => ({ lastSeen: Date.now() }),
+ *     }),
+ *   ],
+ * });
+ *
+ * // After a session is created via kavach.auth.session.create(...)
+ * const mod = kavach.plugins.getContext().customSession as CustomSessionModule;
+ * const fields = await mod.getSessionFields(session.id);
+ * // => { theme: 'dark', lastSeen: 1234567890 }
+ * ```
+ */
+
+interface CustomSessionConfig {
+    /** Fields merged into every new session's metadata.custom on creation. */
+    defaultFields?: Record<string, unknown>;
+    /**
+     * Hook called when a new session is being created.
+     *
+     * The return value is merged into `session.metadata.custom` alongside any
+     * `defaultFields`.  If both define the same key, the hook's value wins.
+     */
+    onSessionCreate?: (userId: string, request?: Request) => Promise<Record<string, unknown>>;
+}
+interface CustomSessionModule {
+    /**
+     * Return the custom fields stored in `session.metadata.custom`.
+     *
+     * Returns `null` when the session does not exist or has no custom data.
+     */
+    getSessionFields(sessionId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Merge `fields` into `session.metadata.custom`, overwriting any keys that
+     * already exist.  Existing keys not present in `fields` are preserved.
+     */
+    updateSessionFields(sessionId: string, fields: Record<string, unknown>): Promise<void>;
+}
+declare function createCustomSessionModule(_config: CustomSessionConfig, db: Database): CustomSessionModule;
+declare function customSession(config?: CustomSessionConfig): KavachPlugin;
+
+/**
+ * OAuth Device Authorization Grant (RFC 8628) for KavachOS.
+ *
+ * Supports TVs, CLI tools, smart displays, and any device where the user
+ * cannot easily type a URL or complete an interactive login flow. The device
+ * requests a short code, the user approves on a secondary device (phone /
+ * browser), and the original device polls until authorization is granted.
+ *
+ * @example
+ * ```typescript
+ * const deviceAuth = createDeviceAuthModule({
+ *   verificationUri: 'https://example.com/device',
+ * });
+ *
+ * // 1. CLI tool requests codes
+ * const { userCode, verificationUri } = await deviceAuth.requestCode();
+ * console.log(`Visit ${verificationUri} and enter: ${userCode}`);
+ *
+ * // 2. Poll from CLI
+ * const status = await deviceAuth.checkAuthorization(deviceCode);
+ *
+ * // 3. User approves on browser after logging in
+ * await deviceAuth.authorize(userCode, userId);
+ * ```
+ */
+interface DeviceAuthConfig {
+    /** Code length for the human-readable user code segment (default: 4, produces "XXXX-XXXX") */
+    codeLength?: number;
+    /** Code expiry in seconds (default: 900 = 15 min) */
+    codeExpirySeconds?: number;
+    /** Polling interval in seconds (default: 5) */
+    pollIntervalSeconds?: number;
+    /** Verification URL shown to user */
+    verificationUri: string;
+}
+interface DeviceCodeResponse {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+type DeviceAuthStatus = {
+    status: "pending";
+} | {
+    status: "authorized";
+    userId: string;
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+};
+interface DeviceAuthModule {
+    /** Start device auth flow: returns device_code, user_code, verification_uri */
+    requestCode(): Promise<DeviceCodeResponse>;
+    /** Check if user has authorized (called by polling device) */
+    checkAuthorization(deviceCode: string): Promise<DeviceAuthStatus>;
+    /** Authorize a device (called after user logs in on phone/browser) */
+    authorize(userCode: string, userId: string): Promise<void>;
+    /** Deny a device code (user explicitly rejects) */
+    deny(userCode: string): Promise<void>;
+    /** Handle HTTP requests for the device auth endpoints */
+    handleRequest(request: Request): Promise<Response | null>;
+}
+declare function createDeviceAuthModule(config: DeviceAuthConfig): DeviceAuthModule;
+
+declare function deviceAuth(config: DeviceAuthConfig): KavachPlugin;
+
+declare function emailOtp(config: EmailOtpConfig): KavachPlugin;
+
+/**
+ * GDPR module for KavachOS.
+ *
+ * Implements Article 17 (right to erasure) and Article 20 (right to data
+ * portability) for user accounts. Compliance-critical: every data removal
+ * path is explicit about which tables are affected.
+ *
+ * @example
+ * ```typescript
+ * const gdpr = createGdprModule(db);
+ *
+ * // Export all data for a user
+ * const export = await gdpr.exportUserData(userId);
+ *
+ * // Delete account, keeping anonymized audit trail
+ * const result = await gdpr.deleteUser(userId, { keepAuditLogs: true });
+ *
+ * // Anonymize PII but keep the account (e.g., for orgs that require it)
+ * await gdpr.anonymizeUser(userId);
+ * ```
+ */
+
+interface UserDataExport {
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        createdAt: string;
+    };
+    agents: Array<{
+        id: string;
+        name: string;
+        type: string;
+        status: string;
+        createdAt: string;
+    }>;
+    sessions: Array<{
+        id: string;
+        createdAt: string;
+        expiresAt: string;
+    }>;
+    auditLogs: Array<{
+        action: string;
+        resource: string;
+        result: string;
+        timestamp: string;
+    }>;
+    delegations: Array<{
+        fromAgent: string;
+        toAgent: string;
+        createdAt: string;
+    }>;
+    organizations: Array<{
+        id: string;
+        name: string;
+        role: string;
+    }>;
+    apiKeys: Array<{
+        id: string;
+        name: string;
+        createdAt: string;
+    }>;
+    exportedAt: string;
+}
+interface DeleteOptions {
+    /**
+     * Keep anonymized audit logs (default: true).
+     *
+     * Required for most compliance frameworks — audit records must survive
+     * account deletion. User/agent identity is replaced with a stable hash so
+     * aggregate reporting remains consistent across deleted accounts.
+     */
+    keepAuditLogs?: boolean;
+    /**
+     * Also delete organizations owned by this user (default: false).
+     *
+     * When false, ownership is left in place so other members are unaffected.
+     * Set to true only when the org has no other members or its data should
+     * also be erased.
+     */
+    deleteOrganizations?: boolean;
+}
+interface DeleteResult {
+    deletedAgents: number;
+    deletedSessions: number;
+    deletedDelegations: number;
+    deletedApiKeys: number;
+    anonymizedAuditLogs: number;
+}
+interface GdprModule {
+    /** Export all user data as a structured JSON object (GDPR Article 20). */
+    exportUserData(userId: string): Promise<UserDataExport>;
+    /** Delete all user data (GDPR Article 17). Returns counts of removed records. */
+    deleteUser(userId: string, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Anonymize user data instead of deleting.
+     *
+     * Replaces PII (email, name) with deterministic anonymous values while
+     * keeping the account structure intact. Useful when org membership or
+     * audit referential integrity must be preserved.
+     */
+    anonymizeUser(userId: string): Promise<void>;
+}
+declare function createGdprModule(db: Database): GdprModule;
+
+/**
+ * GDPR plugin for KavachOS.
+ *
+ * Exposes three self-service endpoints that authenticated users can call
+ * to exercise their data rights under GDPR Articles 17 and 20.
+ *
+ * Endpoints:
+ *   GET    /auth/gdpr/export     – download a JSON export of all personal data
+ *   DELETE /auth/gdpr/delete     – permanently delete the account
+ *   POST   /auth/gdpr/anonymize  – strip PII but keep the account shell
+ *
+ * @example
+ * ```typescript
+ * import { createKavach } from 'kavachos';
+ * import { gdpr } from 'kavachos/auth';
+ *
+ * const kavach = await createKavach({
+ *   database: { provider: 'sqlite', url: 'kavach.db' },
+ *   plugins: [gdpr()],
+ * });
+ * ```
+ */
+
+declare function gdpr(): KavachPlugin;
+
+/**
+ * Have I Been Pwned password checking for KavachOS.
+ *
+ * Uses the k-anonymity model: only the first 5 hex characters of the SHA-1
+ * hash are sent to the API. The full hash (and the password itself) never
+ * leave the process.
+ *
+ * @see https://haveibeenpwned.com/API/v3#PwnedPasswords
+ */
+interface HibpConfig {
+    /** Reject passwords seen in more than N breaches (default: 0, reject any). */
+    threshold?: number;
+    /** Custom API base URL, e.g. for a self-hosted HIBP instance. */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 5000). */
+    timeoutMs?: number;
+    /**
+     * What to do when the HIBP API is unreachable or returns an error.
+     * - `'allow'` – treat the password as clean and let the user continue.
+     * - `'block'` – reject the password to be safe.
+     * Default: `'allow'`.
+     */
+    onError?: "allow" | "block";
+}
+interface HibpModule {
+    /**
+     * Check whether the password appears in any known data breach.
+     * Returns the number of times it has been seen, or 0 if clean / API error
+     * with `onError: 'allow'`.
+     */
+    check(password: string): Promise<number>;
+    /**
+     * Like `check`, but throws a `HibpBreachedError` when the breach count
+     * exceeds the configured threshold.
+     */
+    enforce(password: string): Promise<void>;
+}
+declare class HibpBreachedError extends Error {
+    readonly count: number;
+    constructor(count: number);
+}
+declare function createHibpModule(config?: HibpConfig): HibpModule;
+declare class HibpApiError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * JWT session plugin for KavachOS.
+ *
+ * Issues short-lived access JWTs and long-lived refresh tokens for general-purpose
+ * session management. This is distinct from the internal OIDC provider JWT — this
+ * plugin is for apps that want to vend their own session tokens without running a
+ * full OIDC flow.
+ *
+ * Access tokens are stateless JWTs (no DB lookup on verify). Refresh tokens are
+ * opaque random strings stored hashed in the database, soft-revoked on use.
+ *
+ * @example
+ * ```typescript
+ * const sessions = createJwtSessionModule({
+ *   secret: process.env.SESSION_SECRET,
+ *   issuer: 'https://myapp.com',
+ *   customClaims: (user) => ({ role: user.role, org: user.orgId }),
+ * }, db);
+ *
+ * // On login
+ * const result = await sessions.createSession({ id: user.id, email: user.email });
+ * if (result.success) {
+ *   const { accessToken, refreshToken, expiresIn } = result.data;
+ * }
+ *
+ * // On API request
+ * const verified = await sessions.verifySession(bearerToken);
+ * if (verified.success) {
+ *   const { userId, claims } = verified.data;
+ * }
+ *
+ * // On token refresh
+ * const refreshed = await sessions.refreshSession(refreshToken);
+ *
+ * // On logout
+ * await sessions.revokeSession(refreshToken);
+ * ```
+ */
+
+interface JwtSessionConfig {
+    /** Signing key. A plain string uses HMAC-SHA256 (must be >= 32 chars).
+     *  Pass a `CryptoKey` or `JsonWebKey` for RSA/EC algorithms. */
+    secret: string | CryptoKey | JsonWebKey;
+    /** JWT algorithm. Defaults to 'HS256' for string secrets, 'RS256' for keys. */
+    algorithm?: string;
+    /** Access token TTL in seconds. Default: 900 (15 min). */
+    accessTokenTtl?: number;
+    /** Refresh token TTL in seconds. Default: 604800 (7 days). */
+    refreshTokenTtl?: number;
+    /** JWT `iss` claim. */
+    issuer?: string;
+    /** JWT `aud` claim. */
+    audience?: string;
+    /** Attach extra claims to the access token payload. */
+    customClaims?: (user: {
+        id: string;
+        email?: string;
+        name?: string;
+    }) => Record<string, unknown>;
+}
+interface SessionUser {
+    id: string;
+    email?: string;
+    name?: string;
+    image?: string;
+}
+interface SessionTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Seconds until the access token expires (mirrors `accessTokenTtl`). */
+    expiresIn: number;
+}
+interface VerifiedSession {
+    userId: string;
+    email?: string;
+    name?: string;
+    claims: Record<string, unknown>;
+}
+interface JwtSessionModule {
+    /**
+     * Issue a new access + refresh token pair for the given user.
+     *
+     * The refresh token is stored hashed. The raw value is returned once and
+     * cannot be recovered from the database.
+     */
+    createSession(user: SessionUser): Promise<Result<SessionTokens>>;
+    /**
+     * Verify an access token and return the embedded claims.
+     *
+     * Does not touch the database. Fails on expiry, wrong signature, or issuer/
+     * audience mismatch.
+     */
+    verifySession(token: string): Promise<Result<VerifiedSession>>;
+    /**
+     * Exchange a refresh token for a new access + refresh token pair.
+     *
+     * The incoming refresh token is soft-revoked (marked used) on success.
+     * A brand-new refresh token is issued so that each refresh rotates the token.
+     */
+    refreshSession(refreshToken: string): Promise<Result<SessionTokens>>;
+    /**
+     * Revoke a refresh token, preventing any further refreshes.
+     *
+     * Calling this on an already-revoked or unknown token is a no-op (returns
+     * success) so that logout endpoints are idempotent.
+     */
+    revokeSession(refreshToken: string): Promise<Result<void>>;
+}
+/**
+ * Create a JWT session module backed by the provided database.
+ *
+ * The module is stateless beyond the database — multiple instances sharing
+ * the same DB are safe and will honour each other's revocations.
+ */
+declare function createJwtSessionModule(config: JwtSessionConfig, db: Database): JwtSessionModule;
+
+/**
+ * Last login tracking module for KavachOS.
+ *
+ * Records each successful authentication event per user, capturing the method
+ * used, optional IP address, optional user agent, and timestamp. A rolling
+ * window of recent logins is kept — older entries beyond the configured limit
+ * are pruned on every write so storage stays bounded.
+ *
+ * @example
+ * ```typescript
+ * const loginHistory = createLastLoginModule({}, db);
+ *
+ * // After a successful sign-in
+ * await loginHistory.recordLogin({
+ *   userId: 'usr_123',
+ *   method: 'magic-link',
+ *   ip: request.headers.get('x-forwarded-for') ?? undefined,
+ *   userAgent: request.headers.get('user-agent') ?? undefined,
+ * });
+ *
+ * // Show the user their last login on a security page
+ * const result = await loginHistory.getLastLogin('usr_123');
+ * if (result.success) {
+ *   console.log(result.data?.method, result.data?.timestamp);
+ * }
+ * ```
+ */
+
+/**
+ * All supported login methods.
+ *
+ * For OAuth providers use the `oauth:{provider}` pattern, e.g. `oauth:github`,
+ * `oauth:google`, `oauth:microsoft`.
+ */
+type LoginMethod = "email-password" | "magic-link" | "email-otp" | "passkey" | `oauth:${string}` | "username-password" | "phone-sms" | "siwe" | "device-auth" | "anonymous" | "api-key";
+interface LastLoginConfig {
+    /**
+     * Maximum number of login events to retain per user.
+     * Older rows beyond this limit are deleted on every `recordLogin` call.
+     * Default: 10.
+     */
+    maxHistoryPerUser?: number;
+}
+interface RecordLoginInput {
+    userId: string;
+    method: LoginMethod;
+    /** Caller IP address. Stored as-is; normalise before passing if needed. */
+    ip?: string;
+    /** Raw value of the User-Agent request header. */
+    userAgent?: string;
+}
+interface LoginEvent {
+    id: string;
+    userId: string;
+    method: LoginMethod;
+    ip: string | null;
+    userAgent: string | null;
+    timestamp: Date;
+}
+interface LastLoginModule {
+    /**
+     * Record a successful login event for a user.
+     *
+     * If the total stored events for that user exceed `maxHistoryPerUser`, the
+     * oldest events are deleted so only the most recent N are kept.
+     */
+    recordLogin(input: RecordLoginInput): Promise<Result<LoginEvent>>;
+    /**
+     * Retrieve the single most recent login event for a user.
+     *
+     * Returns `null` in `data` when no history exists for the user.
+     */
+    getLastLogin(userId: string): Promise<Result<LoginEvent | null>>;
+    /**
+     * Return login history for a user, newest first.
+     *
+     * @param userId  The user to look up.
+     * @param limit   Maximum number of events to return. Defaults to `maxHistoryPerUser`.
+     */
+    getLoginHistory(userId: string, limit?: number): Promise<Result<LoginEvent[]>>;
+}
+/**
+ * Create a last-login tracking module backed by the provided database.
+ *
+ * The module is stateless — safe to instantiate multiple times against the
+ * same database.
+ */
+declare function createLastLoginModule(config: LastLoginConfig, db: Database): LastLoginModule;
+
+declare function magicLink(config: MagicLinkConfig): KavachPlugin;
+
+interface OAuthProvider {
+    /** Machine-readable provider ID, e.g. `'google'`, `'github'`. */
+    id: string;
+    /** Human-readable provider name. */
+    name: string;
+    /** Base authorization endpoint URL. */
+    authorizationUrl: string;
+    /** Token exchange endpoint URL. */
+    tokenUrl: string;
+    /**
+     * User profile endpoint URL.
+     * Optional — some providers (e.g. Notion) embed user info in the token
+     * response and have no separate endpoint.
+     */
+    userInfoUrl: string | undefined;
+    /** Effective scopes (defaults merged with any user-supplied extras). */
+    scopes: string[];
+    /**
+     * Build the authorization redirect URL.
+     *
+     * @param state        CSRF state value to be validated on callback.
+     * @param codeVerifier PKCE code verifier — the provider derives the challenge.
+     * @param redirectUri  Callback URL to include in the authorization request.
+     */
+    getAuthorizationUrl(state: string, codeVerifier: string, redirectUri: string): Promise<string>;
+    /**
+     * Exchange an authorization code for tokens.
+     *
+     * @param code         The authorization code received on callback.
+     * @param codeVerifier PKCE code verifier used to generate the original challenge.
+     * @param redirectUri  Must match the URI used in the authorization request.
+     */
+    exchangeCode(code: string, codeVerifier: string, redirectUri: string): Promise<OAuthTokens>;
+    /**
+     * Fetch normalized user profile information from the provider.
+     *
+     * @param accessToken A valid access token issued by the provider.
+     */
+    getUserInfo(accessToken: string): Promise<OAuthUserInfo>;
+}
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    /** Lifetime of the access token in seconds. */
+    expiresIn?: number;
+    tokenType: string;
+    /** Raw token response from the provider (unparsed claims). */
+    raw: Record<string, unknown>;
+}
+interface OAuthUserInfo {
+    /** Stable user ID at the provider. */
+    id: string;
+    /**
+     * User email address.
+     * Some providers (e.g. Reddit) do not expose email via OAuth; callers must
+     * handle the undefined case, typically by requiring a separate email step.
+     */
+    email: string | undefined;
+    name?: string;
+    /** URL to the user's avatar image. */
+    avatar?: string;
+    /** Full raw response from the provider's user info endpoint. */
+    raw: Record<string, unknown>;
+}
+
+/**
+ * OAuth proxy module for mobile apps.
+ *
+ * Mobile apps cannot safely store OAuth client secrets. This module acts as a
+ * server-side intermediary: the mobile app redirects to the provider via
+ * KavachOS, which holds the secret and exchanges the authorization code for
+ * tokens on the app's behalf.
+ *
+ * Flow:
+ *   1. Mobile app calls GET /auth/oauth-proxy/start?provider=google&redirect_uri=myapp://callback
+ *   2. KavachOS validates redirect_uri, stores proxy state, returns provider auth URL.
+ *   3. User authenticates with the provider in a browser.
+ *   4. Provider redirects to KavachOS callback with code + state.
+ *   5. KavachOS exchanges the code (using the server-held client secret), then
+ *      redirects the mobile app to its custom scheme URL with tokens as query params.
+ *
+ * Security:
+ *   - redirect_uri is validated against an explicit allowlist — no open redirects.
+ *   - Proxy state is a random UUID stored in memory with a 10-minute TTL.
+ *   - PKCE passthrough: the mobile app may supply a code_challenge; KavachOS
+ *     forwards it to the provider and passes the verifier back via the callback.
+ */
+
+interface OAuthProxyConfig {
+    /**
+     * Allowed redirect URIs for mobile apps (e.g. `"myapp://callback"`).
+     * Only exact matches or scheme-prefix matches (when entry ends with `://`)
+     * are allowed. No wildcards. This is an allowlist — anything not listed
+     * will be rejected.
+     */
+    allowedRedirectUris: string[];
+    /** Rate limit per IP. Defaults to 20 requests per 60 seconds. */
+    rateLimit?: {
+        max: number;
+        windowSeconds: number;
+    };
+    /**
+     * How long a proxy state entry lives in seconds.
+     * Defaults to 600 (10 minutes).
+     */
+    stateTtlSeconds?: number;
+}
+interface ProxyTokens {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn?: number;
+}
+interface OAuthProxyModule {
+    /**
+     * Start the proxy flow.
+     *
+     * Validates `redirectUri` against the allowlist, generates a PKCE verifier,
+     * stores proxy state keyed by an opaque `proxyState` value, and returns the
+     * provider authorization URL for the caller to redirect to.
+     *
+     * @param provider     Provider ID (must be in `providers` map).
+     * @param redirectUri  Mobile app callback URI. Must be in `allowedRedirectUris`.
+     * @param state        Optional caller-supplied state passed back on completion.
+     * @param codeChallenge Optional PKCE code challenge from the mobile app (S256).
+     */
+    startFlow(provider: string, redirectUri: string, state?: string, codeChallenge?: string): Promise<{
+        authUrl: string;
+        proxyState: string;
+    }>;
+    /**
+     * Handle the provider callback.
+     *
+     * Looks up the stored proxy state, exchanges the code with the provider,
+     * and returns the final redirect URL for the mobile app plus the raw tokens.
+     *
+     * @param code        Authorization code from the provider.
+     * @param proxyState  The opaque state value returned by `startFlow`.
+     */
+    handleCallback(code: string, proxyState: string): Promise<{
+        redirectUrl: string;
+        tokens: ProxyTokens;
+    }>;
+    /** Route HTTP requests to the proxy endpoints. Returns null if no match. */
+    handleRequest(request: Request): Promise<Response | null>;
+}
+declare function createOAuthProxyModule(config: OAuthProxyConfig, providers: Record<string, OAuthProvider>, 
+/** Base URL of the KavachOS server, e.g. "https://auth.example.com". */
+baseUrl: string): OAuthProxyModule;
+declare class OAuthProxyError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
+interface OAuthProxyPluginConfig extends OAuthProxyConfig {
+    /**
+     * Provider instances to make available for the proxy.
+     * Keys are the provider IDs used in the `provider` query parameter.
+     *
+     * @example
+     * ```typescript
+     * import { createGoogleProvider } from 'kavachos/auth/oauth/providers/google';
+     *
+     * oauthProxy({
+     *   providers: {
+     *     google: createGoogleProvider({ clientId: '...', clientSecret: '...' }),
+     *   },
+     *   allowedRedirectUris: ['com.example.app://callback'],
+     * })
+     * ```
+     */
+    providers: Record<string, OAuthProvider>;
+}
+declare function oauthProxy(config: OAuthProxyPluginConfig): KavachPlugin;
+
+/**
+ * OIDC Provider module for KavachOS.
+ *
+ * Turns KavachOS into a full OpenID Connect identity provider (IdP).
+ * External applications can register as OIDC clients and authenticate
+ * their users against KavachOS using standard authorization code flow
+ * with PKCE, ID tokens, refresh tokens, discovery, and JWKS.
+ *
+ * @example
+ * ```typescript
+ * import { generateKeyPair } from 'jose';
+ * import { createOidcProviderModule } from 'kavachos/auth';
+ *
+ * const { privateKey } = await generateKeyPair('RS256');
+ * const oidc = createOidcProviderModule(
+ *   {
+ *     issuer: 'https://auth.example.com',
+ *     signingKey: privateKey,
+ *   },
+ *   db,
+ *   getUserClaims,
+ * );
+ *
+ * // Register a client
+ * const client = await oidc.registerClient({
+ *   clientName: 'My App',
+ *   redirectUris: ['https://app.example.com/callback'],
+ * });
+ *
+ * // Discovery
+ * const doc = oidc.getDiscoveryDocument();
+ * ```
+ */
+
+interface OidcProviderConfig {
+    /** Issuer identifier, e.g. "https://auth.example.com". Must be a URL. */
+    issuer: string;
+    /** Private key used to sign ID tokens and access tokens (RSA or EC). */
+    signingKey: CryptoKey | jose.JWK;
+    /** JWT signing algorithm. Default: 'RS256'. */
+    signingAlgorithm?: string;
+    /** Access token lifetime in seconds. Default: 3600 (1 hour). */
+    accessTokenTtl?: number;
+    /** Refresh token lifetime in seconds. Default: 2592000 (30 days). */
+    refreshTokenTtl?: number;
+    /** Authorization code lifetime in seconds. Default: 600 (10 minutes). */
+    authCodeTtl?: number;
+    /** ID token lifetime in seconds. Default: 3600 (1 hour). */
+    idTokenTtl?: number;
+    /** Scopes this provider supports. Default: ['openid', 'profile', 'email']. */
+    supportedScopes?: string[];
+}
+interface RegisterClientInput {
+    clientName: string;
+    redirectUris: string[];
+    grantTypes?: string[];
+    responseTypes?: string[];
+    scopes?: string[];
+    tokenEndpointAuthMethod?: string;
+}
+interface OidcClient {
+    clientId: string;
+    clientSecret: string | null;
+    clientName: string;
+    redirectUris: string[];
+    grantTypes: string[];
+    responseTypes: string[];
+    scopes: string[];
+    tokenEndpointAuthMethod: string;
+    createdAt: Date;
+}
+interface AuthorizeParams {
+    clientId: string;
+    redirectUri: string;
+    responseType: string;
+    scope: string;
+    state?: string;
+    nonce?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: string;
+    /** The authenticated user's ID. Must be resolved before calling authorize. */
+    userId: string;
+}
+interface TokenParams {
+    grantType: string;
+    code?: string;
+    redirectUri?: string;
+    codeVerifier?: string;
+    refreshToken?: string;
+    clientId: string;
+    clientSecret?: string;
+}
+interface TokenResponse {
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+    tokenType: "Bearer";
+    expiresIn: number;
+}
+interface UserInfoClaims {
+    sub: string;
+    email?: string;
+    name?: string;
+    picture?: string;
+    emailVerified?: boolean;
+}
+interface AccessTokenClaims {
+    sub: string;
+    iss: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    jti: string;
+    scope: string;
+    clientId: string;
+}
+interface OidcDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    registration_endpoint: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    subject_types_supported: string[];
+    id_token_signing_alg_values_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    claims_supported: string[];
+    code_challenge_methods_supported: string[];
+}
+interface JsonWebKeySet {
+    keys: jose.JWK[];
+}
+/** Callback to resolve user claims for ID tokens and the userinfo endpoint. */
+type GetUserClaimsFn = (userId: string, scopes: string[]) => Promise<UserInfoClaims>;
+interface OidcProviderModule {
+    registerClient(input: RegisterClientInput): Promise<Result<OidcClient>>;
+    getClient(clientId: string): Promise<Result<OidcClient>>;
+    deleteClient(clientId: string): Promise<Result<void>>;
+    authorize(params: AuthorizeParams): Promise<Result<{
+        code: string;
+        state?: string;
+    }>>;
+    exchangeToken(params: TokenParams): Promise<Result<TokenResponse>>;
+    getUserInfo(accessToken: string): Promise<Result<UserInfoClaims>>;
+    getDiscoveryDocument(): OidcDiscoveryDocument;
+    getJwks(): Promise<JsonWebKeySet>;
+    validateAccessToken(token: string): Promise<Result<AccessTokenClaims>>;
+}
+/**
+ * Create an OIDC Provider module that turns KavachOS into an identity provider.
+ *
+ * @param config       Provider configuration (issuer, signing key, TTLs).
+ * @param db           Drizzle database instance.
+ * @param getUserClaims Callback that resolves user claims given a userId and scopes.
+ */
+declare function createOidcProviderModule(config: OidcProviderConfig, db: Database, getUserClaims: GetUserClaimsFn): OidcProviderModule;
+
+/**
+ * Google One Tap authentication for KavachOS.
+ *
+ * Verifies a Google ID token (issued by the Google Identity Services JS
+ * library) server-side via Google's public JWKS endpoint. No Google SDK
+ * required. Uses `jose` for JWT verification — the same library used
+ * elsewhere in KavachOS.
+ *
+ * Flow:
+ * 1. Front-end includes the Google Identity Services script and mounts the
+ *    One Tap prompt.
+ * 2. On sign-in the browser POSTs the `credential` (ID token) to
+ *    POST /auth/one-tap/callback.
+ * 3. This module verifies the token, finds or creates the user, and returns
+ *    a session.
+ *
+ * CSRF: Google's JS library sets a `g_csrf_token` cookie and includes the
+ * same value in the POST body. Both must match.
+ *
+ * @example
+ * ```typescript
+ * const kavach = await createKavach({
+ *   database: { provider: 'sqlite', url: 'kavach.db' },
+ *   auth: { session: { secret: process.env.SESSION_SECRET } },
+ * });
+ *
+ * // Use via plugin
+ * import { oneTap } from 'kavachos/auth';
+ * // plugins: [oneTap({ clientId: process.env.GOOGLE_CLIENT_ID })]
+ *
+ * // Or use the module directly
+ * const tap = createOneTapModule({ clientId: '...' }, db, sessionManager);
+ * const googleUser = await tap.verify(idToken);
+ * ```
+ */
+
+interface OneTapConfig {
+    /** Google OAuth client ID */
+    clientId: string;
+    /** Auto-create user if not found (default: true) */
+    autoCreateUser?: boolean;
+    /** CSRF token cookie name (default: "g_csrf_token") */
+    csrfCookieName?: string;
+}
+interface GoogleUser {
+    /** Google user ID (stable, use this as the external ID) */
+    sub: string;
+    email: string;
+    emailVerified: boolean;
+    name: string;
+    givenName?: string;
+    familyName?: string;
+    picture?: string;
+}
+interface OneTapModule {
+    /**
+     * Verify a Google ID token and return the decoded user claims.
+     * Throws if the token is invalid, expired, or issued for the wrong audience.
+     */
+    verify(idToken: string): Promise<GoogleUser>;
+    /**
+     * Handle the POST callback from Google's JS library.
+     *
+     * Expects `application/x-www-form-urlencoded` with `credential` and
+     * `g_csrf_token` fields (plus the matching CSRF cookie). Returns a JSON
+     * response with `{ user, session }` on success or null when the path does
+     * not match (allowing fall-through to other handlers).
+     */
+    handleRequest(request: Request): Promise<Response | null>;
+}
+declare class OneTapVerifyError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare function createOneTapModule(config: OneTapConfig, db: Database, sessionManager: SessionManager): OneTapModule;
+
+declare function oneTap(config: OneTapConfig): KavachPlugin;
+
+/**
+ * One-time token module for KavachOS.
+ *
+ * Issues single-use tokens for email verification, password resets,
+ * invitations, and custom flows. The raw token is returned to the caller
+ * once and never persisted — only a SHA-256 hash is stored. Tokens are
+ * invalidated on first use or when they expire.
+ *
+ * @example
+ * ```typescript
+ * const tokens = createOneTimeTokenModule({}, db);
+ *
+ * // Create a password-reset token
+ * const result = await tokens.createToken({
+ *   purpose: 'password-reset',
+ *   identifier: 'alice@example.com',
+ *   ttlSeconds: 1800,
+ * });
+ * if (result.success) {
+ *   await mailer.send({ to: 'alice@example.com', token: result.data.token });
+ * }
+ *
+ * // Validate (and consume) on the reset page
+ * const validation = await tokens.validateToken(incomingToken, 'password-reset');
+ * if (validation.success) {
+ *   // validation.data.identifier === 'alice@example.com'
+ * }
+ * ```
+ */
+
+/** Token purpose discriminator. Use 'custom' for any application-specific flow. */
+type OneTimeTokenPurpose = "email-verify" | "password-reset" | "invitation" | "custom";
+interface OneTimeTokenConfig {
+    /** Default TTL in seconds when none is specified per-call. Default: 3600 (1 hour). */
+    defaultTtlSeconds?: number;
+}
+interface CreateTokenInput {
+    purpose: OneTimeTokenPurpose;
+    /** Email address, user ID, or any caller-supplied key that scopes the token. */
+    identifier: string;
+    /** Arbitrary data to associate with the token (e.g. org ID, invited role). */
+    metadata?: Record<string, unknown>;
+    /** Override the module-level default TTL for this token only. */
+    ttlSeconds?: number;
+}
+interface ValidateTokenResult {
+    identifier: string;
+    metadata?: Record<string, unknown>;
+}
+interface RevokeTokensResult {
+    count: number;
+}
+interface OneTimeTokenModule {
+    /**
+     * Create a new one-time token.
+     *
+     * Returns the raw token (hex string) exactly once. Store it in your email
+     * or link — it cannot be recovered from the database afterwards.
+     */
+    createToken(input: CreateTokenInput): Promise<Result<{
+        token: string;
+        expiresAt: Date;
+    }>>;
+    /**
+     * Validate a token and mark it as used.
+     *
+     * Fails when the token is unknown, already used, expired, or belongs to a
+     * different purpose. On success the token is consumed immediately.
+     */
+    validateToken(token: string, purpose: string): Promise<Result<ValidateTokenResult>>;
+    /**
+     * Revoke all active tokens for an identifier, optionally scoped to a purpose.
+     *
+     * Useful for invalidating outstanding password-reset links when a user
+     * changes their password through another flow, or for cleaning up on account
+     * deletion.
+     */
+    revokeTokens(identifier: string, purpose?: string): Promise<Result<RevokeTokensResult>>;
+}
+/**
+ * Create a one-time token module backed by the provided database.
+ *
+ * The module is stateless — no in-memory caches — so multiple instances
+ * sharing the same database are safe.
+ */
+declare function createOneTimeTokenModule(config: OneTimeTokenConfig, db: Database): OneTimeTokenModule;
+
+/**
+ * OpenAPI 3.1 spec generation plugin for KavachOS.
+ *
+ * Generates a complete OpenAPI document from KavachOS's registered auth
+ * endpoints. Useful for serving at `/api/kavach/openapi.json` or wiring
+ * into Swagger UI / Scalar.
+ *
+ * @example
+ * ```typescript
+ * import { createOpenApiModule } from 'kavachos/auth';
+ *
+ * const openapi = createOpenApiModule();
+ * const spec = openapi.generateSpec({
+ *   title: 'My App Auth API',
+ *   serverUrl: 'https://api.example.com',
+ *   include: ['auth', 'sessions', 'api-keys'],
+ * });
+ *
+ * // In your request handler:
+ * const response = openapi.handleRequest(request);
+ * if (response) return response;
+ * ```
+ */
+type EndpointGroup = "agents" | "auth" | "oauth" | "mcp" | "admin" | "organizations" | "sessions" | "api-keys" | "webhooks";
+interface OpenApiConfig {
+    /** API title shown in spec. Default: "KavachOS API" */
+    title?: string;
+    /** Spec version string. Default: "0.0.1" */
+    version?: string;
+    /** Short description of the API */
+    description?: string;
+    /** Server base URL. Default: "/" */
+    serverUrl?: string;
+    /** Path prefix for all KavachOS endpoints. Default: "/api/kavach" */
+    basePath?: string;
+    /**
+     * Limit which endpoint groups are included in the spec.
+     * When omitted all groups are included.
+     */
+    include?: EndpointGroup[];
+}
+interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+}
+interface OpenApiServer {
+    url: string;
+}
+interface OpenApiSchema {
+    type?: string;
+    properties?: Record<string, OpenApiSchema>;
+    required?: string[];
+    items?: OpenApiSchema;
+    description?: string;
+    example?: unknown;
+    enum?: unknown[];
+    format?: string;
+    nullable?: boolean;
+    additionalProperties?: boolean | OpenApiSchema;
+    oneOf?: OpenApiSchema[];
+}
+interface OpenApiMediaType {
+    schema: OpenApiSchema;
+}
+interface OpenApiRequestBody {
+    required?: boolean;
+    content: Record<string, OpenApiMediaType>;
+}
+interface OpenApiResponse {
+    description: string;
+    content?: Record<string, OpenApiMediaType>;
+}
+interface OpenApiSecurityRequirement {
+    [schemeName: string]: string[];
+}
+interface OpenApiOperation {
+    operationId: string;
+    summary: string;
+    tags: string[];
+    security?: OpenApiSecurityRequirement[];
+    requestBody?: OpenApiRequestBody;
+    responses: Record<string, OpenApiResponse>;
+    parameters?: OpenApiParameter[];
+}
+interface OpenApiParameter {
+    name: string;
+    in: "path" | "query" | "header" | "cookie";
+    required?: boolean;
+    schema: OpenApiSchema;
+    description?: string;
+}
+interface OpenApiPathItem {
+    get?: OpenApiOperation;
+    post?: OpenApiOperation;
+    put?: OpenApiOperation;
+    patch?: OpenApiOperation;
+    delete?: OpenApiOperation;
+}
+interface OpenApiSecurityScheme {
+    type: string;
+    scheme?: string;
+    bearerFormat?: string;
+    description?: string;
+    in?: string;
+    name?: string;
+    flows?: Record<string, unknown>;
+}
+interface OpenApiComponents {
+    securitySchemes: Record<string, OpenApiSecurityScheme>;
+    schemas: Record<string, OpenApiSchema>;
+}
+interface OpenApiDocument {
+    openapi: "3.1.0";
+    info: OpenApiInfo;
+    servers: OpenApiServer[];
+    paths: Record<string, OpenApiPathItem>;
+    components: OpenApiComponents;
+    tags: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+interface OpenApiModule {
+    /** Generate a complete OpenAPI 3.1.0 document */
+    generateSpec(config?: OpenApiConfig): OpenApiDocument;
+    /**
+     * Handle an HTTP request for the spec JSON.
+     *
+     * Returns a `Response` with the spec when the request path ends with
+     * `/openapi.json`. Returns `null` for any other path so the caller's
+     * routing continues normally.
+     */
+    handleRequest(request: Request, config?: OpenApiConfig): Response | null;
+}
+/**
+ * Create an OpenAPI module that generates KavachOS API specifications.
+ *
+ * The returned module is stateless and safe to share across requests.
+ */
+declare function createOpenApiModule(): OpenApiModule;
+
+declare function organization(config?: OrgConfig): KavachPlugin;
+
+declare function passkey(config: PasskeyConfig): KavachPlugin;
+
+/**
+ * Polar payment integration for KavachOS.
+ *
+ * Links Polar customers to KavachOS users, handles subscription lifecycle
+ * webhooks, and stores subscription status. Uses Polar's REST API directly
+ * via fetch — no Polar SDK dependency.
+ *
+ * @example
+ * ```typescript
+ * import { createPolarModule } from 'kavachos/auth';
+ *
+ * const polar = createPolarModule({
+ *   accessToken: process.env.POLAR_ACCESS_TOKEN!,
+ *   webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
+ *   sandbox: process.env.NODE_ENV !== 'production',
+ *   onSubscriptionChange: async (userId, sub) => {
+ *     console.log(`User ${userId} subscription: ${sub.status}`);
+ *   },
+ * }, db);
+ *
+ * const { url } = await polar.createCheckout(userId, 'product_xxx', {
+ *   successUrl: 'https://example.com/success',
+ * });
+ * ```
+ */
+
+interface PolarConfig {
+    /** Polar access token */
+    accessToken: string;
+    /** Polar webhook secret for HMAC-SHA256 signature verification */
+    webhookSecret: string;
+    /** Optional organization ID to scope requests */
+    organizationId?: string;
+    /** Use sandbox.polar.sh instead of polar.sh (default: false) */
+    sandbox?: boolean;
+    /** Callback fired whenever subscription data changes for a user */
+    onSubscriptionChange?: (userId: string, subscription: PolarSubscription) => Promise<void>;
+}
+interface PolarSubscription {
+    id: string;
+    status: "active" | "canceled" | "incomplete" | "past_due" | "trialing" | "unpaid";
+    productId: string;
+    currentPeriodEnd: Date;
+    cancelAtPeriodEnd: boolean;
+}
+interface PolarModule {
+    /** Create a Polar checkout session and return its URL + ID */
+    createCheckout(userId: string, productId: string, options?: {
+        successUrl?: string;
+        customerEmail?: string;
+    }): Promise<{
+        url: string;
+        id: string;
+    }>;
+    /** Return current subscription info for a user from the database */
+    getSubscription(userId: string): Promise<PolarSubscription | null>;
+    /** Verify Polar webhook signature and dispatch to internal handlers */
+    handleWebhook(request: Request): Promise<Response>;
+    /** Route an incoming HTTP request to the appropriate handler (returns null if path unmatched) */
+    handleRequest(request: Request): Promise<Response | null>;
+}
+declare function createPolarModule(config: PolarConfig, db: Database): PolarModule;
+
+declare function polar(config: PolarConfig): KavachPlugin;
+
+/**
+ * In-memory sliding window rate limiter for auth endpoints.
+ *
+ * Uses a Map keyed by the caller-supplied string (typically an IP address).
+ * Each entry stores a list of request timestamps within the current window.
+ * Expired timestamps are pruned on every check so memory stays bounded.
+ */
+interface RateLimitConfig {
+    /** Max requests allowed within the window */
+    max: number;
+    /** Window duration in seconds */
+    window: number;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    /** Requests remaining in the current window */
+    remaining: number;
+    /** When the oldest in-window request expires and a slot re-opens */
+    resetAt: Date;
+}
+interface RateLimiter {
+    /** Check whether the key is within its limit. Consumes one slot when allowed. */
+    check(key: string): RateLimitResult;
+    /** Clear all recorded hits for a key (useful in tests or on successful auth). */
+    reset(key: string): void;
+}
+declare function createRateLimiter(config: RateLimitConfig): RateLimiter;
+
+/**
+ * Higher-order function that wraps a plugin endpoint handler with IP-based
+ * rate limiting. When the limit is exceeded it responds with 429 and a
+ * Retry-After header before the wrapped handler is ever called.
+ */
+
+interface RateLimitMiddlewareOptions {
+    /**
+     * Derive the rate-limit key from the incoming request.
+     *
+     * Defaults to the first non-empty value of:
+     *   x-forwarded-for → first IP in the comma-separated list
+     *   x-real-ip
+     *   "unknown"
+     */
+    keyExtractor?: (request: Request) => string;
+}
+declare function withRateLimit(handler: PluginEndpoint["handler"], limiter: RateLimiter, options?: RateLimitMiddlewareOptions): PluginEndpoint["handler"];
+
+/**
+ * SCIM 2.0 directory sync for KavachOS.
+ *
+ * Implements RFC 7644 (SCIM 2.0 protocol) to allow enterprise identity
+ * providers (Okta, Azure AD, Google Workspace) to provision and deprovision
+ * users and groups automatically.
+ *
+ * Users map to kavach_users. Groups map to kavach_organizations.
+ *
+ * @example
+ * ```typescript
+ * import { createScimModule } from 'kavachos/auth';
+ *
+ * const scim = createScimModule({
+ *   bearerToken: process.env.SCIM_TOKEN,
+ *   onProvision: async (user) => {
+ *     console.log('Provisioned:', user.userName);
+ *   },
+ * }, db);
+ *
+ * // In your request handler:
+ * const response = await scim.handleRequest(request);
+ * ```
+ */
+
+interface ScimConfig {
+    /** Bearer token for SCIM API authentication */
+    bearerToken: string;
+    /** Whether to auto-create users on provision (default: true) */
+    autoCreateUsers?: boolean;
+    /** Whether to auto-deactivate users on deprovision (default: true) */
+    autoDeactivateUsers?: boolean;
+    /** Callback when user is provisioned */
+    onProvision?: (user: ScimUser) => Promise<void>;
+    /** Callback when user is deprovisioned */
+    onDeprovision?: (userId: string) => Promise<void>;
+}
+interface ScimUser {
+    id: string;
+    userName: string;
+    name?: {
+        givenName?: string;
+        familyName?: string;
+    };
+    emails?: Array<{
+        value: string;
+        primary?: boolean;
+    }>;
+    active?: boolean;
+    externalId?: string;
+}
+interface ScimGroup {
+    id: string;
+    displayName: string;
+    externalId?: string;
+    members?: Array<{
+        value: string;
+        display?: string;
+    }>;
+}
+interface ScimModule {
+    handleRequest(request: Request): Promise<Response | null>;
+}
+declare function createScimModule(config: ScimConfig, db: Database): ScimModule;
+
+/**
+ * SCIM 2.0 directory sync plugin for KavachOS.
+ *
+ * Mounts SCIM endpoints under `/scim/v2/` so enterprise IdPs (Okta, Azure AD,
+ * Google Workspace) can provision and deprovision users and groups.
+ *
+ * All endpoints require a static Bearer token supplied via `config.bearerToken`.
+ *
+ * @example
+ * ```typescript
+ * import { createKavach } from 'kavachos';
+ * import { scim } from 'kavachos/auth';
+ *
+ * const kavach = await createKavach({
+ *   database: { provider: 'sqlite', url: 'kavach.db' },
+ *   plugins: [
+ *     scim({
+ *       bearerToken: process.env.SCIM_TOKEN,
+ *       onProvision: async (user) => {
+ *         await sendWelcomeEmail(user.emails?.[0]?.value);
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function scim(config: ScimConfig): KavachPlugin;
+
+/**
+ * Sign In With Ethereum (SIWE) for KavachOS.
+ *
+ * Authenticates users by verifying an Ethereum wallet signature per EIP-4361.
+ * Full secp256k1 recovery requires ethers or viem as peer deps — this module
+ * validates message format and nonce integrity. Add a `verify` override via
+ * `verifySignature` option when you want cryptographic proof.
+ *
+ * @example
+ * ```typescript
+ * const siwe = createSiweModule({
+ *   domain: 'example.com',
+ *   uri: 'https://example.com',
+ *   statement: 'Sign in to Example App',
+ * });
+ *
+ * // 1. Frontend requests a nonce
+ * const nonce = await siwe.generateNonce();
+ *
+ * // 2. Frontend builds the message and asks wallet to sign it
+ * const message = siwe.buildMessage('0xAbc...', nonce, 1);
+ *
+ * // 3. Frontend submits message + signature
+ * const { address, chainId } = await siwe.verify(message, signature);
+ * ```
+ */
+interface SiweConfig {
+    /** Your app's domain (e.g., "example.com") */
+    domain: string;
+    /** URI (e.g., "https://example.com") */
+    uri: string;
+    /** Statement shown in wallet (optional) */
+    statement?: string;
+    /** Nonce TTL in seconds (default: 300) */
+    nonceTtlSeconds?: number;
+    /**
+     * Optional signature verifier. Called with the EIP-4361 message and
+     * hex signature. Should return the recovered Ethereum address.
+     * When omitted, the module trusts the address from the message body
+     * (suitable for development; add viem/ethers recovery in production).
+     */
+    verifySignature?: (message: string, signature: string) => Promise<string>;
+}
+interface SiweModule {
+    /** Generate a nonce for the SIWE message */
+    generateNonce(): Promise<string>;
+    /** Build the EIP-4361 message for the wallet to sign */
+    buildMessage(address: string, nonce: string, chainId?: number): string;
+    /** Verify the signed message and return the Ethereum address */
+    verify(message: string, signature: string): Promise<{
+        address: string;
+        chainId: number;
+    }>;
+    /** Handle full SIWE auth flow via HTTP */
+    handleRequest(request: Request): Promise<Response | null>;
+}
+interface SiweVerifyResult {
+    address: string;
+    chainId: number;
+}
+declare function createSiweModule(config: SiweConfig): SiweModule;
+
+declare function siwe(config: SiweConfig): KavachPlugin;
+
+/**
+ * Stripe payment integration for KavachOS.
+ *
+ * Links Stripe customers to KavachOS users, handles subscription lifecycle
+ * webhooks, and stores subscription status. Uses Stripe's REST API directly
+ * via fetch — no Stripe SDK dependency.
+ *
+ * @example
+ * ```typescript
+ * import { createStripeModule } from 'kavachos/auth';
+ *
+ * const stripe = createStripeModule({
+ *   secretKey: process.env.STRIPE_SECRET_KEY!,
+ *   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+ *   autoCreateCustomer: true,
+ * }, db);
+ *
+ * const customerId = await stripe.createCustomer(userId, email, name);
+ * const { url } = await stripe.createCheckoutSession(userId, priceId, {
+ *   successUrl: 'https://example.com/success',
+ *   cancelUrl: 'https://example.com/cancel',
+ * });
+ * ```
+ */
+
+interface StripeConfig {
+    /** Stripe secret key (sk_live_... or sk_test_...) */
+    secretKey: string;
+    /** Stripe webhook signing secret (whsec_...) */
+    webhookSecret: string;
+    /** Auto-create a Stripe customer when the user record is referenced (default: true) */
+    autoCreateCustomer?: boolean;
+    /** Stripe API version (default: "2024-12-18.acacia") */
+    apiVersion?: string;
+    /** Callback fired whenever subscription data changes for a user */
+    onSubscriptionChange?: (userId: string, subscription: SubscriptionInfo) => Promise<void>;
+}
+interface SubscriptionInfo {
+    id: string;
+    status: "active" | "canceled" | "past_due" | "trialing" | "unpaid" | "incomplete";
+    priceId: string;
+    currentPeriodEnd: Date;
+    cancelAtPeriodEnd: boolean;
+}
+interface CheckoutOptions {
+    successUrl?: string;
+    cancelUrl?: string;
+    trialDays?: number;
+    metadata?: Record<string, string>;
+}
+interface StripeModule {
+    /** Create a Stripe customer for a user and persist the customer ID */
+    createCustomer(userId: string, email: string, name?: string): Promise<string>;
+    /** Get the Stripe customer ID stored for a user */
+    getCustomerId(userId: string): Promise<string | null>;
+    /** Create a Stripe Checkout Session and return its URL + ID */
+    createCheckoutSession(userId: string, priceId: string, options?: CheckoutOptions): Promise<{
+        url: string;
+        sessionId: string;
+    }>;
+    /** Create a Stripe Billing Portal session and return its URL */
+    createPortalSession(userId: string, returnUrl: string): Promise<{
+        url: string;
+    }>;
+    /** Return current subscription info for a user from the database */
+    getSubscription(userId: string): Promise<SubscriptionInfo | null>;
+    /** Verify Stripe webhook signature and dispatch to internal handlers */
+    handleWebhook(request: Request): Promise<Response>;
+    /** Route an incoming HTTP request to the appropriate handler (returns null if path unmatched) */
+    handleRequest(request: Request): Promise<Response | null>;
+}
+declare function createStripeModule(config: StripeConfig, db: Database): StripeModule;
+
+declare function stripe(config: StripeConfig): KavachPlugin;
+
+type TwoFactorConfig = TotpConfig;
+declare function twoFactor(config?: TwoFactorConfig): KavachPlugin;
+
+/**
+ * Trusted device windows for 2FA in KavachOS.
+ *
+ * After a successful 2FA challenge, a device can be marked as trusted.
+ * Subsequent logins from the same device skip 2FA until the trust window
+ * expires (default 30 days) or trust is explicitly revoked.
+ *
+ * Fingerprints are HMAC-signed to prevent client-side spoofing.
+ */
+
+interface TrustedDeviceConfig {
+    /** How long to trust a device in seconds (default: 30 days). */
+    trustDurationSeconds?: number;
+    /** Maximum number of trusted devices per user (default: 10). */
+    maxDevices?: number;
+    /**
+     * Secret used to HMAC-sign fingerprints, preventing client spoofing.
+     * Should be a stable application secret (e.g. from env). If omitted a
+     * random per-process key is used (fingerprints won't survive restarts).
+     */
+    secret?: string;
+}
+interface TrustedDevice {
+    id: string;
+    fingerprint: string;
+    label: string;
+    trustedAt: Date;
+    expiresAt: Date;
+}
+interface TrustedDeviceModule {
+    /**
+     * Mark the device identified by `deviceFingerprint` as trusted for
+     * `userId`. Returns a stable trust token (the record id) that can be
+     * stored in a long-lived cookie.
+     */
+    trustDevice(userId: string, deviceFingerprint: string): Promise<string>;
+    /** Returns true if the device is currently trusted (not expired). */
+    isTrusted(userId: string, deviceFingerprint: string): Promise<boolean>;
+    /** Remove trust for a single device. */
+    revokeDevice(userId: string, deviceFingerprint: string): Promise<void>;
+    /** Remove trust for every device belonging to a user. */
+    revokeAllDevices(userId: string): Promise<void>;
+    /** List all active trusted devices for a user. */
+    listDevices(userId: string): Promise<TrustedDevice[]>;
+    /**
+     * Derive a stable, HMAC-protected fingerprint from request headers.
+     * The same request will always produce the same fingerprint; changing
+     * user-agent or accept-language invalidates the fingerprint.
+     */
+    generateFingerprint(request: Request): string;
+}
+declare function createTrustedDeviceModule(config: TrustedDeviceConfig, db: Database): TrustedDeviceModule;
+/**
+ * Derive a human-readable device label from a request's User-Agent header.
+ * Useful when calling `trustDevice` so the stored label is descriptive.
+ */
+declare function deviceLabelFromRequest(request: Request): string;
+
+export { type AccessTokenClaims, type AdditionalFieldsConfig, type AdditionalFieldsModule, AdminConfig, type AnonymousAuthConfig, type AnonymousAuthModule, ApiKeyManagerConfig, AuthAdapter, type AuthorizeParams, type BearerAuthOptions, type CheckoutOptions, type CreateTokenInput, type CustomSessionConfig, type CustomSessionModule, type DeleteOptions, type DeleteResult, type DeviceAuthConfig, type DeviceAuthModule, type DeviceAuthStatus, type DeviceCodeResponse, EmailOtpConfig, type EndpointGroup, type FieldDefinition, type GdprModule, type GetUserClaimsFn, type GoogleUser, type HeaderAuthOptions, HibpApiError, HibpBreachedError, type HibpConfig, type HibpModule, type JsonWebKeySet, type JwtSessionConfig, type JwtSessionModule, type LastLoginConfig, type LastLoginModule, type LoginEvent, type LoginMethod, MagicLinkConfig, type OAuthProxyConfig, OAuthProxyError, type OAuthProxyModule, type OAuthProxyPluginConfig, type OidcClient, type OidcDiscoveryDocument, type OidcProviderConfig, type OidcProviderModule, type OneTapConfig, type OneTapModule, OneTapVerifyError, type OneTimeTokenConfig, type OneTimeTokenModule, type OneTimeTokenPurpose, type OpenApiComponents, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiMediaType, type OpenApiModule, type OpenApiOperation, type OpenApiParameter, type OpenApiPathItem, type OpenApiRequestBody, type OpenApiResponse, type OpenApiSchema, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServer, OrgConfig, PasskeyConfig, type PolarConfig, type PolarModule, type PolarSubscription, type ProxyTokens, type RateLimitConfig, type RateLimitMiddlewareOptions, type RateLimitResult, type RateLimiter, type RecordLoginInput, type RegisterClientInput, ResolvedUser, type RevokeTokensResult, type ScimConfig, type ScimGroup, type ScimModule, type ScimUser, type SessionTokens, type SessionUser, type SiweConfig, type SiweModule, type SiweVerifyResult, type StripeConfig, type StripeModule, type SubscriptionInfo, type TokenParams, type TokenResponse, TotpConfig, type TrustedDevice, type TrustedDeviceConfig, type TrustedDeviceModule, type TwoFactorConfig, type UserDataExport, type UserInfoClaims, type ValidateTokenResult, type ValidationResult, type VerifiedSession, additionalFields, admin, anonymousAuth, apiKeys, bearerAuth, createAdditionalFieldsModule, createAnonymousAuthModule, createCustomSessionModule, createDeviceAuthModule, createGdprModule, createHibpModule, createJwtSessionModule, createLastLoginModule, createOAuthProxyModule, createOidcProviderModule, createOneTapModule, createOneTimeTokenModule, createOpenApiModule, createPolarModule, createRateLimiter, createScimModule, createSiweModule, createStripeModule, createTrustedDeviceModule, customAuth, customSession, deviceAuth, deviceLabelFromRequest, emailOtp, gdpr, headerAuth, magicLink, oauthProxy, oneTap, organization, passkey, polar, scim, siwe, stripe, twoFactor, withRateLimit };