@korajs/auth 0.1.0

package/dist/chunk-L554ZDPY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/device/device-identity.ts"],"sourcesContent":["import { KoraError } from '@korajs/core'\n\n// --- Auth-specific errors ---\n\n/**\n * Thrown when the Web Crypto API is not available in the current environment.\n * This can happen in older Node.js versions or SSR environments without crypto support.\n */\nexport class CryptoUnavailableError extends KoraError {\n\tconstructor() {\n\t\tsuper(\n\t\t\t'Web Crypto API (crypto.subtle) is not available in this environment. ' +\n\t\t\t\t'Device identity requires crypto.subtle, which is available in modern browsers and Node.js 20+. ' +\n\t\t\t\t'If running in SSR, ensure your runtime provides the Web Crypto API.',\n\t\t\t'CRYPTO_UNAVAILABLE',\n\t\t)\n\t\tthis.name = 'CryptoUnavailableError'\n\t}\n}\n\n/**\n * Thrown when a device identity operation fails (key generation, signing, verification).\n */\nexport class DeviceIdentityError extends KoraError {\n\tconstructor(message: string, context?: Record<string, unknown>) {\n\t\tsuper(message, 'DEVICE_IDENTITY_ERROR', context)\n\t\tthis.name = 'DeviceIdentityError'\n\t}\n}\n\n// --- Encoding helpers ---\n\n/**\n * Encodes an ArrayBuffer as a base64url string (no padding).\n *\n * @param buffer - The binary data to encode\n * @returns A base64url-encoded string without padding characters\n */\nexport function toBase64Url(buffer: ArrayBuffer): string {\n\tconst bytes = new Uint8Array(buffer)\n\tlet binary = ''\n\tfor (let i = 0; i < bytes.length; i++) {\n\t\tbinary += String.fromCharCode(bytes[i] as number)\n\t}\n\t// Standard base64, then convert to base64url (no padding)\n\treturn btoa(binary).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')\n}\n\n/**\n * Decodes a base64url string (no padding) into a Uint8Array.\n *\n * @param str - A base64url-encoded string (with or without padding)\n * @returns The decoded binary data as a Uint8Array\n */\nexport function fromBase64Url(str: string): Uint8Array {\n\t// Convert base64url back to standard base64\n\tlet base64 = str.replace(/-/g, '+').replace(/_/g, '/')\n\t// Add padding if necessary\n\tconst paddingNeeded = (4 - (base64.length % 4)) % 4\n\tbase64 += '='.repeat(paddingNeeded)\n\n\tconst binary = atob(base64)\n\tconst bytes = new Uint8Array(binary.length)\n\tfor (let i = 0; i < binary.length; i++) {\n\t\tbytes[i] = binary.charCodeAt(i)\n\t}\n\treturn bytes\n}\n\n// --- Internal helpers ---\n\n/**\n * Asserts that `crypto.subtle` is available, throwing a clear error if not.\n */\nfunction assertCryptoAvailable(): void {\n\tif (\n\t\ttypeof globalThis.crypto === 'undefined' ||\n\t\ttypeof globalThis.crypto.subtle === 'undefined'\n\t) {\n\t\tthrow new CryptoUnavailableError()\n\t}\n}\n\n/** ECDSA algorithm parameters used throughout the module. */\nconst ECDSA_ALGORITHM: EcKeyGenParams = {\n\tname: 'ECDSA',\n\tnamedCurve: 'P-256',\n}\n\n/** Signing algorithm parameters: ECDSA with SHA-256. */\nconst ECDSA_SIGN_ALGORITHM: EcdsaParams = {\n\tname: 'ECDSA',\n\thash: { name: 'SHA-256' },\n}\n\n// --- Public API ---\n\n/**\n * Generates an ECDSA P-256 key pair for device identity.\n *\n * The private key is marked as non-extractable, ensuring it cannot be\n * exported from the browser's crypto subsystem. This provides\n * proof-of-possession: only code running on this device can sign with the key.\n *\n * @returns A CryptoKeyPair containing the public and private ECDSA P-256 keys\n * @throws {CryptoUnavailableError} If `crypto.subtle` is not available\n * @throws {DeviceIdentityError} If key generation fails\n *\n * @example\n * ```typescript\n * const keyPair = await generateDeviceKeyPair()\n * // keyPair.publicKey can be exported; keyPair.privateKey stays on device\n * ```\n */\nexport async function generateDeviceKeyPair(): Promise<CryptoKeyPair> {\n\tassertCryptoAvailable()\n\n\ttry {\n\t\tconst keyPair = await globalThis.crypto.subtle.generateKey(\n\t\t\tECDSA_ALGORITHM,\n\t\t\t// extractable: false makes the private key non-extractable.\n\t\t\t// The public key is always extractable regardless of this flag.\n\t\t\tfalse,\n\t\t\t['sign', 'verify'],\n\t\t)\n\t\treturn keyPair\n\t} catch (cause) {\n\t\tthrow new DeviceIdentityError(\n\t\t\t'Failed to generate ECDSA P-256 device key pair. ' +\n\t\t\t\t'Ensure the runtime supports the ECDSA algorithm with the P-256 curve.',\n\t\t\t{ cause: cause instanceof Error ? cause.message : String(cause) },\n\t\t)\n\t}\n}\n\n/**\n * Exports the public key from a key pair as a JSON Web Key (JWK).\n *\n * The JWK can be safely transmitted to a server or other devices to identify\n * this device. It contains only the public component of the key pair.\n *\n * @param keyPair - The CryptoKeyPair whose public key should be exported\n * @returns The public key in JWK format\n * @throws {CryptoUnavailableError} If `crypto.subtle` is not available\n * @throws {DeviceIdentityError} If the export operation fails\n *\n * @example\n * ```typescript\n * const keyPair = await generateDeviceKeyPair()\n * const jwk = await exportPublicKeyJwk(keyPair)\n * // jwk contains { kty: 'EC', crv: 'P-256', x: '...', y: '...' }\n * ```\n */\nexport async function exportPublicKeyJwk(keyPair: CryptoKeyPair): Promise<JsonWebKey> {\n\tassertCryptoAvailable()\n\n\ttry {\n\t\tconst jwk = await globalThis.crypto.subtle.exportKey('jwk', keyPair.publicKey)\n\t\treturn jwk\n\t} catch (cause) {\n\t\tthrow new DeviceIdentityError(\n\t\t\t'Failed to export public key as JWK. ' +\n\t\t\t\t'The key pair may be invalid or the public key may not support JWK export.',\n\t\t\t{ cause: cause instanceof Error ? cause.message : String(cause) },\n\t\t)\n\t}\n}\n\n/**\n * Signs a challenge string with the device's private key.\n *\n * Used for proof-of-possession during authentication: the server sends a\n * random challenge, and the device proves it holds the private key by signing it.\n *\n * @param privateKey - The device's private CryptoKey (ECDSA P-256)\n * @param challenge - The challenge string to sign (typically a random nonce from the server)\n * @returns A base64url-encoded ECDSA signature (no padding)\n * @throws {CryptoUnavailableError} If `crypto.subtle` is not available\n * @throws {DeviceIdentityError} If the signing operation fails\n *\n * @example\n * ```typescript\n * const keyPair = await generateDeviceKeyPair()\n * const signature = await signChallenge(keyPair.privateKey, 'server-nonce-abc123')\n * // signature is a base64url string like 'MEUCIQDx...'\n * ```\n */\nexport async function signChallenge(privateKey: CryptoKey, challenge: string): Promise<string> {\n\tassertCryptoAvailable()\n\n\ttry {\n\t\tconst encoded = new TextEncoder().encode(challenge)\n\t\tconst signatureBuffer = await globalThis.crypto.subtle.sign(\n\t\t\tECDSA_SIGN_ALGORITHM,\n\t\t\tprivateKey,\n\t\t\tencoded,\n\t\t)\n\t\treturn toBase64Url(signatureBuffer)\n\t} catch (cause) {\n\t\tthrow new DeviceIdentityError(\n\t\t\t'Failed to sign challenge. ' +\n\t\t\t\t'Ensure the key is a valid ECDSA P-256 private key with \"sign\" usage.',\n\t\t\t{ cause: cause instanceof Error ? cause.message : String(cause) },\n\t\t)\n\t}\n}\n\n/**\n * Verifies a challenge signature against a public key.\n *\n * Used server-side (or on any verifying party) to confirm that a device\n * holds the private key corresponding to the given public key.\n *\n * @param publicKeyJwk - The device's public key in JWK format\n * @param challenge - The original challenge string that was signed\n * @param signature - The base64url-encoded signature to verify\n * @returns `true` if the signature is valid, `false` otherwise\n * @throws {CryptoUnavailableError} If `crypto.subtle` is not available\n * @throws {DeviceIdentityError} If the verification operation fails due to an invalid key or format\n *\n * @example\n * ```typescript\n * const isValid = await verifyChallenge(publicKeyJwk, 'server-nonce-abc123', signature)\n * if (isValid) {\n *   // Device proved possession of the private key\n * }\n * ```\n */\nexport async function verifyChallenge(\n\tpublicKeyJwk: JsonWebKey,\n\tchallenge: string,\n\tsignature: string,\n): Promise<boolean> {\n\tassertCryptoAvailable()\n\n\ttry {\n\t\tconst publicKey = await globalThis.crypto.subtle.importKey(\n\t\t\t'jwk',\n\t\t\tpublicKeyJwk,\n\t\t\tECDSA_ALGORITHM,\n\t\t\ttrue,\n\t\t\t['verify'],\n\t\t)\n\n\t\tconst encoded = new TextEncoder().encode(challenge)\n\t\tconst signatureBytes = fromBase64Url(signature)\n\n\t\tconst isValid = await globalThis.crypto.subtle.verify(\n\t\t\tECDSA_SIGN_ALGORITHM,\n\t\t\tpublicKey,\n\t\t\tsignatureBytes as unknown as ArrayBuffer,\n\t\t\tencoded,\n\t\t)\n\t\treturn isValid\n\t} catch (cause) {\n\t\tthrow new DeviceIdentityError(\n\t\t\t'Failed to verify challenge signature. ' +\n\t\t\t\t'The public key JWK or signature format may be invalid.',\n\t\t\t{\n\t\t\t\tcause: cause instanceof Error ? cause.message : String(cause),\n\t\t\t\tpublicKeyKty: publicKeyJwk.kty,\n\t\t\t\tpublicKeyCrv: publicKeyJwk.crv,\n\t\t\t},\n\t\t)\n\t}\n}\n\n/**\n * Computes a SHA-256 thumbprint of a JWK public key.\n *\n * The thumbprint is computed per RFC 7638: the JWK members required for the key\n * type are serialized in lexicographic order, then hashed with SHA-256. For EC keys\n * (kty: \"EC\"), the required members are `crv`, `kty`, `x`, and `y`.\n *\n * This thumbprint serves as a compact, stable identifier for the device's public key\n * (used as the `dpk` claim in device credentials).\n *\n * @param publicKeyJwk - The public key in JWK format (must be an EC P-256 key)\n * @returns A base64url-encoded SHA-256 thumbprint (no padding)\n * @throws {CryptoUnavailableError} If `crypto.subtle` is not available\n * @throws {DeviceIdentityError} If the thumbprint computation fails or the JWK is missing required fields\n *\n * @example\n * ```typescript\n * const keyPair = await generateDeviceKeyPair()\n * const jwk = await exportPublicKeyJwk(keyPair)\n * const thumbprint = await computePublicKeyThumbprint(jwk)\n * // thumbprint is a base64url string, e.g., 'NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs'\n * ```\n */\nexport async function computePublicKeyThumbprint(publicKeyJwk: JsonWebKey): Promise<string> {\n\tassertCryptoAvailable()\n\n\t// RFC 7638 requires specific members in lexicographic order for each key type.\n\t// For EC (kty: \"EC\"), the required members are: crv, kty, x, y.\n\tif (publicKeyJwk.kty !== 'EC') {\n\t\tthrow new DeviceIdentityError(\n\t\t\t`Expected JWK key type \"EC\" but received \"${publicKeyJwk.kty ?? 'undefined'}\". ` +\n\t\t\t\t'Only ECDSA public keys are supported for device identity.',\n\t\t\t{ kty: publicKeyJwk.kty },\n\t\t)\n\t}\n\n\tif (!publicKeyJwk.crv || !publicKeyJwk.x || !publicKeyJwk.y) {\n\t\tthrow new DeviceIdentityError(\n\t\t\t'JWK is missing required EC fields. ' +\n\t\t\t\t'An EC public key JWK must include \"crv\", \"x\", and \"y\" members.',\n\t\t\t{\n\t\t\t\thasCrv: Boolean(publicKeyJwk.crv),\n\t\t\t\thasX: Boolean(publicKeyJwk.x),\n\t\t\t\thasY: Boolean(publicKeyJwk.y),\n\t\t\t},\n\t\t)\n\t}\n\n\t// Build the canonical JSON with only the required members in lexicographic order.\n\t// Per RFC 7638, no whitespace, keys in sorted order.\n\tconst canonicalJson = JSON.stringify({\n\t\tcrv: publicKeyJwk.crv,\n\t\tkty: publicKeyJwk.kty,\n\t\tx: publicKeyJwk.x,\n\t\ty: publicKeyJwk.y,\n\t})\n\n\ttry {\n\t\tconst encoded = new TextEncoder().encode(canonicalJson)\n\t\tconst hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', encoded)\n\t\treturn toBase64Url(hashBuffer)\n\t} catch (cause) {\n\t\tthrow new DeviceIdentityError(\n\t\t\t'Failed to compute SHA-256 thumbprint of the public key JWK.',\n\t\t\t{ cause: cause instanceof Error ? cause.message : String(cause) },\n\t\t)\n\t}\n}\n"],"mappings":"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","names":[]}

