ngx-webauthn 0.0.2 → 0.2.0

package/fesm2022/ngx-webauthn.mjs

@@ -1,23 +1,56 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, inject, Injectable } from '@angular/core';
+import { HttpClient, HttpErrorResponse } from '@angular/common/http';
 import { throwError, from } from 'rxjs';
-import { map, catchError } from 'rxjs/operators';
+import { map, catchError, timeout, switchMap } from 'rxjs/operators';
 
 /**
- * High-level configuration interfaces for WebAuthn operations
+ * Type guard utilities for WebAuthn operations
  *
- * These interfaces provide a convenient, preset-driven API while still allowing
- * full customization through override properties. They derive from standard WebAuthn
- * types where possible to reduce duplication and ensure compatibility.
+ * These functions help determine the type of input provided to WebAuthn operations,
+ * enabling proper handling of different input formats (high-level configs vs native WebAuthn options).
  */
 /**
- * Type guard to check if input is a RegisterConfig
+ * Type guard to determine if input is a high-level RegisterConfig object.
+ * Distinguishes between RegisterConfig and direct WebAuthn creation options.
+ *
+ * @param input The input to check
+ * @returns True if the input is a RegisterConfig, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isRegisterConfig(input)) {
+ *   // Handle high-level config with preset support
+ *   const options = buildCreationOptionsFromConfig(input, config);
+ * } else {
+ *   // Handle direct WebAuthn options
+ *   const options = parseRegistrationOptions(input);
+ * }
+ * ```
  */
 function isRegisterConfig(input) {
     return typeof input === 'object' && input !== null && 'username' in input;
 }
 /**
- * Type guard to check if input is an AuthenticateConfig
+ * Type guard to determine if input is a high-level AuthenticateConfig object.
+ * Distinguishes between AuthenticateConfig and direct WebAuthn request options.
+ *
+ * Uses the presence of 'username' or 'preset' fields and absence of WebAuthn-specific
+ * fields ('rp', 'user') to identify AuthenticateConfig objects.
+ *
+ * @param input The input to check
+ * @returns True if the input is an AuthenticateConfig, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isAuthenticateConfig(input)) {
+ *   // Handle high-level config with preset support
+ *   const options = buildRequestOptionsFromConfig(input, config);
+ * } else {
+ *   // Handle direct WebAuthn options
+ *   const options = parseAuthenticationOptions(input);
+ * }
+ * ```
  */
 function isAuthenticateConfig(input) {
     return (typeof input === 'object' &&
@@ -27,7 +60,20 @@ function isAuthenticateConfig(input) {
         !('user' in input)); // WebAuthn options have 'user'
 }
 /**
- * Type guard to check if input is WebAuthn creation options
+ * Type guard to check if input contains WebAuthn creation options.
+ * Identifies objects that have the structure of PublicKeyCredentialCreationOptions
+ * by checking for required fields like 'rp' and 'user'.
+ *
+ * @param input The input to check
+ * @returns True if the input has creation options structure, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isCreationOptions(input)) {
+ *   // Input is already in WebAuthn format
+ *   return navigator.credentials.create({ publicKey: input });
+ * }
+ * ```
  */
 function isCreationOptions(input) {
     return (typeof input === 'object' &&
@@ -36,7 +82,20 @@ function isCreationOptions(input) {
         'user' in input);
 }
 /**
- * Type guard to check if input is WebAuthn request options
+ * Type guard to check if input contains WebAuthn request options.
+ * Identifies objects that have the structure of PublicKeyCredentialRequestOptions
+ * by checking for the required 'challenge' field.
+ *
+ * @param input The input to check
+ * @returns True if the input has request options structure, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isRequestOptions(input)) {
+ *   // Input is already in WebAuthn format
+ *   return navigator.credentials.get({ publicKey: input });
+ * }
+ * ```
  */
 function isRequestOptions(input) {
     return (typeof input === 'object' &&
@@ -82,7 +141,7 @@ const PASSKEY_PRESET = {
     },
 };
 /**
- * Preset for using a security key as a second factor after a password.
+ * Preset for using an external security key as a second factor after a password.
  *
  * Best for: Traditional 2FA scenarios where users already have a password
  * and want to add hardware security key as a second factor.
@@ -93,7 +152,7 @@ const PASSKEY_PRESET = {
  * - Favors cross-platform authenticators (USB/NFC security keys)
  * - Credentials typically not synced between devices
  */
-const SECOND_FACTOR_PRESET = {
+const EXTERNAL_SECURITY_KEY_PRESET = {
     ...COMMON_PUB_KEY_CRED_PARAMS,
     authenticatorSelection: {
         residentKey: 'discouraged',
@@ -102,10 +161,10 @@ const SECOND_FACTOR_PRESET = {
     },
 };
 /**
- * Preset for high-security, non-synced, single-device credentials.
+ * Preset for high-security, non-synced, platform authenticator credentials.
  *
  * Best for: High-security scenarios where credentials must stay on a single
- * device and user verification is mandatory.
+ * device and user verification is mandatory using built-in platform authenticators.
  *
  * Features:
  * - Requires platform authenticators (built-in biometrics/PIN)
@@ -113,7 +172,7 @@ const SECOND_FACTOR_PRESET = {
  * - Requires user verification (biometric/PIN)
  * - Credentials bound to specific device (no syncing)
  */
-const DEVICE_BOUND_PRESET = {
+const PLATFORM_AUTHENTICATOR_PRESET = {
     ...COMMON_PUB_KEY_CRED_PARAMS,
     authenticatorSelection: {
         authenticatorAttachment: 'platform',
@@ -127,8 +186,8 @@ const DEVICE_BOUND_PRESET = {
  */
 const PRESET_MAP = {
     passkey: PASSKEY_PRESET,
-    secondFactor: SECOND_FACTOR_PRESET,
-    deviceBound: DEVICE_BOUND_PRESET,
+    externalSecurityKey: EXTERNAL_SECURITY_KEY_PRESET,
+    platformAuthenticator: PLATFORM_AUTHENTICATOR_PRESET,
 };
 
 /**
@@ -139,8 +198,21 @@ const PRESET_MAP = {
  * WebAuthn options ready for the browser API.
  */
 /**
- * Deep merge utility that properly handles nested objects
- * Later properties override earlier ones
+ * Deep merge utility that properly handles nested objects.
+ * Later properties override earlier ones, with recursive merging for nested objects.
+ *
+ * @param target The target object to merge into
+ * @param sources Source objects to merge from (processed left to right)
+ * @returns The merged target object
+ * @example
+ * ```typescript
+ * const result = deepMerge(
+ *   { a: 1, b: { x: 1 } },
+ *   { b: { y: 2 } },
+ *   { c: 3 }
+ * );
+ * // Result: { a: 1, b: { x: 1, y: 2 }, c: 3 }
+ * ```
  */
 function deepMerge(target, ...sources) {
     if (!sources.length)
@@ -161,27 +233,40 @@ function deepMerge(target, ...sources) {
     return deepMerge(target, ...sources);
 }
 /**
- * Check if a value is a plain object
+ * Type guard to check if a value is a plain object (not array, null, or primitive).
+ *
+ * @param item The value to check
+ * @returns True if the item is a plain object, false otherwise
  */
 function isObject(item) {
     return item && typeof item === 'object' && !Array.isArray(item);
 }
 /**
- * Generate a secure random challenge as Uint8Array
+ * Generates a cryptographically secure random challenge for WebAuthn operations.
+ * Uses the Web Crypto API for secure random number generation.
+ *
+ * @returns A 32-byte Uint8Array containing the random challenge
  */
 function generateChallenge$1() {
     return crypto.getRandomValues(new Uint8Array(32));
 }
 /**
- * Generate a user ID from username
- * Uses TextEncoder to convert username to Uint8Array for consistency
+ * Generates a unique user ID based on the username.
+ * Creates a consistent, URL-safe identifier for the user.
+ *
+ * @param username The username to generate an ID from
+ * @returns A Uint8Array containing the encoded user ID
  */
 function generateUserId$1(username) {
     return new TextEncoder().encode(username);
 }
 /**
- * Convert challenge to appropriate format
- * Handles both string (base64url) and Uint8Array inputs
+ * Processes and normalizes challenge values from various input formats.
+ * Handles string (base64url), Uint8Array, or generates a new challenge if none provided.
+ *
+ * @param challenge Optional challenge as string or Uint8Array
+ * @returns Normalized Uint8Array challenge ready for WebAuthn API
+ * @throws {Error} When provided string challenge is not valid base64url
  */
 function processChallenge(challenge) {
     if (!challenge) {
@@ -194,8 +279,14 @@ function processChallenge(challenge) {
     return challenge;
 }
 /**
- * Convert user ID to appropriate format
- * Handles both string (base64url) and Uint8Array inputs
+ * Processes and normalizes user ID values from various input formats.
+ * Handles string (base64url), Uint8Array, or generates from username if none provided.
+ *
+ * @param userId Optional user ID as string or Uint8Array
+ * @param username Username to generate ID from if userId not provided
+ * @returns Normalized Uint8Array user ID ready for WebAuthn API
+ * @throws {Error} When no userId provided and no username available for generation
+ * @throws {Error} When provided string userId is not valid base64url
  */
 function processUserId(userId, username) {
     if (userId) {
@@ -212,7 +303,12 @@ function processUserId(userId, username) {
     return crypto.getRandomValues(new Uint8Array(16));
 }
 /**
- * Convert string credential IDs to PublicKeyCredentialDescriptor format
+ * Processes and normalizes credential descriptors from various input formats.
+ * Converts string credential IDs to proper PublicKeyCredentialDescriptor objects.
+ *
+ * @param credentials Optional array of credential IDs (strings) or full descriptors
+ * @returns Array of normalized PublicKeyCredentialDescriptor objects, or undefined if none provided
+ * @throws {Error} When a credential ID string is not valid base64url
  */
 function processCredentialDescriptors(credentials) {
     if (!credentials || credentials.length === 0) {
@@ -229,7 +325,18 @@ function processCredentialDescriptors(credentials) {
     }));
 }
 /**
- * Resolve a preset configuration by name
+ * Resolves a preset configuration by name.
+ * Returns the complete preset configuration object for the specified preset.
+ *
+ * @param presetName The name of the preset to resolve
+ * @returns The preset configuration object
+ * @throws {Error} When the preset name is not found in PRESET_MAP
+ *
+ * @example
+ * ```typescript
+ * const preset = resolvePreset('passkey');
+ * console.log(preset.authenticatorSelection.userVerification); // 'preferred'
+ * ```
  */
 function resolvePreset(presetName) {
     const preset = PRESET_MAP[presetName];
@@ -239,53 +346,85 @@ function resolvePreset(presetName) {
     return preset;
 }
 /**
- * Build complete PublicKeyCredentialCreationOptions from RegisterConfig
- * Now uses WebAuthnConfig for better defaults and relying party information
+ * Creates base creation options from WebAuthn service configuration.
+ * Establishes default timeout and attestation settings that can be overridden later.
+ *
+ * @param webAuthnConfig The global WebAuthn service configuration
+ * @returns Partial creation options with base settings applied
  */
-function buildCreationOptionsFromConfig(config, webAuthnConfig) {
-    // Start with base configuration from WebAuthnConfig
-    let options = {
+function createBaseCreationOptions(webAuthnConfig) {
+    return {
         timeout: webAuthnConfig.defaultTimeout || 60000,
         attestation: webAuthnConfig.defaultAttestation || 'none',
     };
-    // Apply preset if specified
+}
+/**
+ * Applies preset configuration to base creation options.
+ * Merges preset-specific authenticator selection and public key parameters into the options.
+ *
+ * @param config The register configuration containing preset information
+ * @param baseOptions The base options to apply preset configuration to
+ * @param webAuthnConfig The global WebAuthn service configuration
+ * @returns Options with preset configuration applied
+ */
+function applyPresetConfiguration(config, baseOptions, webAuthnConfig) {
     if (config.preset) {
         const preset = resolvePreset(config.preset);
-        options = deepMerge(options, {
+        return deepMerge(baseOptions, {
             authenticatorSelection: preset.authenticatorSelection,
             pubKeyCredParams: [...preset.pubKeyCredParams], // Convert readonly to mutable
         });
     }
-    else {
-        // Apply default authenticator selection from config
-        if (webAuthnConfig.defaultAuthenticatorSelection) {
-            options.authenticatorSelection =
-                webAuthnConfig.defaultAuthenticatorSelection;
-        }
+    // Apply default authenticator selection from config when no preset
+    if (webAuthnConfig.defaultAuthenticatorSelection) {
+        return {
+            ...baseOptions,
+            authenticatorSelection: webAuthnConfig.defaultAuthenticatorSelection,
+        };
     }
-    // Apply user overrides
+    return baseOptions;
+}
+/**
+ * Applies user-specified overrides to creation options.
+ * Allows users to override any preset or default settings with their own values.
+ *
+ * @param config The register configuration containing user overrides
+ * @param options The options to apply user overrides to
+ * @returns Options with user overrides applied
+ */
+function applyUserOverrides(config, options) {
+    const result = { ...options };
     if (config.timeout !== undefined) {
-        options.timeout = config.timeout;
+        result.timeout = config.timeout;
     }
     if (config.attestation !== undefined) {
-        options.attestation = config.attestation;
+        result.attestation = config.attestation;
     }
     if (config.authenticatorSelection !== undefined) {
-        options.authenticatorSelection = deepMerge(options.authenticatorSelection || {}, config.authenticatorSelection);
+        result.authenticatorSelection = deepMerge(result.authenticatorSelection || {}, config.authenticatorSelection);
     }
     if (config.pubKeyCredParams !== undefined) {
-        options.pubKeyCredParams = config.pubKeyCredParams;
+        result.pubKeyCredParams = config.pubKeyCredParams;
     }
     if (config.extensions !== undefined) {
-        options.extensions = config.extensions;
+        result.extensions = config.extensions;
     }
-    // Handle required fields
+    return result;
+}
+/**
+ * Assembles final creation options with all required WebAuthn fields.
+ * Processes user information, challenge, and applies final service configuration.
+ *
+ * @param options The partially built options from previous steps
+ * @param config The register configuration containing user and RP information
+ * @param webAuthnConfig The global WebAuthn service configuration
+ * @returns Complete PublicKeyCredentialCreationOptions ready for WebAuthn API
+ */
+function assembleFinalCreationOptions(options, config, webAuthnConfig) {
     const challenge = processChallenge(config.challenge);
     const userId = processUserId(config.userId, config.username);
-    // Use relying party from config, with user override capability
     const relyingParty = config.rp || webAuthnConfig.relyingParty;
-    // Build final options
-    const finalOptions = {
+    return {
         ...options,
         rp: relyingParty,
         user: {
@@ -301,11 +440,63 @@ function buildCreationOptionsFromConfig(config, webAuthnConfig) {
         ],
         excludeCredentials: processCredentialDescriptors(config.excludeCredentials),
     };
-    return finalOptions;
 }
 /**
- * Build complete PublicKeyCredentialRequestOptions from AuthenticateConfig
- * Now uses WebAuthnConfig for better defaults
+ * Builds complete WebAuthn creation options from a high-level register configuration.
+ *
+ * This function orchestrates the creation option building process by:
+ * 1. Creating base options from service configuration
+ * 2. Applying preset-specific settings if specified
+ * 3. Applying user overrides for customization
+ * 4. Assembling final options with all required fields
+ *
+ * @param config The high-level register configuration with preset support
+ * @param webAuthnConfig The global WebAuthn service configuration
+ * @returns Complete PublicKeyCredentialCreationOptions ready for navigator.credentials.create()
+ *
+ * @example
+ * ```typescript
+ * const config: RegisterConfig = {
+ *   preset: 'passkey',
+ *   user: {
+ *     id: 'user123',
+ *     name: 'user@example.com',
+ *     displayName: 'John Doe'
+ *   },
+ *   challenge: 'custom-challenge'
+ * };
+ *
+ * const options = buildCreationOptionsFromConfig(config, webAuthnConfig);
+ * // Returns complete creation options ready for WebAuthn API
+ * ```
+ */
+function buildCreationOptionsFromConfig(config, webAuthnConfig) {
+    const baseOptions = createBaseCreationOptions(webAuthnConfig);
+    const presetOptions = applyPresetConfiguration(config, baseOptions, webAuthnConfig);
+    const finalOptions = applyUserOverrides(config, presetOptions);
+    return assembleFinalCreationOptions(finalOptions, config, webAuthnConfig);
+}
+/**
+ * Builds complete WebAuthn request options from a high-level authenticate configuration.
+ *
+ * Handles preset resolution, user overrides, and proper field processing to create
+ * request options suitable for navigator.credentials.get().
+ *
+ * @param config The high-level authenticate configuration with preset support
+ * @param webAuthnConfig The global WebAuthn service configuration
+ * @returns Complete PublicKeyCredentialRequestOptions ready for navigator.credentials.get()
+ *
+ * @example
+ * ```typescript
+ * const config: AuthenticateConfig = {
+ *   preset: 'passkey',
+ *   challenge: 'auth-challenge',
+ *   allowCredentials: ['cred-id-1', 'cred-id-2']
+ * };
+ *
+ * const options = buildRequestOptionsFromConfig(config, webAuthnConfig);
+ * // Returns complete request options ready for WebAuthn API
+ * ```
  */
 function buildRequestOptionsFromConfig(config, webAuthnConfig) {
     // Start with base configuration from WebAuthnConfig
@@ -344,7 +535,21 @@ function buildRequestOptionsFromConfig(config, webAuthnConfig) {
     return finalOptions;
 }
 /**
- * Validate that a RegisterConfig has all required fields
+ * Validates a register configuration for completeness and correctness.
+ * Ensures all required fields are present and properly formatted.
+ *
+ * @param config The register configuration to validate
+ * @throws {Error} When required fields are missing or invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateRegisterConfig(config);
+ *   // Config is valid, proceed with registration
+ * } catch (error) {
+ *   console.error('Invalid register config:', error.message);
+ * }
+ * ```
  */
 function validateRegisterConfig(config) {
     if (!config.username || typeof config.username !== 'string') {
@@ -355,7 +560,21 @@ function validateRegisterConfig(config) {
     }
 }
 /**
- * Validate that an AuthenticateConfig has all required fields
+ * Validates an authenticate configuration for completeness and correctness.
+ * Ensures all required fields are present and properly formatted.
+ *
+ * @param config The authenticate configuration to validate
+ * @throws {Error} When required fields are missing or invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateAuthenticateConfig(config);
+ *   // Config is valid, proceed with authentication
+ * } catch (error) {
+ *   console.error('Invalid authenticate config:', error.message);
+ * }
+ * ```
  */
 function validateAuthenticateConfig(config) {
     if (config.preset && !PRESET_MAP[config.preset]) {
@@ -367,6 +586,10 @@ function validateAuthenticateConfig(config) {
  * Enhanced WebAuthn Error Classes
  * Provides specific, actionable error types for better developer experience
  */
+/**
+ * Enumeration of WebAuthn error types for categorizing different failure scenarios.
+ * Provides semantic error classification for better error handling and user experience.
+ */
 var WebAuthnErrorType;
 (function (WebAuthnErrorType) {
     WebAuthnErrorType["NOT_SUPPORTED"] = "NOT_SUPPORTED";
@@ -377,24 +600,61 @@ var WebAuthnErrorType;
     WebAuthnErrorType["NETWORK_ERROR"] = "NETWORK_ERROR";
     WebAuthnErrorType["SECURITY_ERROR"] = "SECURITY_ERROR";
     WebAuthnErrorType["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    WebAuthnErrorType["REMOTE_ENDPOINT_ERROR"] = "REMOTE_ENDPOINT_ERROR";
+    WebAuthnErrorType["INVALID_REMOTE_OPTIONS"] = "INVALID_REMOTE_OPTIONS";
     WebAuthnErrorType["UNKNOWN"] = "UNKNOWN";
 })(WebAuthnErrorType || (WebAuthnErrorType = {}));
 /**
- * Base WebAuthn error class with additional context
+ * Base WebAuthn error class that provides enhanced error information.
+ * All WebAuthn-specific errors extend from this class for consistent error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.register(config);
+ * } catch (error) {
+ *   if (error instanceof WebAuthnError) {
+ *     console.log('Error type:', error.type);
+ *     console.log('Original error:', error.originalError);
+ *   }
+ * }
+ * ```
  */
 class WebAuthnError extends Error {
     type;
     originalError;
+    /**
+     * Creates a new WebAuthnError instance.
+     *
+     * @param type The semantic error type
+     * @param message Human-readable error message
+     * @param originalError The original error that caused this WebAuthn error (optional)
+     */
     constructor(type, message, originalError) {
         super(message);
         this.type = type;
         this.originalError = originalError;
         this.name = 'WebAuthnError';
     }
+    /**
+     * Factory method to create WebAuthnError from DOMException.
+     * Maps browser DOMException types to semantic WebAuthn error types.
+     *
+     * @param error The DOMException thrown by WebAuthn API
+     * @returns Appropriate WebAuthnError subclass based on the DOMException type
+     */
     static fromDOMException(error) {
         const type = WebAuthnError.mapDOMExceptionToType(error.name);
         return new WebAuthnError(type, error.message, error);
     }
+    /**
+     * Maps DOMException names to WebAuthn error types.
+     * Provides semantic classification of browser-level errors.
+     *
+     * @param name The DOMException name
+     * @returns Corresponding WebAuthnErrorType
+     * @private
+     */
     static mapDOMExceptionToType(name) {
         switch (name) {
             case 'NotSupportedError':
@@ -417,72 +677,268 @@ class WebAuthnError extends Error {
     }
 }
 /**
- * Error thrown when user cancels the WebAuthn operation
+ * Error thrown when the user cancels a WebAuthn operation.
+ * This is the most common error and typically requires no action from the developer.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.register(config);
+ * } catch (error) {
+ *   if (error instanceof UserCancelledError) {
+ *     // User chose not to proceed - this is normal behavior
+ *     console.log('User cancelled the operation');
+ *   }
+ * }
+ * ```
  */
 class UserCancelledError extends WebAuthnError {
+    /**
+     * Creates a new UserCancelledError.
+     *
+     * @param originalError The original DOMException that triggered this error (optional)
+     */
     constructor(originalError) {
         super(WebAuthnErrorType.USER_CANCELLED, 'User cancelled the WebAuthn operation', originalError);
         this.name = 'UserCancelledError';
     }
 }
 /**
- * Error thrown when there's an issue with the authenticator
+ * Error thrown when there's an issue with the authenticator device.
+ * This could indicate hardware problems, invalid state, or other device-specific issues.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.authenticate(config);
+ * } catch (error) {
+ *   if (error instanceof AuthenticatorError) {
+ *     // Show user-friendly message about trying again or using different authenticator
+ *     console.log('Authenticator issue:', error.message);
+ *   }
+ * }
+ * ```
  */
 class AuthenticatorError extends WebAuthnError {
+    /**
+     * Creates a new AuthenticatorError.
+     *
+     * @param message Descriptive error message
+     * @param originalError The original error that caused this authenticator error (optional)
+     */
     constructor(message, originalError) {
         super(WebAuthnErrorType.AUTHENTICATOR_ERROR, `Authenticator error: ${message}`, originalError);
         this.name = 'AuthenticatorError';
     }
 }
 /**
- * Error thrown when the provided options are invalid
+ * Error thrown when the provided WebAuthn options are invalid or malformed.
+ * This typically indicates a programming error in option construction.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.register(invalidConfig);
+ * } catch (error) {
+ *   if (error instanceof InvalidOptionsError) {
+ *     // Check your configuration and options
+ *     console.error('Invalid options provided:', error.message);
+ *   }
+ * }
+ * ```
  */
 class InvalidOptionsError extends WebAuthnError {
+    /**
+     * Creates a new InvalidOptionsError.
+     *
+     * @param message Descriptive error message explaining what's invalid
+     * @param originalError The original error that revealed the invalid options (optional)
+     */
     constructor(message, originalError) {
         super(WebAuthnErrorType.INVALID_OPTIONS, `Invalid options: ${message}`, originalError);
         this.name = 'InvalidOptionsError';
     }
 }
 /**
- * Error thrown when the requested operation is not supported
+ * Error thrown when a WebAuthn operation is not supported in the current environment.
+ * This could be due to browser limitations or missing hardware capabilities.
+ *
+ * @example
+ * ```typescript
+ * if (!webAuthnService.isSupported()) {
+ *   // Handle unsupported environment
+ * }
+ *
+ * try {
+ *   await webAuthnService.register(config);
+ * } catch (error) {
+ *   if (error instanceof UnsupportedOperationError) {
+ *     // Show fallback authentication method
+ *     console.log('WebAuthn not supported, using fallback');
+ *   }
+ * }
+ * ```
  */
 class UnsupportedOperationError extends WebAuthnError {
+    /**
+     * Creates a new UnsupportedOperationError.
+     *
+     * @param message Descriptive error message explaining what's not supported
+     * @param originalError The original error that indicated lack of support (optional)
+     */
     constructor(message, originalError) {
         super(WebAuthnErrorType.UNSUPPORTED_OPERATION, `Unsupported operation: ${message}`, originalError);
         this.name = 'UnsupportedOperationError';
     }
 }
 /**
- * Error thrown when there's a network-related issue
+ * Error thrown when there's a network-related issue during WebAuthn operations.
+ * This is rare but can occur in certain network conditions.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.authenticate(config);
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     // Suggest user check connection and retry
+ *     console.log('Network issue during authentication:', error.message);
+ *   }
+ * }
+ * ```
  */
 class NetworkError extends WebAuthnError {
+    /**
+     * Creates a new NetworkError.
+     *
+     * @param message Descriptive error message about the network issue
+     * @param originalError The original network-related error (optional)
+     */
     constructor(message, originalError) {
         super(WebAuthnErrorType.NETWORK_ERROR, `Network error: ${message}`, originalError);
         this.name = 'NetworkError';
     }
 }
 /**
- * Error thrown when there's a security-related issue
+ * Error thrown when a security violation occurs during WebAuthn operations.
+ * This typically indicates issues with origin validation or other security checks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.register(config);
+ * } catch (error) {
+ *   if (error instanceof SecurityError) {
+ *     // Security issue - check origin, HTTPS, etc.
+ *     console.error('Security violation:', error.message);
+ *   }
+ * }
+ * ```
  */
 class SecurityError extends WebAuthnError {
+    /**
+     * Creates a new SecurityError.
+     *
+     * @param message Descriptive error message about the security issue
+     * @param originalError The original security-related error (optional)
+     */
     constructor(message, originalError) {
         super(WebAuthnErrorType.SECURITY_ERROR, `Security error: ${message}`, originalError);
         this.name = 'SecurityError';
     }
 }
 /**
- * Error thrown when the operation times out
+ * Error thrown when a WebAuthn operation times out.
+ * This can happen when the user takes too long to interact with their authenticator.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.register(config);
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     // Suggest user try again and respond more quickly
+ *     console.log('Operation timed out - please try again');
+ *   }
+ * }
+ * ```
  */
 class TimeoutError extends WebAuthnError {
+    /**
+     * Creates a new TimeoutError.
+     *
+     * @param message Descriptive error message about the timeout
+     * @param originalError The original timeout-related error (optional)
+     */
     constructor(message, originalError) {
         super(WebAuthnErrorType.TIMEOUT_ERROR, `Timeout error: ${message}`, originalError);
         this.name = 'TimeoutError';
     }
 }
+/**
+ * Error thrown when remote endpoint request fails.
+ * Includes network errors, HTTP errors, and timeout errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.registerRemote(request);
+ * } catch (error) {
+ *   if (error instanceof RemoteEndpointError) {
+ *     console.log('Endpoint:', error.context.url);
+ *     console.log('Status:', error.context.status);
+ *   }
+ * }
+ * ```
+ */
+class RemoteEndpointError extends WebAuthnError {
+    context;
+    /**
+     * Creates a new RemoteEndpointError.
+     *
+     * @param message Descriptive error message about the remote endpoint failure
+     * @param context Contextual information about the failed request
+     * @param originalError The original error that caused this remote endpoint error (optional)
+     */
+    constructor(message, context, originalError) {
+        super(WebAuthnErrorType.REMOTE_ENDPOINT_ERROR, `Remote endpoint error: ${message}`, originalError);
+        this.context = context;
+        this.name = 'RemoteEndpointError';
+    }
+}
+/**
+ * Error thrown when remote server returns invalid WebAuthn options.
+ * This indicates the server response doesn't match expected WebAuthn option format.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await webAuthnService.registerRemote(request);
+ * } catch (error) {
+ *   if (error instanceof InvalidRemoteOptionsError) {
+ *     console.log('Invalid server response:', error.message);
+ *   }
+ * }
+ * ```
+ */
+class InvalidRemoteOptionsError extends WebAuthnError {
+    /**
+     * Creates a new InvalidRemoteOptionsError.
+     *
+     * @param message Descriptive error message about the invalid remote options
+     * @param originalError The original error that revealed the invalid options (optional)
+     */
+    constructor(message, originalError) {
+        super(WebAuthnErrorType.INVALID_REMOTE_OPTIONS, `Invalid remote options: ${message}`, originalError);
+        this.name = 'InvalidRemoteOptionsError';
+    }
+}
 
 /**
- * WebAuthn Configuration
- * Provides configuration interfaces and injection token for WebAuthn service
+ * Service-level configuration for WebAuthn operations
+ *
+ * These interfaces define the global configuration that affects the entire WebAuthn service,
+ * including relying party information and default settings.
  */
 /**
  * Default configuration for WebAuthn service
@@ -707,6 +1163,202 @@ function isPublicKeyCredential(credential) {
     return credential !== null && credential.type === 'public-key';
 }
 
+/**
+ * Utility functions for remote WebAuthn option validation
+ *
+ * These utilities provide comprehensive validation of server responses
+ * to ensure they contain valid WebAuthn options before processing.
+ * All validation is done without external dependencies for minimal
+ * bundle size impact.
+ */
+/**
+ * Validates that server response contains valid WebAuthn creation options.
+ * Performs essential validation without external dependencies.
+ *
+ * @param options Response from registration endpoint
+ * @throws {InvalidRemoteOptionsError} When options are invalid or incomplete
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateRemoteCreationOptions(serverResponse);
+ *   // Options are valid, proceed with registration
+ * } catch (error) {
+ *   console.error('Invalid server response:', error.message);
+ * }
+ * ```
+ */
+function validateRemoteCreationOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new InvalidRemoteOptionsError('Response must be an object');
+    }
+    const opts = options;
+    // Validate relying party (required)
+    if (!opts.rp || typeof opts.rp !== 'object') {
+        throw new InvalidRemoteOptionsError('Missing or invalid rp (relying party) field');
+    }
+    if (typeof opts.rp.name !== 'string' || opts.rp.name.trim() === '') {
+        throw new InvalidRemoteOptionsError('rp.name must be a non-empty string');
+    }
+    if (opts.rp.id !== undefined && typeof opts.rp.id !== 'string') {
+        throw new InvalidRemoteOptionsError('rp.id must be a string when provided');
+    }
+    // Validate user (required)
+    if (!opts.user || typeof opts.user !== 'object') {
+        throw new InvalidRemoteOptionsError('Missing or invalid user field');
+    }
+    if (typeof opts.user.id !== 'string' || opts.user.id.trim() === '') {
+        throw new InvalidRemoteOptionsError('user.id must be a non-empty base64url string');
+    }
+    if (typeof opts.user.name !== 'string' || opts.user.name.trim() === '') {
+        throw new InvalidRemoteOptionsError('user.name must be a non-empty string');
+    }
+    if (typeof opts.user.displayName !== 'string' ||
+        opts.user.displayName.trim() === '') {
+        throw new InvalidRemoteOptionsError('user.displayName must be a non-empty string');
+    }
+    // Validate challenge (required)
+    if (!opts.challenge ||
+        typeof opts.challenge !== 'string' ||
+        opts.challenge.trim() === '') {
+        throw new InvalidRemoteOptionsError('Missing or invalid challenge field - must be a non-empty base64url string');
+    }
+    // Validate pubKeyCredParams (required)
+    if (!Array.isArray(opts.pubKeyCredParams)) {
+        throw new InvalidRemoteOptionsError('pubKeyCredParams must be an array');
+    }
+    if (opts.pubKeyCredParams.length === 0) {
+        throw new InvalidRemoteOptionsError('pubKeyCredParams cannot be empty');
+    }
+    // Validate each pubKeyCredParams entry
+    for (let i = 0; i < opts.pubKeyCredParams.length; i++) {
+        const param = opts.pubKeyCredParams[i];
+        if (!param || typeof param !== 'object') {
+            throw new InvalidRemoteOptionsError(`pubKeyCredParams[${i}] must be an object`);
+        }
+        if (param.type !== 'public-key') {
+            throw new InvalidRemoteOptionsError(`pubKeyCredParams[${i}].type must be "public-key"`);
+        }
+        if (typeof param.alg !== 'number') {
+            throw new InvalidRemoteOptionsError(`pubKeyCredParams[${i}].alg must be a number`);
+        }
+    }
+    // Validate optional fields if present
+    if (opts.timeout !== undefined &&
+        (typeof opts.timeout !== 'number' || opts.timeout <= 0)) {
+        throw new InvalidRemoteOptionsError('timeout must be a positive number when provided');
+    }
+    if (opts.attestation !== undefined &&
+        !['none', 'indirect', 'direct', 'enterprise'].includes(opts.attestation)) {
+        throw new InvalidRemoteOptionsError('attestation must be one of: none, indirect, direct, enterprise');
+    }
+    // Validate authenticatorSelection if present
+    if (opts.authenticatorSelection !== undefined) {
+        if (typeof opts.authenticatorSelection !== 'object') {
+            throw new InvalidRemoteOptionsError('authenticatorSelection must be an object when provided');
+        }
+        const authSel = opts.authenticatorSelection;
+        if (authSel.authenticatorAttachment !== undefined &&
+            !['platform', 'cross-platform'].includes(authSel.authenticatorAttachment)) {
+            throw new InvalidRemoteOptionsError('authenticatorAttachment must be "platform" or "cross-platform"');
+        }
+        if (authSel.userVerification !== undefined &&
+            !['required', 'preferred', 'discouraged'].includes(authSel.userVerification)) {
+            throw new InvalidRemoteOptionsError('userVerification must be "required", "preferred", or "discouraged"');
+        }
+        if (authSel.residentKey !== undefined &&
+            !['discouraged', 'preferred', 'required'].includes(authSel.residentKey)) {
+            throw new InvalidRemoteOptionsError('residentKey must be "discouraged", "preferred", or "required"');
+        }
+    }
+    // Validate excludeCredentials if present
+    if (opts.excludeCredentials !== undefined) {
+        if (!Array.isArray(opts.excludeCredentials)) {
+            throw new InvalidRemoteOptionsError('excludeCredentials must be an array when provided');
+        }
+        for (let i = 0; i < opts.excludeCredentials.length; i++) {
+            const cred = opts.excludeCredentials[i];
+            if (!cred || typeof cred !== 'object') {
+                throw new InvalidRemoteOptionsError(`excludeCredentials[${i}] must be an object`);
+            }
+            if (cred.type !== 'public-key') {
+                throw new InvalidRemoteOptionsError(`excludeCredentials[${i}].type must be "public-key"`);
+            }
+            if (typeof cred.id !== 'string' || cred.id.trim() === '') {
+                throw new InvalidRemoteOptionsError(`excludeCredentials[${i}].id must be a non-empty base64url string`);
+            }
+        }
+    }
+}
+/**
+ * Validates that server response contains valid WebAuthn request options.
+ * Performs essential validation without external dependencies.
+ *
+ * @param options Response from authentication endpoint
+ * @throws {InvalidRemoteOptionsError} When options are invalid or incomplete
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateRemoteRequestOptions(serverResponse);
+ *   // Options are valid, proceed with authentication
+ * } catch (error) {
+ *   console.error('Invalid server response:', error.message);
+ * }
+ * ```
+ */
+function validateRemoteRequestOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new InvalidRemoteOptionsError('Response must be an object');
+    }
+    const opts = options;
+    // Validate challenge (required)
+    if (!opts.challenge ||
+        typeof opts.challenge !== 'string' ||
+        opts.challenge.trim() === '') {
+        throw new InvalidRemoteOptionsError('Missing or invalid challenge field - must be a non-empty base64url string');
+    }
+    // Validate optional fields if present
+    if (opts.timeout !== undefined &&
+        (typeof opts.timeout !== 'number' || opts.timeout <= 0)) {
+        throw new InvalidRemoteOptionsError('timeout must be a positive number when provided');
+    }
+    if (opts.userVerification !== undefined &&
+        !['required', 'preferred', 'discouraged'].includes(opts.userVerification)) {
+        throw new InvalidRemoteOptionsError('userVerification must be "required", "preferred", or "discouraged"');
+    }
+    // Validate allowCredentials if present
+    if (opts.allowCredentials !== undefined) {
+        if (!Array.isArray(opts.allowCredentials)) {
+            throw new InvalidRemoteOptionsError('allowCredentials must be an array when provided');
+        }
+        for (let i = 0; i < opts.allowCredentials.length; i++) {
+            const cred = opts.allowCredentials[i];
+            if (!cred || typeof cred !== 'object') {
+                throw new InvalidRemoteOptionsError(`allowCredentials[${i}] must be an object`);
+            }
+            if (cred.type !== 'public-key') {
+                throw new InvalidRemoteOptionsError(`allowCredentials[${i}].type must be "public-key"`);
+            }
+            if (typeof cred.id !== 'string' || cred.id.trim() === '') {
+                throw new InvalidRemoteOptionsError(`allowCredentials[${i}].id must be a non-empty base64url string`);
+            }
+            // Validate transports if present
+            if (cred.transports !== undefined) {
+                if (!Array.isArray(cred.transports)) {
+                    throw new InvalidRemoteOptionsError(`allowCredentials[${i}].transports must be an array when provided`);
+                }
+                const validTransports = ['usb', 'nfc', 'ble', 'internal'];
+                for (let j = 0; j < cred.transports.length; j++) {
+                    if (!validTransports.includes(cred.transports[j])) {
+                        throw new InvalidRemoteOptionsError(`allowCredentials[${i}].transports[${j}] must be one of: ${validTransports.join(', ')}`);
+                    }
+                }
+            }
+        }
+    }
+}
+
 /**
  * Enhanced WebAuthn Service
  *
@@ -724,14 +1376,35 @@ function isPublicKeyCredential(credential) {
  */
 class WebAuthnService {
     config = inject(WEBAUTHN_CONFIG);
+    http = inject(HttpClient);
     /**
-     * Checks if WebAuthn is supported in the current browser
+     * Checks if WebAuthn is supported in the current browser environment.
+     *
+     * @returns True if WebAuthn is supported, false otherwise
+     * @example
+     * ```typescript
+     * if (this.webAuthnService.isSupported()) {
+     *   // Proceed with WebAuthn operations
+     * } else {
+     *   // Show fallback authentication method
+     * }
+     * ```
      */
     isSupported() {
         return isWebAuthnSupported();
     }
     /**
-     * Gets comprehensive WebAuthn support information
+     * Gets detailed WebAuthn support information for the current browser.
+     * Provides information about available authenticator types and capabilities.
+     *
+     * @returns Observable containing WebAuthn support details
+     * @example
+     * ```typescript
+     * this.webAuthnService.getSupport().subscribe(support => {
+     *   console.log('Platform authenticator:', support.platformAuthenticator);
+     *   console.log('Cross-platform authenticator:', support.crossPlatformAuthenticator);
+     * });
+     * ```
      */
     getSupport() {
         if (!this.isSupported()) {
@@ -744,40 +1417,57 @@ class WebAuthnService {
         })), catchError((error) => throwError(() => new WebAuthnError(WebAuthnErrorType.UNKNOWN, 'Failed to check WebAuthn support', error))));
     }
     /**
-     * Registers a new WebAuthn credential with flexible configuration support
+     * Registers a new WebAuthn credential for a user.
      *
-     * @param input Either a high-level RegisterConfig with presets, or direct WebAuthn creation options
-     * @returns Observable of RegistrationResponse with clean, developer-friendly format
+     * Supports two input formats:
+     * 1. High-level RegisterConfig with preset support and automatic option building
+     * 2. Direct PublicKeyCredentialCreationOptions for full control
      *
-     * @example
-     * ```typescript
-     * // Simple preset usage
-     * this.webAuthnService.register({ username: 'john.doe', preset: 'passkey' });
+     * @param input Either a RegisterConfig object or raw WebAuthn creation options
+     * @returns Observable containing the registration response with credential details
      *
-     * // Preset with overrides
-     * this.webAuthnService.register({
-     *   username: 'john.doe',
-     *   preset: 'passkey',
-     *   authenticatorSelection: { userVerification: 'required' }
-     * });
+     * @throws {UnsupportedOperationError} When WebAuthn is not supported
+     * @throws {InvalidOptionsError} When provided options are invalid
+     * @throws {UserCancelledError} When user cancels the registration
+     * @throws {AuthenticatorError} When authenticator encounters an error
+     * @throws {TimeoutError} When the operation times out
+     * @throws {SecurityError} When a security violation occurs
      *
-     * // Direct WebAuthn options (native)
-     * const nativeOptions: PublicKeyCredentialCreationOptions = {
-     *   challenge: new Uint8Array([...]),
-     *   rp: { name: "My App" },
-     *   user: { id: new Uint8Array([...]), name: "user@example.com", displayName: "User" },
-     *   pubKeyCredParams: [{ type: "public-key", alg: -7 }]
+     * @example Using high-level config:
+     * ```typescript
+     * const config: RegisterConfig = {
+     *   preset: 'passkey',
+     *   user: {
+     *     id: 'user123',
+     *     name: 'user@example.com',
+     *     displayName: 'John Doe'
+     *   },
+     *   challenge: 'random-challenge'
      * };
-     * this.webAuthnService.register(nativeOptions);
      *
-     * // Direct WebAuthn options (JSON)
-     * const jsonOptions: PublicKeyCredentialCreationOptionsJSON = {
-     *   challenge: "Y2hhbGxlbmdl",
-     *   rp: { name: "My App" },
-     *   user: { id: "dXNlcklk", name: "user@example.com", displayName: "User" },
+     * this.webAuthnService.register(config).subscribe({
+     *   next: (response) => {
+     *     console.log('Registration successful:', response.credential.id);
+     *   },
+     *   error: (error) => {
+     *     if (error instanceof UserCancelledError) {
+     *       console.log('User cancelled registration');
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @example Using direct options:
+     * ```typescript
+     * const options: PublicKeyCredentialCreationOptions = {
+     *   rp: { name: "Example Corp" },
+     *   user: { id: new Uint8Array([1,2,3]), name: "user@example.com", displayName: "User" },
+     *   challenge: new Uint8Array([4,5,6]),
      *   pubKeyCredParams: [{ type: "public-key", alg: -7 }]
      * };
-     * this.webAuthnService.register(jsonOptions);
+     * this.webAuthnService.register(options).subscribe(response => {
+     *   // Handle response
+     * });
      * ```
      */
     register(input) {
@@ -803,42 +1493,51 @@ class WebAuthnService {
         }
     }
     /**
-     * Authenticates using an existing WebAuthn credential with flexible configuration support
+     * Authenticates a user using an existing WebAuthn credential.
      *
-     * @param input Either a high-level AuthenticateConfig with presets, or direct WebAuthn request options
-     * @returns Observable of AuthenticationResponse with clean, developer-friendly format
+     * Supports two input formats:
+     * 1. High-level AuthenticateConfig with preset support and automatic option building
+     * 2. Direct PublicKeyCredentialRequestOptions for full control
      *
-     * @example
-     * ```typescript
-     * // Simple preset usage
-     * this.webAuthnService.authenticate({ preset: 'passkey' });
+     * @param input Either an AuthenticateConfig object or raw WebAuthn request options
+     * @returns Observable containing the authentication response with assertion details
      *
-     * // Config with credential filtering
-     * this.webAuthnService.authenticate({
-     *   username: 'john.doe',
-     *   preset: 'secondFactor',
-     *   allowCredentials: ['credential-id-1', 'credential-id-2']
-     * });
+     * @throws {UnsupportedOperationError} When WebAuthn is not supported
+     * @throws {InvalidOptionsError} When provided options are invalid
+     * @throws {UserCancelledError} When user cancels the authentication
+     * @throws {AuthenticatorError} When authenticator encounters an error
+     * @throws {TimeoutError} When the operation times out
+     * @throws {SecurityError} When a security violation occurs
      *
-     * // Direct WebAuthn options (JSON)
-     * const jsonOptions: PublicKeyCredentialRequestOptionsJSON = {
-     *   challenge: "Y2hhbGxlbmdl",
-     *   allowCredentials: [{
-     *     type: "public-key",
-     *     id: "Y3JlZElk"
-     *   }]
+     * @example Using high-level config:
+     * ```typescript
+     * const config: AuthenticateConfig = {
+     *   preset: 'passkey',
+     *   challenge: 'auth-challenge',
+     *   allowCredentials: ['credential-id-1', 'credential-id-2']
      * };
-     * this.webAuthnService.authenticate(jsonOptions);
      *
-     * // Direct WebAuthn options (native)
-     * const nativeOptions: PublicKeyCredentialRequestOptions = {
-     *   challenge: new Uint8Array([...]),
-     *   allowCredentials: [{
-     *     type: "public-key",
-     *     id: new Uint8Array([...])
-     *   }]
+     * this.webAuthnService.authenticate(config).subscribe({
+     *   next: (response) => {
+     *     console.log('Authentication successful:', response.credential.id);
+     *   },
+     *   error: (error) => {
+     *     if (error instanceof UserCancelledError) {
+     *       console.log('User cancelled authentication');
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @example Using direct options:
+     * ```typescript
+     * const options: PublicKeyCredentialRequestOptions = {
+     *   challenge: new Uint8Array([1,2,3]),
+     *   allowCredentials: [{ type: 'public-key', id: new Uint8Array([4,5,6]) }]
      * };
-     * this.webAuthnService.authenticate(nativeOptions);
+     * this.webAuthnService.authenticate(options).subscribe(response => {
+     *   // Handle response
+     * });
      * ```
      */
     authenticate(input) {
@@ -848,12 +1547,10 @@ class WebAuthnService {
         try {
             let requestOptions;
             if (isAuthenticateConfig(input)) {
-                // High-level config path: validate, resolve preset, build options
                 validateAuthenticateConfig(input);
                 requestOptions = buildRequestOptionsFromConfig(input, this.config);
             }
             else {
-                // Direct options path: use provided options
                 requestOptions = input;
             }
             const parsedOptions = this.parseAuthenticationOptions(requestOptions);
@@ -864,72 +1561,273 @@ class WebAuthnService {
         }
     }
     /**
-     * Parses registration options, handling both JSON and native formats
+     * Registers a new WebAuthn credential using options fetched from a remote server.
+     *
+     * Sends request data via POST to the configured registration endpoint,
+     * receives PublicKeyCredentialCreationOptionsJSON, then proceeds with
+     * standard WebAuthn registration flow.
+     *
+     * @param request Data to send to server (can be any object your server expects)
+     * @template T Type constraint for the request payload
+     * @returns Observable containing the registration response
+     *
+     * @throws {InvalidOptionsError} When remote registration endpoint is not configured
+     * @throws {RemoteEndpointError} When server request fails
+     * @throws {InvalidRemoteOptionsError} When server returns invalid options
+     *
+     * @example
+     * ```typescript
+     * // Simple request
+     * this.webAuthnService.registerRemote({
+     *   username: 'john.doe@example.com'
+     * }).subscribe(response => console.log('Success:', response));
+     *
+     * // Typed request with additional context
+     * interface ServerPayload {
+     *   tenantId: string;
+     *   department: string;
+     * }
+     *
+     * this.webAuthnService.registerRemote<ServerPayload>({
+     *   tenantId: 'acme-corp',
+     *   department: 'engineering'
+     * }).subscribe(response => console.log('Success:', response));
+     * ```
+     */
+    registerRemote(request) {
+        this.validateRemoteRegistrationConfig();
+        const endpoint = this.config.remoteEndpoints.registration;
+        const timeoutMs = this.config.remoteEndpoints?.requestOptions?.timeout || 10000;
+        return this.http
+            .post(endpoint, request)
+            .pipe(timeout(timeoutMs), map((options) => {
+            validateRemoteCreationOptions(options);
+            return options;
+        }), switchMap((options) => this.register(options)), catchError((error) => this.handleRemoteError(error, endpoint, 'registration')));
+    }
+    /**
+     * Authenticates using WebAuthn with options fetched from a remote server.
+     *
+     * Sends request data via POST to the configured authentication endpoint,
+     * receives PublicKeyCredentialRequestOptionsJSON, then proceeds with
+     * standard WebAuthn authentication flow.
+     *
+     * @param request Optional data to send to server (defaults to empty object)
+     * @template T Type constraint for the request payload
+     * @returns Observable containing the authentication response
+     *
+     * @throws {InvalidOptionsError} When remote authentication endpoint is not configured
+     * @throws {RemoteEndpointError} When server request fails
+     * @throws {InvalidRemoteOptionsError} When server returns invalid options
+     *
+     * @example
+     * ```typescript
+     * // Simple request
+     * this.webAuthnService.authenticateRemote({
+     *   username: 'john.doe@example.com'
+     * }).subscribe(response => console.log('Success:', response));
+     *
+     * // Request with no payload (server uses session/context)
+     * this.webAuthnService.authenticateRemote()
+     *   .subscribe(response => console.log('Success:', response));
+     * ```
+     */
+    authenticateRemote(request = {}) {
+        this.validateRemoteAuthenticationConfig();
+        const endpoint = this.config.remoteEndpoints.authentication;
+        const timeoutMs = this.config.remoteEndpoints?.requestOptions?.timeout || 10000;
+        return this.http
+            .post(endpoint, request)
+            .pipe(timeout(timeoutMs), map((options) => {
+            validateRemoteRequestOptions(options);
+            return options;
+        }), switchMap((options) => this.authenticate(options)), catchError((error) => this.handleRemoteError(error, endpoint, 'authentication')));
+    }
+    /**
+     * Validates that remote registration endpoint is configured
+     * @private
+     */
+    validateRemoteRegistrationConfig() {
+        if (!this.config.remoteEndpoints?.registration) {
+            throw new InvalidOptionsError('Remote registration endpoint not configured. Add remoteEndpoints.registration to your WebAuthn config.');
+        }
+    }
+    /**
+     * Validates that remote authentication endpoint is configured
+     * @private
+     */
+    validateRemoteAuthenticationConfig() {
+        if (!this.config.remoteEndpoints?.authentication) {
+            throw new InvalidOptionsError('Remote authentication endpoint not configured. Add remoteEndpoints.authentication to your WebAuthn config.');
+        }
+    }
+    /**
+     * Handles errors from remote HTTP requests
+     * @private
+     */
+    handleRemoteError(error, url, operation) {
+        if (error instanceof HttpErrorResponse) {
+            const context = {
+                url,
+                method: 'POST',
+                operation,
+                status: error.status,
+                statusText: error.statusText,
+            };
+            return throwError(() => new RemoteEndpointError(`${operation} request failed`, context, error));
+        }
+        // Preserve InvalidRemoteOptionsError instances (validation errors)
+        if (error instanceof InvalidRemoteOptionsError) {
+            return throwError(() => error);
+        }
+        return throwError(() => new WebAuthnError(WebAuthnErrorType.UNKNOWN, `Unexpected error during remote ${operation}`, error));
+    }
+    /**
+     * Parses and normalizes registration options from either native or JSON format.
+     * Converts base64url-encoded strings to Uint8Array where necessary.
+     *
+     * @param options Registration options in either native or JSON format
+     * @returns Normalized PublicKeyCredentialCreationOptions for browser API
+     * @private
      */
     parseRegistrationOptions(options) {
         if (isJSONOptions(options)) {
-            // Use native browser function for JSON options
             return PublicKeyCredential.parseCreationOptionsFromJSON(options);
         }
         else {
-            // Options are already in native format
             return options;
         }
     }
     /**
-     * Parses authentication options, handling both JSON and native formats
+     * Parses and normalizes authentication options from either native or JSON format.
+     * Converts base64url-encoded strings to Uint8Array where necessary.
+     *
+     * @param options Authentication options in either native or JSON format
+     * @returns Normalized PublicKeyCredentialRequestOptions for browser API
+     * @private
      */
     parseAuthenticationOptions(options) {
         if (isJSONOptions(options)) {
-            // Use native browser function for JSON options
             return PublicKeyCredential.parseRequestOptionsFromJSON(options);
         }
         else {
-            // Options are already in native format
             return options;
         }
     }
     /**
-     * Processes the raw credential result into a clean RegistrationResponse
+     * Validates that the credential is a valid PublicKeyCredential.
+     *
+     * @param credential Raw credential from navigator.credentials.create()
+     * @returns Validated PublicKeyCredential
+     * @throws {AuthenticatorError} When credential is invalid or null
+     * @private
      */
-    processRegistrationResult(credential) {
+    validateRegistrationCredential(credential) {
         if (!isPublicKeyCredential(credential)) {
             throw new AuthenticatorError('No credential returned from authenticator');
         }
+        return credential;
+    }
+    /**
+     * Extracts basic credential information (ID and transports).
+     *
+     * @param credential Validated PublicKeyCredential
+     * @returns Object containing credential ID and supported transports
+     * @private
+     */
+    extractCredentialInfo(credential) {
         const response = credential.response;
-        // Extract data using the response methods
-        const credentialId = arrayBufferToBase64url(credential.rawId);
-        const transports = (response.getTransports?.() ||
-            []);
-        let publicKey;
+        return {
+            credentialId: arrayBufferToBase64url(credential.rawId),
+            transports: (response.getTransports?.() ||
+                []),
+        };
+    }
+    /**
+     * Safely extracts the public key with proper error handling.
+     *
+     * @param response AuthenticatorAttestationResponse
+     * @returns Public key as base64url string, or undefined if extraction fails
+     * @private
+     */
+    extractPublicKey(response) {
         try {
             const publicKeyBuffer = response.getPublicKey?.();
             if (publicKeyBuffer) {
-                publicKey = arrayBufferToBase64url(publicKeyBuffer);
+                return arrayBufferToBase64url(publicKeyBuffer);
             }
         }
         catch {
             // Public key extraction failed - this is okay, not all algorithms are supported
+            // Some authenticators or algorithms don't provide extractable public keys
         }
-        // Create the raw response for backward compatibility
-        const rawResponse = {
+        return undefined;
+    }
+    /**
+     * Creates the complete raw WebAuthn response for advanced use cases.
+     * Provides access to all WebAuthn data including attestation objects and metadata.
+     *
+     * @param credential Validated PublicKeyCredential
+     * @param credentialId Already extracted credential ID
+     * @param publicKey Extracted public key (may be undefined)
+     * @returns Complete WebAuthnRegistrationResult with all WebAuthn data
+     * @private
+     */
+    createRawRegistrationResponse(credential, credentialId, publicKey) {
+        const response = credential.response;
+        return {
             credentialId,
-            publicKey: publicKey ||
-                arrayBufferToBase64url(response.getPublicKey?.() || new ArrayBuffer(0)),
+            publicKey: publicKey || arrayBufferToBase64url(new ArrayBuffer(0)), // Clean fallback
             attestationObject: arrayBufferToBase64url(response.attestationObject),
             clientDataJSON: arrayBufferToBase64url(response.clientDataJSON),
-            transports: transports,
+            transports: (response.getTransports?.() ||
+                []),
         };
+    }
+    /**
+     * Assembles the final registration response.
+     * Combines all extracted data into the final response format.
+     *
+     * @param credentialInfo Basic credential information
+     * @param publicKey Extracted public key
+     * @param rawResponse Raw WebAuthn response
+     * @returns Complete RegistrationResponse
+     * @private
+     */
+    assembleRegistrationResponse(credentialInfo, publicKey, rawResponse) {
         return {
             success: true,
-            credentialId,
+            credentialId: credentialInfo.credentialId,
             publicKey,
-            transports,
+            transports: credentialInfo.transports,
             rawResponse,
         };
     }
     /**
-     * Processes the raw credential result into a clean AuthenticationResponse
+     * Processes the result of a WebAuthn registration operation.
+     * Converts the browser credential response into a structured RegistrationResponse.
+     *
+     * @param credential The credential returned by navigator.credentials.create()
+     * @returns Structured registration response with parsed credential data
+     * @throws {AuthenticatorError} When credential creation fails or returns null
+     * @private
+     */
+    processRegistrationResult(credential) {
+        const validCredential = this.validateRegistrationCredential(credential);
+        const credentialInfo = this.extractCredentialInfo(validCredential);
+        const response = validCredential.response;
+        const publicKey = this.extractPublicKey(response);
+        const rawResponse = this.createRawRegistrationResponse(validCredential, credentialInfo.credentialId, publicKey);
+        return this.assembleRegistrationResponse(credentialInfo, publicKey, rawResponse);
+    }
+    /**
+     * Processes the result of a WebAuthn authentication operation.
+     * Converts the browser credential response into a structured AuthenticationResponse.
+     *
+     * @param credential The credential returned by navigator.credentials.get()
+     * @returns Structured authentication response with parsed assertion data
+     * @throws {AuthenticatorError} When authentication fails or returns null
+     * @private
      */
     processAuthenticationResult(credential) {
         if (!isPublicKeyCredential(credential)) {
@@ -941,7 +1839,7 @@ class WebAuthnService {
         if (response.userHandle) {
             userHandle = arrayBufferToBase64url(response.userHandle);
         }
-        // Create the raw response for backward compatibility
+        // Create the complete raw response for advanced use cases
         const rawResponse = {
             credentialId,
             authenticatorData: arrayBufferToBase64url(response.authenticatorData),
@@ -957,36 +1855,81 @@ class WebAuthnService {
         };
     }
     /**
-     * Enhanced error handling that maps DOMExceptions to specific error types
+     * Central error handling dispatcher for WebAuthn operations.
+     * Routes different error types to specialized handlers for proper error classification.
+     *
+     * @param error The error to handle (can be DOMException, TypeError, or any other error)
+     * @returns Observable that throws an appropriate WebAuthnError subclass
+     * @private
      */
     handleWebAuthnError(error) {
-        // Handle DOMExceptions from WebAuthn API
         if (error instanceof DOMException) {
-            switch (error.name) {
-                case 'NotAllowedError':
-                    return throwError(() => new UserCancelledError(error));
-                case 'InvalidStateError':
-                    return throwError(() => new AuthenticatorError('Invalid authenticator state', error));
-                case 'NotSupportedError':
-                    return throwError(() => new UnsupportedOperationError('Operation not supported', error));
-                case 'SecurityError':
-                    return throwError(() => new SecurityError('Security error occurred', error));
-                case 'TimeoutError':
-                    return throwError(() => new TimeoutError('Operation timed out', error));
-                case 'EncodingError':
-                    return throwError(() => new InvalidOptionsError('Encoding error in options', error));
-                default:
-                    return throwError(() => new WebAuthnError(WebAuthnErrorType.UNKNOWN, `Unknown WebAuthn error: ${error.message}`, error));
-            }
+            return this.handleDOMException(error);
         }
-        // Handle JSON parsing errors
-        if (error instanceof TypeError &&
-            (error.message.includes('parseCreationOptionsFromJSON') ||
-                error.message.includes('parseRequestOptionsFromJSON'))) {
-            return throwError(() => new InvalidOptionsError('Invalid JSON options format', error));
+        if (this.isJSONParsingError(error)) {
+            return this.handleJSONParsingError(error);
         }
-        // Handle other errors
-        return throwError(() => new WebAuthnError(WebAuthnErrorType.UNKNOWN, `Unexpected error: ${error.message}`, error));
+        return this.handleUnknownError(error);
+    }
+    /**
+     * Handles DOMExceptions from the WebAuthn API using a mapping approach.
+     * Maps specific DOMException names to appropriate WebAuthnError subclasses.
+     *
+     * @param error The DOMException thrown by the WebAuthn API
+     * @returns Observable that throws an appropriate WebAuthnError subclass
+     * @private
+     */
+    handleDOMException(error) {
+        const errorMap = {
+            NotAllowedError: () => new UserCancelledError(error),
+            InvalidStateError: () => new AuthenticatorError('Invalid authenticator state', error),
+            NotSupportedError: () => new UnsupportedOperationError('Operation not supported', error),
+            SecurityError: () => new SecurityError('Security error occurred', error),
+            TimeoutError: () => new TimeoutError('Operation timed out', error),
+            EncodingError: () => new InvalidOptionsError('Encoding error in options', error),
+        };
+        const errorFactory = errorMap[error.name];
+        const webAuthnError = errorFactory
+            ? errorFactory()
+            : new WebAuthnError(WebAuthnErrorType.UNKNOWN, `Unknown WebAuthn error: ${error.message}`, error);
+        return throwError(() => webAuthnError);
+    }
+    /**
+     * Determines if an error is related to JSON parsing issues.
+     * Specifically checks for TypeError messages indicating JSON parsing failures.
+     *
+     * @param error The error to check
+     * @returns True if the error is a JSON parsing error, false otherwise
+     * @private
+     */
+    isJSONParsingError(error) {
+        return (error instanceof TypeError &&
+            (error.message.includes('parseCreationOptionsFromJSON') ||
+                error.message.includes('parseRequestOptionsFromJSON')));
+    }
+    /**
+     * Handles JSON parsing errors specifically.
+     * These errors occur when invalid JSON format options are provided.
+     *
+     * @param error The TypeError from JSON parsing
+     * @returns Observable that throws an InvalidOptionsError
+     * @private
+     */
+    handleJSONParsingError(error) {
+        // At this point we know it's a TypeError from isJSONParsingError check
+        return throwError(() => new InvalidOptionsError('Invalid JSON options format', error));
+    }
+    /**
+     * Handles any unexpected errors that don't fall into other categories.
+     * Provides a fallback for errors that aren't DOMExceptions or JSON parsing errors.
+     *
+     * @param error The unexpected error
+     * @returns Observable that throws a generic WebAuthnError
+     * @private
+     */
+    handleUnknownError(error) {
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        return throwError(() => new WebAuthnError(WebAuthnErrorType.UNKNOWN, `Unexpected error: ${message}`, error instanceof Error ? error : new Error(String(error))));
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.0.3", ngImport: i0, type: WebAuthnService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.0.3", ngImport: i0, type: WebAuthnService, providedIn: 'root' });
@@ -1031,22 +1974,6 @@ function provideWebAuthn(relyingParty, config = {}) {
         WebAuthnService,
     ];
 }
-/**
- * @deprecated Use provideWebAuthn(relyingParty, config) instead.
- * This version is kept for backward compatibility but requires relying party information.
- */
-function provideWebAuthnLegacy(config) {
-    if (!config.relyingParty) {
-        throw new Error('WebAuthn configuration must include relying party information. Use provideWebAuthn(relyingParty, config) instead.');
-    }
-    return [
-        {
-            provide: WEBAUTHN_CONFIG,
-            useValue: config,
-        },
-        WebAuthnService,
-    ];
-}
 
 // Core service
 
@@ -1054,5 +1981,5 @@ function provideWebAuthnLegacy(config) {
  * Generated bundle index. Do not edit.
  */
 
-export { AuthenticatorError, DEFAULT_WEBAUTHN_CONFIG, DEVICE_BOUND_PRESET, InvalidOptionsError, NetworkError, PASSKEY_PRESET, PRESET_MAP, SECOND_FACTOR_PRESET, SecurityError, TimeoutError, UnsupportedOperationError, UserCancelledError, WEBAUTHN_CONFIG, WebAuthnError, WebAuthnErrorType, WebAuthnService, arrayBufferToBase64, arrayBufferToBase64url, arrayBufferToCredentialId, arrayBufferToString, base64ToArrayBuffer, base64urlToArrayBuffer, createWebAuthnConfig, credentialIdToArrayBuffer, generateChallenge, generateUserId, getDefaultPubKeyCredParams, getSupportedTransports, isJSONOptions, isPlatformAuthenticatorAvailable, isPublicKeyCredential, isWebAuthnSupported, provideWebAuthn, provideWebAuthnLegacy, stringToArrayBuffer, validateRegistrationOptions };
+export { AuthenticatorError, DEFAULT_WEBAUTHN_CONFIG, EXTERNAL_SECURITY_KEY_PRESET, InvalidOptionsError, InvalidRemoteOptionsError, NetworkError, PASSKEY_PRESET, PLATFORM_AUTHENTICATOR_PRESET, PRESET_MAP, RemoteEndpointError, SecurityError, TimeoutError, UnsupportedOperationError, UserCancelledError, WEBAUTHN_CONFIG, WebAuthnError, WebAuthnErrorType, WebAuthnService, arrayBufferToBase64, arrayBufferToBase64url, arrayBufferToCredentialId, arrayBufferToString, base64ToArrayBuffer, base64urlToArrayBuffer, createWebAuthnConfig, credentialIdToArrayBuffer, generateChallenge, generateUserId, getDefaultPubKeyCredParams, getSupportedTransports, isAuthenticateConfig, isCreationOptions, isJSONOptions, isPlatformAuthenticatorAvailable, isPublicKeyCredential, isRegisterConfig, isRequestOptions, isWebAuthnSupported, provideWebAuthn, stringToArrayBuffer, validateRegistrationOptions, validateRemoteCreationOptions, validateRemoteRequestOptions };
 //# sourceMappingURL=ngx-webauthn.mjs.map