@korajs/auth 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,780 @@
+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 { KoraError } from '@korajs/core';
+
+/**
+ * Configuration for the server-side TokenManager.
+ */
+interface TokenManagerConfig {
+    /** Secret key for signing JWTs (HMAC-SHA256) */
+    secret: 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;
+}
+/**
+ * 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)
+ *
+ * @example
+ * ```typescript
+ * const tokenManager = new TokenManager({ secret: 'my-signing-secret' })
+ *
+ * // Issue all tokens at once
+ * const tokens = tokenManager.issueTokens('user-123', 'device-456')
+ *
+ * // Validate an access token
+ * const payload = tokenManager.validateToken(tokens.accessToken)
+ *
+ * // Refresh when the access token expires
+ * const newTokens = tokenManager.refreshAccessToken(tokens.refreshToken)
+ * ```
+ */
+declare class TokenManager {
+    private readonly secret;
+    private readonly accessTokenLifetime;
+    private readonly refreshTokenLifetime;
+    private readonly deviceCredentialLifetime;
+    constructor(config: TokenManagerConfig);
+    /**
+     * Issue a signed JWT access token.
+     *
+     * Access tokens are short-lived (default 15 minutes) and used to authorize
+     * API requests. When expired, use {@link refreshAccessToken} with a valid
+     * refresh token to obtain a new one.
+     *
+     * @param userId - The subject (user ID) to encode in the token
+     * @param deviceId - The device ID of the requesting device
+     * @returns A signed JWT string with type 'access'
+     */
+    issueAccessToken(userId: string, deviceId: string): string;
+    /**
+     * Issue a signed JWT refresh token.
+     *
+     * Refresh tokens are longer-lived (default 90 days) and used exclusively
+     * to obtain new access tokens via {@link refreshAccessToken}. They should
+     * be stored securely and never sent to resource APIs.
+     *
+     * @param userId - The subject (user ID) to encode in the token
+     * @param deviceId - The device ID of the requesting device
+     * @returns A signed JWT string with type 'refresh'
+     */
+    issueRefreshToken(userId: string, deviceId: string): string;
+    /**
+     * Issue a signed device credential token.
+     *
+     * Device credentials are long-lived tokens bound to a device's public key.
+     * They include a `mustCheckinBy` deadline; if the device does not check in
+     * before this deadline, the credential should be treated as revoked.
+     *
+     * @param userId - The subject (user ID) to encode in the token
+     * @param deviceId - The device ID of the requesting device
+     * @param publicKeyThumbprint - SHA-256 thumbprint of the device's public key
+     * @returns A signed JWT string with type 'device_credential'
+     */
+    issueDeviceCredential(userId: string, deviceId: string, publicKeyThumbprint: string): string;
+    /**
+     * Issue a complete set of authentication tokens.
+     *
+     * Always issues an access token and refresh token. If a `publicKeyThumbprint`
+     * is provided, also issues a device credential.
+     *
+     * @param userId - The subject (user ID) to encode in the tokens
+     * @param deviceId - The device ID of the requesting device
+     * @param publicKeyThumbprint - Optional SHA-256 thumbprint of the device's public key.
+     *   When provided, a device credential is included in the returned tokens.
+     * @returns An {@link AuthTokens} object containing the issued tokens
+     */
+    issueTokens(userId: string, deviceId: string, publicKeyThumbprint?: string): AuthTokens;
+    /**
+     * Validate and decode a token.
+     *
+     * Verifies the HMAC-SHA256 signature and checks that the token has not expired.
+     * Returns null (rather than throwing) for invalid or expired tokens, so callers
+     * can handle authentication failure without try/catch.
+     *
+     * @param token - The JWT string to validate
+     * @returns The decoded {@link TokenPayload} if valid, or null if the token is
+     *   invalid, expired, or missing required claims
+     */
+    validateToken(token: string): TokenPayload | null;
+    /**
+     * 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.
+     *
+     * 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): {
+        accessToken: string;
+        refreshToken: string;
+    } | null;
+}
+
+/**
+ * A user as visible to the application layer.
+ * Does not include sensitive fields like password hash or salt.
+ */
+interface AuthUser {
+    /** Unique user identifier (UUID v7 or crypto.randomUUID) */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name: string;
+    /** Timestamp when the user was created (milliseconds since epoch) */
+    createdAt: number;
+}
+/**
+ * Internal user record that includes credentials.
+ * Extends AuthUser with password hash and salt for verification.
+ */
+interface StoredUser extends AuthUser {
+    /** Hex-encoded PBKDF2 derived key */
+    passwordHash: string;
+    /** Hex-encoded random salt used during hashing */
+    salt: string;
+}
+/**
+ * A device registered to a user.
+ */
+interface AuthDevice {
+    /** Unique device identifier */
+    id: string;
+    /** ID of the user who owns this device */
+    userId: string;
+    /** Base64url-encoded public key (or thumbprint) for the device */
+    publicKey: string;
+    /** Human-readable device name */
+    name: string;
+    /** Whether the device has been revoked */
+    revoked: boolean;
+    /** Timestamp when the device was first registered (milliseconds since epoch) */
+    createdAt: number;
+    /** Timestamp when the device was last seen (milliseconds since epoch) */
+    lastSeenAt: number;
+}
+/**
+ * Thrown when a user account already exists with the given email.
+ */
+declare class DuplicateEmailError extends KoraError {
+    constructor(email: string);
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryUserStore()
+ * const user = await store.createUser({
+ *   email: 'alice@example.com',
+ *   passwordHash: 'abc123...',
+ *   salt: 'def456...',
+ *   name: 'Alice',
+ * })
+ * ```
+ */
+declare class InMemoryUserStore {
+    /** Users indexed by ID */
+    private readonly usersById;
+    /** Users indexed by email (lowercase) for fast lookup */
+    private readonly usersByEmail;
+    /** Devices indexed by device ID */
+    private readonly devicesById;
+    /** Device IDs indexed by user ID for fast listing */
+    private readonly devicesByUserId;
+    /**
+     * Create a new user account.
+     *
+     * @param params - User creation parameters
+     * @param params.email - The user's email address (must be unique, case-insensitive)
+     * @param params.passwordHash - Hex-encoded PBKDF2 derived key
+     * @param params.salt - Hex-encoded salt used during hashing
+     * @param params.name - The user's display name
+     * @returns The created user (without sensitive credential fields)
+     * @throws {DuplicateEmailError} If a user with the same email already exists
+     */
+    createUser(params: {
+        email: string;
+        passwordHash: string;
+        salt: string;
+        name: string;
+    }): Promise<AuthUser>;
+    /**
+     * Find a user by email address.
+     *
+     * @param email - The email to search for (case-insensitive)
+     * @returns The stored user record including credentials, or null if not found
+     */
+    findByEmail(email: string): Promise<StoredUser | null>;
+    /**
+     * Find a user by ID.
+     *
+     * @param id - The user ID to search for
+     * @returns The stored user record including credentials, or null if not found
+     */
+    findById(id: string): Promise<StoredUser | null>;
+    /**
+     * Register a device for a user.
+     *
+     * If a device with the same ID already exists and is not revoked, it is
+     * returned as-is (idempotent registration). If it was previously revoked,
+     * it is re-activated with updated details.
+     *
+     * @param params - Device registration parameters
+     * @param params.id - Unique device identifier
+     * @param params.userId - ID of the user who owns the device
+     * @param params.publicKey - Base64url-encoded device public key or thumbprint
+     * @param params.name - Human-readable device name
+     * @returns The registered device record
+     */
+    registerDevice(params: {
+        id: string;
+        userId: string;
+        publicKey: string;
+        name: string;
+    }): Promise<AuthDevice>;
+    /**
+     * Find a device by its ID.
+     *
+     * @param deviceId - The device ID to search for
+     * @returns The device record, or null if not found
+     */
+    findDevice(deviceId: string): Promise<AuthDevice | null>;
+    /**
+     * List all devices registered for a user.
+     *
+     * @param userId - The user ID whose devices to list
+     * @returns Array of device records (includes revoked devices)
+     */
+    listDevices(userId: string): Promise<AuthDevice[]>;
+    /**
+     * Revoke a device, preventing it from being used for authentication.
+     *
+     * This is a soft revoke — the device record remains but is marked as revoked.
+     * If the device does not exist, this is a no-op.
+     *
+     * @param deviceId - The ID of the device to revoke
+     */
+    revokeDevice(deviceId: string): Promise<void>;
+    /**
+     * Update the last-seen timestamp for a device.
+     *
+     * Called when a device authenticates or syncs to track activity.
+     * If the device does not exist, this is a no-op.
+     *
+     * @param deviceId - The ID of the device to update
+     */
+    touchDevice(deviceId: string): Promise<void>;
+}
+
+/**
+ * Configuration for building the built-in auth routes.
+ */
+interface AuthRoutesConfig {
+    /** The user/device store backing the auth routes */
+    userStore: InMemoryUserStore;
+    /** The token manager for issuing and validating JWTs */
+    tokenManager: TokenManager;
+}
+/**
+ * Response envelope returned by all auth route handlers.
+ *
+ * Successful responses include a `data` field; failures include an `error` string.
+ * The `status` field maps directly to an HTTP status code.
+ */
+interface AuthRouteResponse<T> {
+    /** HTTP status code */
+    status: number;
+    /** Either the success payload or an error message */
+    body: {
+        data: T;
+    } | {
+        error: string;
+    };
+}
+/**
+ * HTTP route handlers for the built-in Kora auth provider.
+ *
+ * These are framework-agnostic functions that accept parsed request bodies and return
+ * structured responses. The server package is responsible for wiring them into its
+ * HTTP server (e.g., mapping `POST /auth/signup` to `handleSignUp`).
+ *
+ * All handlers follow the same pattern:
+ * - Validate input
+ * - Perform the operation
+ * - Return `{ status, body: { data } }` on success
+ * - Return `{ status, body: { error } }` on failure
+ *
+ * @example
+ * ```typescript
+ * const routes = new BuiltInAuthRoutes({
+ *   userStore: new InMemoryUserStore(),
+ *   tokenManager: new TokenManager({ secret: 'my-secret' }),
+ * })
+ *
+ * // Wire into an HTTP server:
+ * app.post('/auth/signup', async (req, res) => {
+ *   const result = await routes.handleSignUp(req.body)
+ *   res.status(result.status).json(result.body)
+ * })
+ * ```
+ */
+declare class BuiltInAuthRoutes {
+    private readonly userStore;
+    private readonly tokenManager;
+    constructor(config: AuthRoutesConfig);
+    /**
+     * Handle user sign-up (POST /auth/signup).
+     *
+     * Validates email format and password length, hashes the password,
+     * creates the user, optionally registers a device, and issues tokens.
+     *
+     * @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.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)
+     * @returns Auth response with the created user and tokens, or an error
+     */
+    handleSignUp(body: {
+        email: string;
+        password: string;
+        name?: string;
+        deviceId?: string;
+        devicePublicKey?: string;
+    }): Promise<AuthRouteResponse<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>>;
+    /**
+     * Handle user sign-in (POST /auth/signin).
+     *
+     * Looks up the user by email, verifies the password, optionally registers
+     * a new device, and issues tokens.
+     *
+     * @param body - Sign-in request body
+     * @param body.email - The user's email address
+     * @param body.password - The plaintext password
+     * @param body.deviceId - Optional device ID to register
+     * @param body.devicePublicKey - Optional device public key (base64url)
+     * @returns Auth response with the user and tokens, or an error
+     */
+    handleSignIn(body: {
+        email: string;
+        password: string;
+        deviceId?: string;
+        devicePublicKey?: string;
+    }): Promise<AuthRouteResponse<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>>;
+    /**
+     * 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.
+     *
+     * @param body - Refresh request body
+     * @param body.refreshToken - The current refresh token
+     * @returns Auth response with new tokens, or an error
+     */
+    handleRefresh(body: {
+        refreshToken: string;
+    }): Promise<AuthRouteResponse<AuthTokens>>;
+    /**
+     * Handle get-current-user (GET /auth/me).
+     *
+     * Validates the access token and returns the authenticated user's profile.
+     *
+     * @param accessToken - The JWT access token (without "Bearer " prefix)
+     * @returns Auth response with the user profile, or an error
+     */
+    handleGetMe(accessToken: string): Promise<AuthRouteResponse<AuthUser>>;
+    /**
+     * Handle list-devices (GET /auth/devices).
+     *
+     * Validates the access token and returns all devices registered for the user.
+     *
+     * @param accessToken - The JWT access token (without "Bearer " prefix)
+     * @returns Auth response with the device list, or an error
+     */
+    handleListDevices(accessToken: string): Promise<AuthRouteResponse<AuthDevice[]>>;
+    /**
+     * Handle device revocation (DELETE /auth/device/:id).
+     *
+     * Validates the access token and revokes the specified 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
+     * @returns Auth response with success flag, or an error
+     */
+    handleRevokeDevice(accessToken: string, deviceId: string): Promise<AuthRouteResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Creates a sync server auth provider compatible with `@korajs/server`.
+     *
+     * The returned object implements the `AuthProvider` interface from
+     * `@korajs/server`, validating access tokens and returning an auth
+     * context containing the user ID and device metadata. This bridges
+     * the built-in auth system with the sync server's authentication layer.
+     *
+     * @returns An object with an `authenticate` method suitable for KoraSyncServer's `auth` config
+     *
+     * @example
+     * ```typescript
+     * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
+     * const syncServer = new KoraSyncServer({
+     *   store,
+     *   auth: routes.toSyncAuthProvider(),
+     * })
+     * ```
+     */
+    toSyncAuthProvider(): {
+        authenticate(token: string): Promise<{
+            userId: string;
+            scopes?: Record<string, Record<string, unknown>>;
+            metadata?: Record<string, unknown>;
+        } | null>;
+    };
+}
+
+/**
+ * Creates a signed JWT (HS256) from a payload and secret.
+ *
+ * The token is structured as `header.payload.signature` per RFC 7519.
+ * Only HMAC-SHA256 is supported. The header is always `{"alg":"HS256","typ":"JWT"}`.
+ *
+ * @param payload - The claims to include in the token. Must be JSON-serializable.
+ * @param secret - The HMAC-SHA256 secret key used for signing.
+ * @returns A signed JWT string in the format `header.payload.signature`
+ *
+ * @example
+ * ```typescript
+ * const token = encodeJwt(
+ *   { sub: 'user-123', exp: Math.floor(Date.now() / 1000) + 900 },
+ *   'my-secret'
+ * )
+ * ```
+ */
+declare function encodeJwt(payload: Record<string, unknown>, secret: string): string;
+/**
+ * Decodes a JWT without verifying its signature.
+ *
+ * Use this only when you need to inspect claims (e.g., reading `exp` to decide
+ * whether to attempt a refresh) and do NOT need to trust the token's authenticity.
+ * For trusted reads, use {@link verifyJwt} instead.
+ *
+ * @param token - The JWT string to decode
+ * @returns The decoded payload as a record, or null if the token is malformed
+ *
+ * @example
+ * ```typescript
+ * const claims = decodeJwt(token)
+ * if (claims && typeof claims.sub === 'string') {
+ *   console.log('User:', claims.sub)
+ * }
+ * ```
+ */
+declare function decodeJwt(token: string): Record<string, unknown> | null;
+/**
+ * Decodes a JWT and verifies its HMAC-SHA256 signature.
+ *
+ * Returns the payload only if the signature is valid. Returns null if the token
+ * is malformed, has an invalid signature, or cannot be parsed.
+ *
+ * This function does NOT check expiration. Use {@link isExpired} separately
+ * to check the `exp` claim, allowing callers to distinguish between
+ * "invalid signature" (security issue) and "expired" (normal lifecycle).
+ *
+ * @param token - The JWT string to verify
+ * @param secret - The HMAC-SHA256 secret key that was used to sign the token
+ * @returns The decoded payload if the signature is valid, or null otherwise
+ *
+ * @example
+ * ```typescript
+ * const claims = verifyJwt(token, 'my-secret')
+ * if (claims === null) {
+ *   throw new Error('Invalid token signature')
+ * }
+ * if (isExpired(claims)) {
+ *   throw new Error('Token has expired')
+ * }
+ * ```
+ */
+declare function verifyJwt(token: string, secret: string): Record<string, unknown> | null;
+/**
+ * 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.
+ *
+ * @param payload - An object with an optional `exp` field (seconds since epoch)
+ * @returns true if the token has expired, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const claims = verifyJwt(token, secret)
+ * if (claims && isExpired(claims)) {
+ *   // Token signature is valid but it has expired -- attempt refresh
+ * }
+ * ```
+ */
+declare function isExpired(payload: {
+    exp?: number;
+}): boolean;
+
+interface HashResult {
+    /** Hex-encoded PBKDF2 derived key. */
+    hash: string;
+    /** Hex-encoded random salt used during hashing. */
+    salt: string;
+}
+/**
+ * Hashes a password using PBKDF2 with a cryptographically random salt.
+ *
+ * Uses SHA-512 with 600,000 iterations and a 32-byte random salt,
+ * producing a 64-byte derived key. Both the hash and salt are returned
+ * as hex-encoded strings for storage.
+ *
+ * @param password - The plaintext password to hash
+ * @returns The hex-encoded hash and salt
+ *
+ * @example
+ * ```typescript
+ * const { hash, salt } = await hashPassword('my-secret-password')
+ * // Store hash and salt in the database
+ * ```
+ */
+declare function hashPassword(password: string): Promise<HashResult>;
+/**
+ * Verifies a plaintext password against a stored hash and salt using
+ * timing-safe comparison to prevent timing attacks.
+ *
+ * Re-derives the key from the password and salt using the same PBKDF2
+ * parameters, then compares the result against the stored hash using
+ * `crypto.timingSafeEqual` to avoid leaking information through
+ * response timing.
+ *
+ * @param password - The plaintext password to verify
+ * @param hash - The hex-encoded hash to compare against
+ * @param salt - The hex-encoded salt that was used to produce the hash
+ * @returns `true` if the password matches, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyPassword('my-secret-password', storedHash, storedSalt)
+ * if (isValid) {
+ *   // Grant access
+ * }
+ * ```
+ */
+declare function verifyPassword(password: string, hash: string, salt: string): Promise<boolean>;
+
+/**
+ * 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;
+        deviceId: string;
+    } | null>;
+    /**
+     * Look up a user by ID.
+     *
+     * @param userId - The user's ID
+     * @returns The user profile, or null if not found
+     */
+    getUser(userId: string): Promise<AuthUser | null>;
+    /**
+     * Revoke a device. Requires a valid access token for authorization.
+     *
+     * @param accessToken - The caller's access token
+     * @param deviceId - The ID of the device to revoke
+     * @throws If the token is invalid or the device does not belong to the caller
+     */
+    revokeDevice(accessToken: string, deviceId: string): Promise<void>;
+    /**
+     * List all devices for the authenticated user.
+     *
+     * @param accessToken - The caller's access token
+     * @returns Array of device records
+     * @throws If the token is invalid
+     */
+    listDevices(accessToken: string): Promise<AuthDevice[]>;
+}
+/**
+ * Error thrown by provider adapter methods when an operation fails.
+ * Wraps the HTTP-style status and error message from route handlers
+ * into an exception for use in the adapter pattern.
+ */
+declare class AuthProviderError extends Error {
+    /** HTTP-style status code */
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Built-in authentication provider implementing email/password authentication.
+ *
+ * Wraps {@link BuiltInAuthRoutes} in the {@link AuthProviderAdapter} interface,
+ * converting HTTP-style responses into direct return values and exceptions.
+ * This is the default provider shipped with Kora and is suitable for
+ * applications that want simple email/password auth without external services.
+ *
+ * @example
+ * ```typescript
+ * import { BuiltInProvider } from '@korajs/auth'
+ * import { InMemoryUserStore } from '@korajs/auth'
+ * import { TokenManager } from '@korajs/auth'
+ *
+ * const provider = new BuiltInProvider({
+ *   userStore: new InMemoryUserStore(),
+ *   tokenManager: new TokenManager({ secret: process.env.AUTH_SECRET }),
+ * })
+ *
+ * const { user, tokens } = await provider.signUp({
+ *   email: 'alice@example.com',
+ *   password: 'strong-password-123',
+ *   name: 'Alice',
+ * })
+ * ```
+ */
+declare class BuiltInProvider implements AuthProviderAdapter {
+    private readonly routes;
+    private readonly tokenManager;
+    private readonly userStore;
+    constructor(config: AuthRoutesConfig);
+    /** @inheritdoc */
+    signUp(params: SignUpParams): Promise<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>;
+    /** @inheritdoc */
+    signIn(params: SignInParams): Promise<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>;
+    /** @inheritdoc */
+    refreshTokens(refreshToken: string): Promise<AuthTokens>;
+    /** @inheritdoc */
+    validateAccessToken(token: string): Promise<{
+        userId: string;
+        deviceId: string;
+    } | null>;
+    /** @inheritdoc */
+    getUser(userId: string): Promise<AuthUser | null>;
+    /** @inheritdoc */
+    revokeDevice(accessToken: string, deviceId: string): Promise<void>;
+    /** @inheritdoc */
+    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 };