fix(nfc): require backend feature; rename to nfc-backend-{pcsc,libnfc} (#193)

Stacked on top of #186.

## Summary

- Fix build failure when only the `nfc` umbrella feature is enabled (no
backend).
- Gate `transport::nfc` on `any(nfc-backend-pcsc, nfc-backend-libnfc)`
so the broken code never compiles in the bad combo.
- Emit a single clear `compile_error!` from `lib.rs` instead of three
cascade errors out of `transport/nfc/device.rs`.
- Rename backend features to `nfc-backend-pcsc` and `nfc-backend-libnfc`
to make the umbrella relationship explicit.
- Restructure the example list in the top-level README into a transport
× protocol table.
- NFC cells show both backend variants (`nfc-backend-pcsc`,
`nfc-backend-libnfc`).
- Extend CI with per-backend coverage so this can't regress.
  - Build `libwebauthn` with only `nfc-backend-pcsc` enabled.
  - Build `libwebauthn` with only `nfc-backend-libnfc` enabled.

## Build matrix verified locally

| Command | Behavior |
| ------------------------------------------- |
--------------------------------------- |
| `cargo build` (no features) | Builds; NFC examples auto-skipped. |
| `cargo build --features nfc` | Single clear `compile_error!`. |
| `cargo build --features nfc-backend-pcsc` | Builds NFC examples. |
| `cargo build --features nfc-backend-libnfc` | Checks pass (link needs
`libnfc`). |

## Test plan

- [x] `cargo build` (default features) succeeds, NFC examples skipped.
- [x] `cargo build --features nfc` produces a single `compile_error!`
with the helpful message.
- [x] `cargo build --example webauthn_nfc --features nfc-backend-pcsc`
builds.
- [x] On a CI/dev machine with `libnfc` installed, `--features
nfc-backend-libnfc` links successfully.
- [x] New CI steps run green on this PR.

Author: AlfioEmanueleFresta

.github/workflows/rust.yml

@@ -21,6 +21,10 @@ jobs:
         run: cargo fmt --all -- --check
       - name: Build
         run: cargo build --workspace --all-targets --all-features
+      - name: Build with only nfc-backend-pcsc
+        run: cargo build -p libwebauthn --examples --features nfc-backend-pcsc
+      - name: Build with only nfc-backend-libnfc
+        run: cargo build -p libwebauthn --examples --features nfc-backend-libnfc
       - name: Run tests
         run: cargo test --workspace --verbose
       - name: Verify libwebauthn publishes cleanly

README.md

@@ -55,13 +55,33 @@ Validating the relying party ID against the calling origin requires the [Public
 ## Example programs
 
 After cloning, you can try out [one of the libwebauthn examples](libwebauthn/examples):
+
 ```
 $ cd libwebauthn
 $ git submodule update --init
-$ cargo run --example webauthn_hid
-$ cargo run --example webauthn_nfc
-$ cargo run --example webauthn_cable
-$ cargo run --example u2f_hid
+```
+
+| Transport             | FIDO U2F                                                                                                                       | WebAuthn (FIDO2)                                                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **USB (HID)**         | `cargo run --example u2f_hid`                                                                                                  | `cargo run --example webauthn_hid`<br>`cargo run --example webauthn_json_hid`                                                              |
+| **Bluetooth (BLE)**   | `cargo run --example u2f_ble`                                                                                                  | —                                                                                                                                          |
+| **NFC** [^nfc]        | `cargo run --features nfc-backend-pcsc --example u2f_nfc`<br>`cargo run --features nfc-backend-libnfc --example u2f_nfc`       | `cargo run --features nfc-backend-pcsc --example webauthn_nfc`<br>`cargo run --features nfc-backend-libnfc --example webauthn_nfc`         |
+| **Hybrid (caBLE v2)** | —                                                                                                                              | `cargo run --example webauthn_cable`                                                                                                       |
+
+[^nfc]: `nfc-backend-pcsc` is pure userspace and recommended on most systems. `nfc-backend-libnfc` requires the `libnfc` system library. Both can be enabled together; the first FIDO device found by either backend is used.
+
+Additional HID-only examples cover specific FIDO2 features and authenticator management:
+
+```
+$ cargo run --example webauthn_extensions_hid
+$ cargo run --example webauthn_preflight_hid
+$ cargo run --example webauthn_prf_hid
+$ cargo run --example prf_test
+$ cargo run --example hid_device_selection
+$ cargo run --example change_pin_hid
+$ cargo run --example bio_enrollment_hid
+$ cargo run --example authenticator_config_hid
+$ cargo run --example cred_management
 ```
 
 ## Contributing

libwebauthn/Cargo.toml

@@ -16,8 +16,8 @@ path = "src/lib.rs"
 [features]
 default = []
 nfc = ["apdu-core", "apdu"]
-pcsc = [ "nfc", "dep:pcsc" ]
-libnfc = [
+nfc-backend-pcsc = ["nfc", "dep:pcsc"]
+nfc-backend-libnfc = [
   "nfc",
   "nfc1-sys",
   "nfc1",

libwebauthn/src/lib.rs

@@ -6,6 +6,14 @@
 #![cfg_attr(not(any(test, feature = "virt")), deny(clippy::todo))]
 #![cfg_attr(not(any(test, feature = "virt")), deny(clippy::unreachable))]
 
+#[cfg(all(
+    feature = "nfc",
+    not(any(feature = "nfc-backend-pcsc", feature = "nfc-backend-libnfc"))
+))]
+compile_error!(
+    "the `nfc` feature is an umbrella that requires at least one backend; enable `nfc-backend-pcsc` and/or `nfc-backend-libnfc`"
+);
+
 pub mod fido;
 pub mod management;
 pub mod ops;

libwebauthn/src/transport/mod.rs

@@ -8,7 +8,7 @@ pub mod hid;
 /// A mock channel that can be used in tests to
 /// queue expected requests and responses in unittests
 pub mod mock;
-#[cfg(feature = "nfc")]
+#[cfg(any(feature = "nfc-backend-pcsc", feature = "nfc-backend-libnfc"))]
 pub mod nfc;
 
 mod channel;

libwebauthn/src/transport/nfc/device.rs

@@ -9,17 +9,17 @@ use crate::{
 };
 
 use super::channel::NfcChannel;
-#[cfg(feature = "libnfc")]
+#[cfg(feature = "nfc-backend-libnfc")]
 use super::libnfc;
-#[cfg(feature = "pcsc")]
+#[cfg(feature = "nfc-backend-pcsc")]
 use super::pcsc;
 use super::{Context, Nfc};
 
 #[derive(Clone, Debug)]
 enum DeviceInfo {
-    #[cfg(feature = "libnfc")]
+    #[cfg(feature = "nfc-backend-libnfc")]
     LibNfc(libnfc::Info),
-    #[cfg(feature = "pcsc")]
+    #[cfg(feature = "nfc-backend-pcsc")]
     Pcsc(pcsc::Info),
 }
 
@@ -31,9 +31,9 @@ pub struct NfcDevice {
 impl fmt::Display for DeviceInfo {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match &self {
-            #[cfg(feature = "libnfc")]
+            #[cfg(feature = "nfc-backend-libnfc")]
             DeviceInfo::LibNfc(info) => write!(f, "{}", info),
-            #[cfg(feature = "pcsc")]
+            #[cfg(feature = "nfc-backend-pcsc")]
             DeviceInfo::Pcsc(info) => write!(f, "{}", info),
         }
     }
@@ -46,14 +46,14 @@ impl fmt::Display for NfcDevice {
 }
 
 impl NfcDevice {
-    #[cfg(feature = "libnfc")]
+    #[cfg(feature = "nfc-backend-libnfc")]
     pub fn new_libnfc(info: libnfc::Info) -> Self {
         NfcDevice {
             info: DeviceInfo::LibNfc(info),
         }
     }
 
-    #[cfg(feature = "pcsc")]
+    #[cfg(feature = "nfc-backend-pcsc")]
     pub fn new_pcsc(info: pcsc::Info) -> Self {
         NfcDevice {
             info: DeviceInfo::Pcsc(info),
@@ -63,9 +63,9 @@ impl NfcDevice {
     async fn channel_sync(&self) -> Result<NfcChannel<Context>, Error> {
         trace!("nfc channel {:?}", self);
         let mut channel: NfcChannel<Context> = match &self.info {
-            #[cfg(feature = "libnfc")]
+            #[cfg(feature = "nfc-backend-libnfc")]
             DeviceInfo::LibNfc(info) => info.channel(),
-            #[cfg(feature = "pcsc")]
+            #[cfg(feature = "nfc-backend-pcsc")]
             DeviceInfo::Pcsc(info) => info.channel(),
         }?;
 
@@ -101,9 +101,9 @@ pub async fn get_nfc_device() -> Result<Option<NfcDevice>, Error> {
     // we'll potentially have the same device discovered by
     // both backends and thus added multiple times to the list.
     let list_devices_fns = [
-        #[cfg(feature = "libnfc")]
+        #[cfg(feature = "nfc-backend-libnfc")]
         libnfc::list_devices,
-        #[cfg(feature = "pcsc")]
+        #[cfg(feature = "nfc-backend-pcsc")]
         pcsc::list_devices,
     ];
 
@@ -121,11 +121,11 @@ pub async fn get_nfc_device() -> Result<Option<NfcDevice>, Error> {
 #[instrument]
 pub fn is_nfc_available() -> bool {
     let mut available = false;
-    #[cfg(feature = "libnfc")]
+    #[cfg(feature = "nfc-backend-libnfc")]
     {
         available |= libnfc::is_nfc_available();
     }
-    #[cfg(feature = "pcsc")]
+    #[cfg(feature = "nfc-backend-pcsc")]
     {
         available |= pcsc::is_nfc_available();
     }

libwebauthn/src/transport/nfc/mod.rs

@@ -3,9 +3,9 @@ use std::fmt::{Display, Formatter};
 pub mod channel;
 pub mod commands;
 pub mod device;
-#[cfg(feature = "libnfc")]
+#[cfg(feature = "nfc-backend-libnfc")]
 pub mod libnfc;
-#[cfg(feature = "pcsc")]
+#[cfg(feature = "nfc-backend-pcsc")]
 pub mod pcsc;
 
 pub use device::{get_nfc_device, is_nfc_available};