Authenticator Selection Hints Processing

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

Loading

Diagram sources

• hints.js
• constants.js
• auth-advanced.js

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

Loading

Diagram sources

• constants.js

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

• hints.js

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]

Loading

Diagram sources

• hints.js

Section sources

• hints.js

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

Loading

Diagram sources

• main.js
• json-editor.js

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

• tab.html
• tab.html

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]

Loading

Diagram sources

• auth-advanced.js
• hints.js

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]

Loading

Diagram sources

• auth-advanced.js
• hints.js

Section sources

• auth-advanced.js

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

Loading

Diagram sources

• hints.js

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

• hints.js

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

Loading

Diagram sources

• hints.js

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

Loading

Section sources

• hints.js

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

• hints.js

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]

Loading

Diagram sources

• hints.js

Section sources

• hints.js

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

• auth-advanced.js
• json-editor.js

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.