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}