feat(webauthn): related-origins validation (WebAuthn L3 §5.11)

README.md

@@ -68,16 +68,18 @@ $ git submodule update --init
 The basic ceremony examples (register + authenticate) cover all transports. The
 WebAuthn examples consume and emit JSON per the [WebAuthn IDL][webauthn].
 
-| Transport             | FIDO U2F                                                                                                                 | WebAuthn (FIDO2)                                                                                                                   |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| **USB (HID)**         | `cargo run --example u2f_hid`                                                                                            | `cargo run --example webauthn_hid`                                                                                                 |
-| **Bluetooth (BLE)**   | `cargo run --example u2f_ble`                                                                                            | `cargo run --example webauthn_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 + CTAP 2.3)** | —                                                                                                             | `cargo run --example webauthn_cable`                                                                                               |
-| **Hybrid (caBLE v2)** | —                                                                                                                        | `cargo run --example webauthn_cable_wss`                                                                                           |
+| Transport                        | FIDO U2F                                                                                                                 | WebAuthn (FIDO2) [^ro]                                                                                                                                                          |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **USB (HID)**                    | `cargo run --example u2f_hid`                                                                                            | `cargo run --example webauthn_hid`                                                                                                            |
+| **Bluetooth (BLE)**              | `cargo run --example u2f_ble`                                                                                            | `cargo run --example webauthn_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 + CTAP 2.3)** | —                                                                                                                        | `cargo run --example webauthn_cable`                                                                                                          |
+| **Hybrid (caBLE v2)**            | —                                                                                                                        | `cargo run --example webauthn_cable_wss`                                                                                                      |
 
 [^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.
 
+[^ro]: The ceremony examples run with related origins disabled (they are same-origin, so it never applies). The bundled reqwest-backed [related-origins](https://www.w3.org/TR/webauthn-3/#sctn-related-origins) source is shown in the `webauthn_related_origins_hid` example below, behind the optional `reqwest-related-origins-source` feature. Consumers that ship their own HTTP stack can implement `HttpClient` or `RelatedOriginsSource` directly.
+
 Additional HID-only examples cover specific FIDO2 features and authenticator management:
 
 ```
@@ -88,6 +90,9 @@ $ cargo run --example webauthn_prf_hid
 $ cargo run --example prf_replay -- CREDENTIAL_ID FIRST_PRF_INPUT
 $ cargo run --example device_selection_hid
 
+# Related origins (reqwest-backed well-known fetch)
+$ cargo run --features reqwest-related-origins-source --example webauthn_related_origins_hid
+
 # CTAP2 authenticator management
 $ cargo run --example change_pin_hid
 $ cargo run --example bio_enrollment_hid

libwebauthn/Cargo.toml

@@ -39,6 +39,10 @@ nfc-backend-libnfc = [
 # external crates (e.g. libwebauthn-tests) can plug in a virtual HID transport
 # for end-to-end tests.
 virt = []
+# Provides the reqwest-backed HttpClient and ReqwestRelatedOriginsSource. Off by
+# default so the core crate stays HTTP-client-free. Consumers that want the
+# default fetch opt in, others implement HttpClient or RelatedOriginsSource.
+reqwest-related-origins-source = ["dep:reqwest"]
 
 [dependencies]
 base64-url = "3.0.0"
@@ -47,6 +51,7 @@ tracing = "0.1.29"
 idna = "1.0.3"
 publicsuffix = "2.3"
 url = "2.5"
+http = "1"
 maplit = "1.0.2"
 sha2 = "0.10.2"
 uuid = { version = "1.5.0", features = ["serde", "v4"] }
@@ -100,6 +105,12 @@ apdu = { version = "0.4.0", optional = true }
 pcsc = { version = "2.9.0", optional = true }
 nfc1 = { version = "=0.6.0", optional = true, default-features = false }
 nfc1-sys = { version = "0.3.9", optional = true, default-features = false }
+reqwest = { version = "0.12", default-features = false, features = [
+    "rustls-tls-native-roots",
+    "http2",
+    "stream",
+    "charset",
+], optional = true }
 
 [dev-dependencies]
 tracing-subscriber = { version = "0.3.3", features = ["env-filter"] }
@@ -161,6 +172,11 @@ path = "examples/features/webauthn_preflight_hid.rs"
 name = "webauthn_prf_hid"
 path = "examples/features/webauthn_prf_hid.rs"
 
+[[example]]
+name = "webauthn_related_origins_hid"
+path = "examples/features/webauthn_related_origins_hid.rs"
+required-features = ["reqwest-related-origins-source"]
+
 [[example]]
 name = "prf_replay"
 path = "examples/features/prf_replay.rs"

libwebauthn/examples/ceremony/webauthn_ble.rs

@@ -1,8 +1,8 @@
 use std::error::Error;
 
 use libwebauthn::ops::webauthn::{
-    DatFilePublicSuffixList, GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin,
-    WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    DatFilePublicSuffixList, GetAssertionRequest, JsonFormat, MakeCredentialRequest,
+    OriginValidation, RelatedOrigins, RequestOrigin, RequestSettings, WebAuthnIDLResponse as _,
 };
 use libwebauthn::proto::ctap2::Ctap2PublicKeyCredentialDescriptor;
 use libwebauthn::transport::ble::list_devices;
@@ -52,8 +52,15 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
                     "attestation": "none"
                 }
                 "#;
+        let settings = RequestSettings {
+            origin: OriginValidation::Validate {
+                public_suffix_list: &psl,
+                related_origins: RelatedOrigins::Disabled,
+            },
+        };
         let make_credentials_request: MakeCredentialRequest =
-            MakeCredentialRequest::from_json(&request_origin, &psl, request_json)
+            MakeCredentialRequest::prepare(&request_origin, request_json, &settings)
+                .await
                 .expect("Failed to parse request JSON");
         println!(
             "WebAuthn MakeCredential request: {:?}",
@@ -97,7 +104,8 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
                 "#
         );
         let get_assertion: GetAssertionRequest =
-            GetAssertionRequest::from_json(&request_origin, &psl, &request_json)
+            GetAssertionRequest::prepare(&request_origin, &request_json, &settings)
+                .await
                 .expect("Failed to parse request JSON");
         println!("WebAuthn GetAssertion request: {:?}", get_assertion);
 

libwebauthn/examples/ceremony/webauthn_cable.rs

@@ -11,8 +11,8 @@ use qrcode::render::unicode;
 use qrcode::QrCode;
 
 use libwebauthn::ops::webauthn::{
-    DatFilePublicSuffixList, JsonFormat, MakeCredentialRequest, RequestOrigin, WebAuthnIDL as _,
-    WebAuthnIDLResponse as _,
+    DatFilePublicSuffixList, JsonFormat, MakeCredentialRequest, OriginValidation, RelatedOrigins,
+    RequestOrigin, RequestSettings, WebAuthnIDLResponse as _,
 };
 use libwebauthn::transport::{Channel as _, Device};
 use libwebauthn::webauthn::WebAuthn;
@@ -58,6 +58,12 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let psl = DatFilePublicSuffixList::from_system_file().expect(
         "PSL not available; install the publicsuffix-list package or pass an explicit path",
     );
+    let settings = RequestSettings {
+        origin: OriginValidation::Validate {
+            public_suffix_list: &psl,
+            related_origins: RelatedOrigins::Disabled,
+        },
+    };
 
     let mut device: CableQrCodeDevice = CableQrCodeDevice::new_transient(
         QrCodeOperationHint::MakeCredential,
@@ -79,8 +85,10 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let state_recv = channel.get_ux_update_receiver();
     tokio::spawn(common::handle_cable_updates(state_recv));
 
-    let request = MakeCredentialRequest::from_json(&request_origin, &psl, MAKE_CREDENTIAL_REQUEST)
-        .expect("Failed to parse request JSON");
+    let request =
+        MakeCredentialRequest::prepare(&request_origin, MAKE_CREDENTIAL_REQUEST, &settings)
+            .await
+            .expect("Failed to parse request JSON");
 
     let response = retry_user_errors!(channel.webauthn_make_credential(&request)).unwrap();
     let response_json = response

libwebauthn/examples/ceremony/webauthn_cable_wss.rs

@@ -14,8 +14,8 @@ use qrcode::QrCode;
 use tokio::time::sleep;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin, SystemPublicSuffixList,
-    WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    GetAssertionRequest, JsonFormat, MakeCredentialRequest, OriginValidation, RelatedOrigins,
+    RequestOrigin, RequestSettings, SystemPublicSuffixList, WebAuthnIDLResponse as _,
 };
 use libwebauthn::transport::cable::channel::CableChannel;
 use libwebauthn::transport::{Channel as _, Device};
@@ -95,9 +95,18 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         let state_recv = channel.get_ux_update_receiver();
         tokio::spawn(common::handle_cable_updates(state_recv));
 
-        let request =
-            MakeCredentialRequest::from_json(&request_origin, &psl, MAKE_CREDENTIAL_REQUEST)
-                .expect("Failed to parse request JSON");
+        let request = MakeCredentialRequest::prepare(
+            &request_origin,
+            MAKE_CREDENTIAL_REQUEST,
+            &RequestSettings {
+                origin: OriginValidation::Validate {
+                    public_suffix_list: &psl,
+                    related_origins: RelatedOrigins::Disabled,
+                },
+            },
+        )
+        .await
+        .expect("Failed to parse request JSON");
 
         let response = retry_user_errors!(channel.webauthn_make_credential(&request)).unwrap();
         let response_json = response
@@ -155,8 +164,18 @@ async fn run_get_assertion(
     let state_recv = channel.get_ux_update_receiver();
     tokio::spawn(common::handle_cable_updates(state_recv));
 
-    let request = GetAssertionRequest::from_json(request_origin, psl, GET_ASSERTION_REQUEST)
-        .expect("Failed to parse request JSON");
+    let request = GetAssertionRequest::prepare(
+        request_origin,
+        GET_ASSERTION_REQUEST,
+        &RequestSettings {
+            origin: OriginValidation::Validate {
+                public_suffix_list: psl,
+                related_origins: RelatedOrigins::Disabled,
+            },
+        },
+    )
+    .await
+    .expect("Failed to parse request JSON");
     let response = retry_user_errors!(channel.webauthn_get_assertion(&request)).unwrap();
     for assertion in &response.assertions {
         let assertion_json = assertion

libwebauthn/examples/ceremony/webauthn_hid.rs

@@ -2,8 +2,8 @@ use std::error::Error;
 use std::time::Duration;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin, SystemPublicSuffixList,
-    WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    GetAssertionRequest, JsonFormat, MakeCredentialRequest, OriginValidation, RelatedOrigins,
+    RequestOrigin, RequestSettings, SystemPublicSuffixList, WebAuthnIDLResponse as _,
 };
 use libwebauthn::proto::ctap2::Ctap2PublicKeyCredentialDescriptor;
 use libwebauthn::transport::hid::list_devices;
@@ -32,6 +32,12 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         let psl = SystemPublicSuffixList::auto().expect(
             "PSL not available; install the publicsuffix-list (or publicsuffix-list-dafsa) package, or pass an explicit path",
         );
+        let settings = RequestSettings {
+            origin: OriginValidation::Validate {
+                public_suffix_list: &psl,
+                related_origins: RelatedOrigins::Disabled,
+            },
+        };
         let request_json = r#"
                 {
                     "rp": {
@@ -57,7 +63,8 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
                 }
                 "#;
         let make_credentials_request: MakeCredentialRequest =
-            MakeCredentialRequest::from_json(&request_origin, &psl, request_json)
+            MakeCredentialRequest::prepare(&request_origin, request_json, &settings)
+                .await
                 .expect("Failed to parse request JSON");
         println!(
             "WebAuthn MakeCredential request: {:?}",
@@ -101,7 +108,8 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
                 "#
         );
         let get_assertion: GetAssertionRequest =
-            GetAssertionRequest::from_json(&request_origin, &psl, &request_json)
+            GetAssertionRequest::prepare(&request_origin, &request_json, &settings)
+                .await
                 .expect("Failed to parse request JSON");
         println!("WebAuthn GetAssertion request: {:?}", get_assertion);
 

libwebauthn/examples/ceremony/webauthn_nfc.rs

@@ -1,8 +1,8 @@
 use std::error::Error;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin, SystemPublicSuffixList,
-    WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    GetAssertionRequest, JsonFormat, MakeCredentialRequest, OriginValidation, RelatedOrigins,
+    RequestOrigin, RequestSettings, SystemPublicSuffixList, WebAuthnIDLResponse as _,
 };
 use libwebauthn::transport::nfc::{get_nfc_device, is_nfc_available};
 use libwebauthn::transport::{Channel as _, Device};
@@ -30,9 +30,14 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let psl = SystemPublicSuffixList::auto().expect(
         "PSL not available; install the publicsuffix-list (or publicsuffix-list-dafsa) package, or pass an explicit path",
     );
-    let make_credentials_request = MakeCredentialRequest::from_json(
+    let settings = RequestSettings {
+        origin: OriginValidation::Validate {
+            public_suffix_list: &psl,
+            related_origins: RelatedOrigins::Disabled,
+        },
+    };
+    let make_credentials_request = MakeCredentialRequest::prepare(
         &request_origin,
-        &psl,
         r#"
         {
             "rp": {
@@ -57,7 +62,9 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
             "attestation": "none"
         }
         "#,
+        &settings,
     )
+    .await
     .expect("Failed to parse request JSON");
     println!(
         "WebAuthn MakeCredential request: {:?}",
@@ -74,9 +81,8 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         .expect("Failed to serialize MakeCredential response");
     println!("WebAuthn MakeCredential response (JSON):\n{response_json}");
 
-    let get_assertion = GetAssertionRequest::from_json(
+    let get_assertion = GetAssertionRequest::prepare(
         &request_origin,
-        &psl,
         r#"
         {
             "challenge": "Y3JlZGVudGlhbHMtZm9yLWxpbnV4L2xpYndlYmF1dGhu",
@@ -85,7 +91,9 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
             "userVerification": "discouraged"
         }
         "#,
+        &settings,
     )
+    .await
     .expect("Failed to parse request JSON");
     println!("WebAuthn GetAssertion request: {:?}", get_assertion);