Authenticator Selection Hints Processing - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Authenticator Selection Hints Processing

Table of Contents

  1. Introduction
  2. System Architecture
  3. Core Components
  4. User Interface Integration
  5. Data Flow and Processing
  6. Enforcement Logic
  7. Two-Way Synchronization
  8. Examples and Usage Patterns
  9. Error Handling and Validation
  10. Integration with WebAuthn

Introduction

The authenticator selection hints system is a sophisticated mechanism that enables users to express preferences for authenticator types through intuitive checkbox interfaces. This system bridges the gap between user-friendly hint selections and the technical WebAuthn specification's authenticatorAttachment requirements, ensuring optimal user experiences while maintaining compatibility across different authenticator types.

The system operates on three primary hint categories: client-device, hybrid, and security-key, each mapping to specific authenticator attachment types that guide browser behavior during credential creation and authentication processes.

System Architecture

The authenticator selection hints system follows a modular architecture with clear separation of concerns:

graph TB
subgraph "User Interface Layer"
UI[HTML Checkboxes]
Events[Event Handlers]
end
subgraph "JavaScript Processing Layer"
Collect[collectSelectedHints]
Apply[applyHintsToCheckboxes]
Derive[deriveAllowedAttachmentsFromHints]
Enforce[ensureAuthenticationHintsAllowed]
end
subgraph "WebAuthn Integration"
Attachments[authenticatorAttachment Values]
Options[WebAuthn Options]
Credentials[Credential Filtering]
end
subgraph "Backend Processing"
Python[Python Backend]
Validation[Validation Logic]
end
UI --> Events
Events --> Collect
Events --> Apply
Collect --> Derive
Apply --> Attachments
Derive --> Attachments
Attachments --> Options
Options --> Credentials
Options --> Python
Python --> Validation
Enforce --> Options

Diagram sources

Core Components

HINT_ATTACHMENT_MAP Configuration

The system relies on a central mapping configuration that defines how user-selected hints translate to authenticator attachment values:

graph LR
subgraph "User Hints"
CD[client-device]
H[hybrid]
SK[security-key]
end
subgraph "Attachment Mappings"
CD --> Platform[platform]
H --> Cross[cross-platform]
SK --> Cross
end
subgraph "WebAuthn Values"
Platform --> PlatformVal["'platform'"]
Cross --> CrossVal["'cross-platform'"]
end

Diagram sources

Hint Collection System

The collectSelectedHints function gathers user selections based on the current scope (registration vs authentication):

Scope Checkbox IDs Hint Values
Registration hint-client-device, hint-hybrid, hint-security-key client-device, hybrid, security-key
Authentication hint-client-device-auth, hint-hybrid-auth, hint-security-key-auth client-device, hybrid, security-key

Section sources

Attachment Resolution Engine

The deriveAllowedAttachmentsFromHints function transforms hint values into authenticator attachment specifications:

flowchart TD
Input[Hint Array] --> Normalize[Normalize Values]
Normalize --> Filter[Filter Non-Empty]
Filter --> Map[Mapped Values Lookup]
Map --> Dedupe[Deduplicate Attachments]
Dedupe --> Output[Attachment Array]
Map --> SecurityKey{security-key?}
Map --> Hybrid{hybrid?}
Map --> ClientDevice{client-device?}
SecurityKey --> CrossPlatform[cross-platform]
Hybrid --> CrossPlatform
ClientDevice --> Platform[platform]

Diagram sources

Section sources

User Interface Integration

Checkbox Event Handling

The system integrates seamlessly with the main application through event listeners that trigger updates when hint selections change:

sequenceDiagram
participant User as User
participant UI as Checkbox UI
participant JS as JavaScript Handler
participant State as Application State
participant JSON as JSON Editor
User->>UI : Click Hint Checkbox
UI->>JS : Trigger Change Event
JS->>JS : collectSelectedHints()
JS->>State : Update Internal State
JS->>JSON : Refresh JSON Representation
JS->>UI : Apply Updated Hints

Diagram sources

HTML Template Integration

The system utilizes dedicated checkbox elements in both registration and authentication contexts:

Element ID Purpose Scope
hint-client-device Platform authenticators Registration
hint-hybrid Cross-platform hybrid devices Registration
hint-security-key Security keys Registration
hint-client-device-auth Platform authenticators Authentication
hint-hybrid-auth Cross-platform hybrid devices Authentication
hint-security-key-auth Security keys Authentication

Section sources

Data Flow and Processing

Registration Flow

During credential registration, the system processes hints through multiple stages:

flowchart TD
Start[User Selects Hints] --> Collect[collectSelectedHints]
Collect --> Validate[Validate Selections]
Validate --> Derive[deriveAllowedAttachmentsFromHints]
Derive --> Apply[applyAuthenticatorAttachmentPreference]
Apply --> Filter[Filter Stored Credentials]
Filter --> Create[Create Registration Options]
Create --> Submit[Submit to Server]

Diagram sources

Authentication Flow

Authentication processing follows a similar pattern with additional enforcement logic:

flowchart TD
AuthStart[Authentication Request] --> AuthCollect[collectSelectedHints]
AuthCollect --> AuthValidate[ensureAuthenticationHintsAllowed]
AuthValidate --> AuthFilter[Filter Allow Credentials]
AuthFilter --> AuthOptions[Prepare Auth Options]
AuthOptions --> AuthSubmit[Submit Authentication]

Diagram sources

Section sources

Enforcement Logic

Compatibility Validation

The ensureAuthenticationHintsAllowed function serves as the primary enforcement mechanism, ensuring that hint selections are compatible with available credentials:

