Add support for parsing Signature-Agent as sfv::Dictionary + simplify library (#61)

AkshatM · web-flow · commit 8ba0c4ab817b · 2025-10-22T10:53:40.000-04:00
* Simplify interface: concentrate into `lookup_component` method

This change removes the following constructs:

1. `WebBotAuthSignedMessage`
2. `SignedMessage::fetch_all_signature_headers`
3. `SignedMessage::fetch_all_signature_inputs`

and modifies the `lookup_component` method to be the primary source of
information about a message. The goal here is to make it possible to
treat all HTTP headers, including special ones like `Signature-Agent`,
etc. on the same footing. It also removes a source of complexity for
implementors, since they would need to maintain an independent method
just to fetch special values.

* Add support for parsing Signature-Agent as an sfv::Dictionary

This change supports handling Signature-Agent as either an
sfv::Dictionary or an sfv::Item. To decide which way to process, it
relies on whether or not the `Signature-Agent` header listed in the
`Signature-Input` field has an associated `key` parameter. If present,
it attempts to parse as a dictionary.

I've added tests to ensure both types can be handled perfectly well.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -30,6 +30,7 @@ sha2 = "0.10.9"
 base64 = "0.22.1"
 serde_json = "1.0.140"
 data-url = "0.3.1"
+regex = "1.12.2"
 
 # workspace dependencies
 web-bot-auth = { version = "0.5.1", path = "./crates/web-bot-auth" }
diff --git a/crates/http-signature-directory/src/main.rs b/crates/http-signature-directory/src/main.rs
@@ -11,7 +11,7 @@ use reqwest::{
 };
 use serde::{Deserialize, Serialize};
 use web_bot_auth::{
-    components::{CoveredComponent, DerivedComponent},
+    components::{CoveredComponent, DerivedComponent, HTTPField},
     keyring::{JSONWebKeySet, KeyRing, Thumbprintable},
     message_signatures::{MessageVerifier, SignedMessage},
 };
@@ -68,18 +68,21 @@ struct SignedDirectory {
 }
 
 impl SignedMessage for SignedDirectory {
-    fn fetch_all_signature_headers(&self) -> Vec<String> {
-        self.signature.clone()
-    }
-    fn fetch_all_signature_inputs(&self) -> Vec<String> {
-        self.input.clone()
-    }
-    fn lookup_component(&self, name: &CoveredComponent) -> Option<String> {
-        match *name {
+    fn lookup_component(&self, name: &CoveredComponent) -> Vec<String> {
+        match name {
             CoveredComponent::Derived(DerivedComponent::Authority { .. }) => {
-                Some(self.authority.clone())
+                vec![self.authority.clone()]
+            }
+            CoveredComponent::HTTP(HTTPField { name, .. }) => {
+                if name == "signature" {
+                    return self.signature.clone();
+                }
+                if name == "signature-input" {
+                    return self.input.clone();
+                }
+                vec![]
             }
-            _ => None,
+            _ => vec![],
         }
     }
 }
diff --git a/crates/web-bot-auth/Cargo.toml b/crates/web-bot-auth/Cargo.toml
@@ -15,6 +15,7 @@ categories.workspace = true
 [dependencies]
 ed25519-dalek = { workspace = true }
 indexmap = { workspace = true }
+regex = { workspace = true }
 sfv = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
diff --git a/crates/web-bot-auth/src/lib.rs b/crates/web-bot-auth/src/lib.rs
diff --git a/crates/web-bot-auth/src/message_signatures.rs b/crates/web-bot-auth/src/message_signatures.rs
@@ -1,11 +1,14 @@
-use crate::components::CoveredComponent;
+use super::ImplementationError;
+use crate::components::{self, CoveredComponent, HTTPField};
 use crate::keyring::{Algorithm, KeyRing};
 use indexmap::IndexMap;
+use regex::bytes::Regex;
 use sfv::SerializeValue;
 use std::fmt::Write as _;
+use std::sync::LazyLock;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
-
-use super::ImplementationError;
+static OBSOLETE_LINE_FOLDING: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"\s*\r\n\s+").unwrap());
 
 /// The component parameters associated with the signature in `Signature-Input`
 #[derive(Clone, Debug)]
@@ -153,8 +156,26 @@ impl SignatureBaseBuilder {
                 self.components
                     .into_iter()
                     .map(|component| match message.lookup_component(&component) {
-                        Some(serialized_value) => Ok((component, serialized_value)),
-                        None => Err(ImplementationError::LookupError(component)),
+                        v if v.len() == 1 => Ok((component, v[0].to_owned())),
+                        v if v.len() > 1 && matches!(component, CoveredComponent::HTTP(_)) => {
+                            let mut register: Vec<String> = vec![];
+
+                            for header_value in v.into_iter() {
+                                register.push(
+                                    // replace leading / trailing whitespace and obsolete line folding,
+                                    // per HTTP message signature spec
+                                    String::from_utf8(
+                                        OBSOLETE_LINE_FOLDING
+                                            .replace_all(header_value.as_bytes().trim_ascii(), b" ")
+                                            .into_owned(),
+                                    )
+                                    .map_err(|_| ImplementationError::NonAsciiContentFound)?,
+                                );
+                            }
+
+                            Ok((component, register.join(", ")))
+                        }
+                        _ => Err(ImplementationError::LookupError(component)),
                     })
                     .collect::<Result<Vec<(CoveredComponent, String)>, ImplementationError>>()?,
             ),
@@ -215,31 +236,14 @@ impl SignatureBase {
 /// Trait that messages seeking verification should implement to facilitate looking up
 /// raw values from the underlying message.
 pub trait SignedMessage {
-    /// Obtain every `Signature` header in the message. Despite the name, you can omit
-    /// `Signature` that are known to be invalid ahead of time. However, each `Signature-`
-    /// header should be unparsed and be a valid sfv::Item::Dictionary value. You should
-    /// separately implement looking this up in `lookup_component` as an HTTP header with
-    /// multiple values, although including these as signature components when signing is
-    /// NOT recommended. During verification, invalid values (those that cannot be
-    /// parsed as an sfv::Dictionary) will be skipped without raising an error.
-    fn fetch_all_signature_headers(&self) -> Vec<String>;
-    /// Obtain every `Signature-Input` header in the message. Despite the name, you
-    /// can omit `Signature-Input` that are known to be invalid ahead of time. However,
-    /// each `Signature-Input` header should be unparsed and be a valid sfv::Item::Dictionary
-    /// value (meaning it should be encased in double quotes). You should separately implement
-    /// looking this up in `lookup_component` as an HTTP header with multiple values, although
-    /// including these as signature components when signing is NOT recommended. During
-    /// verification, invalid values (those that cannot be parsed as an sfv::Dictionary) will
-    /// be skipped will be skipped without raising an error.
-    fn fetch_all_signature_inputs(&self) -> Vec<String>;
-    /// Obtain the serialized value of a covered component. Implementations should
+    /// Retrieve the raw value(s) of a covered component. Implementations should
     /// respect any parameter values set on the covered component per the message
-    /// signature spec. Component values that cannot be found must return None.
+    /// signature spec. Component values that cannot be found must return an empty vector.
     /// `CoveredComponent::HTTP` fields are guaranteed to have lowercase ASCII names, so
     /// care should be taken to ensure HTTP field names in the message are checked in a
-    /// case-insensitive way. HTTP fields with multiple values should be combined into a
-    /// single string in the manner described in <https://www.rfc-editor.org/rfc/rfc9421#name-http-fields>.
-    fn lookup_component(&self, name: &CoveredComponent) -> Option<String>;
+    /// case-insensitive way. Only `CoveredComponent::Http` should return a vector with
+    /// more than one element.
+    fn lookup_component(&self, name: &CoveredComponent) -> Vec<String>;
 }
 
 /// Trait that messages seeking signing should implement to generate `Signature-Input`
@@ -386,6 +390,8 @@ impl MessageSigner {
 /// of the chosen labl and its components.
 #[derive(Clone, Debug)]
 pub struct ParsedLabel {
+    /// The label that was chosen.
+    pub label: sfv::Key,
     /// The signature obtained from the message that verifiers will verify
     pub signature: Vec<u8>,
     /// The signature base obtained from the message, containining both the chosen
@@ -424,27 +430,33 @@ impl MessageVerifier {
         P: Fn(&(sfv::Key, sfv::InnerList)) -> bool,
     {
         let signature_input = message
-            .fetch_all_signature_inputs()
+            .lookup_component(&CoveredComponent::HTTP(HTTPField {
+                name: "signature-input".to_string(),
+                parameters: components::HTTPFieldParametersSet(vec![]),
+            }))
             .into_iter()
             .filter_map(|sig_input| sfv::Parser::new(&sig_input).parse_dictionary().ok())
             .reduce(|mut acc, sig_input| {
                 acc.extend(sig_input);
                 acc
             })
             .ok_or(ImplementationError::ParsingError(
-                "No `Signature-Input` headers found".to_string(),
+                "No validly-formatted `Signature-Input` headers found".to_string(),
             ))?;
 
         let mut signature_header = message
-            .fetch_all_signature_headers()
+            .lookup_component(&CoveredComponent::HTTP(HTTPField {
+                name: "signature".to_string(),
+                parameters: components::HTTPFieldParametersSet(vec![]),
+            }))
             .into_iter()
             .filter_map(|sig_input| sfv::Parser::new(&sig_input).parse_dictionary().ok())
             .reduce(|mut acc, sig_input| {
                 acc.extend(sig_input);
                 acc
             })
             .ok_or(ImplementationError::ParsingError(
-                "No `Signature` headers found".to_string(),
+                "No validly-formatted `Signature` headers found".to_string(),
             ))?;
 
         let (label, innerlist) = signature_input
@@ -483,7 +495,11 @@ impl MessageVerifier {
         let base = builder.into_signature_base(message)?;
 
         Ok(MessageVerifier {
-            parsed: ParsedLabel { signature, base },
+            parsed: ParsedLabel {
+                label,
+                signature,
+                base,
+            },
         })
     }
 
@@ -550,18 +566,22 @@ mod tests {
     struct StandardTestVector {}
 
     impl SignedMessage for StandardTestVector {
-        fn fetch_all_signature_headers(&self) -> Vec<String> {
-            vec!["sig1=:uz2SAv+VIemw+Oo890bhYh6Xf5qZdLUgv6/PbiQfCFXcX/vt1A8Pf7OcgL2yUDUYXFtffNpkEr5W6dldqFrkDg==:".to_owned()]
-        }
-        fn fetch_all_signature_inputs(&self) -> Vec<String> {
-            vec![r#"sig1=("@authority");created=1735689600;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";alg="ed25519";expires=1735693200;nonce="gubxywVx7hzbYKatLgzuKDllDAIXAkz41PydU7aOY7vT+Mb3GJNxW0qD4zJ+IOQ1NVtg+BNbTCRUMt1Ojr5BgA==";tag="web-bot-auth""#.to_owned()]
-        }
-        fn lookup_component(&self, name: &CoveredComponent) -> Option<String> {
-            match *name {
+        fn lookup_component(&self, name: &CoveredComponent) -> Vec<String> {
+            match name {
+                CoveredComponent::HTTP(HTTPField { name, .. }) => {
+                    if name == "signature" {
+                        return vec!["sig1=:uz2SAv+VIemw+Oo890bhYh6Xf5qZdLUgv6/PbiQfCFXcX/vt1A8Pf7OcgL2yUDUYXFtffNpkEr5W6dldqFrkDg==:".to_owned()];
+                    }
+
+                    if name == "signature-input" {
+                        return vec![r#"sig1=("@authority");created=1735689600;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";alg="ed25519";expires=1735693200;nonce="gubxywVx7hzbYKatLgzuKDllDAIXAkz41PydU7aOY7vT+Mb3GJNxW0qD4zJ+IOQ1NVtg+BNbTCRUMt1Ojr5BgA==";tag="web-bot-auth""#.to_owned()];
+                    }
+                    vec![]
+                }
                 CoveredComponent::Derived(DerivedComponent::Authority { .. }) => {
-                    Some("example.com".to_string())
+                    vec!["example.com".to_string()]
                 }
-                _ => None,
+                _ => vec![],
             }
         }
     }
diff --git a/examples/rust/signing.rs b/examples/rust/signing.rs
@@ -15,7 +15,9 @@
 use indexmap::IndexMap;
 use std::{time::Duration, vec};
 use web_bot_auth::{
-    components::{CoveredComponent, DerivedComponent, HTTPField, HTTPFieldParametersSet},
+    components::{
+        CoveredComponent, DerivedComponent, HTTPField, HTTPFieldParameters, HTTPFieldParametersSet,
+    },
     keyring::Algorithm,
     message_signatures::{MessageSigner, UnsignedMessage},
 };
@@ -36,9 +38,11 @@ impl UnsignedMessage for MyThing {
             (
                 CoveredComponent::HTTP(HTTPField {
                     name: "signature-agent".to_string(),
-                    parameters: HTTPFieldParametersSet(vec![]),
+                    parameters: HTTPFieldParametersSet(vec![HTTPFieldParameters::Key(
+                        "agent1".to_string(),
+                    )]),
                 }),
-                "\"https://myexample.com\"".to_string(),
+                r#"agent1="https://myexample.com""#.to_string(),
             ),
         ])
     }
@@ -50,12 +54,14 @@ impl UnsignedMessage for MyThing {
 }
 
 fn main() {
-    // Signing a message
+    // Signing a message - private key pulled from https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/
+    // and only for example purposes.
     let private_key = vec![
         0x9f, 0x83, 0x62, 0xf8, 0x7a, 0x48, 0x4a, 0x95, 0x4e, 0x6e, 0x74, 0x0c, 0x5b, 0x4c, 0x0e,
         0x84, 0x22, 0x91, 0x39, 0xa2, 0x0a, 0xa8, 0xab, 0x56, 0xff, 0x66, 0x58, 0x6f, 0x6a, 0x7d,
         0x29, 0xc5,
     ];
+    // sample keyid pulled from https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/
     let signer = MessageSigner {
         keyid: "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U".into(),
         nonce: "ZO3/XMEZjrvSnLtAP9M7jK0WGQf3J+pbmQRUpKDhF9/jsNCWqUh2sq+TH4WTX3/GpNoSZUa8eNWMKqxWp2/c2g==".into(),
diff --git a/examples/rust/verify.rs b/examples/rust/verify.rs
@@ -13,7 +13,7 @@
 // limitations under the License.
 
 use web_bot_auth::{
-    SignatureAgentLink, WebBotAuthSignedMessage, WebBotAuthVerifier,
+    SignatureAgentLink, WebBotAuthVerifier,
     components::{CoveredComponent, DerivedComponent, HTTPField},
     keyring::{Algorithm, KeyRing},
     message_signatures::SignedMessage,
@@ -22,34 +22,30 @@ use web_bot_auth::{
 struct MySignedMsg;
 
 impl SignedMessage for MySignedMsg {
-    fn fetch_all_signature_headers(&self) -> Vec<String> {
-        vec!["sig1=:GXzHSRZ9Sf6WwLOZjxAhfE6WEUPfDMrVBJITsL2sbG8gtcZgqKe2Yn7uavk0iNQrfcPzgGq8h8Pk5osNGqdtCw==:".to_owned()]
-    }
-    fn fetch_all_signature_inputs(&self) -> Vec<String> {
-        vec![r#"sig1=("@authority" "signature-agent");alg="ed25519";keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";nonce="ZO3/XMEZjrvSnLtAP9M7jK0WGQf3J+pbmQRUpKDhF9/jsNCWqUh2sq+TH4WTX3/GpNoSZUa8eNWMKqxWp2/c2g==";tag="web-bot-auth";created=1749332605;expires=1749332615"#.to_owned()]
-    }
-    fn lookup_component(&self, name: &CoveredComponent) -> Option<String> {
+    fn lookup_component(&self, name: &CoveredComponent) -> Vec<String> {
         match name {
             CoveredComponent::Derived(DerivedComponent::Authority { .. }) => {
-                Some("example.com".to_string())
+                vec!["example.com".to_string()]
             }
             CoveredComponent::HTTP(HTTPField { name, .. }) => {
                 if name == "signature-agent" {
-                    return Some(String::from("\"https://myexample.com\""));
+                    return vec![r#"agent1="https://myexample.com""#.to_string()];
                 }
-                None
+
+                if name == "signature" {
+                    return vec![r#"sig1=:EZZ8VJcVQ9WgiUytQWAfEvRWLLu2O+UkJ15aVI//dfLTCLnr1Vg2CDXXlrW4D+OjBB6zu/UkFtxpKzbXh2ESBg==:"#.to_string()];
+                }
+
+                if name == "signature-input" {
+                    return vec![r#"sig1=("@authority" "signature-agent";key="agent1");keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";nonce="ZO3/XMEZjrvSnLtAP9M7jK0WGQf3J+pbmQRUpKDhF9/jsNCWqUh2sq+TH4WTX3/GpNoSZUa8eNWMKqxWp2/c2g==";tag="web-bot-auth";created=1761143856;expires=1761143866"#.to_string()];
+                }
+                vec![]
             }
-            _ => None,
+            _ => vec![],
         }
     }
 }
 
-impl WebBotAuthSignedMessage for MySignedMsg {
-    fn fetch_all_signature_agents(&self) -> Vec<String> {
-        vec!["\"https://myexample.com\"".into()]
-    }
-}
-
 fn main() {
     // Verifying a Web Bot Auth message
     let public_key = [
@@ -58,6 +54,7 @@ fn main() {
         0xd1, 0xbb,
     ];
     let mut keyring = KeyRing::default();
+    // sample keyid pulled from https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/
     keyring.import_raw(
         "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U".to_string(),
         Algorithm::Ed25519,
diff --git a/examples/rust/verify_arbitrary.rs b/examples/rust/verify_arbitrary.rs
@@ -13,26 +13,30 @@
 // limitations under the License.
 
 use web_bot_auth::{
-    components::{CoveredComponent, DerivedComponent},
+    components::{CoveredComponent, DerivedComponent, HTTPField},
     keyring::{Algorithm, KeyRing},
     message_signatures::{MessageVerifier, SignedMessage},
 };
 
 struct MySignedMsg;
 
 impl SignedMessage for MySignedMsg {
-    fn fetch_all_signature_headers(&self) -> Vec<String> {
-        vec!["sig1=:uz2SAv+VIemw+Oo890bhYh6Xf5qZdLUgv6/PbiQfCFXcX/vt1A8Pf7OcgL2yUDUYXFtffNpkEr5W6dldqFrkDg==:".to_owned()]
-    }
-    fn fetch_all_signature_inputs(&self) -> Vec<String> {
-        vec![r#"sig1=("@authority");created=1735689600;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";alg="ed25519";expires=1735693200;nonce="gubxywVx7hzbYKatLgzuKDllDAIXAkz41PydU7aOY7vT+Mb3GJNxW0qD4zJ+IOQ1NVtg+BNbTCRUMt1Ojr5BgA==";tag="web-bot-auth""#.to_owned()]
-    }
-    fn lookup_component(&self, name: &CoveredComponent) -> Option<String> {
-        match *name {
+    fn lookup_component(&self, name: &CoveredComponent) -> Vec<String> {
+        match name {
             CoveredComponent::Derived(DerivedComponent::Authority { .. }) => {
-                Some("example.com".to_string())
+                vec!["example.com".to_string()]
+            }
+            CoveredComponent::HTTP(HTTPField { name, .. }) => {
+                if name == "signature" {
+                    return vec!["sig1=:uz2SAv+VIemw+Oo890bhYh6Xf5qZdLUgv6/PbiQfCFXcX/vt1A8Pf7OcgL2yUDUYXFtffNpkEr5W6dldqFrkDg==:".to_owned()];
+                }
+
+                if name == "signature-input" {
+                    return vec![r#"sig1=("@authority");created=1735689600;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";alg="ed25519";expires=1735693200;nonce="gubxywVx7hzbYKatLgzuKDllDAIXAkz41PydU7aOY7vT+Mb3GJNxW0qD4zJ+IOQ1NVtg+BNbTCRUMt1Ojr5BgA==";tag="web-bot-auth""#.to_owned()];
+                }
+                vec![]
             }
-            _ => None,
+            _ => vec![],
         }
     }
 }
