@korajs/auth 0.1.0 → 0.3.1

package/dist/server.d.ts

@@ -1,32 +1,111 @@
-import { A as AuthTokens, T as TokenPayload } from './device-identity-DiwdLsUB.js';
-export { f as computePublicKeyThumbprint, v as verifyChallenge } from './device-identity-DiwdLsUB.js';
+import { A as AuthTokens, T as TokenPayload } from './operation-encryptor-DRmKNWpF.js';
+export { O as OperationEncryptionError, e as OperationEncryptor, f as OperationEncryptorConfig, h as computePublicKeyThumbprint, l as isEncryptedField, v as verifyChallenge } from './operation-encryptor-DRmKNWpF.js';
 import { KoraError } from '@korajs/core';
 
+/**
+ * Interface for server-side token revocation storage.
+ *
+ * Implementing this interface allows the TokenManager to:
+ * - Revoke individual tokens by their `jti`
+ * - Detect refresh token reuse (potential theft indicator)
+ * - Invalidate all tokens for a specific device on revocation
+ *
+ * The in-memory implementation ({@link InMemoryTokenRevocationStore}) is suitable
+ * for development. Production deployments should use a persistent store (Redis, database).
+ */
+interface TokenRevocationStore {
+    /**
+     * Check whether a token has been revoked.
+     * @param jti - The JWT ID to check
+     * @returns true if the token has been revoked
+     */
+    isRevoked(jti: string): Promise<boolean>;
+    /**
+     * Revoke a specific token by its JWT ID.
+     * @param jti - The JWT ID to revoke
+     * @param expiresAt - The token's original expiration time (seconds since epoch).
+     *   The store may use this to auto-purge expired revocations.
+     */
+    revoke(jti: string, expiresAt: number): Promise<void>;
+    /**
+     * Revoke all tokens associated with a specific device.
+     * Called when a device is revoked to invalidate all its tokens.
+     * @param deviceId - The device ID whose tokens should be revoked
+     */
+    revokeAllForDevice(deviceId: string): Promise<void>;
+}
+/**
+ * In-memory token revocation store.
+ *
+ * Suitable for development and testing. Revoked tokens are stored in a Set
+ * and automatically cleaned up when they would have expired naturally.
+ *
+ * **Not suitable for production**: revocations are lost on server restart
+ * and not shared across server instances. Use a Redis or database-backed
+ * store in production.
+ */
+declare class InMemoryTokenRevocationStore implements TokenRevocationStore {
+    private readonly revokedTokens;
+    private readonly revokedDevices;
+    isRevoked(jti: string): Promise<boolean>;
+    revoke(jti: string, expiresAt: number): Promise<void>;
+    revokeAllForDevice(deviceId: string): Promise<void>;
+    /**
+     * Check if a device has been revoked.
+     */
+    isDeviceRevoked(deviceId: string): boolean;
+    /**
+     * Remove expired revocations to prevent unbounded memory growth.
+     * Call periodically (e.g., every hour) in long-running servers.
+     */
+    cleanup(): void;
+}
 /**
  * Configuration for the server-side TokenManager.
  */
 interface TokenManagerConfig {
-    /** Secret key for signing JWTs (HMAC-SHA256) */
-    secret: string;
+    /**
+     * Secret key for signing JWTs (HMAC-SHA256).
+     *
+     * Must be at least 32 characters (256 bits). Use {@link TokenManager.generateSecret}
+     * to create a cryptographically random secret.
+     *
+     * For key rotation, provide an array of secrets. The first secret is used for
+     * signing new tokens; all secrets are tried during verification (newest first).
+     * This allows graceful rotation: add the new secret at index 0, then remove
+     * the old secret after all tokens signed with it have expired.
+     */
+    secret: string | string[];
     /** Access token lifetime in milliseconds (default: 15 minutes) */
     accessTokenLifetime?: number;
     /** Refresh token lifetime in milliseconds (default: 90 days) */
     refreshTokenLifetime?: number;
     /** Device credential lifetime in milliseconds (default: 90 days) */
     deviceCredentialLifetime?: number;
+    /**
+     * Optional token revocation store. When provided, enables:
+     * - Individual token revocation via `revokeToken()`
+     * - Refresh token reuse detection (consumed tokens are tracked)
+     * - Device-level token invalidation via `revokeDeviceTokens()`
+     *
+     * Without a revocation store, tokens are valid until they expire.
+     */
+    revocationStore?: TokenRevocationStore;
 }
 /**
  * Server-side token manager responsible for issuing, refreshing, and validating
  * Kora authentication tokens.
  *
- * Uses HMAC-SHA256 signed JWTs. Supports three token types:
- * - **Access tokens**: Short-lived tokens for API authorization (default: 15 min)
- * - **Refresh tokens**: Longer-lived tokens for obtaining new access tokens (default: 90 days)
- * - **Device credentials**: Long-lived credentials bound to a device key pair (default: 90 days)
+ * Uses HMAC-SHA256 signed JWTs with unique `jti` identifiers for every token.
+ * Supports key rotation (multiple secrets), token revocation, and refresh token
+ * reuse detection.
  *
  * @example
  * ```typescript
- * const tokenManager = new TokenManager({ secret: 'my-signing-secret' })
+ * const tokenManager = new TokenManager({
+ *   secret: TokenManager.generateSecret(),
+ *   revocationStore: new InMemoryTokenRevocationStore(),
+ * })
  *
  * // Issue all tokens at once
  * const tokens = tokenManager.issueTokens('user-123', 'device-456')
@@ -35,15 +114,26 @@ interface TokenManagerConfig {
  * const payload = tokenManager.validateToken(tokens.accessToken)
  *
  * // Refresh when the access token expires
- * const newTokens = tokenManager.refreshAccessToken(tokens.refreshToken)
+ * const newTokens = await tokenManager.refreshAccessToken(tokens.refreshToken)
  * ```
  */
 declare class TokenManager {
-    private readonly secret;
+    /** All signing/verification secrets (index 0 = current signing key) */
+    private readonly secrets;
     private readonly accessTokenLifetime;
     private readonly refreshTokenLifetime;
     private readonly deviceCredentialLifetime;
+    private readonly revocationStore;
     constructor(config: TokenManagerConfig);
+    /**
+     * Generate a cryptographically random secret suitable for HMAC-SHA256 signing.
+     *
+     * Returns a 64-character hex string (32 bytes / 256 bits of entropy).
+     * Store this securely (environment variable, secrets manager) — never in source code.
+     *
+     * @returns A random 256-bit hex-encoded secret
+     */
+    static generateSecret(): string;
     /**
      * Issue a signed JWT access token.
      *
@@ -97,7 +187,8 @@ declare class TokenManager {
     /**
      * Validate and decode a token.
      *
-     * Verifies the HMAC-SHA256 signature and checks that the token has not expired.
+     * Verifies the HMAC-SHA256 signature (trying all configured secrets for key rotation),
+     * checks that the token has not expired, and validates all required claims.
      * Returns null (rather than throwing) for invalid or expired tokens, so callers
      * can handle authentication failure without try/catch.
      *
@@ -106,22 +197,52 @@ declare class TokenManager {
      *   invalid, expired, or missing required claims
      */
     validateToken(token: string): TokenPayload | null;
+    /**
+     * Validate a token and check it against the revocation store.
+     *
+     * Like {@link validateToken}, but also checks whether the token's `jti` has been
+     * revoked. Requires a revocation store to be configured.
+     *
+     * @param token - The JWT string to validate
+     * @returns The decoded {@link TokenPayload} if valid and not revoked, or null otherwise
+     */
+    validateTokenWithRevocation(token: string): Promise<TokenPayload | null>;
+    /**
+     * Revoke a specific token by its JWT ID.
+     *
+     * Requires a revocation store to be configured. After revocation, the token
+     * will be rejected by {@link validateTokenWithRevocation}.
+     *
+     * @param jti - The JWT ID of the token to revoke
+     * @param expiresAt - The token's expiration time (seconds since epoch)
+     */
+    revokeToken(jti: string, expiresAt: number): Promise<void>;
+    /**
+     * Revoke all tokens for a specific device.
+     *
+     * Called when a device is revoked to ensure all its existing tokens
+     * (access, refresh, and device credentials) are invalidated.
+     *
+     * @param deviceId - The device ID whose tokens should be revoked
+     */
+    revokeDeviceTokens(deviceId: string): Promise<void>;
     /**
      * Refresh an access token using a valid refresh token.
      *
-     * Implements **refresh token rotation**: a new refresh token is issued alongside
-     * the new access token, and the old refresh token should be considered consumed.
-     * This limits the window of vulnerability if a refresh token is compromised.
+     * Implements **refresh token rotation with reuse detection**: a new refresh token
+     * is issued alongside the new access token. The old refresh token's `jti` is
+     * recorded in the revocation store (if configured). If a previously consumed
+     * refresh token is presented again, it indicates potential token theft.
      *
      * Returns null if the provided token is invalid, expired, or not a refresh token.
      *
      * @param refreshToken - The refresh token JWT string
      * @returns A new access/refresh token pair, or null if the refresh token is invalid
      */
-    refreshAccessToken(refreshToken: string): {
+    refreshAccessToken(refreshToken: string): Promise<{
         accessToken: string;
         refreshToken: string;
-    } | null;
+    } | null>;
 }
 
 /**
@@ -135,6 +256,8 @@ interface AuthUser {
     email: string;
     /** User's display name */
     name: string;
+    /** Whether the user's email has been verified */
+    emailVerified: boolean;
     /** Timestamp when the user was created (milliseconds since epoch) */
     createdAt: number;
 }