package/dist/device-identity-DiwdLsUB.d.cts

@@ -0,0 +1,247 @@
+import { KoraError } from '@korajs/core';
+
+/**
+ * Authenticated user record.
+ * Represents the public-facing user identity returned by sign-in and sign-up flows.
+ */
+interface AuthUser {
+    /** Unique user identifier (UUID v7) */
+    id: string;
+    /** User's email address, used as the primary login credential */
+    email: string;
+    /** Display name */
+    name: string;
+    /** Timestamp of user creation (milliseconds since epoch) */
+    createdAt: number;
+    /** Timestamp of last profile update (milliseconds since epoch) */
+    updatedAt: number;
+}
+/** The three kinds of tokens issued by the auth system */
+type TokenType = 'access' | 'refresh' | 'device_credential';
+/**
+ * Base payload present in all JWT tokens.
+ * Fields follow standard JWT claim names.
+ */
+interface TokenPayload {
+    /** Subject: the user ID */
+    sub: string;
+    /** Device ID that this token was issued to */
+    dev: string;
+    /** Which kind of token this is */
+    type: TokenType;
+    /** Issued-at time (seconds since epoch, per JWT spec) */
+    iat: number;
+    /** Expiration time (seconds since epoch, per JWT spec) */
+    exp: number;
+}
+/**
+ * Bundle of tokens returned after successful authentication.
+ */
+interface AuthTokens {
+    /** Short-lived access token */
+    accessToken: string;
+    /** Long-lived refresh token */
+    refreshToken: string;
+    /** Optional device credential for offline operation */
+    deviceCredential?: string;
+}
+/** Supported auth provider types */
+type AuthProviderType = 'built-in' | 'custom';
+/** Unlock mechanism for encrypted local storage */
+type UnlockMethod = 'biometric' | 'passphrase' | 'both';
+/**
+ * Encryption settings for locally stored auth credentials.
+ */
+interface AuthEncryptionConfig {
+    /** Whether local credential encryption is enabled */
+    enabled: boolean;
+    /** How the user unlocks encrypted credentials */
+    unlock: UnlockMethod;
+    /** Milliseconds of inactivity before the app auto-locks. Defaults to 15 minutes. */
+    autoLockTimeout?: number;
+}
+/**
+ * Custom lifetimes for each token type.
+ * All values are in milliseconds.
+ */
+interface TokenLifetimeConfig {
+    /** Access token lifetime in ms. Default: 15 minutes. */
+    access?: number;
+    /** Refresh token lifetime in ms. Default: 90 days. */
+    refresh?: number;
+    /** Device credential lifetime in ms. Default: 90 days. */
+    deviceCredential?: number;
+}
+/**
+ * Configuration for the Kora auth system.
+ * Passed to the auth initializer to control provider, encryption, and token behavior.
+ */
+interface AuthConfig {
+    /** Which auth provider to use */
+    provider: AuthProviderType;
+    /** Local encryption settings for stored credentials */
+    encryption?: AuthEncryptionConfig;
+    /** Maximum time a device can operate offline without checking in (ms). Default: 30 days. */
+    maxOfflineDuration?: number;
+    /** Custom token lifetimes */
+    tokenLifetimes?: TokenLifetimeConfig;
+}
+/** Possible authentication states */
+type AuthStatus = 'authenticated' | 'unauthenticated' | 'locked';
+/**
+ * Events emitted by the auth system.
+ * These integrate with Kora's event system for DevTools observability.
+ */
+type AuthEvent = {
+    type: 'auth:signed-in';
+    user: AuthUser;
+} | {
+    type: 'auth:signed-out';
+} | {
+    type: 'auth:locked';
+} | {
+    type: 'auth:unlocked';
+    user: AuthUser;
+} | {
+    type: 'auth:token-refreshed';
+} | {
+    type: 'auth:device-revoked';
+    deviceId: string;
+} | {
+    type: 'auth:permission-changed';
+};
+/** Extract the event type string union from AuthEvent */
+type AuthEventType = AuthEvent['type'];
+
+/**
+ * Thrown when the Web Crypto API is not available in the current environment.
+ * This can happen in older Node.js versions or SSR environments without crypto support.
+ */
+declare class CryptoUnavailableError extends KoraError {
+    constructor();
+}
+/**
+ * Thrown when a device identity operation fails (key generation, signing, verification).
+ */
+declare class DeviceIdentityError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Encodes an ArrayBuffer as a base64url string (no padding).
+ *
+ * @param buffer - The binary data to encode
+ * @returns A base64url-encoded string without padding characters
+ */
+declare function toBase64Url(buffer: ArrayBuffer): string;
+/**
+ * Decodes a base64url string (no padding) into a Uint8Array.
+ *
+ * @param str - A base64url-encoded string (with or without padding)
+ * @returns The decoded binary data as a Uint8Array
+ */
+declare function fromBase64Url(str: string): Uint8Array;
+/**
+ * Generates an ECDSA P-256 key pair for device identity.
+ *
+ * The private key is marked as non-extractable, ensuring it cannot be
+ * exported from the browser's crypto subsystem. This provides
+ * proof-of-possession: only code running on this device can sign with the key.
+ *
+ * @returns A CryptoKeyPair containing the public and private ECDSA P-256 keys
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If key generation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * // keyPair.publicKey can be exported; keyPair.privateKey stays on device
+ * ```
+ */
+declare function generateDeviceKeyPair(): Promise<CryptoKeyPair>;
+/**
+ * Exports the public key from a key pair as a JSON Web Key (JWK).
+ *
+ * The JWK can be safely transmitted to a server or other devices to identify
+ * this device. It contains only the public component of the key pair.
+ *
+ * @param keyPair - The CryptoKeyPair whose public key should be exported
+ * @returns The public key in JWK format
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the export operation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * const jwk = await exportPublicKeyJwk(keyPair)
+ * // jwk contains { kty: 'EC', crv: 'P-256', x: '...', y: '...' }
+ * ```
+ */
+declare function exportPublicKeyJwk(keyPair: CryptoKeyPair): Promise<JsonWebKey>;
+/**
+ * Signs a challenge string with the device's private key.
+ *
+ * Used for proof-of-possession during authentication: the server sends a
+ * random challenge, and the device proves it holds the private key by signing it.
+ *
+ * @param privateKey - The device's private CryptoKey (ECDSA P-256)
+ * @param challenge - The challenge string to sign (typically a random nonce from the server)
+ * @returns A base64url-encoded ECDSA signature (no padding)
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the signing operation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * const signature = await signChallenge(keyPair.privateKey, 'server-nonce-abc123')
+ * // signature is a base64url string like 'MEUCIQDx...'
+ * ```
+ */
+declare function signChallenge(privateKey: CryptoKey, challenge: string): Promise<string>;
+/**
+ * Verifies a challenge signature against a public key.
+ *
+ * Used server-side (or on any verifying party) to confirm that a device
+ * holds the private key corresponding to the given public key.
+ *
+ * @param publicKeyJwk - The device's public key in JWK format
+ * @param challenge - The original challenge string that was signed
+ * @param signature - The base64url-encoded signature to verify
+ * @returns `true` if the signature is valid, `false` otherwise
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the verification operation fails due to an invalid key or format
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyChallenge(publicKeyJwk, 'server-nonce-abc123', signature)
+ * if (isValid) {
+ *   // Device proved possession of the private key
+ * }
+ * ```
+ */
+declare function verifyChallenge(publicKeyJwk: JsonWebKey, challenge: string, signature: string): Promise<boolean>;
+/**
+ * Computes a SHA-256 thumbprint of a JWK public key.
+ *
+ * The thumbprint is computed per RFC 7638: the JWK members required for the key
+ * type are serialized in lexicographic order, then hashed with SHA-256. For EC keys
+ * (kty: "EC"), the required members are `crv`, `kty`, `x`, and `y`.
+ *
+ * This thumbprint serves as a compact, stable identifier for the device's public key
+ * (used as the `dpk` claim in device credentials).
+ *
+ * @param publicKeyJwk - The public key in JWK format (must be an EC P-256 key)
+ * @returns A base64url-encoded SHA-256 thumbprint (no padding)
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the thumbprint computation fails or the JWK is missing required fields
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * const jwk = await exportPublicKeyJwk(keyPair)
+ * const thumbprint = await computePublicKeyThumbprint(jwk)
+ * // thumbprint is a base64url string, e.g., 'NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs'
+ * ```
+ */
+declare function computePublicKeyThumbprint(publicKeyJwk: JsonWebKey): Promise<string>;
+
+export { type AuthTokens as A, CryptoUnavailableError as C, DeviceIdentityError as D, type TokenPayload as T, type AuthConfig as a, type AuthEvent as b, type AuthEventType as c, type AuthStatus as d, type TokenType as e, computePublicKeyThumbprint as f, exportPublicKeyJwk as g, fromBase64Url as h, generateDeviceKeyPair as i, signChallenge as s, toBase64Url as t, verifyChallenge as v };

