@glinr/theauth 0.4.2

package/dist/auth/index.d.ts

@@ -0,0 +1,3466 @@
+import { z } from 'zod';
+import { a5 as AuthAdapter, o as ResolvedUser, X as KavachPlugin, D as Database, _ as AdminConfig, p as SessionManager, a2 as ApiKeyManagerConfig, aa as EmailOtpConfig, P as Permission, ae as MagicLinkConfig, aj as OrgConfig, ao as PasskeyConfig, N as PluginEndpoint, aF as TotpConfig } from '../types-D1sBnWrs.js';
+export { u as AdminModule, $ as AdminUser, a1 as ApiKey, v as ApiKeyManagerModule, a6 as CaptchaConfig, G as CaptchaModule, a7 as CaptchaVerifyResult, a8 as CreateTokenInput, E as EmailOtpModule, ab as EmailVerificationConfig, y as EmailVerificationModule, r as MagicLinkModule, ag as OidcProvider, ah as OneTimeTokenConfig, z as OneTimeTokenModule, ai as OneTimeTokenPurpose, ak as OrgInvitation, al as OrgMember, O as OrgModule, am as OrgRole, an as Organization, ap as PasskeyCredential, s as PasskeyModule, aq as PasswordResetConfig, x as PasswordResetModule, as as PhoneAuthConfig, F as PhoneAuthModule, av as RevokeTokensResult, aw as SSO_ERROR, ax as SamlProvider, aA as SsoAuditEvent, aB as SsoConfig, aC as SsoConnection, aD as SsoError, t as SsoModule, T as TotpModule, aG as TotpSetup, aH as UsernameAuthConfig, w as UsernameAuthModule, aI as ValidateTokenResult, bu as WebhookConfig, bv as WebhookEvent, W as WebhookModule, aS as createAdminModule, aT as createApiKeyManagerModule, aV as createCaptchaModule, aY as createEmailOtpModule, aZ as createEmailVerificationModule, a_ as createMagicLinkModule, a$ as createOneTimeTokenModule, b0 as createOrgModule, b1 as createPasskeyModule, b2 as createPasswordResetModule, b3 as createPhoneAuthModule, b6 as createSsoModule, b7 as createTotpModule, b8 as createUsernameAuthModule, bw as createWebhookModule } from '../types-D1sBnWrs.js';
+import { R as Result } from '../types-BiUe9e8u.js';
+import { AgentType, TrustTier } from '../standards/index.js';
+import * as jose from 'jose';
+import 'drizzle-orm/sqlite-core';
+import '../redirect/index.js';
+
+/**
+ * JWT bearer-token auth adapter.
+ *
+ * Verifies a JWT from the `Authorization: Bearer <token>` header using a
+ * symmetric secret (HS256/HS384/HS512).  Extracts `sub`, `email`, `name`, and
+ * `picture` from the payload and returns them as a `ResolvedUser`.
+ *
+ * @example
+ * ```typescript
+ * import { bearerAuth } from '@glinr/theauth/auth';
+ *
+ * const adapter = bearerAuth({
+ *   secret: process.env.JWT_SECRET,
+ *   issuer: 'https://my-app.example.com',
+ *   audience: 'theauth',
+ * });
+ * ```
+ */
+
+declare const BearerAuthOptionsSchema: z.ZodObject<{
+    /**
+     * Secret used to verify HS256/HS384/HS512 tokens.
+     * Must be at least 32 characters.
+     */
+    secret: z.ZodString;
+    /** Expected `iss` claim.  Omit to skip issuer validation. */
+    issuer: z.ZodOptional<z.ZodString>;
+    /** Expected `aud` claim.  Omit to skip audience validation. */
+    audience: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    secret: string;
+    issuer?: string | undefined;
+    audience?: string | undefined;
+}, {
+    secret: string;
+    issuer?: string | undefined;
+    audience?: string | undefined;
+}>;
+type BearerAuthOptions = z.infer<typeof BearerAuthOptionsSchema>;
+/**
+ * Create an `AuthAdapter` that validates a JWT from the `Authorization: Bearer`
+ * header and maps its claims to a `ResolvedUser`.
+ *
+ * Returns `null` when:
+ * - No `Authorization` header is present
+ * - The header does not use the `Bearer` scheme
+ * - The JWT signature is invalid, the token is expired, or claims do not match
+ *   the configured `issuer` / `audience`
+ */
+declare function bearerAuth(options: BearerAuthOptions): AuthAdapter;
+
+/**
+ * Custom resolver auth adapter.
+ *
+ * Wraps an arbitrary resolver function as an `AuthAdapter`.  Use this when
+ * you need to integrate with an auth provider that does not have a built-in
+ * adapter (e.g. better-auth, Auth.js, Clerk, Supabase Auth, etc.).
+ *
+ * @example Clerk session cookie
+ * ```typescript
+ * import { customAuth } from '@glinr/theauth/auth';
+ * import { clerkClient } from '@clerk/clerk-sdk-node';
+ *
+ * const adapter = customAuth(async (request) => {
+ *   const sessionToken = request.headers.get('cookie')
+ *     ?.split('; ')
+ *     .find(c => c.startsWith('__session='))
+ *     ?.split('=')[1];
+ *
+ *   if (!sessionToken) return null;
+ *
+ *   const session = await clerkClient.sessions.verifySession('', sessionToken);
+ *   return { id: session.userId };
+ * });
+ * ```
+ *
+ * @example better-auth
+ * ```typescript
+ * import { customAuth } from '@glinr/theauth/auth';
+ * import { auth } from './lib/auth';   // your better-auth instance
+ *
+ * const adapter = customAuth(async (request) => {
+ *   const session = await auth.api.getSession({ headers: request.headers });
+ *   if (!session?.user) return null;
+ *   return {
+ *     id: session.user.id,
+ *     email: session.user.email ?? undefined,
+ *     name: session.user.name ?? undefined,
+ *     image: session.user.image ?? undefined,
+ *   };
+ * });
+ * ```
+ */
+
+/**
+ * Create an `AuthAdapter` from a custom resolver function.
+ *
+ * The resolver receives the raw `Request` and must return either a
+ * `ResolvedUser` or `null` (unauthenticated).
+ */
+declare function customAuth(resolver: (request: Request) => Promise<ResolvedUser | null>): AuthAdapter;
+
+/**
+ * Header-based auth adapter.
+ *
+ * Extracts the user ID from a trusted request header.  Designed for services
+ * deployed behind an auth proxy (e.g. Nginx, Cloudflare Access, AWS ALB) that
+ * injects a verified user-identity header before forwarding requests.
+ *
+ * @example Default header (`X-User-Id`)
+ * ```typescript
+ * import { headerAuth } from '@glinr/theauth/auth';
+ *
+ * const adapter = headerAuth();
+ * ```
+ *
+ * @example Custom header
+ * ```typescript
+ * const adapter = headerAuth({ header: 'X-Authenticated-User' });
+ * ```
+ *
+ * IMPORTANT: Only use this adapter when the header cannot be forged by the
+ * client (i.e. the upstream proxy strips or overrides it).
+ */
+
+interface HeaderAuthOptions {
+    /**
+     * Name of the HTTP header that carries the user ID.
+     * Defaults to `X-User-Id`.
+     */
+    header?: string;
+}
+/**
+ * Create an `AuthAdapter` that extracts the user identity from a request header.
+ *
+ * Returns `null` when the header is absent or its value is empty.
+ */
+declare function headerAuth(options?: HeaderAuthOptions): AuthAdapter;
+
+/**
+ * Additional user/session fields plugin for TheAuth.
+ *
+ * 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 '@glinr/theauth';
+ * import { additionalFields } from '@glinr/theauth/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 TheAuth.
+ *
+ * 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>@theauth.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;
+
+interface CostAttributionConfig {
+    /** ISO 4217 currency code, default 'USD' */
+    currency?: string;
+    /** Dollar amounts that trigger alerts */
+    alertThresholds?: {
+        warn: number;
+        critical: number;
+    };
+    /** Called when a threshold is crossed or budget exceeded */
+    onAlert?: (alert: CostAlert) => void | Promise<void>;
+    /** How many days of events to keep, default 90 */
+    retentionDays?: number;
+}
+interface RecordCostInput {
+    agentId: string;
+    /** e.g. 'openai:gpt-4o', 'anthropic:claude-3-5-sonnet', 'mcp:github' */
+    tool: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd: number;
+    metadata?: Record<string, unknown>;
+    /** Attribute to a delegation chain */
+    delegationChainId?: string;
+}
+interface CostReport {
+    agentId: string;
+    period: {
+        start: Date;
+        end: Date;
+    };
+    totalCostUsd: number;
+    byTool: Array<{
+        tool: string;
+        costUsd: number;
+        callCount: number;
+    }>;
+    byDay: Array<{
+        date: string;
+        costUsd: number;
+    }>;
+}
+interface CostAlert {
+    type: "warn" | "critical" | "budget_exceeded";
+    agentId: string;
+    currentCostUsd: number;
+    threshold: number;
+    period: string;
+}
+interface BudgetCheckResult {
+    withinBudget: boolean;
+    spent: number;
+    limit: number | null;
+    remaining: number | null;
+}
+interface CostAttributionModule {
+    recordCost(input: RecordCostInput): Promise<Result<void>>;
+    getAgentCost(agentId: string, period?: {
+        start: Date;
+        end: Date;
+    }): Promise<Result<CostReport>>;
+    getOwnerCost(ownerId: string, period?: {
+        start: Date;
+        end: Date;
+    }): Promise<Result<CostReport>>;
+    getTopAgentsByCost(limit?: number, period?: {
+        start: Date;
+        end: Date;
+    }): Promise<Result<Array<{
+        agentId: string;
+        totalCostUsd: number;
+    }>>>;
+    getDelegationChainCost(chainId: string): Promise<Result<CostReport>>;
+    checkBudget(agentId: string): Promise<Result<BudgetCheckResult>>;
+    cleanup(options?: {
+        retentionDays?: number;
+    }): Promise<Result<{
+        deleted: number;
+    }>>;
+}
+declare function createCostAttributionModule(db: Database, config?: CostAttributionConfig): CostAttributionModule;
+
+/**
+ * Custom session fields plugin for TheAuth.
+ *
+ * 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 '@glinr/theauth';
+ * import { customSession } from '@glinr/theauth/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 TheAuth.
+ *
+ * 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;
+
+/**
+ * Ephemeral agent sessions for TheAuth.
+ *
+ * Short-lived, auto-expiring agent credentials for single-task use. Designed
+ * for computer-use agents (Claude, GPT with browsing, operator loops) that
+ * should not hold persistent tokens across invocations.
+ *
+ * Each session spins up a temporary agent, issues a bounded bearer token, and
+ * tracks how many actions have been consumed. When the TTL lapses or the
+ * action budget is exhausted the token becomes invalid and the underlying
+ * agent is automatically revoked.
+ *
+ * @example
+ * ```typescript
+ * const mod = createEphemeralSessionModule({ db });
+ *
+ * // Create a 5-minute, 10-action session
+ * const result = await mod.createSession({
+ *   ownerId: 'user-123',
+ *   permissions: [{ resource: 'tool:browser', actions: ['navigate', 'click'] }],
+ *   ttlSeconds: 300,
+ *   maxActions: 10,
+ * });
+ *
+ * if (!result.success) throw new Error(result.error.message);
+ *
+ * const { token } = result.data;
+ *
+ * // Each time the agent performs an action
+ * await mod.consumeAction(token);
+ * ```
+ */
+
+interface EphemeralSessionConfig {
+    db: Database;
+    /** Default TTL for sessions in seconds (default: 300 = 5 min) */
+    defaultTtlSeconds?: number;
+    /** Hard ceiling on TTL in seconds (default: 3600 = 1 hour) */
+    maxTtlSeconds?: number;
+    /** Automatically revoke the underlying agent when the session expires (default: true) */
+    autoRevokeOnExpiry?: boolean;
+    /** Group all actions under a shared audit session ID (default: true) */
+    auditGrouping?: boolean;
+}
+interface CreateEphemeralSessionInput {
+    ownerId: string;
+    name?: string;
+    permissions: Permission[];
+    /** Seconds until the session expires (capped at maxTtlSeconds) */
+    ttlSeconds?: number;
+    /** Optional cap on the number of actions the token may authorize */
+    maxActions?: number;
+    metadata?: Record<string, unknown>;
+}
+interface EphemeralSession {
+    sessionId: string;
+    agentId: string;
+    /** Bearer token — shown once, never stored in plain text */
+    token: string;
+    expiresAt: Date;
+    maxActions: number | null;
+    actionsUsed: number;
+    status: "active" | "expired" | "exhausted" | "revoked";
+    /** Shared audit group ID for all actions within the session */
+    auditGroupId: string;
+    createdAt: Date;
+}
+interface EphemeralSessionValidateResult {
+    sessionId: string;
+    agentId: string;
+    remainingActions: number | null;
+    /** Seconds until the token expires */
+    expiresIn: number;
+    auditGroupId: string;
+}
+interface EphemeralSessionModule {
+    createSession(input: CreateEphemeralSessionInput): Promise<Result<EphemeralSession>>;
+    validateSession(token: string): Promise<Result<EphemeralSessionValidateResult>>;
+    consumeAction(token: string): Promise<Result<{
+        actionsRemaining: number | null;
+    }>>;
+    revokeSession(sessionId: string): Promise<Result<void>>;
+    listActiveSessions(ownerId: string): Promise<Result<EphemeralSession[]>>;
+    cleanupExpired(): Promise<Result<{
+        count: number;
+    }>>;
+}
+declare function createEphemeralSessionModule(config: EphemeralSessionConfig): EphemeralSessionModule;
+
+/**
+ * Real-time event streaming via Server-Sent Events (SSE) for TheAuth.
+ *
+ * Provides a persistent connection feed of audit events, agent lifecycle
+ * changes, auth events, and anomalies. SOC teams and monitoring systems can
+ * subscribe instead of polling the audit API or relying solely on webhooks.
+ *
+ * Endpoint: GET /api/kavach/events/stream
+ * Auth: Bearer token via Authorization header or `?token=` query param
+ * Filtering: `?types=audit,agent.created`
+ * Replay: `?since=2026-01-01T00:00:00Z` or Last-Event-ID header
+ *
+ * @example
+ * ```typescript
+ * const stream = createEventStreamModule({ db, requireAuth: true });
+ *
+ * // In your request handler
+ * const response = stream.handleRequest(request);
+ * if (response) return response;
+ *
+ * // Emit from anywhere in your app
+ * stream.emit({
+ *   id: crypto.generateId(),
+ *   type: 'agent.created',
+ *   timestamp: new Date(),
+ *   data: { agentId: 'ag_123', name: 'my-agent' },
+ * });
+ * ```
+ */
+
+declare const EVENT_TYPES: readonly ["audit", "agent.created", "agent.revoked", "agent.rotated", "auth.signin", "auth.signout", "auth.failed", "delegation.created", "delegation.revoked", "budget.exceeded", "anomaly.detected", "cost.recorded"];
+type EventType = (typeof EVENT_TYPES)[number];
+interface StreamEvent {
+    id: string;
+    type: EventType;
+    timestamp: Date;
+    data: Record<string, unknown>;
+    agentId?: string;
+    userId?: string;
+}
+interface EventStreamConfig {
+    db: Database;
+    /** Maximum concurrent SSE connections (default: 100) */
+    maxConnections?: number;
+    /** Heartbeat interval in milliseconds (default: 30000) */
+    heartbeatIntervalMs?: number;
+    /** Restrict which event types this stream delivers (default: all) */
+    eventTypes?: EventType[];
+    /** Require a valid Bearer token to connect (default: true) */
+    requireAuth?: boolean;
+    /**
+     * Validate a Bearer token and return the subscriber ID (userId or agentId)
+     * on success, or null on failure.
+     *
+     * Only called when `requireAuth` is true. When omitted, any non-empty token
+     * is accepted and used as the subscriber ID.
+     */
+    validateToken?: (token: string) => Promise<string | null>;
+}
+interface EventStreamModule {
+    /** Emit an event to all connected clients. */
+    emit(event: StreamEvent): void;
+    /** Handle an incoming HTTP request. Returns a Response or null when the request is not an SSE request. */
+    handleRequest(request: Request): Response | null;
+    /** Current number of active SSE connections. */
+    getConnectionCount(): number;
+    /** Replay persisted events since a timestamp, optionally filtered by type. */
+    replay(since: Date, types?: EventType[]): Promise<Result<StreamEvent[]>>;
+    /** Close all active connections and stop heartbeats. */
+    close(): void;
+}
+declare function createEventStreamModule(config: EventStreamConfig): EventStreamModule;
+
+/**
+ * Agent identity federation for TheAuth.
+ *
+ * Allows an agent created in one TheAuth instance (Service A) to
+ * authenticate at another TheAuth instance (Service B) without
+ * re-registration. The agent's identity, trust score, permissions,
+ * and delegation scope travel with the federation token.
+ *
+ * Federation tokens are short-lived JWTs signed by the source instance.
+ * The target instance verifies them by fetching the source's public key
+ * from `/.well-known/kavach-federation.json`. Optionally, a Verifiable
+ * Credential can be embedded for offline verification.
+ *
+ * @example
+ * ```typescript
+ * import { createFederationModule } from '@glinr/theauth/auth';
+ * import { generateKeyPair, exportJWK } from 'jose';
+ *
+ * const { publicKey, privateKey } = await generateKeyPair('EdDSA');
+ *
+ * const federation = createFederationModule({
+ *   instanceId: 'instance-a',
+ *   instanceUrl: 'https://a.example.com',
+ *   signingKey: privateKey,
+ * });
+ *
+ * // Issue a token for an agent to carry to Service B
+ * const result = await federation.issueFederationToken('agent-123');
+ * ```
+ */
+
+declare const TrustLevelSchema: z.ZodEnum<["full", "limited", "verify-only"]>;
+type TrustLevel = z.infer<typeof TrustLevelSchema>;
+interface TrustedInstance {
+    instanceId: string;
+    instanceUrl: string;
+    publicKey?: JsonWebKey;
+    trustLevel?: TrustLevel;
+}
+interface FederationConfig {
+    /** Unique identifier for this TheAuth instance */
+    instanceId: string;
+    /** Public URL of this instance */
+    instanceUrl: string;
+    /** EdDSA private key for signing federation tokens */
+    signingKey: CryptoKey;
+    /** Pre-configured trusted instances */
+    trustedInstances?: TrustedInstance[];
+    /** Trust any TheAuth instance (dev mode only) */
+    autoTrust?: boolean;
+    /** Federation token lifetime in seconds. Default: 300 (5 minutes). */
+    tokenTtlSeconds?: number;
+}
+interface FederationToken {
+    /** Signed JWT */
+    token: string;
+    /** Token expiration */
+    expiresAt: Date;
+    /** Agent this token was issued for */
+    agentId: string;
+    /** Source instance ID */
+    sourceInstance: string;
+}
+interface FederatedAgent {
+    /** Agent ID from the source instance */
+    agentId: string;
+    /** Instance that issued this agent's identity */
+    sourceInstance: string;
+    /** Source instance URL */
+    sourceInstanceUrl: string;
+    /** Permissions carried by the token */
+    permissions: string[];
+    /** Trust level (0-1) from the source instance */
+    trustScore: number;
+    /** Delegation scope, if any */
+    delegationScope: string[];
+    /** When this token was verified */
+    verifiedAt: Date;
+    /** Embedded Verifiable Credential JWT, if present */
+    credential?: string;
+}
+interface InstanceIdentity {
+    /** This instance's ID */
+    instanceId: string;
+    /** This instance's URL */
+    instanceUrl: string;
+    /** Public key in JWK format for verifying federation tokens */
+    publicKeyJwk: JsonWebKey;
+    /** Protocol version */
+    protocolVersion: string;
+    /** Supported features */
+    features: string[];
+}
+interface IssueFederationTokenInput {
+    /** Agent ID to issue the token for */
+    agentId: string;
+    /** Optional target instance ID (audience restriction) */
+    targetInstance?: string;
+    /** Agent permissions to include in the token */
+    permissions?: string[];
+    /** Agent trust score (0-1) */
+    trustScore?: number;
+    /** Delegation scope */
+    delegationScope?: string[];
+    /** Optional VC JWT to embed */
+    credential?: string;
+}
+/** The well-known document served at /.well-known/kavach-federation.json */
+interface FederationWellKnown {
+    instanceId: string;
+    instanceUrl: string;
+    publicKeyJwk: JsonWebKey;
+    protocolVersion: string;
+    features: string[];
+}
+interface FederationModule {
+    /** Issue a federation token for an agent to use at another service */
+    issueFederationToken(input: IssueFederationTokenInput): Promise<Result<FederationToken>>;
+    /** Verify a federation token from another TheAuth instance */
+    verifyFederationToken(token: string): Promise<Result<FederatedAgent>>;
+    /** Get this instance's identity (for the well-known endpoint) */
+    getInstanceIdentity(): Promise<InstanceIdentity>;
+    /** Add a trusted instance */
+    addTrustedInstance(instance: TrustedInstance): Result<void>;
+    /** Remove a trusted instance by ID */
+    removeTrustedInstance(instanceId: string): Result<void>;
+    /** List all trusted instances */
+    listTrustedInstances(): TrustedInstance[];
+    /** Discover another instance via its well-known URL */
+    discoverInstance(url: string, fetchFn?: typeof globalThis.fetch): Promise<Result<TrustedInstance>>;
+}
+/**
+ * Create a federation module for cross-instance agent identity.
+ *
+ * The module signs short-lived JWTs that carry agent identity, permissions,
+ * and trust score. Remote instances verify these tokens using the source's
+ * public key, fetched from the well-known endpoint or pre-configured.
+ */
+declare function createFederationModule(config: FederationConfig): FederationModule;
+
+/**
+ * GDPR module for TheAuth.
+ *
+ * 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 TheAuth.
+ *
+ * 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 '@glinr/theauth';
+ * import { gdpr } from '@glinr/theauth/auth';
+ *
+ * const kavach = await createKavach({
+ *   database: { provider: 'sqlite', url: 'kavach.db' },
+ *   plugins: [gdpr()],
+ * });
+ * ```
+ */
+
+declare function gdpr(): KavachPlugin;
+
+/**
+ * Have I Been Pwned password checking for TheAuth.
+ *
+ * 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 TheAuth.
+ *
+ * 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>;
+    /**
+     * Emit IETF agentic JWT claims on issued access tokens.
+     *
+     * When true, `agent_id`, `agent_type`, and `trust_tier` are included
+     * in the token payload if the corresponding values are present on
+     * `SessionUser.agenticContext`. Claims not present in the context are
+     * omitted rather than fabricated. Off by default.
+     *
+     * @default false
+     */
+    emitAgenticJwtClaims?: boolean;
+}
+/**
+ * Optional agentic context carried alongside a session user.
+ *
+ * Used when `JwtSessionConfig.emitAgenticJwtClaims` is true to populate
+ * draft-goswami-agentic-jwt-00 claims on the issued access token.
+ */
+interface AgenticSessionContext {
+    /** Stable agent identifier (populates `agent_id`). */
+    agentId?: string;
+    /** Operational mode (populates `agent_type`). */
+    agentType?: AgentType;
+    /** Trust tier band at issuance (populates `trust_tier`). */
+    trustTier?: TrustTier;
+}
+interface SessionUser {
+    id: string;
+    email?: string;
+    name?: string;
+    image?: string;
+    /**
+     * Optional agentic context. Only used when
+     * `JwtSessionConfig.emitAgenticJwtClaims` is true.
+     */
+    agenticContext?: AgenticSessionContext;
+}
+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 TheAuth.
+ *
+ * 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;
+
+/**
+ * Types for the OAuth 2.0 / OIDC provider system.
+ *
+ * TheAuth uses PKCE (S256) for all provider flows regardless of whether
+ * the provider strictly requires it. This prevents authorization code
+ * interception attacks on both public and confidential clients.
+ */
+interface OAuthProviderConfig {
+    /** OAuth application client ID. */
+    clientId: string;
+    /** OAuth application client secret. */
+    clientSecret: string;
+    /**
+     * Additional scopes to request on top of the provider defaults.
+     * The provider's default scopes are always included.
+     */
+    scopes?: string[];
+    /**
+     * Override the redirect URI registered with the provider.
+     * When omitted the module uses the `redirectUri` passed at call time.
+     */
+    redirectUri?: string;
+}
+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>;
+}
+interface OAuthModuleConfig {
+    /**
+     * Map of provider ID to provider instance.
+     *
+     * @example
+     * ```typescript
+     * import { createGoogleProvider } from '@glinr/theauth/auth/oauth/providers/google';
+     * import { createGithubProvider } from '@glinr/theauth/auth/oauth/providers/github';
+     *
+     * providers: {
+     *   google: createGoogleProvider({ clientId: '...', clientSecret: '...' }),
+     *   github: createGithubProvider({ clientId: '...', clientSecret: '...' }),
+     * }
+     * ```
+     */
+    providers: Record<string, OAuthProvider>;
+    /**
+     * How long an OAuth state entry lives before it is considered expired.
+     * Defaults to 600 seconds (10 minutes).
+     */
+    stateTtlSeconds?: number;
+}
+interface OAuthModule {
+    /**
+     * Generate a PKCE-protected authorization URL and persist the state.
+     *
+     * Call this on your `/auth/:provider` route and redirect the user to the
+     * returned URL.
+     *
+     * @returns `{ url, state }` — redirect to `url`; `state` is stored in the DB.
+     */
+    getAuthorizationUrl(providerId: string, redirectUri: string): Promise<{
+        url: string;
+        state: string;
+    }>;
+    /**
+     * Handle the provider callback and resolve (or create) a linked account.
+     *
+     * Call this on your `/auth/:provider/callback` route.
+     *
+     * @param providerId  The provider that issued the callback.
+     * @param code        The authorization code from the query string.
+     * @param state       The state value from the query string (validated against DB).
+     * @param redirectUri Must match the URI used in `getAuthorizationUrl`.
+     * @returns The linked account row and normalized user info.
+     */
+    handleCallback(providerId: string, code: string, state: string, redirectUri: string): Promise<OAuthCallbackResult>;
+    /**
+     * Manually link an OAuth provider account to an existing TheAuth user.
+     *
+     * Useful when you want to add a second provider to a user who already
+     * authenticated via a different method.
+     */
+    linkAccount(userId: string, providerId: string, userInfo: OAuthUserInfo, tokens: OAuthTokens): Promise<OAuthAccount>;
+    /**
+     * Look up the TheAuth user linked to a given provider account.
+     *
+     * Returns `null` when no link exists yet.
+     */
+    findLinkedUser(providerId: string, providerAccountId: string): Promise<{
+        userId: string;
+    } | null>;
+}
+interface OAuthCallbackResult {
+    /** Whether this callback created a new linked account (vs. found an existing one). */
+    isNewAccount: boolean;
+    account: OAuthAccount;
+    userInfo: OAuthUserInfo;
+    tokens: OAuthTokens;
+}
+interface OAuthAccount {
+    id: string;
+    userId: string;
+    provider: string;
+    providerAccountId: string;
+    accessToken: string;
+    refreshToken: string | null;
+    expiresAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * OAuth module factory.
+ *
+ * Provides three operations on top of any configured set of providers:
+ *
+ * 1. `getAuthorizationUrl` — generate a PKCE-protected authorization URL and
+ *    persist the state + code verifier to the database.
+ * 2. `handleCallback` — validate state, exchange the code, fetch user info,
+ *    and create or return an existing linked account.
+ * 3. `linkAccount` — manually link provider tokens to an existing user.
+ * 4. `findLinkedUser` — look up which user owns a provider account.
+ *
+ * All state operations use the `kavach_oauth_states` table; all account links
+ * use the `kavach_oauth_accounts` table — both defined in `./schema.ts`.
+ */
+
+/**
+ * Create an OAuth module bound to a database instance.
+ *
+ * @example
+ * ```typescript
+ * import { createOAuthModule } from '@glinr/theauth/auth/oauth';
+ * import { createGoogleProvider } from '@glinr/theauth/auth/oauth/providers/google';
+ *
+ * const oauth = createOAuthModule(db, {
+ *   providers: {
+ *     google: createGoogleProvider({ clientId: '...', clientSecret: '...' }),
+ *   },
+ * });
+ *
+ * // On /auth/google
+ * const { url } = await oauth.getAuthorizationUrl('google', 'https://my.app/callback');
+ * return redirect(url);
+ *
+ * // On /auth/google/callback
+ * const { account, userInfo } = await oauth.handleCallback(
+ *   'google', req.query.code, req.query.state, 'https://my.app/callback',
+ * );
+ * ```
+ */
+declare function createOAuthModule(db: Database, config: OAuthModuleConfig): OAuthModule;
+
+interface OAuthPluginConfig extends OAuthModuleConfig {
+    /**
+     * Build the redirect URI for a given provider.
+     *
+     * When omitted the plugin constructs the URI from `ctx.config.baseUrl`
+     * using the pattern `{baseUrl}/auth/oauth/callback/{provider}`.
+     */
+    buildRedirectUri?: (provider: string, baseUrl: string) => string;
+}
+declare function oauth(config: OAuthPluginConfig): KavachPlugin;
+
+/**
+ * Apple Sign In provider (OAuth 2.0 / OIDC).
+ *
+ * Endpoints:
+ * - Authorization: https://appleid.apple.com/auth/authorize
+ * - Token:         https://appleid.apple.com/auth/token
+ *
+ * Notes:
+ * - Apple does not expose a dedicated UserInfo endpoint. Instead, it embeds
+ *   user claims (email, name) in the `id_token` JWT on first authorization.
+ *   On subsequent authorizations the `user` form-post field is absent — only
+ *   the `id_token` carries the `sub` and `email` claims.
+ * - PKCE S256 is supported and recommended.
+ * - `response_mode` must be `form_post` when requesting the `name` scope,
+ *   because Apple POSTs back a `user` JSON field alongside the code.
+ * - The `name` scope only delivers user data on the *first* authorization.
+ *   Store it immediately; subsequent logins will not include it.
+ *
+ * Docs: https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms
+ */
+
+/**
+ * Create an Apple Sign In provider instance.
+ *
+ * Apple requires a JWT client secret (signed with your private key) rather
+ * than a static secret. Generate the client secret JWT before passing it in
+ * as `clientSecret`.
+ *
+ * @example
+ * ```typescript
+ * const apple = createAppleProvider({
+ *   clientId: process.env.APPLE_CLIENT_ID,       // Services ID, e.g. com.example.app
+ *   clientSecret: appleClientSecretJwt,           // ES256 JWT generated from private key
+ * });
+ * ```
+ */
+declare function createAppleProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Atlassian OAuth 2.0 (3LO) provider.
+ *
+ * Endpoints:
+ * - Authorization: https://auth.atlassian.com/authorize
+ * - Token:         https://auth.atlassian.com/oauth/token
+ * - UserInfo:      https://api.atlassian.com/me
+ *
+ * Notes:
+ * - PKCE S256 is supported by Atlassian's OAuth 2.0 implementation.
+ * - The `audience` parameter (`api.atlassian.com`) is required on the
+ *   authorization URL. Without it, tokens will not be accepted by the
+ *   Atlassian APIs.
+ * - The `read:me` scope grants access to the user's identity (account ID,
+ *   email, name, avatar). Add `offline_access` if refresh tokens are needed.
+ * - Atlassian account IDs are in the format `557058:xxxxxxxx-xxxx-...`.
+ *
+ * Docs: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
+ */
+
+declare const DEFAULT_ATLASSIAN_SCOPES: string[];
+declare function normalizeProfile$9(raw: Record<string, unknown>): OAuthUserInfo;
+/**
+ * Create an Atlassian OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const atlassian = createAtlassianProvider({
+ *   clientId: process.env.ATLASSIAN_CLIENT_ID,
+ *   clientSecret: process.env.ATLASSIAN_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createAtlassianProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Discord OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://discord.com/api/oauth2/authorize
+ * - Token:         https://discord.com/api/oauth2/token
+ * - UserInfo:      https://discord.com/api/users/@me
+ *
+ * Notes:
+ * - PKCE S256 is supported as of the Discord OAuth 2.0 implementation.
+ * - The `identify` scope grants access to the user object (ID, username,
+ *   avatar). The `email` scope is required separately to receive the email.
+ * - Avatar URLs are constructed from the user ID and avatar hash. When the
+ *   user has no custom avatar, `avatar` is null and Discord serves a default
+ *   based on the discriminator (or username for the new username system).
+ * - Discord user IDs are Snowflakes (64-bit integers serialized as strings).
+ *
+ * Docs: https://discord.com/developers/docs/topics/oauth2
+ */
+
+declare const DEFAULT_DISCORD_SCOPES: string[];
+/**
+ * Create a Discord OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const discord = createDiscordProvider({
+ *   clientId: process.env.DISCORD_CLIENT_ID,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createDiscordProvider(config: OAuthProviderConfig): OAuthProvider;
+declare function normalizeProfile$8(raw: Record<string, unknown>): OAuthUserInfo;
+
+/**
+ * Dropbox OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://www.dropbox.com/oauth2/authorize
+ * - Token:         https://api.dropboxapi.com/oauth2/token
+ * - UserInfo:      https://api.dropboxapi.com/2/users/get_current_account (POST)
+ *
+ * Notes:
+ * - PKCE S256 is supported by Dropbox's OAuth 2.0 implementation (since 2021).
+ * - The userinfo endpoint is a POST with an empty body (JSON null is the
+ *   documented request body). No query params are needed.
+ * - The `account_info.read` scope grants access to basic account info including
+ *   email, name, and account ID.
+ * - Dropbox account IDs start with "dbid:" and are stable across sessions.
+ * - The `name` object contains `display_name`, `given_name`, `surname`, etc.
+ *
+ * Docs: https://developers.dropbox.com/oauth-guide
+ */
+
+declare const DEFAULT_DROPBOX_SCOPES: string[];
+declare function normalizeProfile$7(raw: Record<string, unknown>): OAuthUserInfo;
+/**
+ * Create a Dropbox OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const dropbox = createDropboxProvider({
+ *   clientId: process.env.DROPBOX_CLIENT_ID,
+ *   clientSecret: process.env.DROPBOX_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createDropboxProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Figma OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://www.figma.com/oauth
+ * - Token:         https://api.figma.com/v1/oauth/token
+ * - UserInfo:      https://api.figma.com/v1/me
+ *
+ * Notes:
+ * - PKCE S256 is supported by Figma's OAuth implementation.
+ * - The `file_read` scope is the minimum required for sign-in; it grants
+ *   read access to files, projects, and user information.
+ * - The email address is always returned; Figma accounts always have one.
+ *
+ * Docs: https://www.figma.com/developers/api#authentication
+ */
+
+declare const DEFAULT_FIGMA_SCOPES: string[];
+declare function normalizeProfile$6(raw: Record<string, unknown>): OAuthUserInfo;
+/**
+ * Create a Figma OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const figma = createFigmaProvider({
+ *   clientId: process.env.FIGMA_CLIENT_ID,
+ *   clientSecret: process.env.FIGMA_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createFigmaProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Generic OIDC provider factory.
+ *
+ * Builds a fully functional OAuthProvider from a minimal config. When an
+ * OIDC issuer URL is supplied the factory constructs the standard
+ * `/.well-known/openid-configuration` discovery URL. Explicit endpoint
+ * overrides take precedence over discovery, so the factory works with
+ * providers that do not implement RFC 8414.
+ *
+ * Spec references:
+ * - OIDC Discovery: https://openid.net/specs/openid-connect-discovery-1_0.html
+ * - RFC 8414 (OAuth 2.0 Authorization Server Metadata)
+ */
+
+interface GenericOIDCConfig {
+    /** Machine-readable provider ID, e.g. `'okta'`, `'auth0'`. */
+    id: string;
+    /** Human-readable display name, e.g. `'Okta'`. */
+    name: string;
+    /**
+     * OIDC issuer URL. Used to derive the discovery document URL as
+     * `${issuer}/.well-known/openid-configuration` when explicit endpoint
+     * overrides are not provided.
+     *
+     * @example "https://dev-12345678.okta.com"
+     */
+    issuer: string;
+    /** OAuth application client ID. */
+    clientId: string;
+    /** OAuth application client secret. */
+    clientSecret: string;
+    /**
+     * Scopes to request. Defaults to `['openid', 'email', 'profile']`.
+     */
+    scopes?: string[];
+    /**
+     * Override the redirect URI registered with the provider.
+     * When omitted the URI passed at call time is used.
+     */
+    redirectUri?: string;
+    /** Authorization endpoint. Overrides discovery. */
+    authorizationUrl?: string;
+    /** Token endpoint. Overrides discovery. */
+    tokenUrl?: string;
+    /** UserInfo endpoint. Overrides discovery. */
+    userinfoUrl?: string;
+}
+/**
+ * Create an OAuthProvider backed by a standard OIDC issuer.
+ *
+ * Endpoints are resolved from the issuer's discovery document on first use
+ * and cached in memory for the lifetime of the process. Pass explicit
+ * `authorizationUrl`, `tokenUrl`, and `userinfoUrl` to bypass discovery.
+ *
+ * @example
+ * ```typescript
+ * const okta = genericOIDC({
+ *   id: "okta",
+ *   name: "Okta",
+ *   issuer: "https://dev-12345678.okta.com",
+ *   clientId: process.env.OKTA_CLIENT_ID,
+ *   clientSecret: process.env.OKTA_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function genericOIDC(config: GenericOIDCConfig): OAuthProvider;
+
+/**
+ * GitHub OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://github.com/login/oauth/authorize
+ * - Token:         https://github.com/login/oauth/access_token
+ * - UserInfo:      https://api.github.com/user
+ * - Emails:        https://api.github.com/user/emails (for primary verified email)
+ *
+ * Notes:
+ * - GitHub does not natively support PKCE in its OAuth flow, but we send the
+ *   `code_challenge` parameter anyway — it is silently ignored, which is safe.
+ *   The code verifier is still validated server-side within TheAuth state
+ *   storage so the CSRF protection guarantee holds.
+ * - The `user:email` scope is required to read the primary email when it is
+ *   set to private on the GitHub profile.
+ * - GitHub tokens do not carry an `expires_in` field for classic tokens.
+ *
+ * Docs: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps
+ */
+
+/**
+ * Create a GitHub OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const github = createGithubProvider({
+ *   clientId: process.env.GITHUB_CLIENT_ID,
+ *   clientSecret: process.env.GITHUB_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createGithubProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * GitLab OAuth 2.0 provider.
+ *
+ * Endpoints (gitlab.com — self-managed instances replace the base URL):
+ * - Authorization: https://gitlab.com/oauth/authorize
+ * - Token:         https://gitlab.com/oauth/token
+ * - UserInfo:      https://gitlab.com/api/v4/user
+ *
+ * Notes:
+ * - PKCE S256 is supported.
+ * - The `read_user` scope grants access to the `/api/v4/user` endpoint which
+ *   returns the authenticated user's profile including email.
+ * - GitLab user IDs are integers; they are converted to strings for the
+ *   TheAuth normalized format.
+ * - For self-managed GitLab instances, override the URLs by providing a
+ *   custom base URL and constructing the provider accordingly.
+ *
+ * Docs: https://docs.gitlab.com/ee/api/oauth2.html
+ */
+
+/**
+ * Create a GitLab OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const gitlab = createGitlabProvider({
+ *   clientId: process.env.GITLAB_CLIENT_ID,
+ *   clientSecret: process.env.GITLAB_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createGitlabProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Google OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints:
+ * - Authorization: https://accounts.google.com/o/oauth2/v2/auth
+ * - Token:         https://oauth2.googleapis.com/token
+ * - UserInfo:      https://www.googleapis.com/oauth2/v3/userinfo
+ *
+ * PKCE S256 is always enforced. Google supports it for all client types
+ * and the spec mandates it for public clients.
+ *
+ * Docs: https://developers.google.com/identity/protocols/oauth2
+ */
+
+/**
+ * Create a Google OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const google = createGoogleProvider({
+ *   clientId: process.env.GOOGLE_CLIENT_ID,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createGoogleProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * LinkedIn OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints:
+ * - Authorization: https://www.linkedin.com/oauth/v2/authorization
+ * - Token:         https://www.linkedin.com/oauth/v2/accessToken
+ * - UserInfo:      https://api.linkedin.com/v2/userinfo (OIDC endpoint)
+ *
+ * Notes:
+ * - LinkedIn's OIDC userinfo endpoint (`/v2/userinfo`) is available when the
+ *   `openid` scope is requested. It returns standard OIDC claims including
+ *   `sub`, `name`, `email`, and `picture`.
+ * - PKCE is not supported by LinkedIn's OAuth server. The code challenge is
+ *   sent for symmetry but silently ignored. CSRF protection via `state` still
+ *   applies within TheAuth.
+ * - The `sub` claim is the LinkedIn member ID and is stable across sessions.
+ *
+ * Docs: https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2
+ */
+
+/**
+ * Create a LinkedIn OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const linkedin = createLinkedInProvider({
+ *   clientId: process.env.LINKEDIN_CLIENT_ID,
+ *   clientSecret: process.env.LINKEDIN_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createLinkedInProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Microsoft identity platform (Entra ID / Azure AD) OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints (common tenant — works for personal accounts and work/school):
+ * - Authorization: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
+ * - Token:         https://login.microsoftonline.com/common/oauth2/v2.0/token
+ * - UserInfo:      https://graph.microsoft.com/v1.0/me
+ *
+ * Notes:
+ * - PKCE S256 is supported and required for public clients.
+ * - `User.Read` is a Microsoft Graph permission, not a standard OIDC scope.
+ *   It grants access to the `/me` endpoint.
+ * - The `id` field on the Graph `/me` response is the Entra object ID, which
+ *   is stable across tenant changes and is safe to use as a primary key.
+ * - For single-tenant apps, replace `common` with the tenant ID or domain.
+ *
+ * Docs: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow
+ */
+
+/**
+ * Create a Microsoft identity platform OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const microsoft = createMicrosoftProvider({
+ *   clientId: process.env.MICROSOFT_CLIENT_ID,
+ *   clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createMicrosoftProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Notion OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://api.notion.com/v1/oauth/authorize
+ * - Token:         https://api.notion.com/v1/oauth/token
+ * - UserInfo:      embedded in the token response (`owner` field)
+ *
+ * Notes:
+ * - Notion does not have a separate UserInfo endpoint. User identity is
+ *   returned as part of the token exchange response inside `owner.user`.
+ *   The provider captures the token response in a closure so that
+ *   `getUserInfo` can extract it without a redundant network call.
+ * - The token endpoint uses HTTP Basic auth (client_id:client_secret).
+ * - All Notion API requests require the `Notion-Version` header.
+ * - Notion uses integration-level permissions rather than OAuth scopes.
+ *   Workspaces a user authorizes appear in `workspace_id` / `workspace_name`
+ *   in the token response.
+ * - The `owner.user.person.email` field is present only when the integration
+ *   is authorized by a person (not a bot). For bot authorizations
+ *   `owner.type` is `"workspace"` and `email` may be absent.
+ * - PKCE is not documented by Notion; the code_challenge is omitted for
+ *   compatibility with their authorization server.
+ *
+ * Docs: https://developers.notion.com/docs/authorization
+ */
+
+declare const DEFAULT_NOTION_SCOPES: string[];
+declare function normalizeProfile$5(raw: Record<string, unknown>): OAuthUserInfo;
+/**
+ * Create a Notion OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const notion = createNotionProvider({
+ *   clientId: process.env.NOTION_CLIENT_ID,
+ *   clientSecret: process.env.NOTION_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createNotionProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Preset OAuth provider configs.
+ *
+ * Each export is a factory function that takes `(clientId, clientSecret)`
+ * and returns a config accepted by `genericOIDC` or usable directly as a
+ * plain provider when the provider does not support OIDC discovery.
+ *
+ * OIDC-capable providers (Auth0, Okta) use `genericOIDC` and require the
+ * caller to supply their tenant/domain as a third argument.
+ *
+ * All other presets return a `GenericOIDCConfig`-compatible object with
+ * explicit endpoints so they work without any network discovery call.
+ */
+
+/**
+ * Facebook (Meta) OAuth 2.0.
+ *
+ * Docs: https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
+ */
+declare function facebookProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Spotify OAuth 2.0.
+ *
+ * Docs: https://developer.spotify.com/documentation/web-api/concepts/authorization
+ */
+declare function spotifyProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Twitch OAuth 2.0 / OIDC.
+ *
+ * Docs: https://dev.twitch.tv/docs/authentication
+ */
+declare function twitchProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Reddit OAuth 2.0.
+ *
+ * Docs: https://github.com/reddit-archive/reddit/wiki/OAuth2
+ */
+declare function redditProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Dropbox OAuth 2.0.
+ *
+ * Docs: https://developers.dropbox.com/oauth-guide
+ */
+declare function dropboxProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Zoom OAuth 2.0 / OIDC.
+ *
+ * Docs: https://developers.zoom.us/docs/integrations/oauth/
+ */
+declare function zoomProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Notion OAuth 2.0.
+ *
+ * Docs: https://developers.notion.com/docs/authorization
+ */
+declare function notionProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Figma OAuth 2.0.
+ *
+ * Docs: https://www.figma.com/developers/api#authentication
+ */
+declare function figmaProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Bitbucket OAuth 2.0.
+ *
+ * Docs: https://developer.atlassian.com/cloud/bitbucket/oauth-2/
+ */
+declare function bitbucketProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Atlassian OAuth 2.0 (Jira, Confluence, etc.).
+ *
+ * Docs: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
+ */
+declare function atlassianProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Yahoo OAuth 2.0 / OIDC.
+ *
+ * Docs: https://developer.yahoo.com/oauth2/guide/
+ */
+declare function yahooProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * LINE Login OAuth 2.0 / OIDC.
+ *
+ * Docs: https://developers.line.biz/en/docs/line-login/integrate-line-login/
+ */
+declare function lineProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Coinbase OAuth 2.0.
+ *
+ * Docs: https://docs.cdp.coinbase.com/coinbase-app/docs/coinbase-connect-reference
+ */
+declare function coinbaseProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * TikTok OAuth 2.0.
+ *
+ * Docs: https://developers.tiktok.com/doc/oauth-user-access-token-management
+ */
+declare function tiktokProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * PayPal OAuth 2.0 / OIDC.
+ *
+ * Docs: https://developer.paypal.com/api/rest/authentication/
+ */
+declare function paypalProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Salesforce OAuth 2.0 / OIDC.
+ *
+ * Docs: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm
+ */
+declare function salesforceProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * VK ID OAuth 2.0.
+ *
+ * Docs: https://id.vk.com/about/business/go/docs/ru/vkid/latest/vkid/sdk/web/get-started
+ */
+declare function vkProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Kakao OAuth 2.0.
+ *
+ * Docs: https://developers.kakao.com/docs/latest/en/kakaologin/rest-api
+ */
+declare function kakaoProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Naver OAuth 2.0.
+ *
+ * Docs: https://developers.naver.com/docs/login/api/api.md
+ */
+declare function naverProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Hugging Face OAuth 2.0 / OIDC.
+ *
+ * Docs: https://huggingface.co/docs/hub/en/oauth
+ */
+declare function huggingfaceProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Roblox OAuth 2.0 / OIDC.
+ *
+ * Docs: https://create.roblox.com/docs/cloud/open-cloud/oauth2-overview
+ */
+declare function robloxProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Vercel OAuth 2.0.
+ *
+ * Docs: https://vercel.com/docs/integrations/create-integration/submit-integration#oauth2
+ */
+declare function vercelProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Linear OAuth 2.0.
+ *
+ * Docs: https://developers.linear.app/docs/oauth/authentication
+ */
+declare function linearProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Railway OAuth 2.0.
+ *
+ * Docs: https://docs.railway.app/reference/public-api#oauth2
+ */
+declare function railwayProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Kick OAuth 2.0.
+ *
+ * Docs: https://docs.kick.com/getting-started/authorization-oauth2-flow
+ */
+declare function kickProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * WeChat OAuth 2.0 (Web Login via QR code).
+ *
+ * Docs: https://developers.weixin.qq.com/doc/oplatform/en/Website_App/WeChat_Login/Wechat_Login.html
+ */
+declare function wechatProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Polar OAuth 2.0 / OIDC.
+ *
+ * Docs: https://docs.polar.sh/api-reference/oauth2
+ */
+declare function polarProvider(clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Auth0 OIDC provider.
+ *
+ * Requires the Auth0 tenant domain (e.g. `"dev-abc123.us.auth0.com"`).
+ *
+ * Docs: https://auth0.com/docs/authenticate/protocols/openid-connect-protocol
+ *
+ * @example
+ * ```typescript
+ * const auth0 = auth0Provider("dev-abc123.us.auth0.com", clientId, clientSecret);
+ * ```
+ */
+declare function auth0Provider(domain: string, clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * Okta OIDC provider.
+ *
+ * Requires the Okta domain (e.g. `"dev-12345678.okta.com"`).
+ *
+ * Docs: https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/
+ *
+ * @example
+ * ```typescript
+ * const okta = oktaProvider("dev-12345678.okta.com", clientId, clientSecret);
+ * ```
+ */
+declare function oktaProvider(domain: string, clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+/**
+ * AWS Cognito OIDC provider.
+ *
+ * Requires the Cognito hosted UI domain (e.g. `"my-app.auth.us-east-1.amazoncognito.com"`).
+ *
+ * Docs: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html
+ *
+ * @example
+ * ```typescript
+ * const cognito = cognitoProvider(
+ *   "my-app.auth.us-east-1.amazoncognito.com",
+ *   clientId,
+ *   clientSecret,
+ * );
+ * ```
+ */
+declare function cognitoProvider(domain: string, clientId: string, clientSecret: string, scopes?: string[]): OAuthProvider;
+
+/**
+ * Reddit OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://www.reddit.com/api/v1/authorize
+ * - Token:         https://www.reddit.com/api/v1/access_token
+ * - UserInfo:      https://oauth.reddit.com/api/v1/me
+ *
+ * Notes:
+ * - Reddit's token endpoint uses HTTP Basic authentication (client_id as the
+ *   username, client_secret as the password) rather than posting credentials
+ *   in the request body.
+ * - The `identity` scope grants access to the user's Reddit account info.
+ * - Reddit does not expose the user's email address via OAuth; the `name`
+ *   field (Reddit username) is the stable identifier.
+ * - The UserInfo endpoint requires a descriptive `User-Agent` header. Reddit
+ *   blocks requests with generic agents (e.g., "python-requests"). Format:
+ *   `platform:app_id:version (by /u/username)`.
+ * - Avatar URLs (`icon_img`) include query parameters; strip them when storing
+ *   to avoid caching issues.
+ * - PKCE is supported but Reddit also accepts flows without it for server-side
+ *   apps; TheAuth uses PKCE S256 consistently.
+ *
+ * Docs: https://www.reddit.com/dev/api/oauth
+ */
+
+declare const DEFAULT_REDDIT_SCOPES: string[];
+/**
+ * Create a Reddit OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const reddit = createRedditProvider({
+ *   clientId: process.env.REDDIT_CLIENT_ID,
+ *   clientSecret: process.env.REDDIT_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createRedditProvider(config: OAuthProviderConfig): OAuthProvider;
+declare function normalizeProfile$4(raw: Record<string, unknown>): OAuthUserInfo;
+
+/**
+ * Slack OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints:
+ * - Authorization: https://slack.com/oauth/v2/authorize
+ * - Token:         https://slack.com/api/oauth.v2.access
+ * - UserInfo:      https://slack.com/api/openid.connect.userInfo
+ *
+ * Notes:
+ * - Slack's v2 OAuth uses OpenID Connect for user sign-in. The
+ *   `openid.connect.userInfo` endpoint returns OIDC-standard claims.
+ * - The token exchange response has a nested structure: `authed_user.access_token`
+ *   for the user token and a bot token at the top level when bot scopes are
+ *   included. For sign-in we want the user token.
+ * - PKCE is not natively supported by Slack's OAuth v2 server. The code
+ *   challenge is sent but silently ignored — CSRF protection via `state` still
+ *   applies within TheAuth.
+ * - Slack user IDs are workspace-scoped, not global. The `sub` claim from the
+ *   OIDC userinfo endpoint is the globally unique identifier across workspaces.
+ *
+ * Docs: https://api.slack.com/authentication/sign-in-with-slack
+ */
+
+declare const DEFAULT_SLACK_SCOPES: string[];
+/**
+ * Create a Slack OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const slack = createSlackProvider({
+ *   clientId: process.env.SLACK_CLIENT_ID,
+ *   clientSecret: process.env.SLACK_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createSlackProvider(config: OAuthProviderConfig): OAuthProvider;
+declare function normalizeProfile$3(raw: Record<string, unknown>): OAuthUserInfo;
+
+/**
+ * Spotify OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://accounts.spotify.com/authorize
+ * - Token:         https://accounts.spotify.com/api/token
+ * - UserInfo:      https://api.spotify.com/v1/me
+ *
+ * Notes:
+ * - PKCE S256 is supported and encouraged for public clients.
+ * - The `user-read-email` scope is required to get the user's email.
+ * - The `user-read-private` scope is required to access the user's country
+ *   and subscription type. Both are included in the defaults for sign-in.
+ * - Email may be absent from the response when the account was created without
+ *   one (e.g., via Facebook sign-up on Spotify). Handle the undefined case.
+ * - Avatar images are returned as an array of `images`; the first entry is
+ *   typically the largest.
+ *
+ * Docs: https://developer.spotify.com/documentation/web-api/concepts/authorization
+ */
+
+declare const DEFAULT_SPOTIFY_SCOPES: string[];
+declare function normalizeProfile$2(raw: Record<string, unknown>): OAuthUserInfo;
+/**
+ * Create a Spotify OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const spotify = createSpotifyProvider({
+ *   clientId: process.env.SPOTIFY_CLIENT_ID,
+ *   clientSecret: process.env.SPOTIFY_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createSpotifyProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Twitch OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://id.twitch.tv/oauth2/authorize
+ * - Token:         https://id.twitch.tv/oauth2/token
+ * - UserInfo:      https://api.twitch.tv/helix/users
+ *
+ * Notes:
+ * - PKCE S256 is supported by the Twitch OAuth 2.0 implementation.
+ * - The `user:read:email` scope is required to receive the user's email address.
+ * - The UserInfo endpoint (/helix/users) requires a `Client-ID` header in
+ *   addition to the Bearer token. Without it the request returns 400.
+ * - User data is nested under a `data` array; the authenticated user is always
+ *   the first element.
+ * - Profile image URLs are direct CDN links and may change when the user
+ *   updates their profile picture.
+ *
+ * Docs: https://dev.twitch.tv/docs/authentication/
+ */
+
+declare const DEFAULT_TWITCH_SCOPES: string[];
+/**
+ * Create a Twitch OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const twitch = createTwitchProvider({
+ *   clientId: process.env.TWITCH_CLIENT_ID,
+ *   clientSecret: process.env.TWITCH_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createTwitchProvider(config: OAuthProviderConfig): OAuthProvider;
+declare function normalizeProfile$1(raw: Record<string, unknown>): OAuthUserInfo;
+
+/**
+ * Twitter / X OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://twitter.com/i/oauth2/authorize
+ * - Token:         https://api.twitter.com/2/oauth2/token
+ * - UserInfo:      https://api.twitter.com/2/users/me
+ *
+ * Notes:
+ * - Twitter OAuth 2.0 (the v2 API) mandates PKCE S256 for all public clients.
+ *   Confidential clients may omit PKCE but it is always safer to include it.
+ * - The token exchange requires HTTP Basic auth (`client_id:client_secret`)
+ *   rather than including credentials in the request body.
+ * - The `/2/users/me` endpoint returns a minimal set of fields by default.
+ *   Additional fields (profile_image_url, name) must be requested via the
+ *   `user.fields` query parameter.
+ * - Twitter does not return an email address through the standard OAuth 2.0
+ *   flow. Email access requires a separate elevated API access application
+ *   and the `tweet.read` scope alone does not grant it.
+ * - User IDs are numeric strings and stable across username changes.
+ *
+ * Docs: https://developer.twitter.com/en/docs/authentication/oauth-2-0/authorization-code
+ */
+
+/**
+ * Create a Twitter / X OAuth provider instance.
+ *
+ * Twitter requires PKCE for all flows. The `clientSecret` is still needed for
+ * the token exchange (sent as HTTP Basic auth).
+ *
+ * @example
+ * ```typescript
+ * const twitter = createTwitterProvider({
+ *   clientId: process.env.TWITTER_CLIENT_ID,
+ *   clientSecret: process.env.TWITTER_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createTwitterProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Zoom OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://zoom.us/oauth/authorize
+ * - Token:         https://zoom.us/oauth/token
+ * - UserInfo:      https://api.zoom.us/v2/users/me
+ *
+ * Notes:
+ * - PKCE S256 is supported by Zoom's OAuth implementation.
+ * - The `user:read` scope grants read access to the authenticated user's
+ *   account details including email, name, and profile picture.
+ * - Zoom user IDs are alphanumeric strings, not numeric.
+ * - The `pic_url` field may be absent when the user has not set a profile photo.
+ *
+ * Docs: https://developers.zoom.us/docs/integrations/oauth/
+ */
+
+declare const DEFAULT_ZOOM_SCOPES: string[];
+declare function normalizeProfile(raw: Record<string, unknown>): OAuthUserInfo;
+/**
+ * Create a Zoom OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const zoom = createZoomProvider({
+ *   clientId: process.env.ZOOM_CLIENT_ID,
+ *   clientSecret: process.env.ZOOM_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createZoomProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * 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
+ * TheAuth, 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. TheAuth validates redirect_uri, stores proxy state, returns provider auth URL.
+ *   3. User authenticates with the provider in a browser.
+ *   4. Provider redirects to TheAuth callback with code + state.
+ *   5. TheAuth 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; TheAuth
+ *     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 TheAuth 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 '@glinr/theauth/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 TheAuth.
+ *
+ * Turns TheAuth into a full OpenID Connect identity provider (IdP).
+ * External applications can register as OIDC clients and authenticate
+ * their users against TheAuth using standard authorization code flow
+ * with PKCE, ID tokens, refresh tokens, discovery, and JWKS.
+ *
+ * @example
+ * ```typescript
+ * import { generateKeyPair } from 'jose';
+ * import { createOidcProviderModule } from '@glinr/theauth/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 TheAuth 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 TheAuth.
+ *
+ * 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 TheAuth.
+ *
+ * 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 '@glinr/theauth/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;
+
+/**
+ * OpenAPI 3.1 spec generation plugin for TheAuth.
+ *
+ * Generates a complete OpenAPI document from TheAuth's registered auth
+ * endpoints. Useful for serving at `/api/kavach/openapi.json` or wiring
+ * into Swagger UI / Scalar.
+ *
+ * @example
+ * ```typescript
+ * import { createOpenApiModule } from '@glinr/theauth/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: "TheAuth 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 TheAuth 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 TheAuth 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 TheAuth.
+ *
+ * Links Polar customers to TheAuth 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 '@glinr/theauth/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;
+
+/**
+ * Shared store interface for the rateLimit() plugin.
+ * Kept in a separate file to avoid circular imports between
+ * rate-limit.ts and the individual store implementations.
+ */
+/** Store backend interface for the rateLimit() plugin. */
+interface RateLimitStore {
+    /**
+     * Increment the hit count for `key` within a `windowMs`-millisecond window.
+     * Returns the updated count and the unix timestamp (ms) when the window resets.
+     */
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Clear all recorded hits for a key. */
+    reset(key: string): Promise<void>;
+}
+
+/**
+ * rateLimit() plugin for TheAuth.
+ *
+ * Wraps auth endpoints with configurable per-IP (and per-agent) throttling.
+ * Intercepts requests via the onRequest lifecycle hook before any handler
+ * runs, keeping the limiting logic decoupled from individual endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { createKavach } from '@glinr/theauth';
+ * import { rateLimit } from '@glinr/theauth/auth';
+ * import { kvStore } from '@glinr/theauth/auth/stores/kv';
+ *
+ * const kavach = createKavach({
+ *   plugins: [
+ *     rateLimit({
+ *       signIn:        { window: '15m', max: 10 },
+ *       signUp:        { window: '1h',  max: 5  },
+ *       passwordReset: { window: '1h',  max: 3  },
+ *       agentAuthorize:{ window: '1m',  max: 100 },
+ *       default:       { window: '1m',  max: 60  },
+ *       store: kvStore(env.CACHE_KV),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/** Per-endpoint rate limit configuration */
+interface EndpointLimit {
+    /** Duration string: "15m", "1h", "30s", "1d" */
+    window: string;
+    /** Maximum number of requests allowed within the window */
+    max: number;
+}
+interface RateLimitConfig$1 {
+    /** Limit for POST /auth/sign-in */
+    signIn?: EndpointLimit;
+    /** Limit for POST /auth/sign-up */
+    signUp?: EndpointLimit;
+    /** Limit for POST /auth/password-reset */
+    passwordReset?: EndpointLimit;
+    /** Limit for POST /auth/agent/authorize */
+    agentAuthorize?: EndpointLimit;
+    /** Fallback limit applied to all other /auth/* paths */
+    default?: EndpointLimit;
+    /**
+     * Storage backend.
+     * Pass "memory" or omit to use the built-in in-memory store.
+     * Pass a KVStore (or any RateLimitStore) for edge deployments.
+     */
+    store?: "memory" | RateLimitStore;
+    /**
+     * Extract a rate-limit key from the request.
+     * Defaults to reading x-forwarded-for → x-real-ip → "unknown".
+     */
+    keyExtractor?: (request: Request) => string;
+    /**
+     * Custom response factory called when a limit is exceeded.
+     * Defaults to a JSON 429 response with Retry-After header.
+     */
+    onLimit?: (request: Request, retryAfter: number) => Response;
+}
+declare function rateLimit(config?: RateLimitConfig$1): 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"];
+
+/**
+ * Relationship-Based Access Control (ReBAC) engine for TheAuth.
+ *
+ * Inspired by Google Zanzibar. Models authorization as a graph of typed
+ * relationships between subjects (users, agents, teams) and objects
+ * (orgs, workspaces, projects, documents). Permission checks traverse the
+ * graph, following both direct relationships and parent-child inheritance.
+ *
+ * Key ideas:
+ * - Resources live in a hierarchy (org > workspace > project > document).
+ * - Relationships connect subjects to objects with a named relation.
+ * - Permission rules define how relations compose. An "editor" implicitly
+ *   has "viewer" access; a "viewer" on a workspace inherits "viewer" on
+ *   child projects.
+ * - Graph traversal is depth-limited to prevent runaway queries.
+ */
+
+interface ReBACConfig {
+    /** Maximum graph traversal depth for permission checks (default: 10). */
+    maxDepth?: number;
+    /** Permission rules per resource type. Key is the resource type. */
+    permissionRules?: Record<string, PermissionRuleSet>;
+}
+/**
+ * Defines how relations map to permissions for a given resource type.
+ *
+ * `implies` — relation X implies relation Y (e.g. editor implies viewer).
+ * `inherits` — permission P on this resource's parent also grants P here.
+ */
+interface PermissionRuleSet {
+    /** Which relations imply which other relations on the same object. */
+    implies?: Record<string, string[]>;
+    /** Permissions inherited from the parent resource. `true` = all, or list. */
+    inheritFromParent?: boolean | string[];
+}
+interface ResourceNode {
+    id: string;
+    type: string;
+    parentId?: string;
+    parentType?: string;
+}
+interface Relationship {
+    id: string;
+    subjectType: string;
+    subjectId: string;
+    relation: string;
+    objectType: string;
+    objectId: string;
+    createdAt: Date;
+}
+interface CheckParams {
+    subjectType: string;
+    subjectId: string;
+    permission: string;
+    objectType: string;
+    objectId: string;
+}
+interface CheckResult {
+    allowed: boolean;
+    path?: string[];
+}
+interface ListObjectsParams {
+    subjectType: string;
+    subjectId: string;
+    permission: string;
+    objectType: string;
+}
+interface ListSubjectsParams {
+    objectType: string;
+    objectId: string;
+    permission: string;
+    subjectType: string;
+}
+interface ExpandParams {
+    type: string;
+    id: string;
+}
+interface ReBACModule {
+    /** Register a resource in the hierarchy. */
+    createResource(node: ResourceNode): Promise<Result<ResourceNode>>;
+    /** Remove a resource and all its relationships. */
+    deleteResource(type: string, id: string): Promise<Result<void>>;
+    /** Get a resource by type and id. */
+    getResource(type: string, id: string): Promise<Result<ResourceNode | null>>;
+    /** Create a relationship between a subject and an object. */
+    addRelationship(rel: Omit<Relationship, "id" | "createdAt">): Promise<Result<Relationship>>;
+    /** Remove a specific relationship. */
+    removeRelationship(subjectType: string, subjectId: string, relation: string, objectType: string, objectId: string): Promise<Result<void>>;
+    /**
+     * Check whether a subject has a permission on an object.
+     * Returns the relationship path when access is granted.
+     */
+    check(params: CheckParams): Promise<Result<CheckResult>>;
+    /** List all object IDs of a given type that a subject can access with a permission. */
+    listObjects(params: ListObjectsParams): Promise<Result<string[]>>;
+    /** List all subject IDs of a given type that hold a permission on an object. */
+    listSubjects(params: ListSubjectsParams): Promise<Result<string[]>>;
+    /** Return all relationships where the given entity is subject or object. */
+    expand(params: ExpandParams): Promise<Result<Relationship[]>>;
+}
+declare function createReBACModule(config: ReBACConfig, db: Database): ReBACModule;
+
+/**
+ * SCIM 2.0 directory sync for TheAuth.
+ *
+ * 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 '@glinr/theauth/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 TheAuth.
+ *
+ * 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 '@glinr/theauth';
+ * import { scim } from '@glinr/theauth/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 TheAuth.
+ *
+ * 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;
+
+/**
+ * Cloudflare KV rate limit store.
+ *
+ * Each key stores a JSON object { count, resetAt } with a TTL so Cloudflare
+ * automatically evicts expired windows without any extra cleanup logic.
+ *
+ * The KV namespace is passed in at construction time so this module remains
+ * free of any Cloudflare-specific imports (it only uses the KV interface that
+ * Workers expose at runtime).
+ */
+
+/** Minimal KV namespace interface — compatible with Cloudflare Workers KVNamespace */
+interface KVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class KVStore implements RateLimitStore {
+    private readonly kv;
+    constructor(kv: KVNamespace);
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+}
+/** Factory function to create a KVStore from a KV namespace binding */
+declare function kvStore(kv: KVNamespace): KVStore;
+
+/**
+ * In-memory rate limit store.
+ *
+ * Uses a Map keyed by a caller-supplied string. Each entry tracks the current
+ * hit count and the unix timestamp (ms) at which the window resets. Expired
+ * windows are reset on the next increment so memory stays bounded without
+ * needing a background sweep.
+ */
+
+declare class MemoryStore implements RateLimitStore {
+    private readonly entries;
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+}
+
+/**
+ * Stripe payment integration for TheAuth.
+ *
+ * Links Stripe customers to TheAuth 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 '@glinr/theauth/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 TheAuth.
+ *
+ * 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): Promise<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 BudgetCheckResult, type CheckParams, type CheckResult, type CheckoutOptions, type CostAlert, type CostAttributionConfig, type CostAttributionModule, type CostReport, type CreateEphemeralSessionInput, type CustomSessionConfig, type 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, type DeleteOptions, type DeleteResult, type DeviceAuthConfig, type DeviceAuthModule, type DeviceAuthStatus, type DeviceCodeResponse, EVENT_TYPES, EmailOtpConfig, type EndpointGroup, type EndpointLimit, type EphemeralSession, type EphemeralSessionConfig, type EphemeralSessionModule, type EphemeralSessionValidateResult, type EventStreamConfig, type EventStreamModule, type EventType, type ExpandParams, type FederatedAgent, type FederationConfig, type FederationModule, type FederationToken, type FederationWellKnown, type FieldDefinition, type GdprModule, type GenericOIDCConfig, type GetUserClaimsFn, type GoogleUser, type HeaderAuthOptions, HibpApiError, HibpBreachedError, type HibpConfig, type HibpModule, type InstanceIdentity, type IssueFederationTokenInput, type JsonWebKeySet, type JwtSessionConfig, type JwtSessionModule, type KVNamespace, KVStore, type LastLoginConfig, type LastLoginModule, type ListObjectsParams, type ListSubjectsParams, type LoginEvent, type LoginMethod, MagicLinkConfig, MemoryStore, type OAuthAccount, type OAuthCallbackResult, type OAuthModule, type OAuthModuleConfig, type OAuthPluginConfig, type OAuthProvider, type OAuthProviderConfig, type OAuthProxyConfig, OAuthProxyError, type OAuthProxyModule, type OAuthProxyPluginConfig, type OAuthTokens, type OAuthUserInfo, type OidcClient, type OidcDiscoveryDocument, type OidcProviderConfig, type OidcProviderModule, type OneTapConfig, type OneTapModule, OneTapVerifyError, 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 PermissionRuleSet, type PolarConfig, type PolarModule, type PolarSubscription, type ProxyTokens, type RateLimitConfig, type RateLimitMiddlewareOptions, type RateLimitConfig$1 as RateLimitPluginConfig, type RateLimitResult, type RateLimitStore, type RateLimiter, type ReBACConfig, type ReBACModule, type RecordCostInput, type RecordLoginInput, type RegisterClientInput, type Relationship, ResolvedUser, type ResourceNode, type ScimConfig, type ScimGroup, type ScimModule, type ScimUser, type SessionTokens, type SessionUser, type SiweConfig, type SiweModule, type SiweVerifyResult, type StreamEvent, type StripeConfig, type StripeModule, type SubscriptionInfo, type TokenParams, type TokenResponse, TotpConfig, type TrustLevel, type TrustedDevice, type TrustedDeviceConfig, type TrustedDeviceModule, type TrustedInstance, type TwoFactorConfig, type UserDataExport, type UserInfoClaims, type ValidationResult, type 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, normalizeProfile$9 as normalizeAtlassianProfile, normalizeProfile$8 as normalizeDiscordProfile, normalizeProfile$7 as normalizeDropboxProfile, normalizeProfile$6 as normalizeFigmaProfile, normalizeProfile$5 as normalizeNotionProfile, normalizeProfile$4 as normalizeRedditProfile, normalizeProfile$3 as normalizeSlackProfile, normalizeProfile$2 as normalizeSpotifyProfile, normalizeProfile$1 as normalizeTwitchProfile, normalizeProfile as 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 };