docs: add module-level documentation

libwebauthn/src/fido.rs

@@ -1,3 +1,17 @@
+//! Protocol abstractions shared between FIDO2 (CTAP2) and FIDO U2F (CTAP1).
+//! This module models the common protocol surface of the two standards,
+//! including protocol negotiation via [`FidoProtocol`], revision tracking via
+//! [`FidoRevision`], and the [`AuthenticatorData`] structure returned by a
+//! device during authentication and attestation ceremonies.
+//!
+//! [`AuthenticatorData`] is the central type. It carries the relying party ID
+//! hash, the user presence and verification flags, the signature counter,
+//! optional attested credential data (the device AAGUID, credential ID, and
+//! credential public key), and any protocol extension outputs. The module
+//! serializes and deserializes these responses per the CTAP2 specification and
+//! preserves the COSE key bytes verbatim, so the device signatures a relying
+//! party verifies stay intact.
+
 use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};
 use serde::{
     de::{DeserializeOwned, Error as DesError, Visitor},

libwebauthn/src/lib.rs

@@ -1,3 +1,70 @@
+//! libwebauthn is a Linux platform library implementing the FIDO2/WebAuthn and
+//! FIDO U2F specifications. It provides traits for performing WebAuthn
+//! operations (make credential and get assertion) and U2F operations (register
+//! and sign) against authenticator devices connected over USB, Bluetooth, or
+//! optionally NFC. The core abstractions are the [`WebAuthn`](webauthn::WebAuthn)
+//! and [`U2F`](u2f::U2F) traits that drive the protocol logic, and the
+//! [`Channel`](transport::Channel) trait that abstracts communication with a
+//! physical authenticator.
+//!
+//! While an operation runs, the library may need user verification. It surfaces
+//! this through the [`UvUpdate`] enum and related types such as
+//! [`PinRequiredUpdate`] and [`PinNotSetUpdate`], which let an application
+//! collect input (PIN entry or a presence confirmation) and feed it back into
+//! the ongoing operation. The [`transport`] module manages device discovery and
+//! communication, and the [`pin`] module handles the cryptographic side of PIN
+//! and user verification.
+//!
+//! # Getting started
+//!
+//! A typical flow is to enumerate devices on your transport of choice, open a
+//! [`Channel`](transport::Channel) to each one, and run a ceremony on that
+//! channel. The ceremony traits are blanket-implemented for every channel:
+//! [`WebAuthn`](webauthn::WebAuthn) for make-credential and get-assertion, and
+//! the [`management`] traits ([`CredentialManagement`](management::CredentialManagement),
+//! [`AuthenticatorConfig`](management::AuthenticatorConfig),
+//! [`BioEnrollment`](management::BioEnrollment)) for the administrative
+//! ceremonies. The make-credential and get-assertion requests are built from
+//! their WebAuthn IDL (the JSON the browser API speaks) with
+//! [`MakeCredentialRequest::prepare`](ops::webauthn::MakeCredentialRequest::prepare)
+//! and [`GetAssertionRequest::prepare`](ops::webauthn::GetAssertionRequest::prepare),
+//! which validate the caller origin against the relying party ID.
+//!
+//! ```no_run
+//! use libwebauthn::ops::webauthn::{
+//!     MakeCredentialRequest, RelatedOrigins, RequestOrigin, RequestSettings,
+//!     SystemPublicSuffixList,
+//! };
+//! use libwebauthn::transport::hid::list_devices;
+//! use libwebauthn::transport::Device;
+//! use libwebauthn::webauthn::WebAuthn;
+//!
+//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
+//! // 1. Enumerate authenticators on your transport of choice (HID shown here).
+//! let devices = list_devices().await?;
+//!
+//! for mut device in devices {
+//!     // 2. Open a channel to the device.
+//!     let mut channel = device.channel().await?;
+//!
+//!     // 3. Build a request from its WebAuthn IDL JSON.
+//!     let origin: RequestOrigin = "https://example.org".try_into().expect("invalid origin");
+//!     let psl = SystemPublicSuffixList::auto().expect("public suffix list unavailable");
+//!     let settings = RequestSettings {
+//!         public_suffix_list: &psl,
+//!         related_origins: RelatedOrigins::Disabled,
+//!     };
+//!     let request_json = r#"{ "rp": { "id": "example.org", "name": "Example" } }"#; // abbreviated
+//!     let request =
+//!         MakeCredentialRequest::prepare(&origin, request_json, &settings).await?;
+//!
+//!     // 4. Run the ceremony on the channel.
+//!     let _response = channel.webauthn_make_credential(&request).await?;
+//! }
+//! # Ok(())
+//! # }
+//! ```
+
 // Tests and the virt test-utility feature are allowed to use unwrap/expect/panic for convenience.
 #![cfg_attr(not(any(test, feature = "virt")), deny(clippy::unwrap_used))]
 #![cfg_attr(not(any(test, feature = "virt")), deny(clippy::expect_used))]

libwebauthn/src/management.rs

@@ -1,3 +1,16 @@
+//! Administration interfaces for CTAP2 authenticators. This module exposes
+//! traits for managing device configuration, biometric enrollment, and stored
+//! credentials over any [`Channel`](crate::transport::Channel) transport. These
+//! operations require user verification through a PIN or biometric factor, and
+//! the protocol handles token acquisition and retry internally.
+//!
+//! Use [`CredentialManagement`] to enumerate and delete resident credentials,
+//! [`AuthenticatorConfig`] to adjust device settings such as PIN policy and
+//! enterprise attestation, and [`BioEnrollment`] to manage biometric templates.
+//! Each trait is blanket-implemented for any
+//! [`Channel`](crate::transport::Channel), so the same API works across every
+//! transport.
+
 mod bio_enrollment;
 pub use bio_enrollment::BioEnrollment;
 

libwebauthn/src/ops/mod.rs

@@ -1,2 +1,25 @@
+//! Request and response types for WebAuthn registration and authentication
+//! ceremonies, alongside the legacy FIDO U2F operation types. The main types are
+//! [`MakeCredentialRequest`](webauthn::MakeCredentialRequest) and
+//! [`GetAssertionRequest`](webauthn::GetAssertionRequest), which describe the
+//! parameters for creating and asserting a credential, and the matching
+//! [`MakeCredentialResponse`](webauthn::MakeCredentialResponse) and
+//! [`GetAssertionResponse`](webauthn::GetAssertionResponse) that carry the
+//! outcome. The request types also cover WebAuthn extensions such as PRF,
+//! HMAC secret, credProtect, and large blob storage.
+//!
+//! Always build these requests from their WebAuthn IDL JSON with
+//! [`MakeCredentialRequest::prepare`](webauthn::MakeCredentialRequest::prepare)
+//! and [`GetAssertionRequest::prepare`](webauthn::GetAssertionRequest::prepare):
+//! `prepare` validates the caller origin against the relying party ID, so it is
+//! the only safe way to construct an operation.
+//!
+//! The module also defines the operation kinds and user verification
+//! requirements, client data hashing helpers, and conversions between the
+//! WebAuthn IDL (JSON) representation and the internal types. A U2F response can
+//! be promoted to its WebAuthn equivalent through the
+//! [`UpgradableResponse`](u2f::UpgradableResponse) trait, which bridges legacy
+//! credentials into the WebAuthn world.
+
 pub mod u2f;
 pub mod webauthn;

libwebauthn/src/pin.rs

@@ -1,3 +1,18 @@
+//! PIN and user-verification interaction for CTAP2 authenticators. This module
+//! implements the PIN/UV authentication protocols (`PinUvAuthProtocolOne` and
+//! `PinUvAuthProtocolTwo`), which perform ECDH key agreement and AES-CBC
+//! encryption with HMAC authentication. These are the primitives used to derive
+//! a shared secret, encrypt a PIN, and produce the authentication parameters
+//! sent during registration and assertion.
+//!
+//! The public surface exposes [`PinRequestReason`] and [`PinNotSetReason`] so a
+//! caller can tell why a PIN is being requested or why setting one failed, and
+//! [`PinManagement`] for initiating PIN changes. In normal use a caller does not
+//! touch this module directly. PIN requests reach the application through the
+//! [`UvUpdate`](crate::UvUpdate) flow in the crate root, delivered as
+//! [`PinRequiredUpdate`](crate::PinRequiredUpdate) and
+//! [`PinNotSetUpdate`](crate::PinNotSetUpdate).
+
 use std::time::Duration;
 
 use aes::cipher::{block_padding::NoPadding, BlockDecryptMut};

libwebauthn/src/proto/mod.rs

@@ -1,3 +1,16 @@
+//! The wire protocol layer for FIDO2/CTAP2 and FIDO U2F/CTAP1 authenticators.
+//! This module defines how device commands and responses are encoded and
+//! decoded: the CBOR request and response structures for CTAP2, the APDU frames
+//! for CTAP1, COSE keys, attestation statements, and the protocol status codes
+//! in [`CtapError`]. The [`Ctap1`](ctap1::Ctap1) and [`Ctap2`](ctap2::Ctap2)
+//! handlers drive these exchanges at the wire level.
+//!
+//! Alongside the core commands it covers CTAP2 preflight (checking which
+//! credentials a device holds before a ceremony), the PIN/UV authentication
+//! protocols, client PIN management, biometric enrollment, and on-device
+//! credential management. The encodings follow the FIDO Alliance specifications
+//! and account for the difference between APDU-based CTAP1 and CBOR-based CTAP2.
+
 mod error;
 
 pub mod ctap1;

libwebauthn/src/transport/mod.rs

@@ -1,3 +1,16 @@
+//! Transport layer that carries CTAP messages to FIDO2/WebAuthn authenticators.
+//! It abstracts over several physical media: HID (USB), BLE (Bluetooth Low
+//! Energy), caBLE (the cable/hybrid mode), and NFC (available when the
+//! `nfc-backend-pcsc` or `nfc-backend-libnfc` feature is enabled). The two core
+//! abstractions are [`Channel`], an open session with an authenticator that
+//! sends and receives CTAP messages, and [`Device`], a discovered authenticator
+//! from which a [`Channel`] can be opened.
+//!
+//! Supporting pieces include the [`Transport`] trait that identifies a specific
+//! transport implementation and the [`Ctap2AuthTokenStore`] trait for caching
+//! PIN/UV authentication tokens across operations. Each medium provides its own
+//! channel and device adapters suited to its protocol and hardware constraints.
+
 pub(crate) mod error;
 
 pub mod ble;

libwebauthn/src/u2f.rs

@@ -1,3 +1,13 @@
+//! High-level FIDO U2F (CTAP1) client API for registering and authenticating
+//! against an authenticator device. The [`U2F`] trait is blanket-implemented for
+//! any [`Channel`] and offers three async operations: protocol negotiation,
+//! registration, and signing.
+//!
+//! [`RegisterRequest`] and [`SignRequest`] describe the inputs, while the
+//! corresponding response types carry the results back to the caller. The trait
+//! handles the full lifecycle of a U2F exchange, from negotiating the device
+//! protocol through running the request with error handling.
+
 use async_trait::async_trait;
 use tracing::{instrument, warn};
 

libwebauthn/src/webauthn.rs

@@ -1,3 +1,18 @@
+//! High-level FIDO2 (CTAP2) client API for WebAuthn ceremonies. The [`WebAuthn`]
+//! trait is blanket-implemented for any [`Channel`]. Its
+//! [`webauthn_make_credential`](WebAuthn::webauthn_make_credential) and
+//! [`webauthn_get_assertion`](WebAuthn::webauthn_get_assertion) methods run the
+//! full CTAP2 make-credential and get-assertion ceremonies, including the user
+//! verification flow, PIN and biometric token handling, credential filtering via
+//! preflight, and extension support. When a device does not support FIDO2, the
+//! ceremony falls back to U2F (CTAP1).
+//!
+//! User verification is handled internally by the [`pin_uv_auth_token`] module,
+//! which manages PIN and biometric UV, reuse of a cached pinUvAuthToken, shared
+//! secret establishment, and the fallback from biometric to PIN. Failures are
+//! reported as [`Error`], which distinguishes CTAP protocol errors
+//! ([`CtapError`]), transport errors, and platform errors.
+
 pub mod error;
 pub mod pin_uv_auth_token;