@korajs/auth 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,7 +1,148 @@
-export { A as AuthClient, a as AuthClientConfig, b as AuthError, c as AuthState, d as AuthUser } from './auth-client-CrDNuh10.js';
-import { A as AuthTokens } from './device-identity-DiwdLsUB.js';
-export { a as AuthConfig, b as AuthEvent, c as AuthEventType, d as AuthStatus, C as CryptoUnavailableError, D as DeviceIdentityError, T as TokenPayload, e as TokenType, f as computePublicKeyThumbprint, g as exportPublicKeyJwk, h as fromBase64Url, i as generateDeviceKeyPair, s as signChallenge, t as toBase64Url, v as verifyChallenge } from './device-identity-DiwdLsUB.js';
-import '@korajs/core';
+export { A as AuthClient, a as AuthClientConfig, b as AuthError, c as AuthState, d as AuthUser, C as ClientInvitation, e as ClientMembership, f as ClientOrganization, O as OrgClient, g as OrgClientConfig, h as OrgClientError } from './org-client-BVTLKcIk.js';
+import { A as AuthTokens } from './operation-encryptor-DRmKNWpF.js';
+export { a as AuthConfig, b as AuthEvent, c as AuthEventType, d as AuthStatus, C as CryptoUnavailableError, D as DeviceIdentityError, O as OperationEncryptionError, e as OperationEncryptor, f as OperationEncryptorConfig, T as TokenPayload, g as TokenType, h as computePublicKeyThumbprint, i as exportPublicKeyJwk, j as fromBase64Url, k as generateDeviceKeyPair, l as isEncryptedField, s as signChallenge, t as toBase64Url, v as verifyChallenge } from './operation-encryptor-DRmKNWpF.js';
+import { KoraError } from '@korajs/core';
+
+/**
+ * Thrown when a device key store operation fails.
+ * Provides context about the operation and the underlying cause.
+ */
+declare class DeviceKeyStoreError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Persistent storage interface for ECDSA P-256 device key pairs.
+ *
+ * Device key pairs are used for proof-of-possession authentication:
+ * the private key never leaves the device, and the public key is
+ * registered with the server. This store persists key pairs across
+ * page reloads and app restarts.
+ *
+ * In the browser, CryptoKey objects are structured-cloneable, so they
+ * can be stored directly in IndexedDB without serialization. In Node.js
+ * or test environments, an in-memory implementation is used instead.
+ */
+interface DeviceKeyStore {
+    /**
+     * Persist a key pair for the given device.
+     *
+     * Overwrites any previously stored key pair for the same device ID.
+     *
+     * @param deviceId - The unique device identifier (typically a UUID v7)
+     * @param keyPair - The ECDSA P-256 CryptoKeyPair to store
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    saveKeyPair(deviceId: string, keyPair: CryptoKeyPair): Promise<void>;
+    /**
+     * Load a previously stored key pair for the given device.
+     *
+     * @param deviceId - The unique device identifier
+     * @returns The stored CryptoKeyPair, or null if no key pair exists for the device
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    loadKeyPair(deviceId: string): Promise<CryptoKeyPair | null>;
+    /**
+     * Delete a stored key pair for the given device.
+     *
+     * No-op if no key pair exists for the device ID.
+     *
+     * @param deviceId - The unique device identifier
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    deleteKeyPair(deviceId: string): Promise<void>;
+    /**
+     * Check whether a key pair exists for the given device.
+     *
+     * @param deviceId - The unique device identifier
+     * @returns True if a key pair is stored for the device, false otherwise
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    hasKeyPair(deviceId: string): Promise<boolean>;
+}
+/**
+ * Browser-based device key store backed by IndexedDB.
+ *
+ * CryptoKey objects are structured-cloneable, so they can be stored
+ * directly in IndexedDB without needing to export/import them as JWK.
+ * This preserves the non-extractable flag on private keys, ensuring
+ * they cannot be read even from storage.
+ *
+ * The database uses a single object store (`keypairs`) with the device ID
+ * as the key and the full CryptoKeyPair as the value.
+ *
+ * @example
+ * ```typescript
+ * const store = new IndexedDBDeviceKeyStore()
+ * const keyPair = await generateDeviceKeyPair()
+ * await store.saveKeyPair('device-123', keyPair)
+ *
+ * const loaded = await store.loadKeyPair('device-123')
+ * // loaded.privateKey is still non-extractable
+ * ```
+ */
+declare class IndexedDBDeviceKeyStore implements DeviceKeyStore {
+    private dbPromise;
+    /**
+     * Opens (or creates) the IndexedDB database.
+     *
+     * The database connection is lazily initialized on first use and
+     * reused for subsequent operations. If the database does not exist,
+     * it is created with the `keypairs` object store.
+     */
+    private openDatabase;
+    /** @inheritdoc */
+    saveKeyPair(deviceId: string, keyPair: CryptoKeyPair): Promise<void>;
+    /** @inheritdoc */
+    loadKeyPair(deviceId: string): Promise<CryptoKeyPair | null>;
+    /** @inheritdoc */
+    deleteKeyPair(deviceId: string): Promise<void>;
+    /** @inheritdoc */
+    hasKeyPair(deviceId: string): Promise<boolean>;
+}
+/**
+ * In-memory device key store for Node.js and testing environments.
+ *
+ * Key pairs are stored in a plain Map and do not survive process restarts.
+ * This is suitable for server-side rendering, Node.js scripts, and unit tests
+ * where IndexedDB is not available.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryDeviceKeyStore()
+ * const keyPair = await generateDeviceKeyPair()
+ * await store.saveKeyPair('device-123', keyPair)
+ *
+ * const loaded = await store.loadKeyPair('device-123')
+ * ```
+ */
+declare class InMemoryDeviceKeyStore implements DeviceKeyStore {
+    private readonly store;
+    /** @inheritdoc */
+    saveKeyPair(deviceId: string, keyPair: CryptoKeyPair): Promise<void>;
+    /** @inheritdoc */
+    loadKeyPair(deviceId: string): Promise<CryptoKeyPair | null>;
+    /** @inheritdoc */
+    deleteKeyPair(deviceId: string): Promise<void>;
+    /** @inheritdoc */
+    hasKeyPair(deviceId: string): Promise<boolean>;
+}
+/**
+ * Creates a DeviceKeyStore appropriate for the current environment.
+ *
+ * In browsers where IndexedDB is available, returns an {@link IndexedDBDeviceKeyStore}
+ * that persists CryptoKeyPair objects as structured clones. In Node.js, SSR,
+ * or environments without IndexedDB, returns an {@link InMemoryDeviceKeyStore}.
+ *
+ * @returns A DeviceKeyStore instance for the current environment
+ *
+ * @example
+ * ```typescript
+ * const store = createDeviceKeyStore()
+ * const keyPair = await generateDeviceKeyPair()
+ * await store.saveKeyPair(deviceId, keyPair)
+ * ```
+ */
+declare function createDeviceKeyStore(): DeviceKeyStore;
 
 /**
  * Client-side token storage for Kora auth tokens.
@@ -77,4 +218,566 @@ declare class TokenStore {
     getRefreshToken(): string | null;
 }
 
-export { AuthTokens, TokenStore };
+/**
+ * Thrown when encrypted token storage operations fail.
+ * Includes context about what went wrong to aid debugging without
+ * exposing sensitive key or token material.
+ */
+declare class EncryptedTokenStoreError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Configuration for the encrypted token store.
+ */
+interface EncryptedTokenStoreConfig {
+    /**
+     * Storage key prefix. Defaults to 'kora_auth_encrypted'.
+     * Use different keys if your app runs multiple Kora instances with separate auth.
+     */
+    storageKey?: string;
+    /**
+     * The AES-256-GCM CryptoKey used to encrypt and decrypt tokens.
+     *
+     * This can be:
+     * - A key derived from a user passphrase via {@link deriveEncryptionKey}
+     * - A device-derived key (e.g., from secure hardware or biometric unlock)
+     * - A randomly generated key from {@link generateEncryptionKey}
+     *
+     * The caller is responsible for obtaining the key before constructing the store.
+     */
+    key: CryptoKey;
+}
+/**
+ * Encrypted token store that protects auth tokens at rest.
+ *
+ * Addresses the security vulnerability of storing tokens in plaintext localStorage,
+ * which is accessible to any JavaScript running on the page (XSS attack surface).
+ * Tokens are encrypted with AES-256-GCM before being written to storage.
+ *
+ * The stored format is a JSON string with two base64url-encoded fields:
+ * - `iv`: the 12-byte initialization vector (unique per encryption)
+ * - `data`: the AES-256-GCM ciphertext of the JSON-serialized tokens
+ *
+ * AES-GCM provides both confidentiality (tokens are unreadable without the key)
+ * and integrity (tampered ciphertext is detected and rejected).
+ *
+ * @example
+ * ```typescript
+ * import { deriveEncryptionKey } from '@korajs/auth'
+ *
+ * // Derive a key from the user's passphrase
+ * const { key } = await deriveEncryptionKey('user-passphrase', storedSalt)
+ *
+ * const store = new EncryptedTokenStore({ key })
+ *
+ * // After login: encrypt and persist tokens
+ * await store.saveTokens({ accessToken: '...', refreshToken: '...' })
+ *
+ * // Before API calls: decrypt and retrieve
+ * const accessToken = await store.getAccessToken()
+ *
+ * // On logout: remove encrypted data
+ * store.clearTokens()
+ * ```
+ */
+declare class EncryptedTokenStore {
+    private readonly storageKey;
+    private readonly key;
+    private readonly storage;
+    /**
+     * Creates a new EncryptedTokenStore instance.
+     *
+     * @param config - Configuration including the encryption key and optional storage key
+     */
+    constructor(config: EncryptedTokenStoreConfig);
+    /**
+     * Encrypt and save tokens to persistent storage.
+     *
+     * Serializes the tokens as JSON, encrypts with AES-256-GCM using a fresh
+     * random IV, then stores the result as a JSON object containing the
+     * base64url-encoded IV and ciphertext.
+     *
+     * Overwrites any previously stored tokens.
+     *
+     * @param tokens - The token set to encrypt and store
+     * @throws {EncryptedTokenStoreError} If encryption fails
+     */
+    saveTokens(tokens: AuthTokens): Promise<void>;
+    /**
+     * Load and decrypt tokens from storage.
+     *
+     * Reads the encrypted payload from localStorage, decodes the base64url IV
+     * and ciphertext, decrypts with AES-256-GCM, and parses the resulting JSON.
+     *
+     * Returns null (without throwing) if:
+     * - No tokens have been saved
+     * - The stored data is corrupted or not valid JSON
+     * - Decryption fails (wrong key, tampered ciphertext, or wrong IV)
+     * - The decrypted data does not contain valid token fields
+     *
+     * This fail-silent design prevents decryption errors from crashing the
+     * application. The caller should treat null as "no valid tokens available"
+     * and initiate a re-authentication flow.
+     *
+     * @returns The decrypted {@link AuthTokens}, or null if unavailable or decryption fails
+     */
+    loadTokens(): Promise<AuthTokens | null>;
+    /**
+     * Clear all stored encrypted tokens.
+     *
+     * Removes the encrypted payload from storage. This is a synchronous
+     * operation since it only removes the localStorage entry.
+     *
+     * Call this on logout to ensure no encrypted credential material
+     * remains in persistent storage.
+     */
+    clearTokens(): void;
+    /**
+     * Get the current access token by decrypting stored tokens.
+     *
+     * Returns the raw token string without validating expiration.
+     * The caller is responsible for checking whether the token is
+     * still valid and initiating a refresh if needed.
+     *
+     * @returns The decrypted access token string, or null if no valid tokens are stored
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get the current refresh token by decrypting stored tokens.
+     *
+     * @returns The decrypted refresh token string, or null if no valid tokens are stored
+     */
+    getRefreshToken(): Promise<string | null>;
+}
+
+/**
+ * Thrown when a passkey operation fails (registration, authentication,
+ * or browser API interaction).
+ */
+declare class PasskeyError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when the browser does not support WebAuthn.
+ * Passkey authentication requires a modern browser with the
+ * Web Authentication API (navigator.credentials).
+ */
+declare class PasskeyUnsupportedError extends KoraError {
+    constructor();
+}
+/** Response from a passkey registration (credential creation). */
+interface PasskeyRegistrationResponse {
+    /** Base64url-encoded credential ID */
+    credentialId: string;
+    /** Base64url-encoded public key (COSE format) */
+    publicKey: string;
+    /** Base64url-encoded clientDataJSON */
+    clientDataJSON: string;
+    /** Base64url-encoded attestation object */
+    attestationObject: string;
+}
+/** Response from a passkey authentication (assertion). */
+interface PasskeyAuthenticationResponse {
+    /** Base64url-encoded credential ID */
+    credentialId: string;
+    /** Base64url-encoded authenticator data */
+    authenticatorData: string;
+    /** Base64url-encoded clientDataJSON */
+    clientDataJSON: string;
+    /** Base64url-encoded ECDSA signature */
+    signature: string;
+    /** Base64url-encoded user handle (may be null for non-resident keys) */
+    userHandle: string | null;
+}
+/**
+ * Check if WebAuthn/passkeys are supported in the current environment.
+ *
+ * Returns true if the `navigator.credentials` API is available and supports
+ * the `create` and `get` methods required for WebAuthn.
+ *
+ * @returns `true` if WebAuthn is available, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPasskeySupported()) {
+ *   // Show passkey login option
+ * }
+ * ```
+ */
+declare function isPasskeySupported(): boolean;
+/**
+ * Check if a platform authenticator (biometric) is available.
+ *
+ * A platform authenticator is built into the device (Touch ID, Face ID,
+ * Windows Hello). Returns false if only roaming authenticators (security
+ * keys) are available, or if WebAuthn is not supported.
+ *
+ * @returns `true` if a platform authenticator is available
+ *
+ * @example
+ * ```typescript
+ * if (await isPlatformAuthenticatorAvailable()) {
+ *   // Show "Sign in with Touch ID" button
+ * }
+ * ```
+ */
+declare function isPlatformAuthenticatorAvailable(): Promise<boolean>;
+/**
+ * Create a passkey credential (registration flow).
+ *
+ * Called during user registration. The server provides a challenge and user info,
+ * the browser prompts for biometric verification, and this function returns the
+ * credential data to send back to the server for verification.
+ *
+ * @param options - Registration options from the server
+ * @param options.challenge - Base64url-encoded challenge from server
+ * @param options.rpId - Relying party ID (your domain, e.g. "example.com")
+ * @param options.rpName - Relying party display name (e.g. "My App")
+ * @param options.userId - User ID as base64url-encoded opaque bytes
+ * @param options.userName - User's email or username for display
+ * @param options.userDisplayName - Human-readable display name
+ * @param options.excludeCredentialIds - Credential IDs to exclude (prevents re-registration)
+ * @param options.authenticatorSelection - Authenticator selection criteria
+ * @returns The credential response to send to the server for verification
+ * @throws {PasskeyUnsupportedError} If WebAuthn is not available
+ * @throws {PasskeyError} If credential creation fails or is cancelled by the user
+ *
+ * @example
+ * ```typescript
+ * const credential = await createPasskeyCredential({
+ *   challenge: serverOptions.challenge,
+ *   rpId: 'example.com',
+ *   rpName: 'My App',
+ *   userId: serverOptions.userId,
+ *   userName: 'alice@example.com',
+ *   userDisplayName: 'Alice',
+ * })
+ * // Send `credential` to server for verification
+ * ```
+ */
+declare function createPasskeyCredential(options: {
+    challenge: string;
+    rpId: string;
+    rpName: string;
+    userId: string;
+    userName: string;
+    userDisplayName: string;
+    excludeCredentialIds?: string[];
+    authenticatorSelection?: {
+        authenticatorAttachment?: 'platform' | 'cross-platform';
+        residentKey?: 'required' | 'preferred' | 'discouraged';
+        userVerification?: 'required' | 'preferred' | 'discouraged';
+    };
+}): Promise<PasskeyRegistrationResponse>;
+/**
+ * Authenticate with a passkey (assertion flow).
+ *
+ * Called during login. The server provides a challenge, the browser prompts
+ * for biometric verification, and this function returns the signed assertion
+ * to send back to the server for verification.
+ *
+ * @param options - Authentication options from the server
+ * @param options.challenge - Base64url-encoded challenge from server
+ * @param options.rpId - Relying party ID (your domain)
+ * @param options.allowCredentialIds - Limit authentication to specific credentials
+ * @param options.userVerification - User verification requirement (default: 'preferred')
+ * @param options.timeout - Timeout in milliseconds (default: 60000)
+ * @returns The assertion response to send to the server for verification
+ * @throws {PasskeyUnsupportedError} If WebAuthn is not available
+ * @throws {PasskeyError} If authentication fails or is cancelled by the user
+ *
+ * @example
+ * ```typescript
+ * const assertion = await authenticateWithPasskey({
+ *   challenge: serverOptions.challenge,
+ *   rpId: 'example.com',
+ * })
+ * // Send `assertion` to server for verification
+ * ```
+ */
+declare function authenticateWithPasskey(options: {
+    challenge: string;
+    rpId: string;
+    allowCredentialIds?: string[];
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+    timeout?: number;
+}): Promise<PasskeyAuthenticationResponse>;
+
+/**
+ * Thrown when an encryption or decryption operation fails.
+ * Includes context about what went wrong to aid debugging.
+ */
+declare class EncryptionError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Generates a random 256-bit AES-GCM encryption key.
+ *
+ * The key is extractable so it can be exported for persistence (e.g., encrypted
+ * with a passphrase-derived key and stored locally). Use {@link exportKey} to
+ * get the raw bytes.
+ *
+ * @returns A CryptoKey for AES-256-GCM encryption and decryption
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {EncryptionError} If key generation fails
+ *
+ * @example
+ * ```typescript
+ * const key = await generateEncryptionKey()
+ * // key can be used with encryptData() and decryptData()
+ * ```
+ */
+declare function generateEncryptionKey(): Promise<CryptoKey>;
+/**
+ * Encrypts data using AES-256-GCM with a randomly generated IV.
+ *
+ * Each call generates a fresh 12-byte IV, ensuring that encrypting the same
+ * plaintext twice produces different ciphertext. The IV must be stored alongside
+ * the ciphertext for decryption.
+ *
+ * AES-GCM provides both confidentiality and integrity: the ciphertext includes
+ * an authentication tag that detects tampering.
+ *
+ * @param key - An AES-256-GCM CryptoKey (from {@link generateEncryptionKey} or {@link importKey})
+ * @param plaintext - The data to encrypt
+ * @returns An object containing the ciphertext and the IV used for encryption
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {EncryptionError} If encryption fails
+ *
+ * @example
+ * ```typescript
+ * const key = await generateEncryptionKey()
+ * const data = new TextEncoder().encode('sensitive data')
+ * const { ciphertext, iv } = await encryptData(key, data)
+ * // Store ciphertext and iv together; both are needed for decryption
+ * ```
+ */
+declare function encryptData(key: CryptoKey, plaintext: Uint8Array): Promise<{
+    ciphertext: Uint8Array;
+    iv: Uint8Array;
+}>;
+/**
+ * Decrypts AES-256-GCM encrypted data.
+ *
+ * The IV must be the same one that was used during encryption. AES-GCM
+ * authenticates the ciphertext, so any tampering will cause decryption to fail.
+ *
+ * @param key - The AES-256-GCM CryptoKey used for encryption
+ * @param ciphertext - The encrypted data (from {@link encryptData})
+ * @param iv - The initialization vector used during encryption (from {@link encryptData})
+ * @returns The decrypted plaintext
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {EncryptionError} If decryption fails (wrong key, tampered ciphertext, or wrong IV)
+ *
+ * @example
+ * ```typescript
+ * const decrypted = await decryptData(key, ciphertext, iv)
+ * const text = new TextDecoder().decode(decrypted)
+ * ```
+ */
+declare function decryptData(key: CryptoKey, ciphertext: Uint8Array, iv: Uint8Array): Promise<Uint8Array>;
+/**
+ * Exports an AES-256-GCM CryptoKey to its raw byte representation.
+ *
+ * The raw key is 32 bytes (256 bits). This is useful for persisting the key
+ * (e.g., encrypting it with a passphrase-derived key before storing to disk).
+ *
+ * **Security warning:** Raw key bytes are sensitive material. Never log them,
+ * store them in plaintext, or transmit them over the network without encryption.
+ *
+ * @param key - An extractable AES-256-GCM CryptoKey
+ * @returns The raw key bytes (32 bytes for AES-256)
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {EncryptionError} If the key export fails (e.g., key is not extractable)
+ *
+ * @example
+ * ```typescript
+ * const key = await generateEncryptionKey()
+ * const rawBytes = await exportKey(key)
+ * // rawBytes.length === 32
+ * ```
+ */
+declare function exportKey(key: CryptoKey): Promise<Uint8Array>;
+/**
+ * Imports raw key bytes into an AES-256-GCM CryptoKey.
+ *
+ * The input must be exactly 32 bytes (256 bits). The imported key is extractable
+ * and supports both encrypt and decrypt operations.
+ *
+ * @param rawKey - Raw key bytes (must be exactly 32 bytes for AES-256)
+ * @returns A CryptoKey for AES-256-GCM operations
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {EncryptionError} If the raw key is invalid or import fails
+ *
+ * @example
+ * ```typescript
+ * const rawBytes = new Uint8Array(32) // previously exported key bytes
+ * const key = await importKey(rawBytes)
+ * // key can now be used with encryptData() and decryptData()
+ * ```
+ */
+declare function importKey(rawKey: Uint8Array): Promise<CryptoKey>;
+
+/**
+ * Thrown when a key derivation operation fails.
+ */
+declare class KeyDerivationError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Generates a cryptographically random 32-byte salt for key derivation.
+ *
+ * Each call returns a unique salt. The salt should be stored alongside the
+ * encrypted data so that the same passphrase can reproduce the same key later.
+ *
+ * @returns A random 32-byte Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const salt = generateSalt()
+ * // salt.length === 32
+ * ```
+ */
+declare function generateSalt(): Uint8Array;
+/**
+ * Derives an AES-256-GCM encryption key from a passphrase using PBKDF2.
+ *
+ * Uses PBKDF2 with SHA-256 and 600,000 iterations (OWASP-recommended minimum)
+ * to derive a 256-bit key from the passphrase. The derived key can be used with
+ * the database encryption functions ({@link encryptData}, {@link decryptData}).
+ *
+ * If no salt is provided, a random 32-byte salt is generated. The salt must be
+ * persisted alongside the encrypted data so the key can be re-derived later.
+ *
+ * **Deterministic:** The same passphrase and salt always produce the same key.
+ * This is essential for decryption: the user enters their passphrase, the stored
+ * salt is used, and the identical key is re-derived to decrypt the data.
+ *
+ * @param passphrase - The user's passphrase (any non-empty string)
+ * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @returns An object containing the derived CryptoKey and the salt used
+ * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
+ *
+ * @example
+ * ```typescript
+ * // First time: derive key with a new salt
+ * const { key, salt } = await deriveEncryptionKey('my-secure-passphrase')
+ * // Store the salt alongside the encrypted data
+ *
+ * // Later: re-derive the same key using the stored salt
+ * const { key: sameKey } = await deriveEncryptionKey('my-secure-passphrase', salt)
+ * ```
+ */
+declare function deriveEncryptionKey(passphrase: string, salt?: Uint8Array): Promise<{
+    key: CryptoKey;
+    salt: Uint8Array;
+}>;
+
+/**
+ * Configuration for the AutoLockManager.
+ */
+interface AutoLockConfig {
+    /** Inactivity timeout in milliseconds before auto-locking. */
+    timeout: number;
+    /** Callback invoked when the lock engages (either by timeout or manual lock). */
+    onLock: () => void;
+}
+/**
+ * Manages inactivity-based auto-locking for the encrypted local store.
+ *
+ * The AutoLockManager starts an inactivity timer when {@link start} is called.
+ * If no user activity is reported via {@link reportActivity} within the configured
+ * timeout, the manager transitions to the locked state and invokes the `onLock`
+ * callback.
+ *
+ * This class has no DOM dependencies. It uses `setTimeout` and `clearTimeout` for
+ * timing and accepts an `onLock` callback for side effects. The consuming code is
+ * responsible for wiring DOM events (e.g., visibility changes, user interactions)
+ * to {@link reportActivity}.
+ *
+ * @example
+ * ```typescript
+ * const manager = new AutoLockManager({
+ *   timeout: 15 * 60 * 1000, // 15 minutes
+ *   onLock: () => {
+ *     // Clear decrypted data from memory
+ *     // Show lock screen
+ *   }
+ * })
+ *
+ * manager.start()
+ *
+ * // Call on user interactions to reset the timer
+ * document.addEventListener('click', () => manager.reportActivity())
+ * document.addEventListener('keydown', () => manager.reportActivity())
+ *
+ * // Check lock state
+ * if (manager.isLocked) {
+ *   // Prompt for passphrase
+ * }
+ * ```
+ */
+declare class AutoLockManager {
+    private readonly _timeout;
+    private readonly _onLock;
+    private _timerId;
+    private _isLocked;
+    private _isRunning;
+    constructor(config: AutoLockConfig);
+    /**
+     * Whether the manager is currently in the locked state.
+     *
+     * Becomes `true` when the inactivity timeout fires or {@link lock} is called manually.
+     * Returns to `false` only when {@link unlock} is called.
+     */
+    get isLocked(): boolean;
+    /**
+     * Starts monitoring for inactivity.
+     *
+     * Begins the inactivity countdown. If the manager is already running, this is
+     * a no-op to prevent creating multiple timers. Calling `start()` also resets
+     * the locked state if the manager was previously locked.
+     */
+    start(): void;
+    /**
+     * Stops monitoring for inactivity.
+     *
+     * Clears the pending inactivity timer. Does not change the lock state: if
+     * the manager was locked, it remains locked. If unlocked, it remains unlocked.
+     * To resume monitoring, call {@link start} again.
+     */
+    stop(): void;
+    /**
+     * Reports user activity, resetting the inactivity timer.
+     *
+     * Call this whenever the user interacts with the application (clicks, key presses,
+     * touches, etc.). If the manager is not running or is already locked, this is a no-op.
+     */
+    reportActivity(): void;
+    /**
+     * Manually locks the manager immediately.
+     *
+     * Clears the inactivity timer and transitions to the locked state. The `onLock`
+     * callback is invoked. The manager remains running but locked: call {@link unlock}
+     * to return to the unlocked state, which will restart the inactivity timer.
+     */
+    lock(): void;
+    /**
+     * Unlocks the manager, returning to the unlocked state.
+     *
+     * If the manager is running, the inactivity timer is restarted. If the manager
+     * is not running (was stopped), it simply clears the locked state without
+     * starting a timer.
+     */
+    unlock(): void;
+    /**
+     * Starts the inactivity timer. When it fires, the manager locks.
+     */
+    private _startTimer;
+    /**
+     * Clears the pending inactivity timer, if any.
+     */
+    private _clearTimer;
+}
+
+export { AuthTokens, type AutoLockConfig, AutoLockManager, type DeviceKeyStore, DeviceKeyStoreError, EncryptedTokenStore, type EncryptedTokenStoreConfig, EncryptedTokenStoreError, EncryptionError, InMemoryDeviceKeyStore, IndexedDBDeviceKeyStore, KeyDerivationError, type PasskeyAuthenticationResponse, PasskeyError, type PasskeyRegistrationResponse, PasskeyUnsupportedError, TokenStore, authenticateWithPasskey, createDeviceKeyStore, createPasskeyCredential, decryptData, deriveEncryptionKey, encryptData, exportKey, generateEncryptionKey, generateSalt, importKey, isPasskeySupported, isPlatformAuthenticatorAvailable };