-
Notifications
You must be signed in to change notification settings - Fork 0
MDS Integration
- Introduction
- MDS Data Loading and Caching
- Lazy Loading Mechanism
- Metadata Transformation Pipeline
- Filtering System
- Custom Metadata Management
- UI State Management
- MDS Integration in Authentication Flows
- Conclusion
The Metadata Service (MDS) integration system provides a comprehensive solution for managing FIDO authenticator metadata within the WebAuthn platform. This system enables users to explore authenticator information, upload custom metadata, and leverage metadata for authentication decisions. The implementation combines client-side JavaScript with server-side Python to create a responsive and efficient metadata management experience.
The MDS system follows a layered architecture with distinct components for data loading, transformation, filtering, and display. It implements sophisticated caching and lazy loading mechanisms to optimize performance while maintaining a rich user interface for exploring authenticator metadata.
Section sources
- mds.js
- metadata.py
The MDS data loading system implements a multi-layered approach to ensure reliable access to authenticator metadata. The system prioritizes loading from a verified JSON endpoint, with fallback mechanisms for custom metadata and error handling.
The loading process begins with checking for server-provided metadata snapshots, followed by attempts to load from cached data. If these methods fail, the system fetches the metadata BLOB from the JWS endpoint, decodes the base64 URL payload, and processes the JSON content. The system also handles scenarios where no metadata is available by displaying appropriate messages and UI states.
flowchart TD
Start([Load MDS Data]) --> CheckServerSnapshot["Check for server-provided metadata snapshot"]
CheckServerSnapshot --> |Exists| ApplyServerSnapshot["Apply initial metadata payload"]
CheckServerSnapshot --> |Not exists| CheckCache["Check local metadata cache"]
CheckCache --> |Cached data exists| RestoreCachedData["Restore cached metadata"]
CheckCache --> |No cache| FetchVerifiedJson["Fetch from MDS_VERIFIED_JSON_PATH"]
FetchVerifiedJson --> |Success| ApplyVerifiedMetadata["Apply verified metadata"]
FetchVerifiedJson --> |404 or error| FetchJws["Fetch from MDS_JWS_PATH"]
FetchJws --> |Success| DecodePayload["Decode JWS payload"]
DecodePayload --> ParseJson["Parse JSON metadata"]
ParseJson --> ApplyMetadata["Apply metadata entries"]
ApplyMetadata --> Finalize["Finalize UI state"]
style ApplyServerSnapshot fill:#e1f5fe,stroke:#039be5
style RestoreCachedData fill:#e1f5fe,stroke:#039be5
style ApplyVerifiedMetadata fill:#e1f5fe,stroke:#039be5
style ApplyMetadata fill:#e1f5fe,stroke:#039be5
**Diagram sources **
- mds.js
- general.py
Section sources
- mds.js
- general.py
The MDS system implements a sophisticated lazy loading mechanism through the createMdsLazyLoader function, which optimizes initial page load performance by deferring full parameter parsing. This mechanism loads all entries but only parses UI-visible fields initially, then progressively loads additional details in the background.
The MdsLazyLoader class manages the lazy loading process with several key features:
- Batch processing of entries to avoid blocking the main thread
- Progress tracking and completion callbacks
- Background loading with yielding to maintain UI responsiveness
- Index-based tracking of fully parsed entries
classDiagram
class MdsLazyLoader {
+allEntries : Array
+fullyParsedIndices : Set
+fullyParsedKeys : Map
+isBackgroundLoading : boolean
+backgroundLoadComplete : boolean
+initialize(metadata)
+getAllRawEntries()
+getRawEntryByIndex(index)
+getRawEntryByKey(key)
+startBackgroundLoading(options)
+onProgress(callback)
+onComplete(callback)
+getStats()
+isFullyLoaded()
}
class MdsLazyLoader "Creates" --> createMdsLazyLoader : "Factory function"
MdsLazyLoader --> mds.js : "Used in"
createMdsLazyLoader --> MdsLazyLoader : "Returns instance of"
**Diagram sources **
- mds-lazy-loader.js
- mds.js
Section sources
- mds-lazy-loader.js
- mds.js
The MDS system implements a comprehensive metadata transformation pipeline that converts raw entries into display-ready records through the transformEntry and upgradeEntryToFull functions. This pipeline ensures consistent formatting and presentation of authenticator metadata across the application.
The transformation process begins with lightweight parsing for initial UI display, which only processes fields visible in the list view. This approach significantly improves initial rendering performance. When more detailed information is needed, the system upgrades lightweight entries to full entries by completing the parsing of deferred fields.
flowchart TD
RawEntry([Raw Metadata Entry]) --> TransformLightweight["transformEntryLightweight()"]
TransformLightweight --> LightweightEntry["Lightweight Entry\n(icon, name, protocol,\nuserVerification, etc.)"]
LightweightEntry --> Display["Display in list view"]
Display --> UserInteraction["User requests details"]
UserInteraction --> UpgradeEntry["upgradeEntryToFull()"]
UpgradeEntry --> TransformFull["transformEntry()"]
TransformFull --> FullEntry["Full Entry\n(all fields processed)"]
FullEntry --> DetailView["Display in detail view"]
style TransformLightweight fill:#c8e6c9,stroke:#43a047
style UpgradeEntry fill:#c8e6c9,stroke:#43a047
style TransformFull fill:#c8e6c9,stroke:#43a047
**Diagram sources **
- mds-utils.js
- mds-utils.js
Section sources
- mds-utils.js
The MDS filtering system enables dynamic data exploration through the createFilterDropdown function and FILTER_CONFIG configuration. This system provides users with intuitive dropdown filters for various metadata attributes, allowing them to quickly find specific authenticators.
The filtering implementation includes:
- Configurable filter options for different metadata fields
- Dynamic option population based on available data
- Case-insensitive search with live filtering
- Keyboard navigation support (arrow keys, Enter, Escape)
- Visual feedback for active selections
erDiagram
FILTER_CONFIG ||--o{ FILTER_LOOKUP : "maps to"
FILTER_CONFIG {
string key
string inputId
string optionsKey
boolean expandDropdown
array staticOptions
}
FILTER_LOOKUP {
string key
object config
}
FilterDropdown ||--o{ FILTER_CONFIG : "uses"
FilterDropdown {
object input
function onSelect
array options
array filtered
number activeIndex
object list
object container
function setOptions(options)
function open()
function close()
function filter(query)
function render()
function handleKeyDown(event)
function move(delta)
function select(value)
}
mds.js ||--o{ FilterDropdown : "creates instances"
**Diagram sources **
- mds-constants.js
- mds-dropdown.js
- mds.js
Section sources
- mds-constants.js
- mds-dropdown.js
The MDS system provides comprehensive custom metadata management capabilities, allowing users to upload, list, and delete custom MDS entries. This functionality enables testing with custom authenticator data and integration with private metadata sources.
The custom metadata system operates through a session-based storage mechanism where uploaded metadata files are stored with unique identifiers. The system merges custom entries with the base metadata, ensuring that custom entries take precedence when AAGUIDs conflict.
sequenceDiagram
participant User
participant Frontend
participant Backend
participant Storage
User->>Frontend : Upload JSON file
Frontend->>Backend : POST /api/mds/metadata/upload
Backend->>Storage : Store file with UUID
Storage-->>Backend : Confirm storage
Backend->>Backend : Process metadata entries
Backend->>Storage : Store metadata info
Storage-->>Backend : Confirm info storage
Backend-->>Frontend : Return success with item info
Frontend->>Frontend : Update UI with new item
Frontend-->>User : Show success message
User->>Frontend : Request custom metadata list
Frontend->>Backend : GET /api/mds/metadata/custom
Backend->>Storage : List session files
Storage-->>Backend : Return file list
Backend->>Backend : Process metadata items
Backend-->>Frontend : Return items list
Frontend->>Frontend : Update custom metadata panel
Frontend-->>User : Display available custom metadata
User->>Frontend : Delete custom metadata
Frontend->>Backend : DELETE /api/mds/metadata/custom/{filename}
Backend->>Storage : Delete file and info
Storage-->>Backend : Confirm deletion
Backend-->>Frontend : Return success
Frontend->>Frontend : Remove from UI
Frontend-->>User : Show deletion confirmation
**Diagram sources **
- general.py
- metadata.py
- mds.js
Section sources
- general.py
- metadata.py
- mds.js
The MDS system implements comprehensive UI state management for the MDS overlay, sorting, and column layout. This ensures a consistent user experience across sessions and provides intuitive controls for interacting with metadata.
The state management system tracks:
- Current sort key and direction for table columns
- Column width and layout
- Scroll position and visibility
- Filter states for all filterable fields
- Overlay visibility and message states
classDiagram
class MdsState {
+updateOverlay : HTMLElement
+updateOverlayMessage : HTMLElement
+updateOverlayCancel : HTMLButtonElement
+updateOverlayActions : HTMLElement
+updateOverlayCancelHandler : Function
+updateOverlayAllowCancel : boolean
+customPanelMessages : HTMLElement
+customList : HTMLElement
+tableBody : HTMLElement
+sortKey : string
+sortDirection : string
+byAaguid : Map
+defaultStatus : Object
}
class SortConstants {
+SORT_NONE : 'none'
+SORT_ASCENDING : 'asc'
+SORT_DESCENDING : 'desc'
+SORT_SEQUENCE : Object
+DEFAULT_SORT_KEY : 'dateUpdated'
+DEFAULT_SORT_DIRECTION : 'desc'
}
class ColumnManagement {
+COLUMN_COUNT : 13
+DEFAULT_MIN_COLUMN_WIDTH : 64
+FLOATING_SCROLL_BOTTOM_MARGIN : 24
+FLOATING_SCROLL_SIDE_MARGIN : 16
}
MdsState --> SortConstants : "uses"
MdsState --> ColumnManagement : "uses"
mds.js --> MdsState : "manages"
**Diagram sources **
- mds.js
- mds.js
- mds-constants.js
Section sources
- mds.js
The MDS system integrates with registration and authentication flows to inform authenticator selection and validation. When users interact with credential information, the system can navigate to the corresponding authenticator metadata, providing context about the authenticator's capabilities and certification status.
The integration works by extracting the AAGUID from credential data and using it to locate the corresponding metadata entry. This allows users to verify authenticator details, check certification status, and understand the security properties of the authenticator used in a registration or authentication ceremony.
sequenceDiagram
participant CredentialUI
participant CredentialDisplay
participant MdsSystem
participant MdsTable
CredentialUI->>CredentialDisplay : User clicks MDS icon
CredentialDisplay->>CredentialDisplay : Extract AAGUID from credential
CredentialDisplay->>MdsSystem : navigateToMdsAuthenticator(aaguid)
MdsSystem->>MdsSystem : Check if MDS is loaded
alt MDS not loaded
MdsSystem->>MdsSystem : Show loading indicator
MdsSystem->>MdsSystem : Wait for MDS load
end
MdsSystem->>MdsSystem : Resolve metadata entry by AAGUID
alt Entry found
MdsSystem->>MdsTable : highlightMdsAuthenticatorRow(entry)
MdsTable->>MdsTable : Scroll to and highlight row
MdsTable-->>CredentialDisplay : Return success
CredentialDisplay-->>CredentialUI : Close modal, show success
else Entry not found
CredentialDisplay-->>CredentialUI : Show "metadata unavailable" message
end
**Diagram sources **
- credential-display.js
- credential-display.js
- mds.js
Section sources
- credential-display.js
The Metadata Service (MDS) integration system provides a robust and user-friendly interface for managing FIDO authenticator metadata. By implementing lazy loading, efficient caching, and a comprehensive transformation pipeline, the system delivers a responsive experience even with large metadata sets.
Key features of the system include:
- Efficient data loading with multiple fallback mechanisms
- Progressive enhancement through lazy loading
- Comprehensive metadata transformation for consistent display
- Flexible filtering for dynamic data exploration
- Custom metadata management for testing and integration
- Seamless integration with authentication flows
The system's architecture effectively separates concerns between data loading, transformation, and presentation, making it maintainable and extensible. The combination of client-side optimization and server-side management creates a powerful tool for exploring and understanding FIDO authenticator metadata.