Skip to main content

hyprstream_rpc/
stream_provenance.rs

1//! Per-host provenance signing/verification for the mesh stream plane (#321).
2//!
3//! The chained HMAC on `StreamBlock` proves "the producer held the DH key and
4//! delivered blocks in order" — it does NOT prove "host-X computed this block"
5//! (threat T3 / C-PROV in the authz threat-model). Provenance closes that gap:
6//! each block is signed with the producing host's **per-host hybrid COSE
7//! identity** (Ed25519 + ML-DSA-65, #328 `derive_mesh_mldsa_key`), and the
8//! consumer verifies the signature AND that the signer key is enrolled in the
9//! mesh roster. This is a layer ON TOP of AEAD + HMAC.
10//!
11//! ## Canonical signed region
12//!
13//! The signature covers the *signed region*: the StreamBlock serialized with the
14//! `provenance` field left empty — i.e. exactly [`crate::streaming::encode_stream_block`]
15//! over `(prevMac, sequenceNumber, epoch, payloads)`. The publisher signs that
16//! region, then attaches the `provenance` field; the consumer reconstructs the
17//! same region from the parsed (provenance-cleared) block and verifies. The
18//! signature therefore binds the post-AEAD payloads, the sequence number, and the
19//! epoch — but is independent of the (circular) provenance bytes themselves.
20
21use anyhow::{anyhow, Result};
22
23use crate::crypto::cose_sign::{sign_composite, verify_composite};
24use crate::crypto::pq::{MlDsaSigningKey, MlDsaVerifyingKey};
25use crate::envelope::PqTrustStore;
26use crate::streaming::StreamPayloadData;
27use crate::streaming_capnp;
28
29/// Cap'n Proto file id of `streaming.capnp` — first half of the COSE
30/// `external_aad` schema binding for provenance (prevents cross-schema replay).
31const STREAMING_SCHEMA_ID: u64 = 0xe7f8_a9b0_c1d2_e3f4;
32
33/// Stable inner-type id binding the provenance COSE composite to the StreamBlock
34/// signed region (≠ any envelope type id, so a provenance signature can never be
35/// replayed as a request/response envelope signature).
36const STREAM_BLOCK_PROVENANCE_TYPE_ID: u64 = 0x5374_726d_4270_3031; // "StrmBp01"
37
38/// COSE `external_aad` for StreamBlock provenance signatures.
39fn provenance_external_aad() -> Vec<u8> {
40    crate::crypto::cose_sign1::build_external_aad(
41        STREAMING_SCHEMA_ID,
42        STREAM_BLOCK_PROVENANCE_TYPE_ID,
43    )
44}
45
46/// The producing host's per-host hybrid signing identity (#328): the node's
47/// Ed25519 mesh signer + its deterministically-derived ML-DSA-65 mesh key.
48#[derive(Clone)]
49pub struct ProvenanceSigner {
50    ed_sk: ed25519_dalek::SigningKey,
51    pq_sk: MlDsaSigningKey,
52}
53
54impl ProvenanceSigner {
55    /// Build from the node's Ed25519 mesh signing key. The ML-DSA-65 half is
56    /// derived deterministically via [`crate::node_identity::derive_mesh_mldsa_key`]
57    /// (#157/#328), so the signer matches the `#mesh-pq` key peers anchor.
58    pub fn from_ed25519(ed_sk: ed25519_dalek::SigningKey) -> Self {
59        let pq_sk = crate::node_identity::derive_mesh_mldsa_key(&ed_sk);
60        Self { ed_sk, pq_sk }
61    }
62
63    /// Build from an explicit Ed25519 + ML-DSA-65 keypair.
64    pub fn new(ed_sk: ed25519_dalek::SigningKey, pq_sk: MlDsaSigningKey) -> Self {
65        Self { ed_sk, pq_sk }
66    }
67
68    /// The host's signer kid = its Ed25519 verifying-key bytes (matches the COSE
69    /// inner kid and the mesh-roster key).
70    pub fn signer_kid(&self) -> [u8; 32] {
71        self.ed_sk.verifying_key().to_bytes()
72    }
73
74    /// Sign the canonical `signed_region` with the hybrid COSE composite (#321),
75    /// returning `(signer_kid, cose_sig_bytes)` for the `provenance` field.
76    pub fn sign(&self, signed_region: &[u8]) -> Result<(Vec<u8>, Vec<u8>)> {
77        let aad = provenance_external_aad();
78        let sig = sign_composite(&self.ed_sk, Some(&self.pq_sk), signed_region, &aad)?;
79        Ok((self.signer_kid().to_vec(), sig))
80    }
81}
82
83/// Verify a StreamBlock's provenance (#321), fail-closed.
84///
85/// `roster` resolves the signer's anchored ML-DSA-65 key (the mesh
86/// `KeyedPqTrustStore`); `is_enrolled` confirms the signer's Ed25519 key is a
87/// known/enrolled mesh peer. Rejects on missing/unknown/invalid signer.
88///
89/// `signed_region` is the provenance-cleared block encoding (see module docs);
90/// `signer_kid`/`sig` come from the wire `StreamBlock.provenance` field.
91pub fn verify_provenance(
92    signer_kid: &[u8],
93    sig: &[u8],
94    signed_region: &[u8],
95    roster: &dyn PqTrustStore,
96    is_enrolled: &dyn Fn(&[u8; 32]) -> bool,
97) -> Result<()> {
98    if sig.is_empty() {
99        anyhow::bail!("stream provenance: missing signature (fail-closed)");
100    }
101    let kid: [u8; 32] = signer_kid
102        .try_into()
103        .map_err(|_| anyhow!("stream provenance: signer kid must be 32 bytes (Ed25519)"))?;
104
105    // The signer must be an enrolled mesh peer — never accept an unknown signer.
106    if !is_enrolled(&kid) {
107        anyhow::bail!("stream provenance: signer is not an enrolled mesh peer (unknown signer)");
108    }
109
110    let ed_vk = ed25519_dalek::VerifyingKey::from_bytes(&kid)
111        .map_err(|e| anyhow!("stream provenance: invalid Ed25519 signer key: {e}"))?;
112
113    // The anchored ML-DSA-65 key for this signer (per-host #mesh-pq). Required:
114    // verify under the Hybrid policy (fail-closed on a stripped/absent PQ layer).
115    let pq_vk: MlDsaVerifyingKey = roster
116        .ml_dsa_key_for(&kid)
117        .ok_or_else(|| anyhow!("stream provenance: no anchored ML-DSA-65 key for signer"))?;
118
119    let aad = provenance_external_aad();
120    verify_composite(
121        sig,
122        &ed_vk,
123        Some(&pq_vk),
124        signed_region,
125        &aad,
126        /* require_pq */ true,
127    )
128    .map_err(|e| anyhow!("stream provenance: signature verification failed: {e}"))?;
129    Ok(())
130}
131
132/// Reconstruct the canonical signed region from a parsed (wire) StreamBlock by
133/// re-encoding it with the `provenance` field cleared (#321). Byte-identical to
134/// the publisher's pre-provenance [`crate::streaming::encode_stream_block`].
135pub fn signed_region_from_block(block: &streaming_capnp::stream_block::Reader) -> Result<Vec<u8>> {
136    use streaming_capnp::stream_payload::Which;
137
138    let prev_mac = block.get_prev_mac()?;
139    let sequence_number = block.get_sequence_number();
140    let epoch = block.get_epoch();
141
142    let payloads_reader = block.get_payloads()?;
143    let mut payloads: Vec<StreamPayloadData> = Vec::with_capacity(payloads_reader.len() as usize);
144    for i in 0..payloads_reader.len() {
145        let p = payloads_reader.get(i);
146        let data = match p.which()? {
147            Which::Data(d) => StreamPayloadData::Data(d?.to_vec()),
148            Which::Complete(d) => StreamPayloadData::Complete(d?.to_vec()),
149            Which::Error(e) => {
150                let _ = e?; // error frames are not provenance-signed in practice
151                StreamPayloadData::Error(String::new())
152            }
153            Which::Heartbeat(()) => continue,
154            Which::Tagged(t) => {
155                let t = t?;
156                StreamPayloadData::Tagged {
157                    tag: t.get_tag()?.to_vec(),
158                    payload: t.get_payload()?.to_vec(),
159                    nonce: t.get_nonce()?.to_vec(),
160                    key_commitment: t.get_key_commitment()?.to_vec(),
161                }
162            }
163        };
164        payloads.push(data);
165    }
166
167    crate::streaming::encode_stream_block(prev_mac, sequence_number, epoch, &payloads)
168}
169
170#[cfg(test)]
171#[allow(clippy::unwrap_used, clippy::expect_used)]
172mod tests {
173    use super::*;
174    use crate::envelope::KeyedPqTrustStore;
175    use ed25519_dalek::SigningKey;
176
177    fn signer() -> ProvenanceSigner {
178        ProvenanceSigner::from_ed25519(SigningKey::from_bytes(&[7u8; 32]))
179    }
180
181    /// Build a roster anchoring `signer`'s ML-DSA key, plus an enrolled-set closure.
182    fn roster_for(signer: &ProvenanceSigner) -> (KeyedPqTrustStore, [u8; 32]) {
183        use ml_dsa::Keypair;
184        let kid = signer.signer_kid();
185        let mut store = KeyedPqTrustStore::new();
186        let pq_vk = signer.pq_sk.verifying_key();
187        store.bind(kid, &pq_vk);
188        (store, kid)
189    }
190
191    #[test]
192    fn sign_verify_roundtrip() {
193        let s = signer();
194        let (store, kid) = roster_for(&s);
195        let region = b"canonical signed region bytes";
196        let (signer_kid, sig) = s.sign(region).unwrap();
197        assert_eq!(signer_kid, kid.to_vec());
198
199        let enrolled = |k: &[u8; 32]| *k == kid;
200        verify_provenance(&signer_kid, &sig, region, &store, &enrolled)
201            .expect("valid provenance must verify");
202    }
203
204    #[test]
205    fn tampered_region_rejected() {
206        let s = signer();
207        let (store, kid) = roster_for(&s);
208        let (signer_kid, sig) = s.sign(b"original region").unwrap();
209        let enrolled = |k: &[u8; 32]| *k == kid;
210        let res = verify_provenance(&signer_kid, &sig, b"tampered region", &store, &enrolled);
211        assert!(res.is_err(), "tampered region must fail provenance verify");
212    }
213
214    #[test]
215    fn wrong_signer_rejected() {
216        // A different host signs; verifier anchors the EXPECTED host. The kid won't
217        // resolve in the roster / enrolled set → rejected.
218        let real = signer();
219        let attacker = ProvenanceSigner::from_ed25519(SigningKey::from_bytes(&[9u8; 32]));
220        let (store, real_kid) = roster_for(&real);
221        let region = b"region";
222        let (att_kid, att_sig) = attacker.sign(region).unwrap();
223
224        // Only the real host is enrolled; the attacker's kid is unknown.
225        let enrolled = |k: &[u8; 32]| *k == real_kid;
226        let res = verify_provenance(&att_kid, &att_sig, region, &store, &enrolled);
227        assert!(res.is_err(), "wrong (unenrolled) signer must be rejected");
228    }
229
230    #[test]
231    fn unknown_signer_rejected() {
232        // Signer is enrolled in the set but has NO anchored ML-DSA key (roster miss).
233        let s = signer();
234        let kid = s.signer_kid();
235        let region = b"region";
236        let (signer_kid, sig) = s.sign(region).unwrap();
237        let empty_store = KeyedPqTrustStore::new();
238        let enrolled = |k: &[u8; 32]| *k == kid;
239        let res = verify_provenance(&signer_kid, &sig, region, &empty_store, &enrolled);
240        assert!(
241            res.is_err(),
242            "signer without an anchored PQ key must be rejected"
243        );
244    }
245
246    #[test]
247    fn empty_signature_rejected() {
248        let s = signer();
249        let (store, kid) = roster_for(&s);
250        let enrolled = |k: &[u8; 32]| *k == kid;
251        let res = verify_provenance(kid.as_ref(), &[], b"region", &store, &enrolled);
252        assert!(res.is_err(), "empty signature must fail closed");
253    }
254}