docs(credmgmt): document persistent token usage and add example

Author: AlfioEmanueleFresta

README.md

@@ -33,6 +33,7 @@ _Looking for the D-Bus API proposal?_ Check out [credentialsd][credentialsd].
   - 🟢 GetPinToken
   - 🟢 GetPinUvAuthTokenUsingPinWithPermissions
   - 🟢 GetPinUvAuthTokenUsingUvWithPermissions
+  - 🟢 Persistent pinUvAuthToken for read-only credential management (pcmr, CTAP 2.2+)
 - [Passkey Authentication][passkeys]
   - 🟢 Discoverable credentials (resident keys)
   - 🟢 Hybrid transport (caBLE v2): QR-initiated transactions
@@ -93,6 +94,7 @@ $ cargo run --example change_pin_hid
 $ cargo run --example bio_enrollment_hid
 $ cargo run --example authenticator_config_hid
 $ cargo run --example cred_management_hid
+$ cargo run --example persistent_cred_management_hid
 ```
 
 ## Contributing

libwebauthn/Cargo.toml

@@ -176,3 +176,7 @@ path = "examples/management/authenticator_config_hid.rs"
 [[example]]
 name = "cred_management_hid"
 path = "examples/management/cred_management_hid.rs"
+
+[[example]]
+name = "persistent_cred_management_hid"
+path = "examples/management/persistent_cred_management_hid.rs"

libwebauthn/examples/management/persistent_cred_management_hid.rs

@@ -0,0 +1,85 @@
+//! Read-only credential management backed by a persistent pinUvAuthToken (pcmr).
+//!
+//! A persistent token (CTAP 2.2+) lets a credential manager enumerate passkeys without
+//! re-prompting for the PIN on every launch or replug: the platform mints the token once
+//! and reuses it on later connections, until a PIN change or authenticator reset.
+//!
+//! The token is a long-lived bearer secret, so a real application MUST supply a durable,
+//! secure store (an OS keyring, or encrypted-at-rest with OS access control). This
+//! example uses the in-memory [`EphemeralPersistentTokenStore`], which lives only for the
+//! lifetime of the process: it shows same-session reuse, but not the across-restart
+//! persistence that is the whole point of the feature. Swap in a durable store and the
+//! second run (after replug or restart) skips the PIN prompt too.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use libwebauthn::management::CredentialManagement;
+use libwebauthn::pin::persistent_token::{EphemeralPersistentTokenStore, PersistentTokenStore};
+use libwebauthn::proto::ctap2::Ctap2;
+use libwebauthn::transport::hid::list_devices;
+use libwebauthn::transport::{Channel as _, Device};
+use libwebauthn::webauthn::Error as WebAuthnError;
+
+#[path = "../common/mod.rs"]
+mod common;
+
+const TIMEOUT: Duration = Duration::from_secs(10);
+
+#[tokio::main]
+pub async fn main() -> Result<(), WebAuthnError> {
+    common::setup_logging();
+
+    // Production callers: replace this with a durable, secure store. See the module docs.
+    let store: Arc<dyn PersistentTokenStore> = Arc::new(EphemeralPersistentTokenStore::new());
+
+    let devices = list_devices().await.unwrap();
+    println!("Devices found: {:?}", devices);
+
+    for device in devices {
+        // Attach the store to the device; every channel opened from it forwards the store.
+        let mut device = device.with_persistent_token_store(store.clone());
+        println!("Selected HID authenticator: {}", &device);
+
+        let mut channel = device.channel().await?;
+        let state_recv = channel.get_ux_update_receiver();
+        tokio::spawn(common::handle_uv_updates(state_recv));
+
+        let info = channel.ctap2_get_info().await?;
+        if !info.supports_credential_management() {
+            println!("This authenticator does not support credential management.");
+            continue;
+        }
+        if !info.supports_persistent_credential_management_read_only() {
+            println!(
+                "This authenticator does not advertise perCredMgmtRO. Read-only credential \
+                 management will use an ordinary (ephemeral) pinUvAuthToken and prompt for \
+                 the PIN as usual."
+            );
+        }
+
+        // First pass: with an empty store the platform mints a persistent token, so a PIN
+        // prompt is expected (a UV-capable authenticator may prompt for a touch instead).
+        println!("\nFirst enumeration (expect a PIN prompt if nothing is cached yet):");
+        print_metadata(&mut channel).await?;
+
+        // Second pass: the persistent token is recognized in the store and reused, so no
+        // PIN prompt. With a durable store this also holds across restarts and replugs.
+        println!("\nSecond enumeration (persistent token reused, no PIN prompt expected):");
+        print_metadata(&mut channel).await?;
+
+        return Ok(());
+    }
+
+    Ok(())
+}
+
+async fn print_metadata(channel: &mut impl CredentialManagement) -> Result<(), WebAuthnError> {
+    let metadata = channel.get_credential_metadata(TIMEOUT).await?;
+    println!(
+        "Discoverable credentials: {} (max remaining: {})",
+        metadata.existing_resident_credentials_count,
+        metadata.max_possible_remaining_resident_credentials_count,
+    );
+    Ok(())
+}