# passwordless-lib/fido2-net-lib architecture

> Architecture diagram of the GitHub repository passwordless-lib/fido2-net-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/passwordless-lib/fido2-net-lib
- Repository: https://github.com/passwordless-lib/fido2-net-lib

## Overview

#### Purpose and deliverables
A .NET 8+ FIDO2/WebAuthn relying-party library for issuing registration/assertion challenges and cryptographically validating returned credentials. The repository produces reusable core, model, ASP.NET Core integration, Blazor WASM interop, CTAP2, and development-support packages. Solution entry point: `fido2-net-lib.sln`.

#### Core relying-party engine
`Src/Fido2/Fido2.cs` implements `IFido2` (`Src/Fido2/IFido2.cs`): it creates credential-registration and assertion options, then verifies attestation and assertion responses. This is the security boundary between untrusted browser/authenticator payloads and application-owned credential storage. Its parameter wrappers and response types drive the primary public API.

#### Protocol models and serialization
`Src/Fido2.Models/Fido2Configuration.cs`, `Src/Fido2.Models/CredentialCreateOptions.cs`, and `Src/Fido2.Models/AssertionOptions.cs` define configuration and browser-facing WebAuthn option payloads. Raw browser response models, credential descriptors, extension inputs/outputs, metadata schemas, and source-generated JSON context are centralized in `Src/Fido2.Models`, keeping wire contracts separate from verification logic.

#### Registration and authentication verification
Registration accepts an attestation response plus originally issued options, validates client/origin/challenge/authenticator data, dispatches its attestation format verifier, and returns a public key and credential data for caller persistence. Key paths: `Src/Fido2/AuthenticatorAttestationResponse.cs`, `Src/Fido2/AttestationFormat/AttestationVerifier.cs`, `Src/Fido2/AttestationFormat/Packed.cs`.
Authentication accepts assertion data, stored public key and signature counter, verifies ownership through application callbacks, validates the signature, and returns an updated counter: `Src/Fido2/AuthenticatorAssertionResponse.cs`, `Src/Fido2/MakeAssertionParams.cs`.

#### Trust, metadata, and cryptography
Attestation trust decisions are separated behind metadata interfaces and repositories. `Src/Fido2/IMetadataService.cs` and `Src/Fido2/Metadata/Fido2MetadataServiceRepository.cs` support FIDO Metadata Service retrieval/validation; `Src/Fido2.AspNet/DistributedCacheMetadataService.cs` adds cache-backed use in ASP.NET Core. Format-specific validation covers TPM, Android, Apple, U2F, packed, and none under `Src/Fido2/AttestationFormat`. Cryptographic, ASN.1, CBOR, certificate, and authenticator-data parsing live in `Src/Fido2/Extensions/CryptoUtils.cs`, `Src/Fido2/Asn1Element.cs`, and `Src/Fido2/Cbor`.

#### Host integration and browser boundary
ASP.NET Core applications register the engine through DI extensions in `Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs`; hosts own sessions/challenge lifecycle and durable user/credential storage. Browser WebAuthn ceremony calls remain client-side: `Src/Fido2.BlazorWebAssembly/WebAuthn.cs` bridges to `Src/Fido2.BlazorWebAssembly/wwwroot/js/WebAuthn.ts`. Thus the browser talks to platform/roaming authenticators, while the server remains the verifier and credential record authority.

#### Executable examples and infrastructure
`Demo/Program.cs` starts the ASP.NET Core reference app; `Demo/DemoController.cs` exposes registration/authentication ceremony endpoints, paired with browser scripts in `Demo/wwwroot/js`. `BlazorWasmDemo/Server/Program.cs` hosts the WASM example, whose client bootstraps at `BlazorWasmDemo/Client/Program.cs`. Development-only in-memory credential/metadata support is in `Src/Fido2.Development/DevelopmentInMemoryStore.cs`. CI runs through `.github/workflows/main.yml`; Azure deployment and container hosting are represented by `.github/workflows/azure-deploy.yml` and `BlazorWasmDemo/Server/Dockerfile`.

