ngx-webauthn 0.0.2 → 0.2.0

package/index.d.ts

@@ -2,6 +2,99 @@ import { Observable } from 'rxjs';
 import * as i0 from '@angular/core';
 import { InjectionToken, Provider } from '@angular/core';
 
+/**
+ * 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.
+ */
+
+/**
+ * Required relying party configuration
+ */
+interface RelyingPartyConfig {
+    /**
+     * Human-readable identifier for the Relying Party
+     * @example "ACME Corporation"
+     */
+    name: string;
+    /**
+     * A valid domain string that identifies the Relying Party on whose behalf a given registration or authentication ceremony is being performed
+     * @example "login.example.com" or "example.com"
+     */
+    id?: string;
+}
+/**
+ * Configuration interface for WebAuthn service
+ * Now includes required relying party information and advanced options
+ */
+interface WebAuthnConfig {
+    /**
+     * Required relying party information for WebAuthn operations
+     * This is critical for security - must be configured properly for production use
+     */
+    relyingParty: RelyingPartyConfig;
+    /**
+     * Default timeout for WebAuthn operations in milliseconds
+     * @default 60000
+     */
+    defaultTimeout?: number;
+    /**
+     * Default public key credential algorithms in order of preference
+     * @default [ES256, RS256]
+     */
+    defaultAlgorithms?: PublicKeyCredentialParameters[];
+    /**
+     * Whether to enforce user verification by default
+     * @default false
+     */
+    enforceUserVerification?: boolean;
+    /**
+     * Default attestation conveyance preference
+     * @default "none"
+     */
+    defaultAttestation?: AttestationConveyancePreference;
+    /**
+     * Default authenticator selection criteria
+     */
+    defaultAuthenticatorSelection?: AuthenticatorSelectionCriteria;
+    /**
+     * Optional remote endpoints for fetching WebAuthn options from server
+     */
+    remoteEndpoints?: {
+        /**
+         * Absolute URL for fetching PublicKeyCredentialCreationOptionsJSON
+         * @example "https://api.example.com/webauthn/registration/options"
+         */
+        registration?: string;
+        /**
+         * Absolute URL for fetching PublicKeyCredentialRequestOptionsJSON
+         * @example "https://api.example.com/webauthn/authentication/options"
+         */
+        authentication?: string;
+        /** HTTP request configuration */
+        requestOptions?: {
+            /** Network timeout in milliseconds (separate from WebAuthn timeout) */
+            timeout?: number;
+        };
+    };
+}
+/**
+ * Default configuration for WebAuthn service
+ * Note: relyingParty must be provided by the application
+ */
+declare const DEFAULT_WEBAUTHN_CONFIG: Omit<WebAuthnConfig, 'relyingParty'>;
+/**
+ * Injection token for WebAuthn configuration
+ */
+declare const WEBAUTHN_CONFIG: InjectionToken<WebAuthnConfig>;
+/**
+ * Creates a complete WebAuthn configuration with required relying party information
+ * @param relyingParty Required relying party configuration
+ * @param overrides Optional configuration overrides
+ */
+declare function createWebAuthnConfig(relyingParty: RelyingPartyConfig, overrides?: Partial<Omit<WebAuthnConfig, 'relyingParty'>>): WebAuthnConfig;
+
 /**
  * Preset for modern, passwordless, cross-device credentials.
  *
@@ -28,7 +121,7 @@ declare 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.
@@ -39,7 +132,7 @@ declare const PASSKEY_PRESET: {
  * - Favors cross-platform authenticators (USB/NFC security keys)
  * - Credentials typically not synced between devices
  */
