# yubico/python-fido2 architecture

> Architecture diagram of the GitHub repository yubico/python-fido2, 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/yubico/python-fido2
- Repository: https://github.com/yubico/python-fido2

## Overview

##### Project type and purpose
- This is a language-library project (python-fido2) that implements the FIDO U2F and FIDO2 (WebAuthn) protocols.
- It provides both low-level device communication (CTAP over USB via HID or PC/SC) and higher-level client/server helper classes for Relying Party integration.

##### File structure
- Top-level packages:
- fido2/                ← core library modules
- examples/            ← sample applications
- tests/               ← pytest test suite
- Key sub-packages under fido2/:
- client/              ← client-side abstractions (Windows, WinAPI)
- server.py            ← server-side WebAuthn helper
- ctap1.py, ctap2/     ← CTAP 1 & 2 protocol implementations
- hid/                 ← platform-specific USB HID transports
- pcsc.py              ← optional NFC (PC/SC) transport
- attestation/         ← attestation format parsers and verifiers
- cbor.py, cose.py     ← CBOR encoding/decoding and COSE signature support
- utils.py, features.py, rpid.py, public_suffix_list.dat
- Configuration, build and CI files: pyproject.toml, GitHub workflows, pre-commit, mypy.ini.

##### README for additional insights
- Confirms dual focus: low-level device access (CTAP+HID/PCSC) and higher-level WebAuthn (fido2.client, fido2.server).
- Mentions external dependencies: cryptography, pyscard (optional).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        App["Example Apps"]:::library
    end

    %% API Layer
    subgraph "API Layer"
        ClientAPI["Client API\n(fido2.client)"]:::library
        WinAPI["win_api.py"]:::library
        WindowsImpl["windows.py"]:::library
        ServerAPI["Server API\n(fido2.server)"]:::library
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        CTAPEntry["ctap.py"]:::library
        CTAP1["ctap1.py"]:::library
        subgraph "CTAP2"
            CTAP2Base["base.py"]:::library
            CTAP2Bio["bio.py"]:::library
            CTAP2Cred["credman.py"]:::library
            CTAP2Pin["pin.py"]:::library
            CTAP2Cfg["config.py"]:::library
            CTAP2Ext["extensions.py"]:::library
            CTAP2Blob["blob.py"]:::library
        end
    end

    %% Transport Layer
    subgraph "Transport Layer"
        subgraph HID["USB HID (fido2.hid)"]
            HIDBase["base.py"]:::library
            HIDLinux["linux.py"]:::library
            HIDMac["macos.py"]:::library
            HIDWin["windows.py"]:::library
            HIDFree["freebsd.py"]:::library
            HIDNet["netbsd.py"]:::library
            HIDOpen["openbsd.py"]:::library
        end
        PCSC["pcsc.py"]:::library
    end

    %% Attestation, CBOR/COSE, Utilities
    subgraph "Auxiliary Modules"
        subgraph Attestation["Attestation (fido2.attestation)"]
            AttBase["base.py"]:::library
            AttAndroid["android.py"]:::library
            AttApple["apple.py"]:::library
            AttTPM["tpm.py"]:::library
            AttPacked["packed.py"]:::library
            AttU2F["u2f.py"]:::library
        end
        CBOR["cbor.py"]:::library
        COSE["cose.py"]:::library
        Utils["utils.py"]:::library
        RPID["rpid.py"]:::library
        Features["features.py"]:::library
        PSL["public_suffix_list.dat"]:::library
        WebAuthn["webauthn.py"]:::library
    end

    %% Hardware and Dependencies
    Device["FIDO Authenticator"]:::hardware
    subgraph "External Dependencies"
        Crypto["cryptography"]:::dependency
        PySCard["pyscard"]:::dependency
        OSHID["OS HID Drivers"]:::dependency
    end

    %% Relationships - Requests
    App -->|"invoke"| ClientAPI
    App -->|"invoke"| ServerAPI

    ClientAPI -->|"build CBOR"| CTAPEntry
    CTAPEntry -->|"v1 framing"| CTAP1
    CTAPEntry -->|"v2 framing"| CTAP2Base

    CTAP1 -->|"CTAP1 frame"| HIDBase
    CTAP2Base -->|"CTAP2 frame"| HIDBase
    CTAP2Bio --> HIDBase
    CTAP2Cred --> HIDBase
    CTAP2Pin --> HIDBase
    CTAP2Cfg --> HIDBase
    CTAP2Ext --> HIDBase
    CTAP2Blob --> HIDBase

    HIDBase -->|"USB HID"| Device
    PCSC -->|"PC/SC NFC"| Device

    %% Response Flow
    Device --> HIDBase
    HIDBase --> CTAPEntry
    CTAPEntry --> ClientAPI
    ClientAPI --> App

    %% Server API flows
    ServerAPI -->|"validate credential"| CBOR
    ServerAPI --> COSE
    ServerAPI --> AttBase

    %% Dependencies usage
    CBOR --> Crypto
    COSE --> Crypto
    PCSC --> PySCard
    HIDLinux --> OSHID
    HIDMac --> OSHID
    HIDWin --> OSHID
    HIDFree --> OSHID
    HIDNet --> OSHID
    HIDOpen --> OSHID

    %% Click events
    click App "https://github.com/yubico/python-fido2/tree/main/examples/"
    click ClientAPI "https://github.com/yubico/python-fido2/tree/main/fido2/client/"
    click WinAPI "https://github.com/yubico/python-fido2/blob/main/fido2/client/win_api.py"
    click WindowsImpl "https://github.com/yubico/python-fido2/blob/main/fido2/client/windows.py"
    click ServerAPI "https://github.com/yubico/python-fido2/blob/main/fido2/server.py"
    click CTAPEntry "https://github.com/yubico/python-fido2/blob/main/fido2/ctap.py"
    click CTAP1 "https://github.com/yubico/python-fido2/blob/main/fido2/ctap1.py"
    click CTAP2Base "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/base.py"
    click CTAP2Bio "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/bio.py"
    click CTAP2Cred "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/credman.py"
    click CTAP2Pin "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/pin.py"
    click CTAP2Cfg "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/config.py"
    click CTAP2Ext "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/extensions.py"
    click CTAP2Blob "https://github.com/yubico/python-fido2/blob/main/fido2/ctap2/blob.py"
    click AttBase "https://github.com/yubico/python-fido2/blob/main/fido2/attestation/base.py"
    click AttAndroid "https://github.com/yubico/python-fido2/blob/main/fido2/attestation/android.py"
    click AttApple "https://github.com/yubico/python-fido2/blob/main/fido2/attestation/apple.py"
    click AttTPM "https://github.com/yubico/python-fido2/blob/main/fido2/attestation/tpm.py"
    click AttPacked "https://github.com/yubico/python-fido2/blob/main/fido2/attestation/packed.py"
    click AttU2F "https://github.com/yubico/python-fido2/blob/main/fido2/attestation/u2f.py"
    click CBOR "https://github.com/yubico/python-fido2/blob/main/fido2/cbor.py"
    click COSE "https://github.com/yubico/python-fido2/blob/main/fido2/cose.py"
    click HIDBase "https://github.com/yubico/python-fido2/blob/main/fido2/hid/base.py"
    click HIDLinux "https://github.com/yubico/python-fido2/blob/main/fido2/hid/linux.py"
    click HIDMac "https://github.com/yubico/python-fido2/blob/main/fido2/hid/macos.py"
    click HIDWin "https://github.com/yubico/python-fido2/blob/main/fido2/hid/windows.py"
    click HIDFree "https://github.com/yubico/python-fido2/blob/main/fido2/hid/freebsd.py"
    click HIDNet "https://github.com/yubico/python-fido2/blob/main/fido2/hid/netbsd.py"
    click HIDOpen "https://github.com/yubico/python-fido2/blob/main/fido2/hid/openbsd.py"
    click PCSC "https://github.com/yubico/python-fido2/blob/main/fido2/pcsc.py"

    %% Styles
    classDef library fill:#d0e7ff,stroke:#0366d6,color:#000
    classDef dependency fill:#d8ffdc,stroke:#28a745,color:#000
    classDef hardware fill:#ffe0b2,stroke:#f66,color:#000
```