Main entry points: [`Src/Fido2/Fido2.cs`](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Fido2.cs) (Fido2 engine), [`Src/Fido2/AuthenticatorAttestationResponse.cs`](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AuthenticatorAttestationResponse.cs) (Registration verification), [`Src/Fido2/AttestationFormat/AttestationVerifier.cs`](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AttestationFormat/AttestationVerifier.cs) (Attestation dispatcher), [`Demo/DemoController.cs`](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Demo/DemoController.cs) (Demo ceremonies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Relying-party core"]
  node_public_api["IFido2 API<br/>public interface<br/>[IFido2.cs]"]
  node_engine{{"Fido2 engine<br/>verification engine<br/>[Fido2.cs]"}}
  node_options_models["Options &amp; configuration<br/>protocol models"]
  node_registration["Registration verification<br/>attestation response"]
  node_authentication["Assertion verification<br/>assertion response"]
end

subgraph group_trust["Trust and parsing"]
  node_attestation_dispatch["Attestation dispatcher<br/>format verifier"]
  node_packed["Packed attestation<br/>format verifier<br/>[Packed.cs]"]
  node_metadata_api["Metadata service<br/>trust interface"]
  node_metadata_repo[("Metadata repository<br/>FIDO MDS service")]
  node_crypto_parsing["Crypto &amp; binary parsing<br/>security primitives<br/>[CryptoUtils.cs]"]
end

subgraph group_hosts["Host integrations and examples"]
  node_aspnet_di["ASP.NET Core DI<br/>host integration"]
  node_distributed_metadata[("Distributed metadata cache<br/>ASP.NET metadata service")]
  node_demo_api["Reference demo API<br/>ASP.NET Core app<br/>[Program.cs]"]
  node_demo_controller["Demo ceremonies<br/>HTTP controller<br/>[DemoController.cs]"]
  node_blazor_interop["Blazor WebAuthn bridge<br/>WASM interop<br/>[WebAuthn.cs]"]
  node_browser_webauthn["Browser WebAuthn<br/>JavaScript bridge<br/>[WebAuthn.ts]"]
  node_wasm_server["Blazor WASM host<br/>example server<br/>[Program.cs]"]
  node_wasm_client["Blazor WASM client<br/>example client<br/>[Program.cs]"]
  node_dev_store[("Development in-memory store<br/>development storage")]
end

subgraph group_delivery["Delivery"]
  node_ci["CI workflow<br/>GitHub Actions<br/>[main.yml]"]
  node_container["WASM server container<br/>Docker image"]
end

node_public_api -->|"implemented by"| node_engine
node_engine -->|"issues options"| node_options_models
node_engine -->|"verifies registration"| node_registration
node_engine -->|"verifies assertion"| node_authentication
node_registration -->|"dispatches format"| node_attestation_dispatch
node_registration -->|"validates signed data"| node_crypto_parsing
node_authentication -->|"verifies signature"| node_crypto_parsing
node_attestation_dispatch -->|"supports"| node_packed
node_attestation_dispatch -->|"evaluates trust through"| node_metadata_api
node_metadata_repo -->|"implements"| node_metadata_api
node_aspnet_di -->|"registers"| node_engine
node_distributed_metadata -->|"implements"| node_metadata_api
node_demo_api -->|"uses"| node_aspnet_di
node_demo_api -->|"hosts"| node_demo_controller
node_demo_controller -->|"runs ceremonies"| node_engine
node_demo_controller -.->|"uses in development"| node_dev_store
node_blazor_interop -->|"invokes"| node_browser_webauthn
node_wasm_client -->|"uses"| node_blazor_interop
node_wasm_server -->|"hosts"| node_wasm_client
node_wasm_server -->|"registers verifier"| node_aspnet_di
node_ci -.->|"builds and validates"| node_engine
node_container -->|"packages"| node_wasm_server

click node_public_api "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/IFido2.cs"
click node_engine "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Fido2.cs"
click node_options_models "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.Models/Fido2Configuration.cs"
click node_registration "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AuthenticatorAttestationResponse.cs"
click node_authentication "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AuthenticatorAssertionResponse.cs"
click node_attestation_dispatch "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AttestationFormat/AttestationVerifier.cs"
click node_packed "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AttestationFormat/Packed.cs"
click node_metadata_api "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/IMetadataService.cs"
click node_metadata_repo "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Metadata/Fido2MetadataServiceRepository.cs"
click node_crypto_parsing "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Extensions/CryptoUtils.cs"
click node_aspnet_di "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs"
click node_distributed_metadata "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.AspNet/DistributedCacheMetadataService.cs"
click node_demo_api "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Demo/Program.cs"
click node_demo_controller "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Demo/DemoController.cs"
click node_blazor_interop "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.BlazorWebAssembly/WebAuthn.cs"
click node_browser_webauthn "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.BlazorWebAssembly/wwwroot/js/WebAuthn.ts"
click node_wasm_server "https://github.com/passwordless-lib/fido2-net-lib/blob/main/BlazorWasmDemo/Server/Program.cs"
click node_wasm_client "https://github.com/passwordless-lib/fido2-net-lib/blob/main/BlazorWasmDemo/Client/Program.cs"
click node_dev_store "https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.Development/DevelopmentInMemoryStore.cs"
click node_ci "https://github.com/passwordless-lib/fido2-net-lib/blob/main/.github/workflows/main.yml"
click node_container "https://github.com/passwordless-lib/fido2-net-lib/blob/main/BlazorWasmDemo/Server/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_engine,node_options_models,node_registration,node_authentication toneBlue
class node_attestation_dispatch,node_packed,node_metadata_api,node_metadata_repo,node_crypto_parsing toneAmber
class node_aspnet_di,node_distributed_metadata,node_demo_api,node_demo_controller,node_blazor_interop,node_browser_webauthn,node_wasm_server,node_wasm_client,node_dev_store toneMint
class node_ci,node_container toneRose
```

## Components

### Relying-party core

Reusable verification engine and WebAuthn contracts.

- [IFido2 API](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/IFido2.cs): public interface · Public ceremony creation and verification contract. · `Src/Fido2/IFido2.cs`
- [Fido2 engine](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Fido2.cs): verification engine · Security boundary for untrusted WebAuthn payloads. · `Src/Fido2/Fido2.cs`
- [Options & configuration](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.Models/Fido2Configuration.cs): protocol models · Browser-facing WebAuthn option payloads and relying-party configuration. · `Src/Fido2.Models/Fido2Configuration.cs`
- [Registration verification](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AuthenticatorAttestationResponse.cs): attestation response · Validates registration responses and yields credential material. · `Src/Fido2/AuthenticatorAttestationResponse.cs`
- [Assertion verification](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AuthenticatorAssertionResponse.cs): assertion response · Validates assertions and returns an updated signature counter. · `Src/Fido2/AuthenticatorAssertionResponse.cs`

### Trust and parsing

Attestation trust, format validation, and binary security primitives.

- [Attestation dispatcher](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AttestationFormat/AttestationVerifier.cs): format verifier · `Src/Fido2/AttestationFormat/AttestationVerifier.cs`
- [Packed attestation](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/AttestationFormat/Packed.cs): format verifier · One format-specific attestation validator. · `Src/Fido2/AttestationFormat/Packed.cs`
- [Metadata service](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/IMetadataService.cs): trust interface · Abstraction for attestation trust decisions. · `Src/Fido2/IMetadataService.cs`
- [Metadata repository](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Metadata/Fido2MetadataServiceRepository.cs): FIDO MDS service · Retrieves and validates FIDO metadata. · `Src/Fido2/Metadata/Fido2MetadataServiceRepository.cs`
- [Crypto & binary parsing](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2/Extensions/CryptoUtils.cs): security primitives · Cryptography, ASN.1, CBOR, certificates, and authenticator-data parsing. · `Src/Fido2/Extensions/CryptoUtils.cs`

### Host integrations and examples

Server registration, ceremony endpoints, and browser clients.

- [ASP.NET Core DI](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs): host integration · Registers the relying-party engine with application DI. · `Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs`
- [Distributed metadata cache](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.AspNet/DistributedCacheMetadataService.cs): ASP.NET metadata service · Cache-backed metadata support for ASP.NET Core hosts. · `Src/Fido2.AspNet/DistributedCacheMetadataService.cs`
- [Reference demo API](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Demo/Program.cs): ASP.NET Core app · Exposes registration and authentication ceremony endpoints. · `Demo/Program.cs`
- [Demo ceremonies](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Demo/DemoController.cs): HTTP controller · `Demo/DemoController.cs`
- [Blazor WebAuthn bridge](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.BlazorWebAssembly/WebAuthn.cs): WASM interop · Calls browser WebAuthn APIs from Blazor. · `Src/Fido2.BlazorWebAssembly/WebAuthn.cs`
- [Browser WebAuthn](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.BlazorWebAssembly/wwwroot/js/WebAuthn.ts): JavaScript bridge · Invokes platform or roaming authenticators. · `Src/Fido2.BlazorWebAssembly/wwwroot/js/WebAuthn.ts`
- [Blazor WASM host](https://github.com/passwordless-lib/fido2-net-lib/blob/main/BlazorWasmDemo/Server/Program.cs): example server · Hosts the WebAssembly example. · `BlazorWasmDemo/Server/Program.cs`
- [Blazor WASM client](https://github.com/passwordless-lib/fido2-net-lib/blob/main/BlazorWasmDemo/Client/Program.cs): example client · `BlazorWasmDemo/Client/Program.cs`
- [Development in-memory store](https://github.com/passwordless-lib/fido2-net-lib/blob/main/Src/Fido2.Development/DevelopmentInMemoryStore.cs): development storage · In-memory credential and metadata support. · `Src/Fido2.Development/DevelopmentInMemoryStore.cs`

### Delivery

- [CI workflow](https://github.com/passwordless-lib/fido2-net-lib/blob/main/.github/workflows/main.yml): GitHub Actions · `.github/workflows/main.yml`
- [WASM server container](https://github.com/passwordless-lib/fido2-net-lib/blob/main/BlazorWasmDemo/Server/Dockerfile): Docker image · `BlazorWasmDemo/Server/Dockerfile`

## Connections

- IFido2 API → Fido2 engine: implemented by
- Fido2 engine → Options & configuration: issues options
- Fido2 engine → Registration verification: verifies registration
- Fido2 engine → Assertion verification: verifies assertion
- Registration verification → Attestation dispatcher: dispatches format
- Registration verification → Crypto & binary parsing: validates signed data
- Assertion verification → Crypto & binary parsing: verifies signature
- Attestation dispatcher → Packed attestation: supports
- Attestation dispatcher → Metadata service: evaluates trust through
- Metadata repository → Metadata service: implements
- ASP.NET Core DI → Fido2 engine: registers
- Distributed metadata cache → Metadata service: implements
- Reference demo API → ASP.NET Core DI: uses
- Reference demo API → Demo ceremonies: hosts
- Demo ceremonies → Fido2 engine: runs ceremonies
- Demo ceremonies → Development in-memory store: uses in development
- Blazor WebAuthn bridge → Browser WebAuthn: invokes
- Blazor WASM client → Blazor WebAuthn bridge: uses
- Blazor WASM host → Blazor WASM client: hosts
- Blazor WASM host → ASP.NET Core DI: registers verifier
- CI workflow → Fido2 engine: builds and validates
- WASM server container → Blazor WASM host: packages