flowchart TD
Input[Public Key Options] --> Check{Valid Public Key?}
Check --> |No| ThrowError[Throw Error if Required]
Check --> |Yes| ExtractHints[Extract Hints Array]
ExtractHints --> Normalize[Normalize Hint Values]
Normalize --> CheckSelection{Require Selection?}
CheckSelection --> |Yes & No Hints| ThrowSelection[Throw Selection Error]
CheckSelection --> |No or Has Hints| DeriveAttachments[Derive Attachments from Hints]
DeriveAttachments --> CheckAllowCredentials{Has Allow Credentials?}
CheckAllowCredentials --> |Yes| FilterCredentials[Filter Incompatible Credentials]
CheckAllowCredentials --> |No| CheckFallback{Has Stored Credentials?}
CheckFallback --> |Yes| CreateFallback[Create Fallback Credentials]
CheckFallback --> |No| ReturnAttachments[Return Resolved Attachments]
FilterCredentials --> ReturnAttachments
CreateFallback --> ReturnAttachments
ThrowError --> End[End]
ThrowSelection --> End
ReturnAttachments --> End

Diagram sources

Credential Filtering Logic

The system implements sophisticated credential filtering to ensure compatibility:

Scenario Action Result
Compatible hints + allowCredentials Keep existing credentials No modification
Compatible hints + empty allowCredentials Filter stored credentials Update allowCredentials
Incompatible hints + allowCredentials Remove incompatible credentials Filter allowCredentials
No hints + stored credentials Create fallback credential Add single credential
No hints + no stored credentials Remove allowCredentials Clear allowCredentials

Section sources

Two-Way Synchronization

From UI to WebAuthn Options

The applyHintsToCheckboxes function synchronizes WebAuthn options with UI state:

sequenceDiagram
participant Options as WebAuthn Options
participant Apply as applyHintsToCheckboxes
participant UI as UI Checkboxes
participant Callback as Registration Callbacks
Options->>Apply : Pass hints array
Apply->>Apply : Normalize hint values
Apply->>UI : Set checkbox states
Apply->>Callback : Trigger registration callbacks
Callback->>UI : Update dependent UI elements

Diagram sources

From WebAuthn Options to UI

The synchronization works bidirectionally, ensuring UI reflects current WebAuthn state:

sequenceDiagram
participant Server as Server Response
participant Parse as Option Parser
participant Apply as applyHintsToCheckboxes
participant UI as UI Checkboxes
Server->>Parse : Return WebAuthn options
Parse->>Apply : Extract hints array
Apply->>UI : Update checkbox states
UI->>UI : Reflect current configuration

Section sources

Examples and Usage Patterns

Basic Hint Collection Example

// Collect hints during registration
const registrationHints = collectSelectedHints('registration');
console.log('Selected hints:', registrationHints);
// Output: ["client-device", "security-key"]

// Collect hints during authentication
const authenticationHints = collectSelectedHints('authentication');
console.log('Selected hints:', authenticationHints);
// Output: ["hybrid"]

Attachment Resolution Example

// Resolve hints to attachment types
const hints = ['client-device', 'security-key'];
const attachments = deriveAllowedAttachmentsFromHints(hints);
console.log('Resolved attachments:', attachments);
// Output: ["platform", "cross-platform"]

WebAuthn Option Integration Example

// Apply hints to WebAuthn options
const publicKey = {
    rp: { name: "Example Corp" },
    user: { id: "user123", name: "John Doe" },
    challenge: challengeBytes,
    hints: ['client-device', 'security-key']
};

applyAuthenticatorAttachmentPreference(publicKey, ['platform', 'cross-platform']);
console.log('Updated options:', publicKey);
// Output: authenticatorSelection: { authenticatorAttachment: "platform" }

Section sources

Error Handling and Validation

Input Validation

The system implements comprehensive validation for hint values:

Validation Type Check Error Condition
Type Validation typeof value === 'string' Non-string values ignored
Empty Validation value.trim() Empty strings filtered out
Normalization trim().toLowerCase() Case-insensitive comparison
Known Values KNOWN_HINT_VALUES.has(normalized) Unknown hint values rejected

Runtime Error Handling

The system provides robust error handling for various failure scenarios:

flowchart TD
Operation[Hint Processing Operation] --> TryCatch[Try-Catch Block]
TryCatch --> Success{Success?}
Success --> |Yes| Continue[Continue Processing]
Success --> |No| LogError[Log Error Details]
LogError --> UserFeedback[Provide User Feedback]
UserFeedback --> GracefulDegradation[Graceful Degradation]

Diagram sources

Section sources

Integration with WebAuthn

Credential Creation Influence

Hints directly influence credential creation by setting appropriate authenticator attachment preferences:

Hint Combination Attachment Preference Use Case
client-device only platform Native OS authenticators
security-key only cross-platform USB/FIDO2 security keys
hybrid only cross-platform Bluetooth/NFC devices
Mixed hints cross-platform Flexible authenticator selection
No hints Auto-detect Browser default behavior

Authentication Request Enhancement

During authentication, hints help optimize the request by:

  1. Filtering Allow Credentials: Removing incompatible credentials early
  2. Setting Authenticator Preferences: Guiding browser behavior
  3. Providing Fallback Options: Ensuring authentication success
  4. Validating Compatibility: Preventing authentication failures

Section sources

The authenticator selection hints system represents a sophisticated balance between user experience and technical WebAuthn compliance, enabling seamless integration of user preferences with modern authentication protocols while maintaining robust error handling and validation mechanisms.