# vincss-public-projects/fido2client architecture

> Architecture diagram of the GitHub repository vincss-public-projects/fido2client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vincss-public-projects/fido2client
- Repository: https://github.com/vincss-public-projects/fido2client

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        ExampleApp["Example App (example/)"]:::js
        Preload["Preload Script (preload.ts)"]:::js
        Env["Environment Setup (environment.ts)"]:::js
    end

    %% Public API / Client Layer
    subgraph "Public API / Client Layer"
        direction TB
        Client["client.ts"]:::js
        Session["session.ts"]:::js
        Options["options.ts"]:::js
        Event["event.ts"]:::js
        Base64["base64.ts"]:::js
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        subgraph CTAP2 Module
            direction TB
            CTAP2Core["ctap2.ts"]:::js
            CTAP2Cmds["CTAP2 Commands (cmd/*)"]:::js
        end
        WebAuthn["WebAuthn Wrapper"]:::js
    end

    %% Extensions & Crypto
    subgraph "Utilities & Extensions"
        direction TB
        Extension["Extensions (hmac-secret, etc.)"]:::js
        Crypto["Crypto Utilities"]:::js
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        Multiplexer["Transport Multiplexer"]:::js
        USB["USB Transport"]:::js
        BLE["BLE Transport"]:::js
        NFC["NFC Transport"]:::js
    end

    %% Native / Third-Party Bindings
    subgraph "Native / Third-Party Bindings"
        direction TB
        PCSC["third_party/pcsc"]:::native
        Sign["third_party/sign"]:::native
        USBBinding["third_party/usb"]:::native
        BindingGyp["binding.gyp"]:::native
        Patches["patches/usb+1.7.1.patch"]:::native
    end

    %% Hardware Authenticators
    Authenticator["FIDO2 Authenticator"]:::hardware

    %% Modal UI
    ModalUI["Modal UI (PIN/Touch)"]:::ui

    %% Support & Examples
    subgraph "Support & Examples"
        direction TB
        Examples["example/"]:::support
        Tests["tests/"]:::support
        Dist["dist/"]:::support
        Assets["assets/default/"]:::support
    end

    %% Flow Arrows
    ExampleApp -->|uses API| Client
    Preload -->|uses API| Client
    Env -->|configures| Client

    Client -->|"makeCredential / getAssertion"| CTAP2Core
    CTAP2Core -->|invoke commands| CTAP2Cmds
    CTAP2Core -->|wrap/unwrap| WebAuthn

    CTAP2Core -->|select transport| Multiplexer
    Multiplexer --> USB
    Multiplexer --> BLE
    Multiplexer --> NFC

    USB -->|calls| USBBinding
    BLE -->|node module| Sign
    NFC -->|pcsc| PCSC

    USBBinding --> Authenticator
    Sign --> Authenticator
    PCSC --> Authenticator

    Authenticator -->|response| USBBinding
    USBBinding -->|CBOR payload| CTAP2Core

    CTAP2Core -->|data| WebAuthn
    WebAuthn -->|returns| Client
    Client -->|returns| ExampleApp

    Client -->|needs user interaction| ModalUI
    ModalUI -->|user input| Client

    Examples --> ExampleApp
    Tests -.-> Client
    Dist -.-> Client
    Assets -.-> Examples

    %% Click Events
    click ExampleApp "https://github.com/vincss-public-projects/fido2client/tree/master/example/"
    click Preload "https://github.com/vincss-public-projects/fido2client/blob/master/src/preload.ts"
    click Env "https://github.com/vincss-public-projects/fido2client/blob/master/src/environment.ts"

    click Client "https://github.com/vincss-public-projects/fido2client/blob/master/src/client/client.ts"
    click Session "https://github.com/vincss-public-projects/fido2client/blob/master/src/client/session.ts"
    click Options "https://github.com/vincss-public-projects/fido2client/blob/master/src/client/options.ts"
    click Event "https://github.com/vincss-public-projects/fido2client/blob/master/src/client/event.ts"
    click Base64 "https://github.com/vincss-public-projects/fido2client/blob/master/src/client/base64.ts"

    click CTAP2Core "https://github.com/vincss-public-projects/fido2client/blob/master/src/ctap2/ctap2.ts"
    click CTAP2Cmds "https://github.com/vincss-public-projects/fido2client/tree/master/src/ctap2/cmd/"

    click WebAuthn "https://github.com/vincss-public-projects/fido2client/blob/master/src/webauthn/WrapPublicKeyCredential.ts"

    click Extension "https://github.com/vincss-public-projects/fido2client/blob/master/src/extension/extension.ts"
    click Crypto "https://github.com/vincss-public-projects/fido2client/blob/master/src/crypto/crypto.ts"

    click Multiplexer "https://github.com/vincss-public-projects/fido2client/blob/master/src/transports/transport.ts"
    click USB "https://github.com/vincss-public-projects/fido2client/blob/master/src/transports/usb/usb.ts"
    click BLE "https://github.com/vincss-public-projects/fido2client/blob/master/src/transports/ble/ble.ts"
    click NFC "https://github.com/vincss-public-projects/fido2client/blob/master/src/transports/nfc/nfc.ts"

    click PCSC "https://github.com/vincss-public-projects/fido2client/tree/master/third_party/pcsc"
    click Sign "https://github.com/vincss-public-projects/fido2client/tree/master/third_party/sign"
    click USBBinding "https://github.com/vincss-public-projects/fido2client/tree/master/third_party/usb"
    click BindingGyp "https://github.com/vincss-public-projects/fido2client/blob/master/binding.gyp"
    click Patches "https://github.com/vincss-public-projects/fido2client/blob/master/patches/usb+1.7.1.patch"

    click ModalUI "https://github.com/vincss-public-projects/fido2client/blob/master/src/modal/modal.ts"

    click Examples "https://github.com/vincss-public-projects/fido2client/tree/master/example/"
    click Tests "https://github.com/vincss-public-projects/fido2client/tree/master/tests/"
    click Dist "https://github.com/vincss-public-projects/fido2client/tree/master/dist/"
    click Assets "https://github.com/vincss-public-projects/fido2client/tree/master/assets/default/"

    %% Styles
    classDef js fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef native fill:#c8e6c9,stroke:#388e3c,stroke-width:1px;
    classDef hardware fill:#eeeeee,stroke:#757575,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ui fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px;
    classDef support fill:#f0f0f0,stroke:#9e9e9e,stroke-width:1px;
```