package/dist/device-identity-DiwdLsUB.d.ts

@@ -0,0 +1,247 @@
+import { KoraError } from '@korajs/core';
+
+/**
+ * Authenticated user record.
+ * Represents the public-facing user identity returned by sign-in and sign-up flows.
+ */
+interface AuthUser {
+    /** Unique user identifier (UUID v7) */
+    id: string;
+    /** User's email address, used as the primary login credential */
+    email: string;
+    /** Display name */
+    name: string;
+    /** Timestamp of user creation (milliseconds since epoch) */
+    createdAt: number;
+    /** Timestamp of last profile update (milliseconds since epoch) */
+    updatedAt: number;
+}
+/** The three kinds of tokens issued by the auth system */
+type TokenType = 'access' | 'refresh' | 'device_credential';
+/**
+ * Base payload present in all JWT tokens.
+ * Fields follow standard JWT claim names.
+ */
+interface TokenPayload {
+    /** Subject: the user ID */
+    sub: string;
+    /** Device ID that this token was issued to */
+    dev: string;
+    /** Which kind of token this is */
+    type: TokenType;
+    /** Issued-at time (seconds since epoch, per JWT spec) */
+    iat: number;
+    /** Expiration time (seconds since epoch, per JWT spec) */
+    exp: number;
+}
+/**
+ * Bundle of tokens returned after successful authentication.
+ */
+interface AuthTokens {
+    /** Short-lived access token */
+    accessToken: string;
+    /** Long-lived refresh token */
+    refreshToken: string;
+    /** Optional device credential for offline operation */
+    deviceCredential?: string;
+}
+/** Supported auth provider types */
+type AuthProviderType = 'built-in' | 'custom';
+/** Unlock mechanism for encrypted local storage */
+type UnlockMethod = 'biometric' | 'passphrase' | 'both';
+/**
+ * Encryption settings for locally stored auth credentials.
+ */
+interface AuthEncryptionConfig {
+    /** Whether local credential encryption is enabled */
+    enabled: boolean;
+    /** How the user unlocks encrypted credentials */
+    unlock: UnlockMethod;
+    /** Milliseconds of inactivity before the app auto-locks. Defaults to 15 minutes. */
+    autoLockTimeout?: number;
+}
+/**
+ * Custom lifetimes for each token type.
+ * All values are in milliseconds.
+ */
+interface TokenLifetimeConfig {
+    /** Access token lifetime in ms. Default: 15 minutes. */
+    access?: number;
+    /** Refresh token lifetime in ms. Default: 90 days. */
+    refresh?: number;
+    /** Device credential lifetime in ms. Default: 90 days. */
+    deviceCredential?: number;
+}
+/**
+ * Configuration for the Kora auth system.
+ * Passed to the auth initializer to control provider, encryption, and token behavior.
+ */
+interface AuthConfig {
+    /** Which auth provider to use */
+    provider: AuthProviderType;
+    /** Local encryption settings for stored credentials */
+    encryption?: AuthEncryptionConfig;
+    /** Maximum time a device can operate offline without checking in (ms). Default: 30 days. */
+    maxOfflineDuration?: number;
+    /** Custom token lifetimes */
+    tokenLifetimes?: TokenLifetimeConfig;
+}
+/** Possible authentication states */
+type AuthStatus = 'authenticated' | 'unauthenticated' | 'locked';
+/**
+ * Events emitted by the auth system.
+ * These integrate with Kora's event system for DevTools observability.
+ */
+type AuthEvent = {
+    type: 'auth:signed-in';
+    user: AuthUser;
+} | {
+    type: 'auth:signed-out';
+} | {
+    type: 'auth:locked';
+} | {
+    type: 'auth:unlocked';
+    user: AuthUser;
+} | {
+    type: 'auth:token-refreshed';
+} | {
+    type: 'auth:device-revoked';
+    deviceId: string;
+} | {
+    type: 'auth:permission-changed';
+};
+/** Extract the event type string union from AuthEvent */
+type AuthEventType = AuthEvent['type'];
+
+/**
+ * Thrown when the Web Crypto API is not available in the current environment.
+ * This can happen in older Node.js versions or SSR environments without crypto support.
+ */
+declare class CryptoUnavailableError extends KoraError {
+    constructor();
+}
+/**
+ * Thrown when a device identity operation fails (key generation, signing, verification).
+ */
+declare class DeviceIdentityError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Encodes an ArrayBuffer as a base64url string (no padding).
+ *
+ * @param buffer - The binary data to encode
+ * @returns A base64url-encoded string without padding characters
+ */
+declare function toBase64Url(buffer: ArrayBuffer): string;
+/**
+ * Decodes a base64url string (no padding) into a Uint8Array.
+ *
+ * @param str - A base64url-encoded string (with or without padding)
+ * @returns The decoded binary data as a Uint8Array
+ */
+declare function fromBase64Url(str: string): Uint8Array;
+/**
+ * Generates an ECDSA P-256 key pair for device identity.
+ *
+ * The private key is marked as non-extractable, ensuring it cannot be
+ * exported from the browser's crypto subsystem. This provides
+ * proof-of-possession: only code running on this device can sign with the key.
+ *
+ * @returns A CryptoKeyPair containing the public and private ECDSA P-256 keys
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If key generation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * // keyPair.publicKey can be exported; keyPair.privateKey stays on device
+ * ```
+ */
+declare function generateDeviceKeyPair(): Promise<CryptoKeyPair>;
+/**
+ * Exports the public key from a key pair as a JSON Web Key (JWK).
+ *
+ * The JWK can be safely transmitted to a server or other devices to identify
+ * this device. It contains only the public component of the key pair.
+ *
+ * @param keyPair - The CryptoKeyPair whose public key should be exported
+ * @returns The public key in JWK format
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the export operation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * const jwk = await exportPublicKeyJwk(keyPair)
+ * // jwk contains { kty: 'EC', crv: 'P-256', x: '...', y: '...' }
+ * ```
+ */
+declare function exportPublicKeyJwk(keyPair: CryptoKeyPair): Promise<JsonWebKey>;
+/**
+ * Signs a challenge string with the device's private key.
+ *
+ * Used for proof-of-possession during authentication: the server sends a
+ * random challenge, and the device proves it holds the private key by signing it.
+ *
+ * @param privateKey - The device's private CryptoKey (ECDSA P-256)
+ * @param challenge - The challenge string to sign (typically a random nonce from the server)
+ * @returns A base64url-encoded ECDSA signature (no padding)
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the signing operation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * const signature = await signChallenge(keyPair.privateKey, 'server-nonce-abc123')
+ * // signature is a base64url string like 'MEUCIQDx...'
+ * ```
+ */
+declare function signChallenge(privateKey: CryptoKey, challenge: string): Promise<string>;
+/**
+ * Verifies a challenge signature against a public key.
+ *
+ * Used server-side (or on any verifying party) to confirm that a device
+ * holds the private key corresponding to the given public key.
+ *
+ * @param publicKeyJwk - The device's public key in JWK format
+ * @param challenge - The original challenge string that was signed
+ * @param signature - The base64url-encoded signature to verify
+ * @returns `true` if the signature is valid, `false` otherwise
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the verification operation fails due to an invalid key or format
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyChallenge(publicKeyJwk, 'server-nonce-abc123', signature)
+ * if (isValid) {
+ *   // Device proved possession of the private key
+ * }
+ * ```
+ */
+declare function verifyChallenge(publicKeyJwk: JsonWebKey, challenge: string, signature: string): Promise<boolean>;
+/**
+ * Computes a SHA-256 thumbprint of a JWK public key.
+ *
+ * The thumbprint is computed per RFC 7638: the JWK members required for the key
+ * type are serialized in lexicographic order, then hashed with SHA-256. For EC keys
+ * (kty: "EC"), the required members are `crv`, `kty`, `x`, and `y`.
+ *
+ * This thumbprint serves as a compact, stable identifier for the device's public key
+ * (used as the `dpk` claim in device credentials).
+ *
+ * @param publicKeyJwk - The public key in JWK format (must be an EC P-256 key)
+ * @returns A base64url-encoded SHA-256 thumbprint (no padding)
+ * @throws {CryptoUnavailableError} If `crypto.subtle` is not available
+ * @throws {DeviceIdentityError} If the thumbprint computation fails or the JWK is missing required fields
+ *
+ * @example
+ * ```typescript
+ * const keyPair = await generateDeviceKeyPair()
+ * const jwk = await exportPublicKeyJwk(keyPair)
+ * const thumbprint = await computePublicKeyThumbprint(jwk)
+ * // thumbprint is a base64url string, e.g., 'NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs'
+ * ```
+ */
+declare function computePublicKeyThumbprint(publicKeyJwk: JsonWebKey): Promise<string>;
+
+export { type AuthTokens as A, CryptoUnavailableError as C, DeviceIdentityError as D, type TokenPayload as T, type AuthConfig as a, type AuthEvent as b, type AuthEventType as c, type AuthStatus as d, type TokenType as e, computePublicKeyThumbprint as f, exportPublicKeyJwk as g, fromBase64Url as h, generateDeviceKeyPair as i, signChallenge as s, toBase64Url as t, verifyChallenge as v };