How vincss-public-projects/fido2client works
Project Type and Purpose
• This is an open-source Node.js/Electron library (“@vincss-public-projects/fido2-client”) that implements the W3C WebAuthn (Web Authentication) and FIDO CTAP2 protocols.
• Its goal is to let Node (and Electron) applications communicate with external or embedded FIDO2 authenticators over USB, BLE, or NFC, including PIN-protected flows and default modal UIs for user interaction.
High-Level Architectural Overview
• Layered, modular design that cleanly separates:
• Public API / Client Layer
• Protocol Layer (CTAP2 + WebAuthn wrappers)
• Transport Layer (USB, BLE, NFC)
• Native bindings & third-party code
• Hardware Authenticators
Main Components (to represent as distinct blocks)
A. Application Layer (Node / Electron App)
• Your consuming application or Electron renderer/preload script
• Invokes the library’s public API (e.g., client.create(), client.get(), session management)
B. Public API / Client Layer (src/client)
• client.ts, session.ts, options.ts, event.ts, base64.ts
• Exposes high-level methods: “makeCredential” and “getAssertion”
C. Protocol Layer
1. CTAP2 Module (src/ctap2)
• Encodes/decodes CTAP2 commands and responses
• Sub-package for CTAP2 commands (cmd/*.ts)
2. WebAuthn Wrapper (src/webauthn)
• Translates WebAuthn data structures to/from CTAP2 trips
D. Extensions (src/extension)
• e.g., hmac-secret extension support
E. Crypto Utilities (src/crypto)
• Low-level helpers for hashing, CBOR, COSE
F. Transport Layer (src/transports)
• Multiplexer that selects one transport based on environment/options
• USB (usb/*) – uses node-usb binding with optional patches
• BLE (ble/*) – uses noble on macOS/Windows
• NFC (nfc/*) – uses underlying OS libraries or pcsclite
G. Native / Third-Party Bindings (third_party & binding.gyp)
• PCSC (Smart Card) native C++ code (third_party/pcsc)
• Sign (private key operations) (third_party/sign)
• USB platform code (third_party/usb)
H. Modal UI (src/modal)
• Default Electron/Browser modal implementation for PIN prompts, touch requests
I. Support & Examples
• example/ for usage samples
• tests/ for unit tests
• dist/ for built artifacts
• assets/default for web demo
Relationships & Data Flow
1. App → Public API
2. API → CTAP2 module (encode request)
3. CTAP2 → Transport multiplexer
4. Transport → Native binding / Node module
5. Native → Hardware authenticator (USB/BLE/NFC)
6. Hardware → Native binding → Transport → CTAP2 (decode response)
7. CTAP2 → WebAuthn wrapper → API → App
8. If user interaction needed → Modal UI → returns user input to API
Architectural Patterns & Principles
• Layered architecture (API, protocol, transport, hardware)
• Plugin-style transports: each transport resides in its own subfolder and implements a common interface
• Separation of concerns: CTAP2 vs. WebAuthn vs. transport vs. UI
Essential Details to Capture
• Transport abstraction: show that USB, BLE, NFC are interchangeable under a common interface
• CTAP2 and WebAuthn as two separate but cooperating protocol modules
• Modal UI invoked for PIN or touch interactions
• Native C++ modules for low-level hardware access
• Example app/Electron preload bridging