-declare const SECOND_FACTOR_PRESET: {
+declare const EXTERNAL_SECURITY_KEY_PRESET: {
     readonly authenticatorSelection: {
         readonly residentKey: "discouraged";
         readonly userVerification: "preferred";
@@ -54,10 +147,10 @@ declare 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)
@@ -65,7 +158,7 @@ declare const SECOND_FACTOR_PRESET: {
  * - Requires user verification (biometric/PIN)
  * - Credentials bound to specific device (no syncing)
  */
-declare const DEVICE_BOUND_PRESET: {
+declare const PLATFORM_AUTHENTICATOR_PRESET: {
     readonly authenticatorSelection: {
         readonly authenticatorAttachment: "platform";
         readonly residentKey: "required";
@@ -97,7 +190,7 @@ declare const PRESET_MAP: {
             readonly alg: -257;
         }];
     };
-    readonly secondFactor: {
+    readonly externalSecurityKey: {
         readonly authenticatorSelection: {
             readonly residentKey: "discouraged";
             readonly userVerification: "preferred";
@@ -111,7 +204,7 @@ declare const PRESET_MAP: {
             readonly alg: -257;
         }];
     };
-    readonly deviceBound: {
+    readonly platformAuthenticator: {
         readonly authenticatorSelection: {
             readonly authenticatorAttachment: "platform";
             readonly residentKey: "required";
@@ -132,7 +225,7 @@ declare const PRESET_MAP: {
 type PresetName = keyof typeof PRESET_MAP;
 
 /**
- * High-level configuration interfaces for WebAuthn operations
+ * Operation-level configuration interfaces for WebAuthn operations
  *
  * These interfaces provide a convenient, preset-driven API while still allowing
  * full customization through override properties. They derive from standard WebAuthn
@@ -174,8 +267,8 @@ interface RegisterConfig extends Partial<Pick<PublicKeyCredentialCreationOptions
     /**
      * Optional preset to use as base configuration
      * - 'passkey': Modern passwordless, cross-device credentials
-     * - 'secondFactor': Security key as second factor after password
-     * - 'deviceBound': High-security, device-bound credentials
+     * - 'externalSecurityKey': External security key as second factor after password
+     * - 'platformAuthenticator': High-security, platform authenticator credentials
      */
     preset?: PresetName;
     /**
@@ -251,8 +344,66 @@ type RegisterInput = RegisterConfig | PublicKeyCredentialCreationOptions | Publi
 type AuthenticateInput = AuthenticateConfig | PublicKeyCredentialRequestOptions | PublicKeyCredentialRequestOptionsJSON;
 
 /**
- * Result of WebAuthn registration
- * Simplified version with all ArrayBuffers converted to Base64URL strings
+ * Remote configuration types for WebAuthn operations
+ *
+ * These types provide flexible, type-safe interfaces for communicating with
+ * remote servers that provide WebAuthn options. They use generics to allow
+ * any server payload structure while maintaining TypeScript safety.
+ */
+/**
+ * Request payload for remote registration endpoint.
+ *
+ * Can contain any data your server needs to generate WebAuthn creation options.
+ * Sent as JSON body via POST request.
+ *
+ * @template T The structure of data your server expects
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * webAuthnService.registerRemote({ username: 'user@example.com' });
+ *
+ * // Custom server payload
+ * interface MyPayload { tenantId: string; userId: number; }
+ * webAuthnService.registerRemote<MyPayload>({
+ *   tenantId: 'acme',
+ *   userId: 123
+ * });
+ * ```
+ */
+type RemoteRegistrationRequest<T extends Record<string, any> = Record<string, any>> = T;
+/**
+ * Request payload for remote authentication endpoint.
+ *
+ * Can contain any data your server needs to generate WebAuthn request options.
+ * Sent as JSON body via POST request.
+ *
+ * @template T The structure of data your server expects
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * webAuthnService.authenticateRemote({ username: 'user@example.com' });
+ *
+ * // Custom server payload
+ * interface MyAuthPayload { sessionId: string; context: string; }
+ * webAuthnService.authenticateRemote<MyAuthPayload>({
+ *   sessionId: 'abc123',
+ *   context: 'mobile'
+ * });
+ * ```
+ */
+type RemoteAuthenticationRequest<T extends Record<string, any> = Record<string, any>> = T;
+
+/**
+ * Response interfaces for WebAuthn operations
+ *
+ * This file contains both raw WebAuthn results (converted to Base64URL strings)
+ * and enhanced user-friendly response formats.
+ */
+/**
+ * Raw result of WebAuthn registration
+ * Simplified version with all ArrayBuffers converted to Base64URL strings for easier handling
  */
 interface WebAuthnRegistrationResult {
     credentialId: string;
@@ -262,8 +413,8 @@ interface WebAuthnRegistrationResult {
     transports?: AuthenticatorTransport[];
 }
 /**
- * Result of WebAuthn authentication
- * Simplified version with all ArrayBuffers converted to Base64URL strings
+ * Raw result of WebAuthn authentication
+ * Simplified version with all ArrayBuffers converted to Base64URL strings for easier handling
  */
 interface WebAuthnAuthenticationResult {
     credentialId: string;
@@ -272,17 +423,9 @@ interface WebAuthnAuthenticationResult {
     signature: string;
     userHandle?: string;
 }
-/**
- * Browser support information
- */
-interface WebAuthnSupport {
-    isSupported: boolean;
-    isPlatformAuthenticatorAvailable: boolean;
-    supportedTransports: AuthenticatorTransport[];
-}
 /**
  * Enhanced registration response with clean, developer-friendly format
- * Used by the new high-level register() method
+ * Used by the high-level register() method
  */
 interface RegistrationResponse {
     /**
@@ -303,14 +446,14 @@ interface RegistrationResponse {
      */
     transports?: AuthenticatorTransport[];
     /**
-     * Raw WebAuthn response for advanced users who need access to all data
-     * This preserves backward compatibility and provides access to attestation objects, etc.
+     * Complete raw WebAuthn response for advanced use cases
+     * Provides access to all WebAuthn data including attestation objects, metadata, etc.
      */
     rawResponse?: WebAuthnRegistrationResult;
 }
 /**
  * Enhanced authentication response with clean, developer-friendly format
- * Used by the new high-level authenticate() method
+ * Used by the high-level authenticate() method
  */
 interface AuthenticationResponse {
     /**
@@ -327,11 +470,19 @@ interface AuthenticationResponse {
      */
     userHandle?: string;
     /**
-     * Raw WebAuthn response for advanced users who need access to all data
-     * This preserves backward compatibility and provides access to signatures, etc.
+     * Complete raw WebAuthn response for advanced use cases
+     * Provides access to all WebAuthn data including signatures, authenticator data, etc.
      */
     rawResponse?: WebAuthnAuthenticationResult;
 }
+/**
+ * Browser support information
+ */
+interface WebAuthnSupport {
+    isSupported: boolean;
+    isPlatformAuthenticatorAvailable: boolean;
+    supportedTransports: AuthenticatorTransport[];
+}
 
 /**
  * Enhanced Angular service for WebAuthn operations
@@ -340,186 +491,350 @@ interface AuthenticationResponse {
  */
 declare class WebAuthnService {
     private readonly config;
+    private readonly http;
     /**
-     * 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(): boolean;
     /**
-     * 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(): Observable<WebAuthnSupport>;
     /**
-     * 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: RegisterInput): Observable<RegistrationResponse>;
     /**
-     * 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
+     *
+     * @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
      *
-     * // Config with credential filtering
-     * this.webAuthnService.authenticate({
-     *   username: 'john.doe',
-     *   preset: 'secondFactor',
+     * @example Using high-level config:
+     * ```typescript
+     * const config: AuthenticateConfig = {
+     *   preset: 'passkey',
+     *   challenge: 'auth-challenge',
      *   allowCredentials: ['credential-id-1', 'credential-id-2']
+     * };
+     *
+     * 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');
+     *     }
+     *   }
      * });
+     * ```
      *
-     * // Direct WebAuthn options (JSON)
-     * const jsonOptions: PublicKeyCredentialRequestOptionsJSON = {
-     *   challenge: "Y2hhbGxlbmdl",
-     *   allowCredentials: [{
-     *     type: "public-key",
-     *     id: "Y3JlZElk"
-     *   }]
-     * };
-     * this.webAuthnService.authenticate(jsonOptions);
-     *
-     * // Direct WebAuthn options (native)
-     * const nativeOptions: PublicKeyCredentialRequestOptions = {
-     *   challenge: new Uint8Array([...]),
-     *   allowCredentials: [{
-     *     type: "public-key",
-     *     id: new Uint8Array([...])
-     *   }]
+     * @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: AuthenticateInput): Observable<AuthenticationResponse>;
     /**
-     * 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<T extends Record<string, any> = Record<string, any>>(request: RemoteRegistrationRequest<T>): Observable<RegistrationResponse>;
+    /**
+     * 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<T extends Record<string, any> = Record<string, any>>(request?: RemoteAuthenticationRequest<T>): Observable<AuthenticationResponse>;
+    /**
+     * Validates that remote registration endpoint is configured
+     * @private
+     */
+    private validateRemoteRegistrationConfig;
+    /**
+     * Validates that remote authentication endpoint is configured
+     * @private
+     */
+    private validateRemoteAuthenticationConfig;
+    /**
+     * Handles errors from remote HTTP requests
+     * @private
+     */
+    private handleRemoteError;
+    /**
+     * 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
      */
     private parseRegistrationOptions;
     /**
-     * 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
      */
     private parseAuthenticationOptions;
     /**
-     * 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
      */
-    private processRegistrationResult;
+    private validateRegistrationCredential;
     /**
-     * Processes the raw credential result into a clean AuthenticationResponse
+     * Extracts basic credential information (ID and transports).
+     *
+     * @param credential Validated PublicKeyCredential
+     * @returns Object containing credential ID and supported transports
+     * @private
      */
-    private processAuthenticationResult;
+    private extractCredentialInfo;
     /**
-     * Enhanced error handling that maps DOMExceptions to specific error types
+     * Safely extracts the public key with proper error handling.
+     *
+     * @param response AuthenticatorAttestationResponse
+     * @returns Public key as base64url string, or undefined if extraction fails
+     * @private
      */
-    private handleWebAuthnError;
-    static ɵfac: i0.ɵɵFactoryDeclaration<WebAuthnService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<WebAuthnService>;
-}
-
-/**
- * WebAuthn Configuration
- * Provides configuration interfaces and injection token for WebAuthn service
- */
-
-/**
- * Required relying party configuration
- */
-interface RelyingPartyConfig {
+    private extractPublicKey;
     /**
-     * Human-readable identifier for the Relying Party
-     * @example "ACME Corporation"
+     * 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
      */
-    name: string;
+    private createRawRegistrationResponse;
     /**
-     * A valid domain string that identifies the Relying Party on whose behalf a given registration or authentication ceremony is being performed
-     * @example "login.example.com" or "example.com"
+     * 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
      */
-    id?: string;
-}
-/**
- * Configuration interface for WebAuthn service
- * Now includes required relying party information and advanced options
- */
-interface WebAuthnConfig {
+    private assembleRegistrationResponse;
     /**
-     * Required relying party information for WebAuthn operations
-     * This is critical for security - must be configured properly for production use
+     * 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
      */
-    relyingParty: RelyingPartyConfig;
+    private processRegistrationResult;
     /**
-     * Default timeout for WebAuthn operations in milliseconds
-     * @default 60000
+     * 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
      */
-    defaultTimeout?: number;
+    private processAuthenticationResult;
     /**
-     * Default public key credential algorithms in order of preference
-     * @default [ES256, RS256]
+     * 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
      */
-    defaultAlgorithms?: PublicKeyCredentialParameters[];
+    private handleWebAuthnError;
     /**
-     * Whether to enforce user verification by default
-     * @default false
+     * 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
      */
-    enforceUserVerification?: boolean;
+    private handleDOMException;
     /**
-     * Default attestation conveyance preference
-     * @default "none"
+     * 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
      */
-    defaultAttestation?: AttestationConveyancePreference;
+    private isJSONParsingError;
     /**
-     * Default authenticator selection criteria
+     * 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
      */
-    defaultAuthenticatorSelection?: AuthenticatorSelectionCriteria;
+    private handleJSONParsingError;
+    /**
+     * 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
+     */
+    private handleUnknownError;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WebAuthnService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WebAuthnService>;
 }
-/**
- * Default configuration for WebAuthn service
- * Note: relyingParty must be provided by the application
- */
-declare const DEFAULT_WEBAUTHN_CONFIG: Omit<WebAuthnConfig, 'relyingParty'>;
-/**
- * Injection token for WebAuthn configuration
- */
-declare const WEBAUTHN_CONFIG: InjectionToken<WebAuthnConfig>;
-/**
- * Creates a complete WebAuthn configuration with required relying party information
- * @param relyingParty Required relying party configuration
- * @param overrides Optional configuration overrides
- */
-declare function createWebAuthnConfig(relyingParty: RelyingPartyConfig, overrides?: Partial<Omit<WebAuthnConfig, 'relyingParty'>>): WebAuthnConfig;
 
 /**
  * WebAuthn Providers
@@ -547,16 +862,15 @@ declare function createWebAuthnConfig(relyingParty: RelyingPartyConfig, override
  * ```
  */
 declare function provideWebAuthn(relyingParty: RelyingPartyConfig, config?: Partial<Omit<WebAuthnConfig, 'relyingParty'>>): Provider[];
-/**
- * @deprecated Use provideWebAuthn(relyingParty, config) instead.
- * This version is kept for backward compatibility but requires relying party information.
- */
-declare function provideWebAuthnLegacy(config: WebAuthnConfig): Provider[];
 
 /**
  * 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.
+ */
 declare enum WebAuthnErrorType {
     NOT_SUPPORTED = "NOT_SUPPORTED",
     USER_CANCELLED = "USER_CANCELLED",
@@ -566,58 +880,292 @@ declare enum WebAuthnErrorType {
     NETWORK_ERROR = "NETWORK_ERROR",
     SECURITY_ERROR = "SECURITY_ERROR",
     TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    REMOTE_ENDPOINT_ERROR = "REMOTE_ENDPOINT_ERROR",
+    INVALID_REMOTE_OPTIONS = "INVALID_REMOTE_OPTIONS",
     UNKNOWN = "UNKNOWN"
 }
 /**
- * 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);
+ *   }
+ * }
+ * ```
  */
 declare class WebAuthnError extends Error {
     readonly type: WebAuthnErrorType;
     readonly originalError?: Error | undefined;
+    /**
+     * 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: WebAuthnErrorType, message: string, originalError?: Error | undefined);
+    /**
+     * 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: DOMException): WebAuthnError;
+    /**
+     * Maps DOMException names to WebAuthn error types.
+     * Provides semantic classification of browser-level errors.
+     *
+     * @param name The DOMException name
+     * @returns Corresponding WebAuthnErrorType
+     * @private
+     */
     private static mapDOMExceptionToType;
 }
 /**
- * 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');
+ *   }
+ * }
+ * ```
  */
 declare class UserCancelledError extends WebAuthnError {
+    /**
+     * Creates a new UserCancelledError.
+     *
+     * @param originalError The original DOMException that triggered this error (optional)
+     */
     constructor(originalError?: Error);
 }
 /**
- * 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);
+ *   }
+ * }
+ * ```
  */
 declare 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: string, originalError?: Error);
 }
 /**
- * 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);
+ *   }
+ * }
+ * ```
  */
 declare 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: string, originalError?: Error);
 }
 /**
- * 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');
+ *   }
+ * }
+ * ```
  */
 declare 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: string, originalError?: Error);
 }
 /**
- * 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);
+ *   }
+ * }
+ * ```
  */
 declare 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: string, originalError?: Error);
 }
 /**
- * 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);
+ *   }
+ * }
+ * ```
  */
 declare 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: string, originalError?: Error);
 }
 /**
- * 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');
+ *   }
+ * }
+ * ```
  */
 declare 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: string, originalError?: Error);
+}
+/**
+ * Context information for remote endpoint errors (security-conscious)
+ */
+interface RemoteErrorContext {
+    readonly url: string;
+    readonly method: string;
+    readonly operation: 'registration' | 'authentication';
+    readonly status?: number;
+    readonly statusText?: string;
+}
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare class RemoteEndpointError extends WebAuthnError {
+    readonly context: RemoteErrorContext;
+    /**
+     * 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: string, context: RemoteErrorContext, originalError?: Error);
+}
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare 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: string, originalError?: Error);
 }
 
@@ -698,5 +1246,133 @@ declare function isJSONOptions(options: any): boolean;
  */
 declare function isPublicKeyCredential(credential: Credential | null): credential is PublicKeyCredential;
 
-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 type { AuthenticateConfig, AuthenticateConfig as AuthenticateConfigModel, AuthenticateInput, AuthenticationResponse, PresetName, RegisterConfig, RegisterConfig as RegisterConfigModel, RegisterInput, RegistrationResponse, RelyingPartyConfig, WebAuthnAuthenticationResult, WebAuthnConfig, WebAuthnRegistrationResult, WebAuthnSupport };
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function validateRemoteCreationOptions(options: unknown): asserts options is PublicKeyCredentialCreationOptionsJSON;
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function validateRemoteRequestOptions(options: unknown): asserts options is PublicKeyCredentialRequestOptionsJSON;
+
+/**
+ * Type guard utilities for WebAuthn operations
+ *
+ * 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 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);
+ * }
+ * ```
+ */
+declare function isRegisterConfig(input: unknown): input is RegisterConfig;
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function isAuthenticateConfig(input: unknown): input is AuthenticateConfig;
+/**
+ * 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 });
+ * }
+ * ```
+ */
+declare function isCreationOptions(input: unknown): input is PublicKeyCredentialCreationOptions | PublicKeyCredentialCreationOptionsJSON;
+/**
+ * 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 });
+ * }
+ * ```
+ */
+declare function isRequestOptions(input: unknown): input is PublicKeyCredentialRequestOptions | PublicKeyCredentialRequestOptionsJSON;
+
+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 };
+export type { AuthenticateConfig, AuthenticateInput, AuthenticationResponse, EnhancedRelyingParty, FlexibleChallenge, FlexibleCredentialDescriptors, FlexibleUserId, PresetName, RegisterConfig, RegisterInput, RegistrationResponse, RelyingPartyConfig, RemoteAuthenticationRequest, RemoteErrorContext, RemoteRegistrationRequest, WebAuthnAuthenticationResult, WebAuthnConfig, WebAuthnRegistrationResult, WebAuthnSupport };