Skip to main content

hyprstream_rpc/auth/
signer_suite.rs

1//! Signer-suite thumbprint — the ONE shared helper and encoding for the v16
2//! `cnf.hs_signer_suite` confirmation method (frozen WS-A credential-profile
3//! §1.1/§5). Both the mint side (WS-B `ExchangeDelegated`) and the verify side
4//! (WS-C proof resolution) compute the identical function over the identical
5//! bytes — there is no second hash encoding.
6//!
7//! Content thumbprint: `SHA-256(` RFC 8949 **deterministic-CBOR** of
8//! `[suite_id, [ordered raw component public keys]]` `)`. It uniformly covers a
9//! classical (one-key) and a hybrid (two-key) primary signer group. Component
10//! key order is the suite-plan order — NEVER a kid/group_id/label/position.
11//!
12//! This is a direct port of A's frozen `gen_proof_vectors.py::signer_suite_thumbprint`
13//! (+ its `enc`); the golden vectors in the tests are cross-checked against A's
14//! own tooling at `af08825528627069b3cfbdd763948c4a24689cb5`.
15
16use sha2::{Digest, Sha256};
17
18use super::det_cbor::{det_cbor, DetCborValue};
19
20/// Frozen suite ID for a classical (single Ed25519) primary signer group.
21pub const SUITE_CLASSICAL_ED25519: &str = "hs-cose-sign-ed25519-v1";
22
23/// Frozen suite ID for a hybrid (Ed25519 + ML-DSA-65) primary signer group.
24/// Component order is `[ed25519, ml_dsa_65]`.
25pub const SUITE_HYBRID_ED25519_MLDSA65: &str = "hs-cose-sign-ed25519-mldsa65-wns-v1";
26
27/// The v16 `cnf.hs_signer_suite` content thumbprint: `SHA-256(det-CBOR([suite_id,
28/// [ordered raw component public keys]]))`, using the ONE shared
29/// [`det_cbor`] encoder (no second det-CBOR implementation).
30///
31/// `ordered_component_pubkeys` are the RAW public key bytes in suite-plan order
32/// (Ed25519 = 32 bytes; ML-DSA-65 = 1952 bytes). The result is the 32-byte
33/// digest; callers base64url-encode (no padding) it for the JWT `cnf` member.
34#[must_use]
35pub fn signer_suite_thumbprint(suite_id: &str, ordered_component_pubkeys: &[&[u8]]) -> [u8; 32] {
36    let value = DetCborValue::Array(vec![
37        DetCborValue::Text(suite_id),
38        DetCborValue::Array(
39            ordered_component_pubkeys
40                .iter()
41                .map(|pk| DetCborValue::Bytes(pk))
42                .collect(),
43        ),
44    ]);
45    Sha256::digest(det_cbor(&value)).into()
46}
47
48/// The v16 `cnf.hs_signer_suite` value (base64url, unpadded) for a primary
49/// signer group given its raw component public keys: classical
50/// (`SUITE_CLASSICAL_ED25519`, Ed25519 only) when `ml_dsa_65` is `None`, or
51/// hybrid (`SUITE_HYBRID_ED25519_MLDSA65`, Ed25519 + ML-DSA-65 in that frozen
52/// order) when present. The single place mint paths turn key material into the
53/// stamped confirmation value.
54#[must_use]
55pub fn service_signer_suite_b64(ed25519: &[u8; 32], ml_dsa_65: Option<&[u8]>) -> String {
56    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
57    let thumbprint = match ml_dsa_65 {
58        Some(pq) => signer_suite_thumbprint(SUITE_HYBRID_ED25519_MLDSA65, &[ed25519, pq]),
59        None => signer_suite_thumbprint(SUITE_CLASSICAL_ED25519, &[ed25519]),
60    };
61    URL_SAFE_NO_PAD.encode(thumbprint)
62}
63
64#[cfg(test)]
65mod tests {
66    use super::*;
67    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
68
69    /// Golden vectors computed by A's own frozen `gen_proof_vectors.py`
70    /// (`enc`/`signer_suite_thumbprint`) at `af0882552`, over the fixed inputs
71    /// ed = 32×0x01 and mldsa = 1952×0x02. If these ever change, the mint (B)
72    /// and verify (C) sides have diverged from the frozen A encoding.
73    #[test]
74    fn classical_thumbprint_matches_a_golden_vector() {
75        let ed = [0x01u8; 32];
76        let tp = signer_suite_thumbprint(SUITE_CLASSICAL_ED25519, &[&ed]);
77        assert_eq!(
78            URL_SAFE_NO_PAD.encode(tp),
79            "VKnD78bkwV7dWjvbXrRwAYKWUmcIRjWFY7UwnEkOj_w"
80        );
81    }
82
83    #[test]
84    fn hybrid_thumbprint_matches_a_golden_vector() {
85        let ed = [0x01u8; 32];
86        let mldsa = [0x02u8; 1952];
87        let tp = signer_suite_thumbprint(SUITE_HYBRID_ED25519_MLDSA65, &[&ed, &mldsa]);
88        assert_eq!(
89            URL_SAFE_NO_PAD.encode(tp),
90            "n47qkIMqPn-EuRo0YmrWkGFyyCY0UmVhKE19Bxbtt0U"
91        );
92    }
93
94    /// Component order is load-bearing: swapping the two hybrid keys yields a
95    /// different thumbprint (the encoding never sorts or canonicalizes keys).
96    #[test]
97    fn component_order_is_significant() {
98        let ed = [0x01u8; 32];
99        let mldsa = [0x02u8; 1952];
100        let ordered = signer_suite_thumbprint(SUITE_HYBRID_ED25519_MLDSA65, &[&ed, &mldsa]);
101        let swapped = signer_suite_thumbprint(SUITE_HYBRID_ED25519_MLDSA65, &[&mldsa, &ed]);
102        assert_ne!(ordered, swapped);
103    }
104}