@@ -171,17 +294,72 @@ interface AuthDevice {
  * Thrown when a user account already exists with the given email.
  */
 declare class DuplicateEmailError extends KoraError {
-    constructor(email: string);
+    constructor();
+}
+/**
+ * Generic interface for user and device persistence.
+ *
+ * Implement this interface to provide database-backed user storage for
+ * the built-in auth provider. All methods are async to support both
+ * synchronous (in-memory, SQLite) and asynchronous (PostgreSQL) backends.
+ *
+ * Built-in implementations:
+ * - {@link InMemoryUserStore} — development and testing (no persistence)
+ * - `SqliteUserStore` — SQLite via better-sqlite3 (from `@korajs/auth/server`)
+ * - `PostgresUserStore` — PostgreSQL via postgres-js (from `@korajs/auth/server`)
+ *
+ * @example
+ * ```typescript
+ * import { BuiltInAuthRoutes, SqliteUserStore } from '@korajs/auth/server'
+ *
+ * const userStore = await createSqliteUserStore({ filename: './auth.db' })
+ * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
+ * ```
+ */
+interface UserStore {
+    /** Create a new user account. Throws DuplicateEmailError if email exists. */
+    createUser(params: {
+        email: string;
+        passwordHash: string;
+        salt: string;
+        name: string;
+    }): Promise<AuthUser>;
+    /** Find a user by email address (case-insensitive). */
+    findByEmail(email: string): Promise<StoredUser | null>;
+    /** Find a user by ID. */
+    findById(id: string): Promise<StoredUser | null>;
+    /** Register a device for a user. Idempotent if device already exists and is not revoked. */
+    registerDevice(params: {
+        id: string;
+        userId: string;
+        publicKey: string;
+        name: string;
+    }): Promise<AuthDevice>;
+    /** Find a device by its ID. */
+    findDevice(deviceId: string): Promise<AuthDevice | null>;
+    /** List all devices registered for a user (includes revoked). */
+    listDevices(userId: string): Promise<AuthDevice[]>;
+    /** Soft-revoke a device. No-op if device does not exist. */
+    revokeDevice(deviceId: string): Promise<void>;
+    /** Set a user's email verification status. */
+    setEmailVerified(userId: string, verified: boolean): Promise<void>;
+    /** Update a user's password hash and salt. */
+    updatePassword(userId: string, passwordHash: string, salt: string): Promise<void>;
+    /** List all users. For admin/development use. */
+    listAll(): Promise<StoredUser[]>;
+    /** Update a stored user record. */
+    update(user: StoredUser): Promise<void>;
+    /** Delete a user and all associated devices. */
+    delete(userId: string): Promise<void>;
+    /** Update the last-seen timestamp for a device. No-op if device does not exist. */
+    touchDevice(deviceId: string): Promise<void>;
 }
 /**
  * In-memory user and device store for the built-in auth provider.
  *
  * This is a simple implementation suitable for development and testing.
- * Production applications should replace this with a database-backed store
- * implementing the same interface.
- *
- * All methods are async to match the interface that a real database store
- * would expose, even though the in-memory operations are synchronous.
+ * Production applications should use {@link SqliteUserStore} or
+ * {@link PostgresUserStore} for persistent storage.
  *
  * @example
  * ```typescript
@@ -194,7 +372,7 @@ declare class DuplicateEmailError extends KoraError {
  * })
  * ```
  */
-declare class InMemoryUserStore {
+declare class InMemoryUserStore implements UserStore {
     /** Users indexed by ID */
     private readonly usersById;
     /** Users indexed by email (lowercase) for fast lookup */
@@ -277,6 +455,33 @@ declare class InMemoryUserStore {
      * @param deviceId - The ID of the device to revoke
      */
     revokeDevice(deviceId: string): Promise<void>;
+    /**
+     * Set a user's email verification status.
+     *
+     * @param userId - The user whose email to verify
+     * @param verified - Whether the email is verified
+     */
+    setEmailVerified(userId: string, verified: boolean): Promise<void>;
+    /**
+     * Update a user's password hash and salt.
+     *
+     * @param userId - The user whose password to update
+     * @param passwordHash - New hex-encoded PBKDF2 derived key
+     * @param salt - New hex-encoded salt
+     */
+    updatePassword(userId: string, passwordHash: string, salt: string): Promise<void>;
+    /**
+     * List all users. For admin/development use.
+     */
+    listAll(): Promise<StoredUser[]>;
+    /**
+     * Update a stored user record.
+     */
+    update(user: StoredUser): Promise<void>;
+    /**
+     * Delete a user and all associated devices.
+     */
+    delete(userId: string): Promise<void>;
     /**
      * Update the last-seen timestamp for a device.
      *
@@ -288,14 +493,105 @@ declare class InMemoryUserStore {
     touchDevice(deviceId: string): Promise<void>;
 }
 
+/**
+ * Interface for server-side challenge storage.
+ *
+ * Challenges must be stored server-side with expiry and single-use semantics
+ * to prevent replay attacks on device verification.
+ */
+interface ChallengeStore {
+    /**
+     * Store a challenge for later verification.
+     * @param challenge - The challenge string
+     * @param deviceId - The device this challenge is intended for
+     * @param expiresAt - Timestamp (ms since epoch) when this challenge expires
+     */
+    store(challenge: string, deviceId: string, expiresAt: number): Promise<void>;
+    /**
+     * Consume a challenge (single-use). Returns the associated device ID if the
+     * challenge is valid and not expired, or null if it doesn't exist, has expired,
+     * or was already consumed.
+     */
+    consume(challenge: string): Promise<{
+        deviceId: string;
+    } | null>;
+}
+/**
+ * In-memory challenge store with expiry and single-use semantics.
+ * Suitable for development and testing. Use Redis or a database in production.
+ */
+declare class InMemoryChallengeStore implements ChallengeStore {
+    private readonly challenges;
+    store(challenge: string, deviceId: string, expiresAt: number): Promise<void>;
+    consume(challenge: string): Promise<{
+        deviceId: string;
+    } | null>;
+    /**
+     * Remove expired challenges to prevent unbounded memory growth.
+     */
+    cleanup(): void;
+}
+/**
+ * Interface for rate limiting auth endpoints.
+ *
+ * Rate limiting is critical for preventing brute-force password guessing
+ * and credential stuffing attacks.
+ */
+interface RateLimiter {
+    /**
+     * Check if an action is allowed for the given key.
+     * @param key - Rate limit key (e.g., IP address, email, or composite key)
+     * @returns true if the action is allowed, false if rate limited
+     */
+    isAllowed(key: string): Promise<boolean>;
+    /**
+     * Record that an action was performed for the given key.
+     * Call this after each authentication attempt.
+     */
+    record(key: string): Promise<void>;
+    /**
+     * Reset the rate limit for a key (e.g., after a successful login).
+     */
+    reset(key: string): Promise<void>;
+}
+/**
+ * In-memory sliding window rate limiter.
+ * Suitable for development and single-server deployments.
+ * Use Redis-based rate limiting for multi-server production deployments.
+ */
+declare class InMemoryRateLimiter implements RateLimiter {
+    private readonly attempts;
+    private readonly maxAttempts;
+    private readonly windowMs;
+    /**
+     * @param maxAttempts - Maximum number of attempts within the time window (default: 10)
+     * @param windowMs - Time window in milliseconds (default: 60,000 = 1 minute)
+     */
+    constructor(maxAttempts?: number, windowMs?: number);
+    isAllowed(key: string): Promise<boolean>;
+    record(key: string): Promise<void>;
+    reset(key: string): Promise<void>;
+}
 /**
  * Configuration for building the built-in auth routes.
  */
 interface AuthRoutesConfig {
     /** The user/device store backing the auth routes */
-    userStore: InMemoryUserStore;
+    userStore: UserStore;
     /** The token manager for issuing and validating JWTs */
     tokenManager: TokenManager;
+    /**
+     * Optional challenge store for device verification.
+     * Required for secure device proof-of-possession verification.
+     * If not provided, an in-memory store is created automatically.
+     */
+    challengeStore?: ChallengeStore;
+    /**
+     * Optional rate limiter for authentication endpoints.
+     * If not provided, an in-memory rate limiter is created with defaults
+     * (10 attempts per minute).
+     */
+    rateLimiter?: RateLimiter;
 }
 /**
  * Response envelope returned by all auth route handlers.
@@ -326,11 +622,18 @@ interface AuthRouteResponse<T> {
  * - Return `{ status, body: { data } }` on success
  * - Return `{ status, body: { error } }` on failure
  *
+ * Security features:
+ * - Rate limiting on sign-in/sign-up to prevent brute-force attacks
+ * - Server-side challenge store for device verification (single-use, time-limited)
+ * - Token revocation on sign-out and device revocation
+ * - Input sanitization on all name fields
+ * - Maximum password length to prevent hash-DoS
+ *
  * @example
  * ```typescript
  * const routes = new BuiltInAuthRoutes({
  *   userStore: new InMemoryUserStore(),
- *   tokenManager: new TokenManager({ secret: 'my-secret' }),
+ *   tokenManager: new TokenManager({ secret: TokenManager.generateSecret() }),
  * })
  *
  * // Wire into an HTTP server:
@@ -343,6 +646,8 @@ interface AuthRouteResponse<T> {
 declare class BuiltInAuthRoutes {
     private readonly userStore;
     private readonly tokenManager;
+    private readonly challengeStore;
+    private readonly rateLimiter;
     constructor(config: AuthRoutesConfig);
     /**
      * Handle user sign-up (POST /auth/signup).
@@ -352,10 +657,11 @@ declare class BuiltInAuthRoutes {
      *
      * @param body - Sign-up request body
      * @param body.email - The user's email address
-     * @param body.password - The plaintext password (min 8 characters)
+     * @param body.password - The plaintext password (8-128 characters)
      * @param body.name - Optional display name (defaults to email local part)
      * @param body.deviceId - Optional device ID to register
      * @param body.devicePublicKey - Optional device public key (base64url)
+     * @param clientIp - Optional client IP for rate limiting
      * @returns Auth response with the created user and tokens, or an error
      */
     handleSignUp(body: {
@@ -364,7 +670,7 @@ declare class BuiltInAuthRoutes {
         name?: string;
         deviceId?: string;
         devicePublicKey?: string;
-    }): Promise<AuthRouteResponse<{
+    }, clientIp?: string): Promise<AuthRouteResponse<{
         user: AuthUser;
         tokens: AuthTokens;
     }>>;
@@ -379,6 +685,7 @@ declare class BuiltInAuthRoutes {
      * @param body.password - The plaintext password
      * @param body.deviceId - Optional device ID to register
      * @param body.devicePublicKey - Optional device public key (base64url)
+     * @param clientIp - Optional client IP for rate limiting
      * @returns Auth response with the user and tokens, or an error
      */
     handleSignIn(body: {
@@ -386,7 +693,7 @@ declare class BuiltInAuthRoutes {
         password: string;
         deviceId?: string;
         devicePublicKey?: string;
-    }): Promise<AuthRouteResponse<{
+    }, clientIp?: string): Promise<AuthRouteResponse<{
         user: AuthUser;
         tokens: AuthTokens;
     }>>;
@@ -394,8 +701,8 @@ declare class BuiltInAuthRoutes {
      * Handle token refresh (POST /auth/refresh).
      *
      * Validates the provided refresh token and issues a new token pair
-     * (refresh token rotation). The old refresh token should be considered
-     * consumed after this call.
+     * (refresh token rotation with reuse detection). The old refresh token
+     * is marked as consumed in the revocation store.
      *
      * @param body - Refresh request body
      * @param body.refreshToken - The current refresh token
@@ -404,6 +711,23 @@ declare class BuiltInAuthRoutes {
     handleRefresh(body: {
         refreshToken: string;
     }): Promise<AuthRouteResponse<AuthTokens>>;
+    /**
+     * Handle sign-out (POST /auth/signout).
+     *
+     * Validates the access token and revokes the current refresh token
+     * (if a revocation store is configured). This ensures that stolen
+     * refresh tokens cannot be used after the user signs out.
+     *
+     * @param accessToken - The JWT access token (without "Bearer " prefix)
+     * @param body - Sign-out request body
+     * @param body.refreshToken - The current refresh token to revoke
+     * @returns Auth response with success flag, or an error
+     */
+    handleSignOut(accessToken: string, body: {
+        refreshToken?: string;
+    }): Promise<AuthRouteResponse<{
+        success: boolean;
+    }>>;
     /**
      * Handle get-current-user (GET /auth/me).
      *
@@ -425,8 +749,8 @@ declare class BuiltInAuthRoutes {
     /**
      * Handle device revocation (DELETE /auth/device/:id).
      *
-     * Validates the access token and revokes the specified device.
-     * Only the device's owner can revoke it.
+     * Validates the access token, revokes the specified device, and invalidates
+     * all tokens issued to that device. Only the device's owner can revoke it.
      *
      * @param accessToken - The JWT access token (without "Bearer " prefix)
      * @param deviceId - The ID of the device to revoke
@@ -435,6 +759,73 @@ declare class BuiltInAuthRoutes {
     handleRevokeDevice(accessToken: string, deviceId: string): Promise<AuthRouteResponse<{
         success: boolean;
     }>>;
+    /**
+     * Handle device registration (POST /auth/device/register).
+     *
+     * Requires a valid access token. Registers a new device for the authenticated
+     * user and issues a device credential token bound to the device's public key.
+     *
+     * @param accessToken - The JWT access token (without "Bearer " prefix)
+     * @param body - Device registration request body
+     * @param body.deviceId - Unique identifier for the device
+     * @param body.publicKey - The device's public key as a JWK JSON string
+     * @param body.name - Human-readable device name (e.g., "Chrome on MacBook")
+     * @returns Auth response with the registered device and device credential, or an error
+     */
+    handleDeviceRegister(accessToken: string, body: {
+        deviceId: string;
+        publicKey: string;
+        name: string;
+    }): Promise<AuthRouteResponse<{
+        device: AuthDevice;
+        deviceCredential: string;
+    }>>;
+    /**
+     * Generate a challenge for device proof-of-possession verification.
+     *
+     * Creates a cryptographically random challenge, stores it server-side with
+     * a 60-second TTL and the target device ID, and returns the challenge string.
+     * The client signs this challenge with its private key and submits it via
+     * {@link handleDeviceVerify}.
+     *
+     * @param accessToken - The JWT access token (without "Bearer " prefix)
+     * @param deviceId - The device this challenge is intended for
+     * @returns Auth response with the challenge string, or an error
+     */
+    handleDeviceChallenge(accessToken: string, deviceId: string): Promise<AuthRouteResponse<{
+        challenge: string;
+    }>>;
+    /**
+     * Handle device proof-of-possession verification (POST /auth/device/verify).
+     *
+     * Verifies that the device holds the private key corresponding to its registered
+     * public key by checking a signed challenge. The challenge must have been previously
+     * issued via {@link handleDeviceChallenge} and is single-use.
+     *
+     * On success, issues fresh tokens for the device.
+     *
+     * @param body - Device verification request body
+     * @param body.deviceId - The ID of the device to verify
+     * @param body.challenge - The challenge string (from handleDeviceChallenge)
+     * @param body.signature - The base64url-encoded ECDSA signature of the challenge
+     * @returns Auth response with fresh tokens on success, or an error
+     */
+    handleDeviceVerify(body: {
+        deviceId: string;
+        challenge: string;
+        signature: string;
+    }): Promise<AuthRouteResponse<{
+        tokens: AuthTokens;
+    }>>;
+    /**
+     * Generates a random challenge string for proof-of-possession verification.
+     *
+     * **Deprecated:** Use {@link handleDeviceChallenge} instead, which stores
+     * the challenge server-side with expiry and single-use semantics.
+     *
+     * @returns A 64-character hex string (32 random bytes)
+     */
+    static generateChallenge(): string;
     /**
      * Creates a sync server auth provider compatible with `@korajs/server`.
      *
@@ -443,6 +834,9 @@ declare class BuiltInAuthRoutes {
      * context containing the user ID and device metadata. This bridges
      * the built-in auth system with the sync server's authentication layer.
      *
+     * Also checks device revocation status during authentication, ensuring
+     * that revoked devices are rejected even if their tokens haven't expired.
+     *
      * @returns An object with an `authenticate` method suitable for KoraSyncServer's `auth` config
      *
      * @example
@@ -531,8 +925,9 @@ declare function verifyJwt(token: string, secret: string): Record<string, unknow
  * Checks whether a token payload has expired based on its `exp` claim.
  *
  * The `exp` claim is expected to be in seconds since the Unix epoch (per JWT spec).
- * If the `exp` claim is missing or is not a number, the token is considered
- * non-expiring and this function returns false.
+ * Includes a small clock skew tolerance (5 seconds) to handle minor time
+ * differences between servers. If the `exp` claim is missing or is not a number,
+ * the token is considered non-expiring and this function returns false.
  *
  * @param payload - An object with an optional `exp` field (seconds since epoch)
  * @returns true if the token has expired, false otherwise
@@ -597,91 +992,517 @@ declare function hashPassword(password: string): Promise<HashResult>;
 declare function verifyPassword(password: string, hash: string, salt: string): Promise<boolean>;
 
 /**
- * Parameters for signing up a new user.
+ * A pending password reset request.
  */
-interface SignUpParams {
-    /** The user's email address */
+interface PasswordResetToken {
+    /** Cryptographically random single-use token */
+    token: string;
+    /** User ID the token was generated for */
+    userId: string;
+    /** Email the reset was requested for */
     email: string;
-    /** The plaintext password */
-    password: string;
-    /** Optional display name */
-    name?: string;
-    /** Optional device ID to register with the account */
-    deviceId?: string;
-    /** Optional device public key (base64url) */
-    devicePublicKey?: string;
+    /** When the token was created (ms since epoch) */
+    createdAt: number;
+    /** When the token expires (ms since epoch) */
+    expiresAt: number;
+    /** Whether the token has been consumed */
+    consumed: boolean;
 }
 /**
- * Parameters for signing in an existing user.
+ * Persistence interface for password reset tokens.
  */
-interface SignInParams {
-    /** The user's email address */
-    email: string;
-    /** The plaintext password */
-    password: string;
-    /** Optional device ID to register or associate */
-    deviceId?: string;
-    /** Optional device public key (base64url) */
-    devicePublicKey?: string;
+interface PasswordResetStore {
+    /** Store a reset token. */
+    store(token: PasswordResetToken): Promise<void>;
+    /** Look up a token. Returns null if not found. */
+    get(token: string): Promise<PasswordResetToken | null>;
+    /** Mark a token as consumed. */
+    consume(token: string): Promise<void>;
+    /** Count active (non-consumed, non-expired) tokens for an email. */
+    countActiveForEmail(email: string): Promise<number>;
+    /** Remove expired tokens. */
+    cleanExpired(): Promise<number>;
 }
 /**
- * Abstraction for authentication providers.
- *
- * This interface allows swapping between the built-in email/password provider
- * and external providers (OAuth, SAML, custom) without changing application code.
- * Every provider must support the same core operations: sign up, sign in,
- * token refresh, token validation, user lookup, and device management.
+ * Configuration for the password reset flow.
+ */
+interface PasswordResetConfig {
+    /** User store for looking up users and updating passwords */
+    userStore: UserStore;
+    /** Store for reset tokens. Defaults to InMemoryPasswordResetStore. */
+    resetStore?: PasswordResetStore;
+    /** Token TTL in milliseconds. Defaults to 1 hour. */
+    tokenTtlMs?: number;
+    /** Max reset requests per email in the TTL window. Defaults to 3. */
+    maxRequestsPerEmail?: number;
+    /**
+     * Callback invoked when a reset is requested.
+     * The developer must implement email sending.
+     * If not provided, the token is returned in the route response (development mode).
+     */
+    onResetRequested?: (email: string, token: string, expiresAt: number) => void | Promise<void>;
+}
+declare class PasswordResetError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class ResetTokenExpiredError extends PasswordResetError {
+    constructor();
+}
+declare class ResetTokenNotFoundError extends PasswordResetError {
+    constructor();
+}
+declare class ResetRateLimitedError extends PasswordResetError {
+    constructor();
+}
+declare class InMemoryPasswordResetStore implements PasswordResetStore {
+    private tokens;
+    store(token: PasswordResetToken): Promise<void>;
+    get(token: string): Promise<PasswordResetToken | null>;
+    consume(token: string): Promise<void>;
+    countActiveForEmail(email: string): Promise<number>;
+    cleanExpired(): Promise<number>;
+}
+/**
+ * Manages the password reset flow.
  *
  * @example
  * ```typescript
- * // Use the built-in provider
- * const provider: AuthProviderAdapter = new BuiltInProvider({
- *   userStore: new InMemoryUserStore(),
- *   tokenManager: new TokenManager({ secret: 'my-secret' }),
+ * const resetManager = new PasswordResetManager({
+ *   userStore,
+ *   onResetRequested: async (email, token, expiresAt) => {
+ *     await sendEmail(email, `Reset link: https://app.com/reset?token=${token}`)
+ *   },
  * })
  *
- * const { user, tokens } = await provider.signUp({
- *   email: 'alice@example.com',
- *   password: 'secure-password-123',
- * })
+ * // Request reset (always returns 200 to prevent email enumeration)
+ * const response = await resetManager.requestReset('user@example.com')
+ *
+ * // Consume token and set new password
+ * const response = await resetManager.resetPassword(token, 'newPassword123')
  * ```
  */
-interface AuthProviderAdapter {
+declare class PasswordResetManager {
+    private readonly userStore;
+    private readonly resetStore;
+    private readonly tokenTtlMs;
+    private readonly maxRequestsPerEmail;
+    private readonly onResetRequested?;
+    constructor(config: PasswordResetConfig);
     /**
-     * Create a new user account and issue authentication tokens.
+     * Request a password reset for an email.
+     * Always returns success to prevent email enumeration.
      *
-     * @param params - Sign-up parameters including email, password, and optional device info
-     * @returns The created user and tokens
-     * @throws If the email is already registered or input validation fails
+     * If a callback is configured, invokes it with the token.
+     * In development mode (no callback), returns the token in the response.
      */
-    signUp(params: SignUpParams): Promise<{
-        user: AuthUser;
-        tokens: AuthTokens;
+    requestReset(email: string): Promise<{
+        status: number;
+        body: {
+            data: {
+                message: string;
+                token?: string;
+            };
+        } | {
+            error: string;
+        };
     }>;
     /**
-     * Authenticate an existing user and issue tokens.
-     *
-     * @param params - Sign-in parameters including email and password
-     * @returns The authenticated user and tokens
-     * @throws If the credentials are invalid
+     * Consume a reset token and set a new password.
      */
-    signIn(params: SignInParams): Promise<{
-        user: AuthUser;
-        tokens: AuthTokens;
+    resetPassword(token: string, newPassword: string): Promise<{
+        status: number;
+        body: {
+            data: {
+                message: string;
+            };
+        } | {
+            error: string;
+        };
     }>;
     /**
-     * Exchange a refresh token for new tokens (rotation).
-     *
-     * @param refreshToken - The current refresh token
-     * @returns A new token pair
-     * @throws If the refresh token is invalid or expired
+     * Change password for an authenticated user (requires current password verification).
      */
-    refreshTokens(refreshToken: string): Promise<AuthTokens>;
+    changePassword(userId: string, currentPassword: string, newPassword: string): Promise<{
+        status: number;
+        body: {
+            data: {
+                message: string;
+            };
+        } | {
+            error: string;
+        };
+    }>;
+}
+
+/**
+ * A pending email verification token.
+ */
+interface EmailVerificationToken {
+    /** Cryptographically random single-use token */
+    token: string;
+    /** User ID the token was generated for */
+    userId: string;
+    /** Email being verified */
+    email: string;
+    /** When the token was created (ms since epoch) */
+    createdAt: number;
+    /** When the token expires (ms since epoch) */
+    expiresAt: number;
+    /** Whether the token has been consumed */
+    consumed: boolean;
+}
+/**
+ * Persistence interface for email verification tokens.
+ */
+interface EmailVerificationStore {
+    /** Store a verification token. */
+    store(token: EmailVerificationToken): Promise<void>;
+    /** Look up a token. Returns null if not found. */
+    get(token: string): Promise<EmailVerificationToken | null>;
+    /** Mark a token as consumed. */
+    consume(token: string): Promise<void>;
+    /** Count active (non-consumed, non-expired) tokens for a user. */
+    countActiveForUser(userId: string): Promise<number>;
+    /** Remove expired tokens. */
+    cleanExpired(): Promise<number>;
+}
+/**
+ * Configuration for the email verification flow.
+ */
+interface EmailVerificationConfig {
+    /** User store for looking up users */
+    userStore: UserStore;
+    /** Store for verification tokens. Defaults to InMemoryEmailVerificationStore. */
+    verificationStore?: EmailVerificationStore;
+    /** Token TTL in milliseconds. Defaults to 24 hours. */
+    tokenTtlMs?: number;
+    /** Max verification requests per user per TTL window. Defaults to 3. */
+    maxRequestsPerUser?: number;
     /**
-     * Validate an access token and extract identity claims.
-     *
-     * @param token - The JWT access token
-     * @returns User ID and device ID if valid, or null if invalid/expired
+     * Callback invoked when a verification email should be sent.
+     * The developer must implement email sending.
+     * If not provided, the token is returned in the route response (development mode).
+     */
+    onVerificationRequired?: (email: string, token: string, expiresAt: number) => void | Promise<void>;
+}
+declare class EmailVerificationError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class VerificationTokenExpiredError extends EmailVerificationError {
+    constructor();
+}
+declare class VerificationTokenNotFoundError extends EmailVerificationError {
+    constructor();
+}
+declare class InMemoryEmailVerificationStore implements EmailVerificationStore {
+    private tokens;
+    store(token: EmailVerificationToken): Promise<void>;
+    get(token: string): Promise<EmailVerificationToken | null>;
+    consume(token: string): Promise<void>;
+    countActiveForUser(userId: string): Promise<number>;
+    cleanExpired(): Promise<number>;
+}
+/**
+ * Manages the email verification flow.
+ *
+ * @example
+ * ```typescript
+ * const verifier = new EmailVerificationManager({
+ *   userStore,
+ *   onVerificationRequired: async (email, token, expiresAt) => {
+ *     await sendEmail(email, `Verify: https://app.com/verify?token=${token}`)
+ *   },
+ * })
+ *
+ * // Send verification email
+ * await verifier.sendVerification('user-1', 'user@example.com')
+ *
+ * // Verify email
+ * await verifier.verifyEmail(token)
+ * ```
+ */
+declare class EmailVerificationManager {
+    private readonly userStore;
+    private readonly verificationStore;
+    private readonly tokenTtlMs;
+    private readonly maxRequestsPerUser;
+    private readonly onVerificationRequired?;
+    constructor(config: EmailVerificationConfig);
+    /**
+     * Send a verification email for a user.
+     * Rate-limited to prevent abuse.
+     */
+    sendVerification(userId: string, email: string): Promise<{
+        status: number;
+        body: {
+            data: {
+                message: string;
+                token?: string;
+            };
+        } | {
+            error: string;
+        };
+    }>;
+    /**
+     * Verify an email using a verification token.
+     */
+    verifyEmail(token: string): Promise<{
+        status: number;
+        body: {
+            data: {
+                message: string;
+                userId: string;
+                email: string;
+            };
+        } | {
+            error: string;
+        };
+    }>;
+    /**
+     * Resend verification email for a user.
+     * Delegates to sendVerification with rate limiting.
+     */
+    resendVerification(userId: string): Promise<{
+        status: number;
+        body: {
+            data: {
+                message: string;
+                token?: string;
+            };
+        } | {
+            error: string;
+        };
+    }>;
+}
+
+/**
+ * Minimal better-sqlite3 subset to avoid a hard dependency on the package.
+ * The real Database instance satisfies this at runtime.
+ */
+interface SqliteDatabase {
+    pragma(source: string): unknown;
+    exec(source: string): void;
+    prepare(source: string): {
+        run(...params: unknown[]): unknown;
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+    transaction<T>(fn: () => T): () => T;
+}
+/**
+ * SQLite-backed user and device store using better-sqlite3.
+ *
+ * Provides persistent user storage suitable for single-server deployments,
+ * Electron apps, and development environments. Uses WAL mode for concurrent
+ * read/write performance.
+ *
+ * This implementation uses dynamic imports for better-sqlite3 so projects
+ * that do not use SQLite server-side do not need to install it.
+ *
+ * @example
+ * ```typescript
+ * import { createSqliteUserStore } from '@korajs/auth/server'
+ *
+ * const userStore = await createSqliteUserStore({ filename: './auth.db' })
+ * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
+ * ```
+ */
+declare class SqliteUserStore implements UserStore {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    private ensureTables;
+    createUser(params: {
+        email: string;
+        passwordHash: string;
+        salt: string;
+        name: string;
+    }): Promise<AuthUser>;
+    findByEmail(email: string): Promise<StoredUser | null>;
+    findById(id: string): Promise<StoredUser | null>;
+    registerDevice(params: {
+        id: string;
+        userId: string;
+        publicKey: string;
+        name: string;
+    }): Promise<AuthDevice>;
+    findDevice(deviceId: string): Promise<AuthDevice | null>;
+    listDevices(userId: string): Promise<AuthDevice[]>;
+    revokeDevice(deviceId: string): Promise<void>;
+    setEmailVerified(userId: string, verified: boolean): Promise<void>;
+    updatePassword(userId: string, passwordHash: string, salt: string): Promise<void>;
+    listAll(): Promise<StoredUser[]>;
+    update(user: StoredUser): Promise<void>;
+    delete(userId: string): Promise<void>;
+    touchDevice(deviceId: string): Promise<void>;
+}
+/**
+ * Creates a SqliteUserStore from a file path.
+ *
+ * Uses runtime dynamic imports so projects that do not use SQLite server-side
+ * do not need to install `better-sqlite3`.
+ *
+ * @param options.filename - Path to the SQLite database file, or `:memory:` for in-memory
+ */
+declare function createSqliteUserStore(options: {
+    filename: string;
+}): Promise<SqliteUserStore>;
+
+/**
+ * Minimal typed subset of a postgres-js SQL tag for our queries.
+ * Avoids a hard dependency on the postgres package.
+ * Uses Record<string, unknown>[] for result type to match postgres-js return shape.
+ */
+interface PostgresClient {
+    begin<T>(fn: (sql: PostgresClient) => Promise<T>): Promise<T>;
+    (template: TemplateStringsArray, ...args: unknown[]): Promise<Record<string, unknown>[]>;
+}
+/**
+ * PostgreSQL-backed user and device store using postgres-js.
+ *
+ * Provides persistent user storage suitable for production multi-server
+ * deployments. Uses parameterized queries for SQL injection safety and
+ * transactions for atomic operations.
+ *
+ * This implementation uses dynamic imports for postgres so projects
+ * that do not use PostgreSQL do not need to install it.
+ *
+ * @example
+ * ```typescript
+ * import { createPostgresUserStore } from '@korajs/auth/server'
+ *
+ * const userStore = await createPostgresUserStore({
+ *   connectionString: 'postgres://user:pass@localhost:5432/mydb',
+ * })
+ * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
+ * ```
+ */
+declare class PostgresUserStore implements UserStore {
+    private readonly sql;
+    private readonly ready;
+    constructor(sql: PostgresClient);
+    private ensureTables;
+    createUser(params: {
+        email: string;
+        passwordHash: string;
+        salt: string;
+        name: string;
+    }): Promise<AuthUser>;
+    findByEmail(email: string): Promise<StoredUser | null>;
+    findById(id: string): Promise<StoredUser | null>;
+    registerDevice(params: {
+        id: string;
+        userId: string;
+        publicKey: string;
+        name: string;
+    }): Promise<AuthDevice>;
+    findDevice(deviceId: string): Promise<AuthDevice | null>;
+    listDevices(userId: string): Promise<AuthDevice[]>;
+    revokeDevice(deviceId: string): Promise<void>;
+    setEmailVerified(userId: string, verified: boolean): Promise<void>;
+    updatePassword(userId: string, passwordHash: string, salt: string): Promise<void>;
+    listAll(): Promise<StoredUser[]>;
+    update(user: StoredUser): Promise<void>;
+    delete(userId: string): Promise<void>;
+    touchDevice(deviceId: string): Promise<void>;
+}
+/**
+ * Creates a PostgresUserStore from a connection string.
+ *
+ * Uses runtime dynamic imports so projects that do not use PostgreSQL
+ * do not need to install `postgres`.
+ *
+ * @param options.connectionString - PostgreSQL connection URL (e.g., `postgres://user:pass@host:5432/db`)
+ */
+declare function createPostgresUserStore(options: {
+    connectionString: string;
+}): Promise<PostgresUserStore>;
+
+/**
+ * Parameters for signing up a new user.
+ */
+interface SignUpParams {
+    /** The user's email address */
+    email: string;
+    /** The plaintext password */
+    password: string;
+    /** Optional display name */
+    name?: string;
+    /** Optional device ID to register with the account */
+    deviceId?: string;
+    /** Optional device public key (base64url) */
+    devicePublicKey?: string;
+}
+/**
+ * Parameters for signing in an existing user.
+ */
+interface SignInParams {
+    /** The user's email address */
+    email: string;
+    /** The plaintext password */
+    password: string;
+    /** Optional device ID to register or associate */
+    deviceId?: string;
+    /** Optional device public key (base64url) */
+    devicePublicKey?: string;
+}
+/**
+ * Abstraction for authentication providers.
+ *
+ * This interface allows swapping between the built-in email/password provider
+ * and external providers (OAuth, SAML, custom) without changing application code.
+ * Every provider must support the same core operations: sign up, sign in,
+ * token refresh, token validation, user lookup, and device management.
+ *
+ * @example
+ * ```typescript
+ * // Use the built-in provider
+ * const provider: AuthProviderAdapter = new BuiltInProvider({
+ *   userStore: new InMemoryUserStore(),
+ *   tokenManager: new TokenManager({ secret: 'my-secret' }),
+ * })
+ *
+ * const { user, tokens } = await provider.signUp({
+ *   email: 'alice@example.com',
+ *   password: 'secure-password-123',
+ * })
+ * ```
+ */
+interface AuthProviderAdapter {
+    /**
+     * Create a new user account and issue authentication tokens.
+     *
+     * @param params - Sign-up parameters including email, password, and optional device info
+     * @returns The created user and tokens
+     * @throws If the email is already registered or input validation fails
+     */
+    signUp(params: SignUpParams): Promise<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>;
+    /**
+     * Authenticate an existing user and issue tokens.
+     *
+     * @param params - Sign-in parameters including email and password
+     * @returns The authenticated user and tokens
+     * @throws If the credentials are invalid
+     */
+    signIn(params: SignInParams): Promise<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>;
+    /**
+     * Exchange a refresh token for new tokens (rotation).
+     *
+     * @param refreshToken - The current refresh token
+     * @returns A new token pair
+     * @throws If the refresh token is invalid or expired
+     */
+    refreshTokens(refreshToken: string): Promise<AuthTokens>;
+    /**
+     * Validate an access token and extract identity claims.
+     *
+     * @param token - The JWT access token
+     * @returns User ID and device ID if valid, or null if invalid/expired
      */
     validateAccessToken(token: string): Promise<{
         userId: string;
@@ -777,4 +1598,2390 @@ declare class BuiltInProvider implements AuthProviderAdapter {
     listDevices(accessToken: string): Promise<AuthDevice[]>;
 }
 
-export { type AuthDevice, type AuthProviderAdapter, AuthProviderError, type AuthRouteResponse, type AuthRoutesConfig, type AuthUser, BuiltInAuthRoutes, BuiltInProvider, DuplicateEmailError, InMemoryUserStore, type SignInParams, type SignUpParams, type StoredUser, TokenManager, type TokenManagerConfig, decodeJwt, encodeJwt, hashPassword, isExpired, verifyJwt, verifyPassword };
+/**
+ * Thrown when an operation is not supported by external auth providers.
+ *
+ * External providers delegate user management to the third-party service
+ * (Clerk, Auth0, Supabase, etc.). Operations like sign-up and sign-in must
+ * be performed through the external provider's SDK or UI, not through Kora.
+ */
+declare class ExternalAuthOperationNotSupportedError extends KoraError {
+    constructor(operation: string, provider: string);
+}
+/**
+ * Thrown when an external JWT token fails validation.
+ */
+declare class ExternalTokenValidationError extends KoraError {
+    constructor(reason: string, context?: Record<string, unknown>);
+}
+/**
+ * User information extracted from an external JWT token.
+ * Returned by the claims mapping function.
+ */
+interface ExternalUserInfo {
+    /** Unique user identifier from the external provider */
+    userId: string;
+    /** User's email address, if available in the token claims */
+    email?: string;
+    /** User's display name, if available in the token claims */
+    name?: string;
+    /** Additional metadata from the token claims */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for the external JWT authentication provider.
+ *
+ * Supports two validation modes:
+ * 1. **HMAC secret** (`jwtSecret`): For providers that sign tokens with a shared
+ *    secret (e.g., Supabase). Uses HS256 verification via the existing `verifyJwt` utility.
+ * 2. **Custom validator** (`validateToken`): For providers that use asymmetric keys
+ *    (RS256, ES256) or require custom validation logic (e.g., Clerk with JWKS rotation).
+ *    The developer provides their own validation function.
+ *
+ * At least one of `jwtSecret` or `validateToken` must be provided.
+ *
+ * @example
+ * ```typescript
+ * // With a shared secret (e.g., Supabase)
+ * const provider = new ExternalJwtProvider({
+ *   providerName: 'supabase',
+ *   jwtSecret: process.env.SUPABASE_JWT_SECRET,
+ * })
+ *
+ * // With a custom validator (e.g., Clerk JWKS)
+ * const provider = new ExternalJwtProvider({
+ *   providerName: 'clerk',
+ *   validateToken: async (token) => {
+ *     const claims = await clerkClient.verifyToken(token)
+ *     return claims ? { sub: claims.sub, ...claims } : null
+ *   },
+ * })
+ * ```
+ */
+interface ExternalJwtProviderConfig {
+    /**
+     * Human-readable name of the external auth provider.
+     * Used in error messages and DevTools for identification.
+     * @example 'clerk', 'auth0', 'supabase', 'firebase'
+     */
+    providerName: string;
+    /**
+     * Shared secret for HS256 JWT verification.
+     * Used when the external provider signs tokens with HMAC-SHA256.
+     * Mutually exclusive with `validateToken` (if both are provided,
+     * `validateToken` takes precedence).
+     */
+    jwtSecret?: string;
+    /**
+     * Custom token validator function.
+     * When provided, this is used instead of HS256 HMAC verification.
+     * Receives the raw JWT string and must return the decoded claims
+     * (with at least a `sub` field) or null if the token is invalid.
+     *
+     * Use this for providers that use asymmetric signing (RS256, ES256)
+     * or require JWKS-based key rotation.
+     *
+     * @param token - The raw JWT string to validate
+     * @returns The decoded claims object with at least a `sub` field, or null if invalid
+     */
+    validateToken?: (token: string) => Promise<{
+        sub: string;
+        [key: string]: unknown;
+    } | null>;
+    /**
+     * Map external JWT claims to Kora's expected user format.
+     *
+     * The default mapping extracts:
+     * - `sub` -> `userId` (required)
+     * - `email` -> `email` (optional)
+     * - `name` -> `name` (optional)
+     *
+     * Override this to extract custom claims from your provider's tokens.
+     *
+     * @param claims - The decoded JWT claims object
+     * @returns Kora-compatible user information
+     *
+     * @example
+     * ```typescript
+     * mapClaims: (claims) => ({
+     *   userId: claims.sub as string,
+     *   email: claims.email_address as string,
+     *   name: `${claims.first_name} ${claims.last_name}`,
+     *   metadata: { org: claims.org_id },
+     * })
+     * ```
+     */
+    mapClaims?: (claims: Record<string, unknown>) => ExternalUserInfo;
+}
+/**
+ * Authentication provider adapter for external JWT issuers.
+ *
+ * This adapter validates JWTs issued by third-party auth services (Clerk, Auth0,
+ * Supabase, Firebase, or any custom JWT issuer) and maps their claims to Kora's
+ * internal auth context. It bridges external identity providers with Kora's
+ * sync authentication layer.
+ *
+ * **How it works:**
+ * 1. The client authenticates with the external provider and receives a JWT
+ * 2. The client passes this JWT to Kora's sync server
+ * 3. This adapter validates the JWT and extracts user identity
+ * 4. Kora uses the extracted identity for sync authorization
+ *
+ * **What it does NOT do:**
+ * - Sign up or sign in users (that happens through the external provider)
+ * - Issue or refresh tokens (that is the external provider's responsibility)
+ * - Manage devices (external providers handle their own device tracking)
+ *
+ * @example
+ * ```typescript
+ * import { ExternalJwtProvider } from '@korajs/auth/server'
+ *
+ * const auth = new ExternalJwtProvider({
+ *   providerName: 'clerk',
+ *   validateToken: async (token) => {
+ *     // Use Clerk's SDK or JWKS endpoint to verify
+ *     return verifiedClaims
+ *   },
+ * })
+ *
+ * // Use with Kora sync server
+ * const result = await auth.validateAccessToken('eyJhbG...')
+ * if (result) {
+ *   console.log('User:', result.userId)
+ * }
+ * ```
+ */
+declare class ExternalJwtProvider implements AuthProviderAdapter {
+    private readonly providerName;
+    private readonly jwtSecret;
+    private readonly customValidateToken;
+    private readonly mapClaims;
+    constructor(config: ExternalJwtProviderConfig);
+    /**
+     * Not supported for external providers.
+     *
+     * User registration must be performed through the external auth provider's
+     * SDK or UI. Kora does not manage user accounts for external providers.
+     *
+     * @throws {ExternalAuthOperationNotSupportedError} Always
+     */
+    signUp(_params: SignUpParams): Promise<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>;
+    /**
+     * Not supported for external providers.
+     *
+     * User authentication must be performed through the external auth provider's
+     * SDK or UI. Kora does not manage credentials for external providers.
+     *
+     * @throws {ExternalAuthOperationNotSupportedError} Always
+     */
+    signIn(_params: SignInParams): Promise<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>;
+    /**
+     * Not supported for external providers.
+     *
+     * Token refresh must be performed through the external auth provider's SDK.
+     * Kora does not manage token lifecycle for external providers.
+     *
+     * @throws {ExternalAuthOperationNotSupportedError} Always
+     */
+    refreshTokens(_refreshToken: string): Promise<AuthTokens>;
+    /**
+     * Validate an access token from the external auth provider.
+     *
+     * Uses either the custom `validateToken` function or HS256 HMAC verification
+     * (depending on configuration) to validate the JWT. On success, maps the claims
+     * to Kora's expected format and returns the user ID and device ID.
+     *
+     * The device ID for external providers is derived from the user ID with a
+     * "external-" prefix, since external providers typically don't use Kora's
+     * device identity system.
+     *
+     * @param token - The JWT access token issued by the external provider
+     * @returns User ID and device ID if the token is valid, or null if invalid/expired
+     */
+    validateAccessToken(token: string): Promise<{
+        userId: string;
+        deviceId: string;
+    } | null>;
+    /**
+     * Not supported for external providers.
+     *
+     * User lookup must be performed through the external auth provider's API.
+     *
+     * @throws {ExternalAuthOperationNotSupportedError} Always
+     */
+    getUser(_userId: string): Promise<AuthUser | null>;
+    /**
+     * Not supported for external providers.
+     *
+     * Device revocation must be managed through the external auth provider
+     * or by revoking the user's tokens at the provider level.
+     *
+     * @throws {ExternalAuthOperationNotSupportedError} Always
+     */
+    revokeDevice(_accessToken: string, _deviceId: string): Promise<void>;
+    /**
+     * Not supported for external providers.
+     *
+     * Device listing must be performed through the external auth provider's API.
+     *
+     * @throws {ExternalAuthOperationNotSupportedError} Always
+     */
+    listDevices(_accessToken: string): Promise<AuthDevice[]>;
+    /**
+     * Creates a sync server auth provider compatible with `@korajs/server`.
+     *
+     * Returns an object with an `authenticate` method that validates the external
+     * JWT and returns a Kora-compatible auth context. Use this to wire the external
+     * auth provider into KoraSyncServer.
+     *
+     * @returns An object with an `authenticate` method for KoraSyncServer's `auth` config
+     *
+     * @example
+     * ```typescript
+     * const externalAuth = new ExternalJwtProvider({ ... })
+     * const syncServer = new KoraSyncServer({
+     *   store,
+     *   auth: externalAuth.toSyncAuthProvider(),
+     * })
+     * ```
+     */
+    toSyncAuthProvider(): {
+        authenticate(token: string): Promise<{
+            userId: string;
+            scopes?: Record<string, Record<string, unknown>>;
+            metadata?: Record<string, unknown>;
+        } | null>;
+    };
+    /**
+     * Extract and validate claims from a JWT token.
+     *
+     * Uses the custom validator if configured, otherwise falls back to
+     * HS256 HMAC verification with the configured secret.
+     *
+     * @param token - The raw JWT string
+     * @returns The decoded claims object, or null if the token is invalid
+     */
+    private extractClaims;
+}
+
+/**
+ * Configuration for the Clerk authentication adapter.
+ *
+ * Clerk uses asymmetric signing (RS256) with JWKS key rotation, so this adapter
+ * requires a custom `validateToken` function that handles JWKS-based verification.
+ * The adapter provides sensible defaults for mapping Clerk's JWT claims to Kora's
+ * expected format.
+ *
+ * Clerk JWTs typically contain:
+ * - `sub`: User ID (e.g., "user_2abc123...")
+ * - `email`: Primary email address (if configured in session claims)
+ * - `first_name`, `last_name`: Name fields (if configured in session claims)
+ * - `azp`: Authorized party (your frontend origin)
+ * - `org_id`, `org_slug`, `org_role`: Organization claims (if using Clerk orgs)
+ *
+ * @example
+ * ```typescript
+ * import { createClerkAdapter } from '@korajs/auth/server'
+ *
+ * const clerkAuth = createClerkAdapter({
+ *   validateToken: async (token) => {
+ *     // Use Clerk's backend SDK or your own JWKS verification
+ *     const result = await clerkClient.verifyToken(token)
+ *     return result ? { sub: result.sub, ...result } : null
+ *   },
+ * })
+ *
+ * // Use with Kora sync server
+ * const syncServer = new KoraSyncServer({
+ *   store,
+ *   auth: clerkAuth.toSyncAuthProvider(),
+ * })
+ * ```
+ */
+interface ClerkAdapterConfig {
+    /**
+     * Custom token validator for Clerk JWTs.
+     *
+     * Clerk uses RS256 signing with JWKS key rotation, which requires either
+     * Clerk's backend SDK or a JWKS-based verifier. This function receives
+     * the raw JWT and should return the decoded claims or null.
+     *
+     * @param token - The raw JWT string from the Clerk session
+     * @returns Decoded claims with at least a `sub` field, or null if invalid
+     */
+    validateToken: (token: string) => Promise<{
+        sub: string;
+        [key: string]: unknown;
+    } | null>;
+    /**
+     * Custom claim mapping override.
+     *
+     * By default, the Clerk adapter maps:
+     * - `sub` -> `userId`
+     * - `email` -> `email` (if present)
+     * - `first_name` + `last_name` -> `name` (concatenated, if present)
+     * - `org_id`, `org_slug`, `org_role` -> `metadata` (if present)
+     *
+     * Override this to customize how Clerk claims are mapped to Kora's format.
+     */
+    mapClaims?: ExternalJwtProviderConfig['mapClaims'];
+}
+/**
+ * Creates an ExternalJwtProvider configured for Clerk authentication.
+ *
+ * Clerk uses RS256 signing with JWKS key rotation, so a custom `validateToken`
+ * function must be provided. This function should use Clerk's backend SDK or
+ * a JWKS-based JWT verifier to validate tokens.
+ *
+ * This adapter does NOT depend on `@clerk/backend` or any Clerk SDK. It only
+ * provides sensible defaults for mapping Clerk's JWT claims to Kora's format.
+ * The actual token verification is delegated to the provided `validateToken` function.
+ *
+ * @param config - Clerk adapter configuration
+ * @returns An ExternalJwtProvider instance configured for Clerk
+ *
+ * @example
+ * ```typescript
+ * import { createClerkAdapter } from '@korajs/auth/server'
+ *
+ * const clerkAuth = createClerkAdapter({
+ *   validateToken: async (token) => {
+ *     // Your JWKS verification logic here
+ *     const payload = await verifyWithJwks(token, CLERK_JWKS_URL)
+ *     return payload
+ *   },
+ * })
+ *
+ * const result = await clerkAuth.validateAccessToken(sessionToken)
+ * ```
+ */
+declare function createClerkAdapter(config: ClerkAdapterConfig): ExternalJwtProvider;
+
+/**
+ * Configuration for the Supabase authentication adapter.
+ *
+ * Supabase Auth signs JWTs with HS256 using the project's JWT secret,
+ * which is available in your Supabase project settings under
+ * Settings -> API -> JWT Secret.
+ *
+ * Supabase JWTs typically contain:
+ * - `sub`: User UUID
+ * - `email`: User's email address
+ * - `role`: The database role (e.g., "authenticated", "anon")
+ * - `aud`: Audience (usually "authenticated")
+ * - `app_metadata`: Provider info, roles, etc.
+ * - `user_metadata`: Custom user data (name, avatar, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { createSupabaseAdapter } from '@korajs/auth/server'
+ *
+ * const supabaseAuth = createSupabaseAdapter({
+ *   jwtSecret: process.env.SUPABASE_JWT_SECRET,
+ * })
+ *
+ * // Use with Kora sync server
+ * const syncServer = new KoraSyncServer({
+ *   store,
+ *   auth: supabaseAuth.toSyncAuthProvider(),
+ * })
+ * ```
+ */
+interface SupabaseAdapterConfig {
+    /**
+     * Supabase JWT secret from your project settings.
+     *
+     * Found in: Supabase Dashboard -> Settings -> API -> JWT Secret
+     *
+     * This is the HS256 HMAC secret used to sign and verify Supabase Auth JWTs.
+     * Keep this secret secure and never expose it in client-side code.
+     */
+    jwtSecret: string;
+    /**
+     * Custom claim mapping override.
+     *
+     * By default, the Supabase adapter maps:
+     * - `sub` -> `userId`
+     * - `email` -> `email`
+     * - `user_metadata.full_name` or `user_metadata.name` -> `name`
+     * - `role`, `aud`, `app_metadata` -> `metadata`
+     *
+     * Override this to customize how Supabase claims are mapped to Kora's format.
+     */
+    mapClaims?: ExternalJwtProviderConfig['mapClaims'];
+}
+/**
+ * Creates an ExternalJwtProvider configured for Supabase Auth.
+ *
+ * Supabase Auth uses HS256 signing with the project's JWT secret, making it
+ * compatible with Kora's built-in `verifyJwt` utility. No external SDK is needed.
+ *
+ * This adapter validates the JWT signature and expiration, then maps Supabase's
+ * standard claims (sub, email, role, user_metadata) to Kora's auth context format.
+ *
+ * @param config - Supabase adapter configuration
+ * @returns An ExternalJwtProvider instance configured for Supabase
+ *
+ * @example
+ * ```typescript
+ * import { createSupabaseAdapter } from '@korajs/auth/server'
+ *
+ * const supabaseAuth = createSupabaseAdapter({
+ *   jwtSecret: process.env.SUPABASE_JWT_SECRET,
+ * })
+ *
+ * // Validate a Supabase access token
+ * const result = await supabaseAuth.validateAccessToken(supabaseAccessToken)
+ * if (result) {
+ *   console.log('Supabase user:', result.userId)
+ * }
+ *
+ * // Or use with the sync server
+ * const syncServer = new KoraSyncServer({
+ *   store,
+ *   auth: supabaseAuth.toSyncAuthProvider(),
+ * })
+ * ```
+ */
+declare function createSupabaseAdapter(config: SupabaseAdapterConfig): ExternalJwtProvider;
+
+/**
+ * Thrown when server-side passkey verification fails.
+ */
+declare class PasskeyVerificationError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/** Options returned by generateRegistrationOptions for the client. */
+interface RegistrationOptions {
+    /** Base64url-encoded random challenge (32 bytes) */
+    challenge: string;
+    /** Relying party ID (domain) */
+    rpId: string;
+    /** Relying party display name */
+    rpName: string;
+    /** Base64url-encoded user ID */
+    userId: string;
+    /** User's email or username */
+    userName: string;
+    /** Human-readable display name */
+    userDisplayName: string;
+    /** Credential IDs to exclude (prevents re-registration) */
+    excludeCredentialIds: string[];
+    /** Authenticator selection criteria */
+    authenticatorSelection: {
+        authenticatorAttachment: 'platform';
+        residentKey: 'preferred';
+        userVerification: 'required';
+    };
+    /** Timeout in milliseconds */
+    timeout: number;
+}
+/**
+ * Generate registration options for creating a new passkey.
+ *
+ * Creates a cryptographically random challenge and assembles the options
+ * object that should be sent to the client for `createPasskeyCredential()`.
+ *
+ * The server must store the challenge (keyed by user session or similar)
+ * for later verification when the client responds.
+ *
+ * @param params - Registration parameters
+ * @param params.rpId - Relying party ID (your domain, e.g. "example.com")
+ * @param params.rpName - Relying party display name
+ * @param params.userId - Unique user identifier
+ * @param params.userName - User's email or username
+ * @param params.userDisplayName - Human-readable display name
+ * @param params.existingCredentialIds - Base64url credential IDs to exclude
+ * @returns Registration options to send to the client, including the challenge
+ *
+ * @example
+ * ```typescript
+ * const options = generateRegistrationOptions({
+ *   rpId: 'example.com',
+ *   rpName: 'My App',
+ *   userId: user.id,
+ *   userName: user.email,
+ *   userDisplayName: user.name,
+ * })
+ * // Store options.challenge in session for later verification
+ * // Send options to client
+ * ```
+ */
+declare function generateRegistrationOptions(params: {
+    rpId: string;
+    rpName: string;
+    userId: string;
+    userName: string;
+    userDisplayName: string;
+    existingCredentialIds?: string[];
+}): RegistrationOptions;
+/** Result of verifying a registration response. */
+interface RegistrationVerificationResult {
+    /** Whether the registration response was verified successfully */
+    verified: boolean;
+    /** Base64url-encoded credential ID */
+    credentialId: string;
+    /** Base64url-encoded COSE public key (store this for future authentication) */
+    publicKey: string;
+    /** Initial signature counter from the authenticator */
+    signCount: number;
+}
+/**
+ * Verify a registration response from the client.
+ *
+ * Validates the attestation object and clientDataJSON returned by the browser's
+ * `navigator.credentials.create()` call. Extracts and returns the public key
+ * and credential ID to store in your database.
+ *
+ * This implementation supports the "none" attestation format, which is the most
+ * common and does not require trust in any attestation CA. For higher assurance
+ * scenarios, extend this to verify packed/tpm/android attestation formats.
+ *
+ * @param params - Verification parameters
+ * @param params.credential - The credential response from the client
+ * @param params.expectedChallenge - The challenge that was sent to the client (base64url)
+ * @param params.expectedOrigin - The expected origin (e.g. "https://example.com")
+ * @param params.expectedRpId - The expected relying party ID (e.g. "example.com")
+ * @returns Verification result with the credential ID and public key to store
+ * @throws {PasskeyVerificationError} If the response is invalid or tampered with
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyRegistrationResponse({
+ *   credential: clientResponse,
+ *   expectedChallenge: storedChallenge,
+ *   expectedOrigin: 'https://example.com',
+ *   expectedRpId: 'example.com',
+ * })
+ * if (result.verified) {
+ *   // Store result.credentialId, result.publicKey, result.signCount
+ * }
+ * ```
+ */
+declare function verifyRegistrationResponse(params: {
+    credential: {
+        credentialId: string;
+        publicKey: string;
+        clientDataJSON: string;
+        attestationObject: string;
+    };
+    expectedChallenge: string;
+    expectedOrigin: string;
+    expectedRpId: string;
+}): Promise<RegistrationVerificationResult>;
+/** Options returned by generateAuthenticationOptions for the client. */
+interface AuthenticationOptions {
+    /** Base64url-encoded random challenge (32 bytes) */
+    challenge: string;
+    /** Relying party ID */
+    rpId: string;
+    /** Credential IDs to allow (limit to specific credentials) */
+    allowCredentialIds?: string[];
+    /** User verification requirement */
+    userVerification: 'preferred';
+    /** Timeout in milliseconds */
+    timeout: number;
+}
+/**
+ * Generate authentication options for signing in with a passkey.
+ *
+ * Creates a cryptographically random challenge and assembles the options
+ * object that should be sent to the client for `authenticateWithPasskey()`.
+ *
+ * The server must store the challenge for later verification.
+ *
+ * @param params - Authentication parameters
+ * @param params.rpId - Relying party ID (your domain)
+ * @param params.allowCredentialIds - Base64url credential IDs to allow (optional)
+ * @returns Authentication options to send to the client
+ *
+ * @example
+ * ```typescript
+ * const options = generateAuthenticationOptions({
+ *   rpId: 'example.com',
+ *   allowCredentialIds: user.credentialIds,
+ * })
+ * // Store options.challenge in session
+ * // Send options to client
+ * ```
+ */
+declare function generateAuthenticationOptions(params: {
+    rpId: string;
+    allowCredentialIds?: string[];
+}): AuthenticationOptions;
+/** Result of verifying an authentication response. */
+interface AuthenticationVerificationResult {
+    /** Whether the authentication response was verified successfully */
+    verified: boolean;
+    /** Updated signature counter (store this to detect cloned authenticators) */
+    newSignCount: number;
+}
+/**
+ * Verify an authentication response from the client.
+ *
+ * Validates the signed assertion returned by the browser's
+ * `navigator.credentials.get()` call. Checks the signature against the
+ * stored public key, verifies the challenge and origin, and validates
+ * the signature counter to detect cloned authenticators.
+ *
+ * This implementation supports ECDSA P-256 (ES256, COSE algorithm -7)
+ * signatures, which is the most common algorithm used by platform
+ * authenticators (Touch ID, Face ID, Windows Hello).
+ *
+ * @param params - Verification parameters
+ * @param params.assertion - The assertion response from the client
+ * @param params.expectedChallenge - The challenge that was sent to the client (base64url)
+ * @param params.expectedOrigin - The expected origin (e.g. "https://example.com")
+ * @param params.expectedRpId - The expected relying party ID
+ * @param params.publicKey - The stored COSE public key (base64url, from registration)
+ * @param params.previousSignCount - The previously stored signature counter
+ * @returns Verification result with the new signature counter
+ * @throws {PasskeyVerificationError} If the assertion is invalid
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyAuthenticationResponse({
+ *   assertion: clientAssertion,
+ *   expectedChallenge: storedChallenge,
+ *   expectedOrigin: 'https://example.com',
+ *   expectedRpId: 'example.com',
+ *   publicKey: storedCredential.publicKey,
+ *   previousSignCount: storedCredential.signCount,
+ * })
+ * if (result.verified) {
+ *   // Update stored sign count: storedCredential.signCount = result.newSignCount
+ *   // Issue session tokens
+ * }
+ * ```
+ */
+declare function verifyAuthenticationResponse(params: {
+    assertion: {
+        credentialId: string;
+        authenticatorData: string;
+        clientDataJSON: string;
+        signature: string;
+        userHandle: string | null;
+    };
+    expectedChallenge: string;
+    expectedOrigin: string;
+    expectedRpId: string;
+    publicKey: string;
+    previousSignCount: number;
+}): Promise<AuthenticationVerificationResult>;
+
+/**
+ * An organization (workspace/team) that groups users together.
+ *
+ * Organizations are the fundamental unit of multi-tenancy in Kora.
+ * Data is scoped to organizations, and users access data through
+ * their organization memberships and roles.
+ */
+interface Organization {
+    /** Unique identifier (UUID v7) */
+    id: string;
+    /** Display name of the organization */
+    name: string;
+    /** URL-friendly identifier (unique, lowercase, alphanumeric + hyphens) */
+    slug: string;
+    /** User ID of the organization owner */
+    ownerId: string;
+    /** When the organization was created (ms since epoch) */
+    createdAt: number;
+    /** When the organization was last updated (ms since epoch) */
+    updatedAt: number;
+    /** Arbitrary metadata (plan, billing info, settings, etc.) */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Parameters for creating a new organization.
+ */
+interface CreateOrgParams {
+    /** Display name */
+    name: string;
+    /** URL-friendly slug (auto-generated from name if omitted) */
+    slug?: string;
+    /** Optional metadata to attach */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for updating an existing organization.
+ */
+interface UpdateOrgParams {
+    /** New display name */
+    name?: string;
+    /** New slug */
+    slug?: string;
+    /** Metadata to merge (shallow merge) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Built-in organization roles, ordered by decreasing privilege.
+ *
+ * - **owner**: Full control, can delete org, transfer ownership, manage billing
+ * - **admin**: Manage members and settings, full data access
+ * - **member**: Read + write own data, read shared data
+ * - **viewer**: Read-only access to shared data
+ * - **billing**: Billing management only, no data access
+ */
+declare const ORG_ROLES: readonly ["owner", "admin", "member", "viewer", "billing"];
+type OrgRole = (typeof ORG_ROLES)[number];
+/**
+ * Role hierarchy for permission inheritance.
+ * Higher number = more privilege.
+ */
+declare const ROLE_HIERARCHY: Record<OrgRole, number>;
+/**
+ * Check if one role has at least the privilege level of another.
+ *
+ * @param userRole - The user's current role
+ * @param requiredRole - The minimum role required
+ * @returns true if userRole >= requiredRole in the hierarchy
+ */
+declare function hasRoleLevel(userRole: OrgRole, requiredRole: OrgRole): boolean;
+/**
+ * A user's membership in an organization.
+ */
+interface Membership {
+    /** Unique identifier for this membership record */
+    id: string;
+    /** Organization this membership belongs to */
+    orgId: string;
+    /** User who is a member */
+    userId: string;
+    /** Role within the organization */
+    role: OrgRole;
+    /** User who invited this member (null if founder) */
+    invitedBy: string | null;
+    /** When the user joined the organization (ms since epoch) */
+    joinedAt: number;
+    /** Arbitrary metadata (department, title, etc.) */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Invitation status lifecycle.
+ */
+declare const INVITATION_STATUSES: readonly ["pending", "accepted", "revoked", "expired"];
+type InvitationStatus = (typeof INVITATION_STATUSES)[number];
+/**
+ * An invitation to join an organization.
+ *
+ * Invitations are sent by email and include a single-use token.
+ * They expire after a configurable duration (default: 7 days).
+ */
+interface OrgInvitation {
+    /** Unique identifier */
+    id: string;
+    /** Organization the invitation is for */
+    orgId: string;
+    /** Email address of the invitee */
+    email: string;
+    /** Role the invitee will receive upon accepting */
+    role: OrgRole;
+    /** User who created the invitation */
+    invitedBy: string;
+    /** Cryptographically random single-use token */
+    token: string;
+    /** When the invitation was created (ms since epoch) */
+    createdAt: number;
+    /** When the invitation expires (ms since epoch) */
+    expiresAt: number;
+    /** Current status */
+    status: InvitationStatus;
+}
+/**
+ * Parameters for creating an invitation.
+ */
+interface CreateInvitationParams {
+    /** Email address to invite */
+    email: string;
+    /** Role to assign when the invitation is accepted */
+    role: OrgRole;
+}
+/**
+ * Base error for organization-related operations.
+ */
+declare class OrgError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class OrgNotFoundError extends OrgError {
+    constructor();
+}
+declare class OrgSlugTakenError extends OrgError {
+    constructor();
+}
+declare class MembershipNotFoundError extends OrgError {
+    constructor();
+}
+declare class MemberAlreadyExistsError extends OrgError {
+    constructor();
+}
+declare class InsufficientRoleError extends OrgError {
+    constructor(required: OrgRole);
+}
+declare class CannotRemoveOwnerError extends OrgError {
+    constructor();
+}
+declare class InvitationNotFoundError extends OrgError {
+    constructor();
+}
+declare class InvitationExpiredError extends OrgError {
+    constructor();
+}
+
+/**
+ * Persistence interface for organizations, memberships, and invitations.
+ *
+ * Implement this interface to back organizations with any storage:
+ * - `InMemoryOrgStore` for development and testing
+ * - PostgreSQL/MySQL via Drizzle for production
+ * - SQLite for self-hosted or embedded scenarios
+ *
+ * All methods are async to support any storage backend.
+ */
+interface OrgStore {
+    /** Create a new organization. The caller becomes the owner. */
+    createOrg(ownerId: string, params: CreateOrgParams): Promise<Organization>;
+    /** Get an organization by ID. Returns null if not found. */
+    getOrg(orgId: string): Promise<Organization | null>;
+    /** Get an organization by slug. Returns null if not found. */
+    getOrgBySlug(slug: string): Promise<Organization | null>;
+    /** Update an organization's mutable fields. */
+    updateOrg(orgId: string, params: UpdateOrgParams): Promise<Organization>;
+    /** Delete an organization and all its memberships and invitations. */
+    deleteOrg(orgId: string): Promise<void>;
+    /** List all organizations a user is a member of. */
+    listUserOrgs(userId: string): Promise<Organization[]>;
+    /** Add a user as a member of an organization. */
+    addMember(orgId: string, userId: string, role: OrgRole, invitedBy: string | null): Promise<Membership>;
+    /** Remove a user from an organization. Cannot remove the owner. */
+    removeMember(orgId: string, userId: string): Promise<void>;
+    /** Update a member's role within an organization. */
+    updateMemberRole(orgId: string, userId: string, role: OrgRole): Promise<Membership>;
+    /** List all members of an organization. */
+    listMembers(orgId: string): Promise<Membership[]>;
+    /** Get a specific user's membership in an organization. Returns null if not a member. */
+    getMembership(orgId: string, userId: string): Promise<Membership | null>;
+    /** Transfer ownership of an organization to another member. */
+    transferOwnership(orgId: string, newOwnerId: string): Promise<void>;
+    /** Create an invitation to join an organization. */
+    createInvitation(orgId: string, invitedBy: string, params: CreateInvitationParams): Promise<OrgInvitation>;
+    /** Look up an invitation by its single-use token. Returns null if not found or already consumed. */
+    getInvitationByToken(token: string): Promise<OrgInvitation | null>;
+    /** Consume an invitation (mark as accepted). Returns the invitation details. */
+    consumeInvitation(token: string): Promise<OrgInvitation>;
+    /** Revoke a pending invitation. */
+    revokeInvitation(invitationId: string): Promise<void>;
+    /** List pending invitations for an organization. */
+    listPendingInvitations(orgId: string): Promise<OrgInvitation[]>;
+    /** List pending invitations for a specific email address. */
+    listInvitationsForEmail(email: string): Promise<OrgInvitation[]>;
+    /** Remove expired invitations. Returns count of removed invitations. */
+    cleanExpiredInvitations(): Promise<number>;
+}
+/**
+ * In-memory implementation of OrgStore for development and testing.
+ *
+ * Data is lost when the process exits. For production, implement OrgStore
+ * with a persistent backend (PostgreSQL, MySQL, SQLite via Drizzle).
+ *
+ * @example
+ * ```typescript
+ * const orgStore = new InMemoryOrgStore()
+ * const org = await orgStore.createOrg('user-1', { name: 'Acme Inc', slug: 'acme' })
+ * ```
+ */
+declare class InMemoryOrgStore implements OrgStore {
+    private orgs;
+    private memberships;
+    private invitations;
+    createOrg(ownerId: string, params: CreateOrgParams): Promise<Organization>;
+    getOrg(orgId: string): Promise<Organization | null>;
+    getOrgBySlug(slug: string): Promise<Organization | null>;
+    updateOrg(orgId: string, params: UpdateOrgParams): Promise<Organization>;
+    deleteOrg(orgId: string): Promise<void>;
+    listUserOrgs(userId: string): Promise<Organization[]>;
+    addMember(orgId: string, userId: string, role: OrgRole, invitedBy: string | null): Promise<Membership>;
+    removeMember(orgId: string, userId: string): Promise<void>;
+    updateMemberRole(orgId: string, userId: string, role: OrgRole): Promise<Membership>;
+    listMembers(orgId: string): Promise<Membership[]>;
+    getMembership(orgId: string, userId: string): Promise<Membership | null>;
+    transferOwnership(orgId: string, newOwnerId: string): Promise<void>;
+    createInvitation(orgId: string, invitedBy: string, params: CreateInvitationParams): Promise<OrgInvitation>;
+    getInvitationByToken(token: string): Promise<OrgInvitation | null>;
+    consumeInvitation(token: string): Promise<OrgInvitation>;
+    revokeInvitation(invitationId: string): Promise<void>;
+    listPendingInvitations(orgId: string): Promise<OrgInvitation[]>;
+    listInvitationsForEmail(email: string): Promise<OrgInvitation[]>;
+    cleanExpiredInvitations(): Promise<number>;
+}
+
+/**
+ * Response envelope returned by all org route handlers.
+ * Mirrors AuthRouteResponse for consistency.
+ */
+interface OrgRouteResponse<T> {
+    /** HTTP status code */
+    status: number;
+    /** Either the success payload or an error message */
+    body: {
+        data: T;
+    } | {
+        error: string;
+    };
+}
+/**
+ * Configuration for the org route handlers.
+ */
+interface OrgRoutesConfig {
+    /** The organization store backing all org operations */
+    orgStore: OrgStore;
+}
+/**
+ * Server-side route handlers for organization management.
+ *
+ * These handlers enforce authorization (role checks), input validation,
+ * and produce transport-agnostic response objects. Wire them to your
+ * HTTP framework (Express, Hono, Fastify, etc.):
+ *
+ * @example
+ * ```typescript
+ * const orgRoutes = new OrgRoutes({ orgStore: new InMemoryOrgStore() })
+ *
+ * app.post('/orgs', async (req, res) => {
+ *   const result = await orgRoutes.createOrg(req.userId, req.body)
+ *   res.status(result.status).json(result.body)
+ * })
+ * ```
+ */
+declare class OrgRoutes {
+    private readonly store;
+    constructor(config: OrgRoutesConfig);
+    /**
+     * Create a new organization. The authenticated user becomes the owner.
+     */
+    createOrg(userId: string, params: {
+        name?: unknown;
+        slug?: unknown;
+        metadata?: unknown;
+    }): Promise<OrgRouteResponse<Organization>>;
+    /**
+     * Get an organization by ID. Requires membership.
+     */
+    getOrg(userId: string, orgId: string): Promise<OrgRouteResponse<Organization>>;
+    /**
+     * Update an organization. Requires admin or higher.
+     */
+    updateOrg(userId: string, orgId: string, params: {
+        name?: unknown;
+        slug?: unknown;
+        metadata?: unknown;
+    }): Promise<OrgRouteResponse<Organization>>;
+    /**
+     * Delete an organization. Requires owner.
+     */
+    deleteOrg(userId: string, orgId: string): Promise<OrgRouteResponse<{
+        deleted: true;
+    }>>;
+    /**
+     * List all organizations the authenticated user belongs to.
+     */
+    listUserOrgs(userId: string): Promise<OrgRouteResponse<Organization[]>>;
+    /**
+     * Add a member to an organization. Requires admin or higher.
+     */
+    addMember(userId: string, orgId: string, params: {
+        targetUserId?: unknown;
+        role?: unknown;
+    }): Promise<OrgRouteResponse<Membership>>;
+    /**
+     * Remove a member from an organization. Requires admin or higher.
+     * Members can also remove themselves (leave).
+     */
+    removeMember(userId: string, orgId: string, targetUserId: string): Promise<OrgRouteResponse<{
+        removed: true;
+    }>>;
+    /**
+     * Update a member's role. Requires admin or higher.
+     */
+    updateMemberRole(userId: string, orgId: string, params: {
+        targetUserId?: unknown;
+        role?: unknown;
+    }): Promise<OrgRouteResponse<Membership>>;
+    /**
+     * List all members of an organization. Requires membership.
+     */
+    listMembers(userId: string, orgId: string): Promise<OrgRouteResponse<Membership[]>>;
+    /**
+     * Transfer ownership to another member. Requires owner.
+     */
+    transferOwnership(userId: string, orgId: string, params: {
+        newOwnerId?: unknown;
+    }): Promise<OrgRouteResponse<{
+        transferred: true;
+    }>>;
+    /**
+     * Create an invitation to join the organization. Requires admin or higher.
+     */
+    createInvitation(userId: string, orgId: string, params: {
+        email?: unknown;
+        role?: unknown;
+    }): Promise<OrgRouteResponse<OrgInvitation>>;
+    /**
+     * Accept an invitation by its token. The authenticated user joins the org.
+     */
+    acceptInvitation(userId: string, params: {
+        token?: unknown;
+    }): Promise<OrgRouteResponse<Membership>>;
+    /**
+     * Revoke a pending invitation. Requires admin or higher.
+     */
+    revokeInvitation(userId: string, orgId: string, invitationId: string): Promise<OrgRouteResponse<{
+        revoked: true;
+    }>>;
+    /**
+     * List pending invitations for an organization. Requires admin or higher.
+     */
+    listPendingInvitations(userId: string, orgId: string): Promise<OrgRouteResponse<OrgInvitation[]>>;
+    /**
+     * List pending invitations for the authenticated user's email.
+     */
+    listMyInvitations(email: string): Promise<OrgRouteResponse<OrgInvitation[]>>;
+    /**
+     * Check if the caller has the required role in the org.
+     * Returns an error response if not authorized, or null if authorized.
+     */
+    private requireRole;
+}
+
+/**
+ * A permission is a `resource:action` string.
+ *
+ * Resources are typically collection names or system resources.
+ * Actions are the operations allowed on that resource.
+ *
+ * @example
+ * ```typescript
+ * const permission: Permission = 'todos:write'
+ * const adminPerm: Permission = 'org:manage-members'
+ * const wildcard: Permission = 'todos:*'  // all actions on todos
+ * const superAdmin: Permission = '*:*'     // all actions on all resources
+ * ```
+ */
+type Permission = `${string}:${string}`;
+/**
+ * Parse a permission string into its resource and action parts.
+ */
+declare function parsePermission(permission: Permission): {
+    resource: string;
+    action: string;
+};
+/**
+ * Check if a granted permission covers a required permission.
+ * Supports wildcards: `todos:*` covers `todos:read`, `*:*` covers everything.
+ */
+declare function permissionCovers(granted: Permission, required: Permission): boolean;
+/**
+ * A role definition describes a named set of permissions with optional inheritance.
+ *
+ * Roles form a hierarchy via `inherits`. When evaluating permissions,
+ * all inherited roles' permissions are included transitively.
+ *
+ * @example
+ * ```typescript
+ * const roles: RoleDefinition[] = [
+ *   { name: 'viewer', permissions: ['todos:read', 'projects:read'] },
+ *   { name: 'member', permissions: ['todos:write', 'projects:write'], inherits: ['viewer'] },
+ *   { name: 'admin', permissions: ['org:manage-members'], inherits: ['member'] },
+ * ]
+ * ```
+ */
+interface RoleDefinition {
+    /** Unique name for this role */
+    name: string;
+    /** Permissions directly granted to this role */
+    permissions: Permission[];
+    /** Roles this role inherits from (all their permissions are included) */
+    inherits?: string[];
+}
+/**
+ * Default built-in roles for organizations.
+ *
+ * These can be overridden or extended using `defineRoles()`.
+ */
+declare const BUILT_IN_ROLES: readonly RoleDefinition[];
+/**
+ * Configuration for the RBAC engine.
+ */
+interface RbacConfig {
+    /** Role definitions. Defaults to BUILT_IN_ROLES if not provided. */
+    roles?: RoleDefinition[];
+}
+/**
+ * A sync scope filter for a single collection.
+ * The keys are field names and values are the required values.
+ * A special `__readonly` key can be set to restrict to read-only access.
+ *
+ * @example
+ * ```typescript
+ * // Only sync todos belonging to the user within the org
+ * const scope: ScopeFilter = { orgId: 'org-123', userId: 'user-456' }
+ *
+ * // Read-only scope for viewers
+ * const readOnlyScope: ScopeFilter = { orgId: 'org-123', __readonly: true }
+ * ```
+ */
+interface ScopeFilter {
+    [field: string]: unknown;
+}
+/**
+ * A complete set of sync scopes, keyed by collection name.
+ *
+ * @example
+ * ```typescript
+ * const scopes: SyncScopes = {
+ *   todos: { orgId: 'org-123' },
+ *   projects: { orgId: 'org-123' },
+ * }
+ * ```
+ */
+type SyncScopes = Record<string, ScopeFilter>;
+/**
+ * Custom scope resolver for a specific collection.
+ * Given the user context, returns the scope filter for that collection.
+ */
+type CollectionScopeResolver = (ctx: ScopeContext) => ScopeFilter | null;
+/**
+ * Context passed to scope resolvers.
+ */
+interface ScopeContext {
+    userId: string;
+    orgId: string;
+    role: string;
+    permissions: Permission[];
+}
+declare class RbacError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class InvalidPermissionError extends RbacError {
+    constructor(permission: string);
+}
+declare class RoleNotFoundError extends RbacError {
+    constructor(role: string);
+}
+declare class CircularInheritanceError extends RbacError {
+    constructor(chain: string[]);
+}
+
+/**
+ * Permission evaluation engine for role-based access control.
+ *
+ * The engine resolves permissions through role inheritance, supports
+ * wildcard matching, and integrates with the OrgStore for membership lookups.
+ *
+ * @example
+ * ```typescript
+ * const rbac = new RbacEngine({ orgStore })
+ *
+ * // Check a permission
+ * const canWrite = await rbac.hasPermission('user-1', 'org-1', 'todos:write')
+ *
+ * // Get all permissions for a user in an org
+ * const perms = await rbac.getUserPermissions('user-1', 'org-1')
+ *
+ * // Resolve sync scopes
+ * const scopes = await rbac.resolveScopes('user-1', 'org-1')
+ * ```
+ */
+declare class RbacEngine {
+    private readonly orgStore;
+    private readonly roleMap;
+    private readonly resolvedPermissions;
+    private readonly collectionResolvers;
+    constructor(orgStore: OrgStore, config?: RbacConfig);
+    /**
+     * Check if a user has a specific permission in an organization.
+     *
+     * Resolves the user's role from the org membership, then evaluates
+     * the role's permissions (including inherited ones) against the required permission.
+     *
+     * Returns false (not an error) if the user is not a member.
+     */
+    hasPermission(userId: string, orgId: string, permission: Permission): Promise<boolean>;
+    /**
+     * Get all effective permissions for a user in an organization.
+     *
+     * Returns an empty array if the user is not a member.
+     */
+    getUserPermissions(userId: string, orgId: string): Promise<Permission[]>;
+    /**
+     * Get all effective permissions for a role name.
+     * Includes permissions from inherited roles.
+     *
+     * @throws {RoleNotFoundError} if the role is not defined
+     */
+    getRolePermissions(roleName: string): Permission[];
+    /**
+     * Check if a role has a specific permission.
+     */
+    roleHasPermission(roleName: string, permission: Permission): boolean;
+    /**
+     * Register a custom scope resolver for a collection.
+     *
+     * Custom resolvers override the default scope logic for that collection.
+     */
+    registerScopeResolver(collection: string, resolver: CollectionScopeResolver): void;
+    /**
+     * Resolve sync scopes for a user in an organization.
+     *
+     * The scopes determine what data the user can see and modify during sync.
+     * - Owner/Admin: all org data
+     * - Member: all org data (read + write)
+     * - Viewer: all org data (read-only)
+     * - Billing: no data scopes (billing-only access)
+     *
+     * Custom collection resolvers can override the defaults.
+     *
+     * @param collections - List of collection names to resolve scopes for.
+     *                      If not provided, only custom-registered collections are included.
+     */
+    resolveScopes(userId: string, orgId: string, collections?: string[]): Promise<SyncScopes | null>;
+    /**
+     * Get all defined role names.
+     */
+    getRoleNames(): string[];
+    /**
+     * Get a role definition by name.
+     */
+    getRoleDefinition(roleName: string): RoleDefinition | null;
+    /**
+     * Validate all role definitions for circular inheritance and unknown references.
+     */
+    private validateRoles;
+    /**
+     * Detect circular inheritance in role hierarchy.
+     */
+    private detectCircularInheritance;
+    /**
+     * Recursively resolve all permissions for a role, including inherited permissions.
+     */
+    private resolvePermissionsForRole;
+}
+/**
+ * Builder for defining custom roles.
+ *
+ * @example
+ * ```typescript
+ * const roles = defineRoles()
+ *   .role('viewer', ['*:read'])
+ *   .role('editor', ['*:write'], { inherits: ['viewer'] })
+ *   .role('admin', ['org:manage-members'], { inherits: ['editor'] })
+ *   .build()
+ * ```
+ */
+declare function defineRoles(): RoleBuilder;
+declare class RoleBuilder {
+    private roles;
+    /**
+     * Add a role definition.
+     */
+    role(name: string, permissions: Permission[], options?: {
+        inherits?: string[];
+    }): RoleBuilder;
+    /**
+     * Include the built-in roles as a base.
+     */
+    withBuiltInRoles(): RoleBuilder;
+    /**
+     * Build and return the role definitions array.
+     */
+    build(): RoleDefinition[];
+}
+
+/**
+ * Resolves sync scopes for org-aware data filtering.
+ *
+ * Given a user, an organization, and a set of collections, this resolver
+ * determines what data the user should receive during sync:
+ *
+ * - **Owner/Admin**: All data in the org (no field-level filtering)
+ * - **Member**: All org data with read/write access
+ * - **Viewer**: All org data with read-only flag
+ * - **Billing**: No data access (empty scopes)
+ *
+ * Developers can register per-collection scope resolvers for fine-grained control.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new OrgScopeResolver(orgStore, rbacEngine)
+ *
+ * // Custom scope: members only see their own todos
+ * resolver.registerCollectionScope('todos', (ctx) => {
+ *   if (ctx.role === 'member') {
+ *     return { orgId: ctx.orgId, userId: ctx.userId }
+ *   }
+ *   return { orgId: ctx.orgId }  // admins/owners see all
+ * })
+ *
+ * const scopes = await resolver.resolve('user-1', 'org-1', ['todos', 'projects'])
+ * // { todos: { orgId: 'org-1', userId: 'user-1' }, projects: { orgId: 'org-1' } }
+ * ```
+ */
+declare class OrgScopeResolver {
+    private readonly orgStore;
+    private readonly rbac;
+    private readonly collectionScopes;
+    constructor(orgStore: OrgStore, rbac: RbacEngine);
+    /**
+     * Register a custom scope resolver for a collection.
+     * This overrides the default orgId-based filtering for that collection.
+     */
+    registerCollectionScope(collection: string, resolver: CollectionScopeResolver): void;
+    /**
+     * Resolve sync scopes for all specified collections.
+     *
+     * Returns null if the user is not a member of the organization.
+     * Returns an empty object if the user has no data access (e.g., billing role).
+     */
+    resolve(userId: string, orgId: string, collections: string[]): Promise<SyncScopes | null>;
+    /**
+     * Check if a user can write to a specific collection in an org.
+     */
+    canWrite(userId: string, orgId: string, collection: string): Promise<boolean>;
+    /**
+     * Check if a user can read from a specific collection in an org.
+     */
+    canRead(userId: string, orgId: string, collection: string): Promise<boolean>;
+    private resolveCollectionScope;
+}
+
+/**
+ * Configuration for an OAuth 2.0 provider.
+ */
+interface OAuthProviderConfig {
+    /** Provider identifier (e.g., 'google', 'github', 'microsoft') */
+    providerId: string;
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+    /** Authorization endpoint URL */
+    authorizationUrl: string;
+    /** Token exchange endpoint URL */
+    tokenUrl: string;
+    /** User info endpoint URL */
+    userInfoUrl: string;
+    /** OAuth scopes to request */
+    scopes: string[];
+    /** Redirect URI for the callback */
+    redirectUri: string;
+}
+/**
+ * Tokens returned by the OAuth provider after code exchange.
+ */
+interface OAuthTokens {
+    /** OAuth access token */
+    accessToken: string;
+    /** Token type (usually 'Bearer') */
+    tokenType: string;
+    /** Access token expiry in seconds (if provided) */
+    expiresIn?: number;
+    /** Refresh token (if provided) */
+    refreshToken?: string;
+    /** ID token (if provided, e.g., OpenID Connect) */
+    idToken?: string;
+    /** Granted scopes (may differ from requested scopes) */
+    scope?: string;
+}
+/**
+ * User information from the OAuth provider.
+ */
+interface OAuthUserInfo {
+    /** Provider-specific user ID */
+    providerId: string;
+    /** Provider name (e.g., 'google', 'github') */
+    provider: string;
+    /** User's email address (may be null if not granted) */
+    email: string | null;
+    /** Whether the email is verified by the provider */
+    emailVerified: boolean;
+    /** User's display name */
+    name: string | null;
+    /** URL to the user's avatar/profile picture */
+    avatarUrl: string | null;
+    /** Raw profile data from the provider */
+    rawProfile: Record<string, unknown>;
+}
+/**
+ * State stored during the OAuth flow for CSRF protection.
+ */
+interface OAuthState {
+    /** Random state parameter for CSRF protection */
+    state: string;
+    /** Provider ID */
+    provider: string;
+    /** Redirect URI used for this flow */
+    redirectUri: string;
+    /** When this state was created (ms since epoch) */
+    createdAt: number;
+    /** When this state expires (ms since epoch) */
+    expiresAt: number;
+    /** Optional: user-defined data to pass through the flow */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Store for OAuth state parameters.
+ */
+interface OAuthStateStore {
+    /** Store a state parameter for later validation. */
+    store(state: OAuthState): Promise<void>;
+    /** Consume a state parameter (single-use). Returns null if not found or expired. */
+    consume(stateValue: string): Promise<OAuthState | null>;
+    /** Clean up expired states. */
+    cleanExpired(): Promise<number>;
+}
+/**
+ * A linked OAuth identity for a user.
+ * Users can have multiple linked identities (e.g., Google + GitHub).
+ */
+interface LinkedIdentity {
+    /** Unique ID of this link */
+    id: string;
+    /** Kora user ID */
+    userId: string;
+    /** OAuth provider name */
+    provider: string;
+    /** Provider-specific user ID */
+    providerUserId: string;
+    /** Provider email (at time of linking) */
+    email: string | null;
+    /** When this identity was linked */
+    linkedAt: number;
+}
+declare class OAuthError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class OAuthStateMismatchError extends OAuthError {
+    constructor();
+}
+declare class OAuthCodeExchangeError extends OAuthError {
+    constructor(details?: string);
+}
+declare class OAuthUserInfoError extends OAuthError {
+    constructor(details?: string);
+}
+declare class OAuthProviderNotFoundError extends OAuthError {
+    constructor(provider: string);
+}
+
+/**
+ * In-memory OAuth state store for development.
+ * Use Redis or a database in production for multi-server deployments.
+ */
+declare class InMemoryOAuthStateStore implements OAuthStateStore {
+    private readonly states;
+    store(state: OAuthState): Promise<void>;
+    consume(stateValue: string): Promise<OAuthState | null>;
+    cleanExpired(): Promise<number>;
+}
+/**
+ * Configuration for the OAuth manager.
+ */
+interface OAuthManagerConfig {
+    /** Registered OAuth providers */
+    providers: OAuthProviderConfig[];
+    /** State store. Defaults to InMemoryOAuthStateStore. */
+    stateStore?: OAuthStateStore;
+    /** State TTL in milliseconds. Defaults to 10 minutes. */
+    stateTtlMs?: number;
+    /**
+     * Custom fetch function. Defaults to global fetch.
+     * Useful for testing or custom HTTP clients.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Manages the OAuth 2.0 authorization code flow.
+ *
+ * Supports any standard OAuth 2.0 / OpenID Connect provider.
+ * Pre-built configurations available for Google, GitHub, and Microsoft.
+ *
+ * @example
+ * ```typescript
+ * const oauth = new OAuthManager({
+ *   providers: [
+ *     googleProvider({ clientId: '...', clientSecret: '...', redirectUri: '...' }),
+ *     githubProvider({ clientId: '...', clientSecret: '...', redirectUri: '...' }),
+ *   ],
+ * })
+ *
+ * // Step 1: Generate authorization URL
+ * const { url, state } = await oauth.getAuthorizationUrl('google')
+ * // Redirect user to url...
+ *
+ * // Step 2: Handle callback
+ * const { tokens, userInfo } = await oauth.handleCallback('google', code, stateParam)
+ * ```
+ */
+declare class OAuthManager {
+    private readonly providers;
+    private readonly stateStore;
+    private readonly stateTtlMs;
+    private readonly fetchFn;
+    constructor(config: OAuthManagerConfig);
+    /**
+     * Generate an authorization URL for the user to visit.
+     * Returns the URL and the state parameter for CSRF validation.
+     */
+    getAuthorizationUrl(providerId: string, metadata?: Record<string, unknown>): Promise<{
+        url: string;
+        state: string;
+    }>;
+    /**
+     * Handle the OAuth callback after the user authorizes.
+     * Validates the state parameter, exchanges the code for tokens,
+     * and fetches user info.
+     *
+     * @param providerId - The OAuth provider
+     * @param code - The authorization code from the callback
+     * @param state - The state parameter from the callback
+     * @returns Tokens and user info from the provider
+     */
+    handleCallback(providerId: string, code: string, state: string): Promise<{
+        tokens: OAuthTokens;
+        userInfo: OAuthUserInfo;
+        stateMetadata?: Record<string, unknown>;
+    }>;
+    /**
+     * Get a registered provider by ID.
+     */
+    getProvider(providerId: string): OAuthProviderConfig;
+    /**
+     * List all registered provider IDs.
+     */
+    getProviderIds(): string[];
+    private exchangeCodeForTokens;
+    private fetchUserInfo;
+}
+interface ProviderFactoryConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}
+/**
+ * Create a Google OAuth provider configuration.
+ */
+declare function googleProvider(config: ProviderFactoryConfig): OAuthProviderConfig;
+/**
+ * Create a GitHub OAuth provider configuration.
+ */
+declare function githubProvider(config: ProviderFactoryConfig): OAuthProviderConfig;
+/**
+ * Create a Microsoft OAuth provider configuration.
+ */
+declare function microsoftProvider(config: ProviderFactoryConfig & {
+    tenantId?: string;
+}): OAuthProviderConfig;
+
+/**
+ * A user session with metadata.
+ */
+interface Session {
+    /** Unique session ID */
+    id: string;
+    /** User ID */
+    userId: string;
+    /** Device ID (if available) */
+    deviceId: string | null;
+    /** IP address of the client (for display, not for security decisions) */
+    ipAddress: string | null;
+    /** User agent string */
+    userAgent: string | null;
+    /** When the session was created */
+    createdAt: number;
+    /** When the session was last active */
+    lastActiveAt: number;
+    /** When the session expires (absolute expiry) */
+    expiresAt: number;
+    /** Whether MFA has been completed for this session */
+    mfaVerified: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for the session manager.
+ */
+interface SessionManagerConfig {
+    /** Session store implementation */
+    store: SessionStore;
+    /** Session TTL in milliseconds. Default: 7 days */
+    sessionTtlMs?: number;
+    /** Idle timeout in milliseconds. Default: 30 minutes */
+    idleTimeoutMs?: number;
+    /** Maximum concurrent sessions per user. Default: 10 */
+    maxSessionsPerUser?: number;
+    /** Whether to extend session on activity. Default: true */
+    slidingWindow?: boolean;
+}
+/**
+ * Parameters for creating a new session.
+ */
+interface CreateSessionParams {
+    userId: string;
+    deviceId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    mfaVerified?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Store for session data.
+ */
+interface SessionStore {
+    /** Create a new session */
+    create(session: Session): Promise<void>;
+    /** Get a session by ID */
+    getById(sessionId: string): Promise<Session | null>;
+    /** Update a session */
+    update(session: Session): Promise<void>;
+    /** Delete a session */
+    delete(sessionId: string): Promise<void>;
+    /** Get all sessions for a user */
+    listByUserId(userId: string): Promise<Session[]>;
+    /** Delete all sessions for a user */
+    deleteAllForUser(userId: string): Promise<number>;
+    /** Delete all sessions for a user except one */
+    deleteAllExcept(userId: string, keepSessionId: string): Promise<number>;
+    /** Clean up expired sessions */
+    cleanExpired(): Promise<number>;
+}
+declare class SessionError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class SessionNotFoundError extends SessionError {
+    constructor(sessionId: string);
+}
+declare class SessionExpiredError extends SessionError {
+    constructor(sessionId: string);
+}
+declare class SessionLimitExceededError extends SessionError {
+    constructor(userId: string, limit: number);
+}
+declare class SessionMfaRequiredError extends SessionError {
+    constructor(sessionId: string);
+}
+/**
+ * In-memory session store for development and testing.
+ */
+declare class InMemorySessionStore implements SessionStore {
+    private readonly sessions;
+    create(session: Session): Promise<void>;
+    getById(sessionId: string): Promise<Session | null>;
+    update(session: Session): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    listByUserId(userId: string): Promise<Session[]>;
+    deleteAllForUser(userId: string): Promise<number>;
+    deleteAllExcept(userId: string, keepSessionId: string): Promise<number>;
+    cleanExpired(): Promise<number>;
+}
+/**
+ * Manages user sessions with support for:
+ * - Session creation, validation, and revocation
+ * - Sliding window expiry (extends on activity)
+ * - Idle timeout detection
+ * - Max concurrent sessions per user
+ * - MFA verification tracking
+ * - "Sign out everywhere" support
+ *
+ * @example
+ * ```typescript
+ * const sessions = new SessionManager({
+ *   store: new InMemorySessionStore(),
+ *   sessionTtlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   idleTimeoutMs: 30 * 60 * 1000, // 30 minutes
+ *   maxSessionsPerUser: 5,
+ * })
+ *
+ * // Create session on login
+ * const session = await sessions.create({
+ *   userId: 'user-123',
+ *   ipAddress: '192.168.1.1',
+ *   userAgent: 'Mozilla/5.0...',
+ * })
+ *
+ * // Validate session on each request
+ * const valid = await sessions.validate(session.id)
+ *
+ * // Touch session to extend idle timeout
+ * await sessions.touch(session.id)
+ * ```
+ */
+declare class SessionManager {
+    private readonly store;
+    private readonly sessionTtlMs;
+    private readonly idleTimeoutMs;
+    private readonly maxSessionsPerUser;
+    private readonly slidingWindow;
+    constructor(config: SessionManagerConfig);
+    /**
+     * Create a new session for a user.
+     * Enforces the maximum concurrent sessions limit.
+     */
+    create(params: CreateSessionParams): Promise<Session>;
+    /**
+     * Validate a session.
+     * Returns the session if valid, throws if not found or expired.
+     */
+    validate(sessionId: string): Promise<Session>;
+    /**
+     * Touch a session to update its last activity time.
+     * If sliding window is enabled, also extends the absolute expiry.
+     */
+    touch(sessionId: string): Promise<Session>;
+    /**
+     * Mark a session as MFA-verified.
+     */
+    markMfaVerified(sessionId: string): Promise<Session>;
+    /**
+     * Require MFA verification on a session.
+     * Throws SessionMfaRequiredError if MFA is not verified.
+     */
+    requireMfa(sessionId: string): Promise<Session>;
+    /**
+     * Revoke (delete) a session.
+     */
+    revoke(sessionId: string): Promise<void>;
+    /**
+     * Revoke all sessions for a user (sign out everywhere).
+     * Returns the number of sessions revoked.
+     */
+    revokeAll(userId: string): Promise<number>;
+    /**
+     * Revoke all sessions for a user except the current one.
+     * Returns the number of sessions revoked.
+     */
+    revokeOthers(userId: string, currentSessionId: string): Promise<number>;
+    /**
+     * List all active sessions for a user.
+     */
+    listSessions(userId: string): Promise<Session[]>;
+    /**
+     * Clean up expired sessions.
+     * Returns the number of sessions cleaned.
+     */
+    cleanExpired(): Promise<number>;
+}
+
+/**
+ * Configuration for TOTP MFA.
+ */
+interface TotpConfig {
+    /** Issuer name shown in authenticator apps (e.g., "MyApp") */
+    issuer: string;
+    /** Number of digits in the TOTP code. Default: 6 */
+    digits?: number;
+    /** Time step in seconds. Default: 30 */
+    period?: number;
+    /** Hash algorithm. Default: 'SHA-1' (most compatible with authenticator apps) */
+    algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+    /** Number of time windows to check before/after current. Default: 1 */
+    window?: number;
+    /** Number of recovery codes to generate. Default: 8 */
+    recoveryCodes?: number;
+}
+/**
+ * A TOTP secret with metadata for a user.
+ */
+interface TotpSecret {
+    /** User ID */
+    userId: string;
+    /** Raw secret bytes (base32-encoded for display) */
+    secret: string;
+    /** Whether MFA is verified (user has confirmed setup with a valid code) */
+    verified: boolean;
+    /** Hashed recovery codes (unused ones only) */
+    recoveryCodes: string[];
+    /** When this secret was created */
+    createdAt: number;
+    /** When MFA was verified (confirmed with first valid code) */
+    verifiedAt: number | null;
+}
+/**
+ * Setup result returned when enabling TOTP MFA.
+ */
+interface TotpSetupResult {
+    /** The raw secret in base32 encoding (for manual entry) */
+    secret: string;
+    /** otpauth:// URI for QR code generation */
+    uri: string;
+    /** Plaintext recovery codes (shown once, then discarded) */
+    recoveryCodes: string[];
+}
+/**
+ * Store for TOTP secrets.
+ */
+interface TotpStore {
+    /** Save or update a TOTP secret for a user */
+    save(secret: TotpSecret): Promise<void>;
+    /** Get a TOTP secret by user ID */
+    getByUserId(userId: string): Promise<TotpSecret | null>;
+    /** Delete TOTP secret for a user (disable MFA) */
+    delete(userId: string): Promise<void>;
+}
+declare class TotpError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class TotpInvalidCodeError extends TotpError {
+    constructor();
+}
+declare class TotpNotEnabledError extends TotpError {
+    constructor(userId: string);
+}
+declare class TotpAlreadyEnabledError extends TotpError {
+    constructor(userId: string);
+}
+declare class TotpNotVerifiedError extends TotpError {
+    constructor(userId: string);
+}
+declare class TotpRecoveryExhaustedError extends TotpError {
+    constructor();
+}
+/**
+ * In-memory TOTP store for development and testing.
+ */
+declare class InMemoryTotpStore implements TotpStore {
+    private readonly secrets;
+    save(secret: TotpSecret): Promise<void>;
+    getByUserId(userId: string): Promise<TotpSecret | null>;
+    delete(userId: string): Promise<void>;
+}
+/**
+ * Manages TOTP-based Multi-Factor Authentication.
+ *
+ * Implements RFC 6238 (TOTP) and RFC 4226 (HOTP) with Web Crypto API.
+ * Compatible with Google Authenticator, Authy, 1Password, and other
+ * TOTP-compatible authenticator apps.
+ *
+ * @example
+ * ```typescript
+ * const totp = new TotpManager({
+ *   issuer: 'MyApp',
+ *   store: new InMemoryTotpStore(),
+ * })
+ *
+ * // Step 1: Enable MFA (returns QR code URI and recovery codes)
+ * const setup = await totp.enable('user-123', 'alice@example.com')
+ * // Show setup.uri as QR code, show setup.recoveryCodes once
+ *
+ * // Step 2: Verify setup with a code from authenticator app
+ * await totp.verifySetup('user-123', '123456')
+ *
+ * // Step 3: On login, verify TOTP code
+ * const valid = await totp.verify('user-123', '654321')
+ * ```
+ */
+declare class TotpManager {
+    private readonly store;
+    private readonly issuer;
+    private readonly digits;
+    private readonly period;
+    private readonly algorithm;
+    private readonly window;
+    private readonly recoveryCodeCount;
+    constructor(config: TotpConfig & {
+        store: TotpStore;
+    });
+    /**
+     * Enable TOTP MFA for a user.
+     * Returns the secret URI (for QR code) and recovery codes.
+     * The user must verify setup with a valid code before MFA is active.
+     */
+    enable(userId: string, accountName: string): Promise<TotpSetupResult>;
+    /**
+     * Verify the TOTP setup by confirming the user can generate a valid code.
+     * Must be called after `enable()` and before MFA is enforced.
+     */
+    verifySetup(userId: string, code: string): Promise<boolean>;
+    /**
+     * Verify a TOTP code during login.
+     * Returns true if the code is valid, false otherwise.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * Verify a recovery code as an alternative to TOTP.
+     * Recovery codes are single-use.
+     */
+    verifyRecoveryCode(userId: string, recoveryCode: string): Promise<boolean>;
+    /**
+     * Regenerate recovery codes. Requires a valid TOTP code for authorization.
+     * Replaces all existing recovery codes.
+     */
+    regenerateRecoveryCodes(userId: string, totpCode: string): Promise<string[]>;
+    /**
+     * Disable TOTP MFA for a user.
+     * Requires a valid TOTP code or recovery code for authorization.
+     */
+    disable(userId: string, code: string): Promise<void>;
+    /**
+     * Check if a user has TOTP MFA enabled and verified.
+     */
+    isEnabled(userId: string): Promise<boolean>;
+    /**
+     * Get the number of remaining recovery codes for a user.
+     */
+    remainingRecoveryCodes(userId: string): Promise<number>;
+    private validateCode;
+}
+/**
+ * Encode bytes to base32 string (RFC 4648, no padding).
+ */
+declare function base32Encode(data: Uint8Array): string;
+/**
+ * Decode a base32 string to bytes (RFC 4648).
+ */
+declare function base32Decode(encoded: string): Uint8Array;
+
+/**
+ * Actions that can be audited.
+ */
+declare const AUDIT_ACTIONS: readonly ["user.signup", "user.signin", "user.signout", "user.token_refresh", "user.password_change", "user.password_reset_request", "user.password_reset", "user.email_verify", "mfa.enable", "mfa.verify_setup", "mfa.verify", "mfa.recovery_used", "mfa.recovery_regenerate", "mfa.disable", "session.create", "session.revoke", "session.revoke_all", "session.expired", "oauth.authorize", "oauth.callback", "oauth.link", "oauth.unlink", "user.create", "user.update", "user.delete", "user.suspend", "user.unsuspend", "org.create", "org.update", "org.delete", "org.member_add", "org.member_remove", "org.member_role_change", "org.ownership_transfer", "org.invitation_create", "org.invitation_accept", "org.invitation_revoke", "admin.user_lookup", "admin.impersonate", "admin.config_change"];
+type AuditAction = (typeof AUDIT_ACTIONS)[number];
+/**
+ * An audit log entry.
+ */
+interface AuditEntry {
+    /** Unique entry ID */
+    id: string;
+    /** When this event occurred */
+    timestamp: number;
+    /** The action that was performed */
+    action: AuditAction;
+    /** Who performed the action (user ID, "system", or "anonymous") */
+    actorId: string;
+    /** The type of actor */
+    actorType: 'user' | 'admin' | 'system';
+    /** The target of the action (e.g., user ID, org ID, session ID) */
+    targetId: string | null;
+    /** The type of target */
+    targetType: string | null;
+    /** IP address of the actor */
+    ipAddress: string | null;
+    /** User agent */
+    userAgent: string | null;
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Error message if the action failed */
+    errorMessage: string | null;
+    /** Additional structured context */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Query parameters for searching audit logs.
+ */
+interface AuditLogQuery {
+    /** Filter by actor ID */
+    actorId?: string;
+    /** Filter by target ID */
+    targetId?: string;
+    /** Filter by action(s) */
+    actions?: AuditAction[];
+    /** Filter by success/failure */
+    success?: boolean;
+    /** Start time (inclusive) */
+    startTime?: number;
+    /** End time (inclusive) */
+    endTime?: number;
+    /** Maximum number of entries to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Store for audit log entries.
+ */
+interface AuditLogStore {
+    /** Append an audit entry */
+    append(entry: AuditEntry): Promise<void>;
+    /** Query audit entries */
+    query(params: AuditLogQuery): Promise<AuditEntry[]>;
+    /** Count matching entries */
+    count(params: AuditLogQuery): Promise<number>;
+    /** Delete entries older than a given timestamp */
+    purgeOlderThan(timestamp: number): Promise<number>;
+}
+declare class AuditLogError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * In-memory audit log store for development and testing.
+ */
+declare class InMemoryAuditLogStore implements AuditLogStore {
+    private readonly entries;
+    append(entry: AuditEntry): Promise<void>;
+    query(params: AuditLogQuery): Promise<AuditEntry[]>;
+    count(params: AuditLogQuery): Promise<number>;
+    purgeOlderThan(timestamp: number): Promise<number>;
+    private filterEntries;
+}
+/**
+ * Structured audit logger for authentication events.
+ *
+ * Records all security-relevant actions for compliance and debugging.
+ * Designed to be plugged into the auth system at key decision points.
+ *
+ * @example
+ * ```typescript
+ * const auditLog = new AuditLogger({
+ *   store: new InMemoryAuditLogStore(),
+ * })
+ *
+ * await auditLog.log({
+ *   action: 'user.signin',
+ *   actorId: 'user-123',
+ *   actorType: 'user',
+ *   success: true,
+ *   ipAddress: '192.168.1.1',
+ * })
+ *
+ * const entries = await auditLog.query({ actorId: 'user-123', limit: 50 })
+ * ```
+ */
+declare class AuditLogger {
+    private readonly store;
+    private readonly retentionMs;
+    constructor(config: {
+        store: AuditLogStore;
+        retentionDays?: number;
+    });
+    /**
+     * Log an audit event.
+     */
+    log(params: {
+        action: AuditAction;
+        actorId: string;
+        actorType?: 'user' | 'admin' | 'system';
+        targetId?: string;
+        targetType?: string;
+        ipAddress?: string;
+        userAgent?: string;
+        success?: boolean;
+        errorMessage?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<AuditEntry>;
+    /**
+     * Query audit log entries.
+     */
+    query(params: AuditLogQuery): Promise<AuditEntry[]>;
+    /**
+     * Count matching audit entries.
+     */
+    count(params: AuditLogQuery): Promise<number>;
+    /**
+     * Purge old entries based on retention policy.
+     * Returns the number of entries purged.
+     */
+    purge(): Promise<number>;
+    /**
+     * Get recent activity for a user.
+     */
+    getUserActivity(userId: string, limit?: number): Promise<AuditEntry[]>;
+    /**
+     * Get failed login attempts for a user within a time window.
+     */
+    getFailedLogins(userId: string, windowMs: number): Promise<AuditEntry[]>;
+}
+
+/**
+ * Configuration for the Admin API.
+ */
+interface AdminApiConfig {
+    /** User store for managing users */
+    userStore: UserStore;
+    /** Session store for managing sessions (optional) */
+    sessionStore?: SessionStore;
+    /** Audit logger (optional) */
+    auditLogger?: AuditLogger;
+}
+/**
+ * Paginated result set.
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * User list query parameters.
+ */
+interface UserListQuery {
+    /** Search by email (substring match) */
+    email?: string;
+    /** Filter by email verified status */
+    emailVerified?: boolean;
+    /** Maximum number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Admin-level user update (different from self-update).
+ */
+interface AdminUserUpdate {
+    /** Update display name */
+    name?: string;
+    /** Set email verified status */
+    emailVerified?: boolean;
+    /** Update email (admin override) */
+    email?: string;
+}
+declare class AdminApiError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class AdminUserNotFoundError extends AdminApiError {
+    constructor(userId: string);
+}
+declare class AdminUnauthorizedError extends AdminApiError {
+    constructor();
+}
+/**
+ * Administrative API for managing users, sessions, and system configuration.
+ *
+ * Provides elevated operations that should only be accessible to administrators.
+ * All operations are audit-logged when an AuditLogger is configured.
+ *
+ * @example
+ * ```typescript
+ * const admin = new AdminApi({
+ *   userStore: myUserStore,
+ *   sessionStore: mySessionStore,
+ *   auditLogger: myAuditLogger,
+ * })
+ *
+ * // List users
+ * const { data, total } = await admin.listUsers({ limit: 20 })
+ *
+ * // Suspend a user (revokes all sessions)
+ * await admin.suspendUser('admin-user-id', 'target-user-id', 'Policy violation')
+ * ```
+ */
+declare class AdminApi {
+    private readonly userStore;
+    private readonly sessionStore;
+    private readonly auditLogger;
+    constructor(config: AdminApiConfig);
+    /**
+     * Get a user by ID with full details.
+     */
+    getUser(adminId: string, userId: string): Promise<AuthUser>;
+    /**
+     * List users with optional filtering and pagination.
+     */
+    listUsers(query?: UserListQuery): Promise<PaginatedResult<AuthUser>>;
+    /**
+     * Update a user's profile (admin-level).
+     */
+    updateUser(adminId: string, userId: string, updates: AdminUserUpdate): Promise<AuthUser>;
+    /**
+     * Delete a user and all associated sessions.
+     */
+    deleteUser(adminId: string, userId: string): Promise<void>;
+    /**
+     * Get all active sessions for a user.
+     */
+    getUserSessions(userId: string): Promise<Session[]>;
+    /**
+     * Revoke all sessions for a user.
+     */
+    revokeUserSessions(adminId: string, userId: string): Promise<number>;
+    /**
+     * Revoke a specific session.
+     */
+    revokeSession(adminId: string, sessionId: string): Promise<void>;
+    /**
+     * Get system statistics.
+     */
+    getStats(): Promise<{
+        totalUsers: number;
+        verifiedUsers: number;
+        unverifiedUsers: number;
+    }>;
+    private audit;
+}
+
+/**
+ * Events that can trigger webhooks.
+ */
+declare const WEBHOOK_EVENTS: readonly ["user.created", "user.updated", "user.deleted", "user.signin", "user.signout", "user.password_changed", "user.email_verified", "mfa.enabled", "mfa.disabled", "session.created", "session.revoked", "org.created", "org.updated", "org.deleted", "org.member_added", "org.member_removed", "org.invitation_created", "org.invitation_accepted"];
+type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+/**
+ * A webhook endpoint configuration.
+ */
+interface WebhookEndpoint {
+    /** Unique endpoint ID */
+    id: string;
+    /** Destination URL */
+    url: string;
+    /** Events this endpoint subscribes to */
+    events: WebhookEvent[];
+    /** Signing secret for HMAC verification */
+    secret: string;
+    /** Whether this endpoint is active */
+    active: boolean;
+    /** When this endpoint was created */
+    createdAt: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A webhook delivery attempt.
+ */
+interface WebhookDelivery {
+    /** Unique delivery ID */
+    id: string;
+    /** Endpoint ID */
+    endpointId: string;
+    /** Event that triggered this delivery */
+    event: WebhookEvent;
+    /** Request payload (JSON) */
+    payload: string;
+    /** HTTP response status (null if network error) */
+    responseStatus: number | null;
+    /** Whether the delivery was successful (2xx response) */
+    success: boolean;
+    /** Error message if delivery failed */
+    error: string | null;
+    /** Number of attempts made */
+    attempts: number;
+    /** When the delivery was first attempted */
+    createdAt: number;
+    /** When the delivery was last attempted */
+    lastAttemptAt: number;
+}
+/**
+ * Payload sent to webhook endpoints.
+ */
+interface WebhookPayload {
+    /** Unique event ID */
+    id: string;
+    /** Event type */
+    event: WebhookEvent;
+    /** When the event occurred */
+    timestamp: number;
+    /** Event data */
+    data: Record<string, unknown>;
+}
+/**
+ * Store for webhook endpoints and deliveries.
+ */
+interface WebhookStore {
+    /** Save a webhook endpoint */
+    saveEndpoint(endpoint: WebhookEndpoint): Promise<void>;
+    /** Get an endpoint by ID */
+    getEndpoint(id: string): Promise<WebhookEndpoint | null>;
+    /** List all endpoints */
+    listEndpoints(): Promise<WebhookEndpoint[]>;
+    /** Delete an endpoint */
+    deleteEndpoint(id: string): Promise<void>;
+    /** Save a delivery record */
+    saveDelivery(delivery: WebhookDelivery): Promise<void>;
+    /** List recent deliveries for an endpoint */
+    listDeliveries(endpointId: string, limit?: number): Promise<WebhookDelivery[]>;
+}
+declare class WebhookError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+declare class WebhookEndpointNotFoundError extends WebhookError {
+    constructor(id: string);
+}
+declare class InMemoryWebhookStore implements WebhookStore {
+    private readonly endpoints;
+    private readonly deliveries;
+    saveEndpoint(endpoint: WebhookEndpoint): Promise<void>;
+    getEndpoint(id: string): Promise<WebhookEndpoint | null>;
+    listEndpoints(): Promise<WebhookEndpoint[]>;
+    deleteEndpoint(id: string): Promise<void>;
+    saveDelivery(delivery: WebhookDelivery): Promise<void>;
+    listDeliveries(endpointId: string, limit?: number): Promise<WebhookDelivery[]>;
+}
+/**
+ * Manages webhook registrations and event delivery.
+ *
+ * Sends HTTP POST requests to registered endpoints when auth events occur.
+ * Includes HMAC-SHA256 signature verification and retry logic.
+ *
+ * @example
+ * ```typescript
+ * const webhooks = new WebhookManager({
+ *   store: new InMemoryWebhookStore(),
+ * })
+ *
+ * // Register an endpoint
+ * const endpoint = await webhooks.register({
+ *   url: 'https://myapp.com/webhooks/auth',
+ *   events: ['user.created', 'user.signin'],
+ * })
+ *
+ * // Dispatch an event (usually called internally by auth system)
+ * await webhooks.dispatch('user.created', { userId: 'user-123', email: 'alice@example.com' })
+ * ```
+ */
+declare class WebhookManager {
+    private readonly store;
+    private readonly fetchFn;
+    constructor(config: {
+        store: WebhookStore;
+        fetch?: typeof globalThis.fetch;
+    });
+    /**
+     * Register a new webhook endpoint.
+     */
+    register(params: {
+        url: string;
+        events: WebhookEvent[];
+        metadata?: Record<string, unknown>;
+    }): Promise<WebhookEndpoint>;
+    /**
+     * Update a webhook endpoint.
+     */
+    update(id: string, updates: {
+        url?: string;
+        events?: WebhookEvent[];
+        active?: boolean;
+    }): Promise<WebhookEndpoint>;
+    /**
+     * Delete a webhook endpoint.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * List all webhook endpoints.
+     */
+    list(): Promise<WebhookEndpoint[]>;
+    /**
+     * Get a specific endpoint.
+     */
+    get(id: string): Promise<WebhookEndpoint>;
+    /**
+     * Get recent deliveries for an endpoint.
+     */
+    getDeliveries(endpointId: string, limit?: number): Promise<WebhookDelivery[]>;
+    /**
+     * Dispatch an event to all matching webhook endpoints.
+     * Delivery is best-effort with retries.
+     */
+    dispatch(event: WebhookEvent, data: Record<string, unknown>): Promise<void>;
+    private deliverToEndpoint;
+}
+/**
+ * Verify a webhook payload signature.
+ * Useful for consumers of webhooks to verify authenticity.
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+
+export { AdminApi, type AdminApiConfig, AdminApiError, AdminUnauthorizedError, AdminUserNotFoundError, type AdminUserUpdate, type AuditAction, type AuditEntry, AuditLogError, type AuditLogQuery, type AuditLogStore, AuditLogger, type AuthDevice, type AuthProviderAdapter, AuthProviderError, type AuthRouteResponse, type AuthRoutesConfig, type AuthUser, type AuthenticationOptions, type AuthenticationVerificationResult, BUILT_IN_ROLES, BuiltInAuthRoutes, BuiltInProvider, CannotRemoveOwnerError, type ChallengeStore, CircularInheritanceError, type ClerkAdapterConfig, type CollectionScopeResolver, type CreateInvitationParams, type CreateOrgParams, type CreateSessionParams, DuplicateEmailError, type EmailVerificationConfig, EmailVerificationError, EmailVerificationManager, type EmailVerificationStore, type EmailVerificationToken, ExternalAuthOperationNotSupportedError, ExternalJwtProvider, type ExternalJwtProviderConfig, ExternalTokenValidationError, type ExternalUserInfo, INVITATION_STATUSES, InMemoryAuditLogStore, InMemoryChallengeStore, InMemoryEmailVerificationStore, InMemoryOAuthStateStore, InMemoryOrgStore, InMemoryPasswordResetStore, InMemoryRateLimiter, InMemorySessionStore, InMemoryTokenRevocationStore, InMemoryTotpStore, InMemoryUserStore, InMemoryWebhookStore, InsufficientRoleError, InvalidPermissionError, InvitationExpiredError, InvitationNotFoundError, type InvitationStatus, type LinkedIdentity, MemberAlreadyExistsError, type Membership, MembershipNotFoundError, OAuthCodeExchangeError, OAuthError, OAuthManager, type OAuthManagerConfig, type OAuthProviderConfig, OAuthProviderNotFoundError, type OAuthState, OAuthStateMismatchError, type OAuthStateStore, type OAuthTokens, type OAuthUserInfo, OAuthUserInfoError, ORG_ROLES, OrgError, type OrgInvitation, OrgNotFoundError, type OrgRole, type OrgRouteResponse, OrgRoutes, type OrgRoutesConfig, OrgScopeResolver, OrgSlugTakenError, type OrgStore, type Organization, type PaginatedResult, PasskeyVerificationError, type PasswordResetConfig, PasswordResetError, PasswordResetManager, type PasswordResetStore, type PasswordResetToken, type Permission, PostgresUserStore, ROLE_HIERARCHY, type RateLimiter, type RbacConfig, RbacEngine, RbacError, type RegistrationOptions, type RegistrationVerificationResult, ResetRateLimitedError, ResetTokenExpiredError, ResetTokenNotFoundError, type RoleDefinition, RoleNotFoundError, type ScopeContext, type ScopeFilter, type Session, SessionError, SessionExpiredError, SessionLimitExceededError, SessionManager, type SessionManagerConfig, SessionMfaRequiredError, SessionNotFoundError, type SessionStore, type SignInParams, type SignUpParams, SqliteUserStore, type StoredUser, type SupabaseAdapterConfig, type SyncScopes, TokenManager, type TokenManagerConfig, type TokenRevocationStore, TotpAlreadyEnabledError, type TotpConfig, TotpError, TotpInvalidCodeError, TotpManager, TotpNotEnabledError, TotpNotVerifiedError, TotpRecoveryExhaustedError, type TotpSecret, type TotpSetupResult, type TotpStore, type UpdateOrgParams, type UserListQuery, type UserStore, VerificationTokenExpiredError, VerificationTokenNotFoundError, type WebhookDelivery, type WebhookEndpoint, WebhookEndpointNotFoundError, WebhookError, type WebhookEvent, WebhookManager, type WebhookPayload, type WebhookStore, base32Decode, base32Encode, createClerkAdapter, createPostgresUserStore, createSqliteUserStore, createSupabaseAdapter, decodeJwt, defineRoles, encodeJwt, generateAuthenticationOptions, generateRegistrationOptions, githubProvider, googleProvider, hasRoleLevel, hashPassword, isExpired, microsoftProvider, parsePermission, permissionCovers, verifyAuthenticationResponse, verifyJwt, verifyPassword, verifyRegistrationResponse, verifyWebhookSignature };