Skip to main content

second_brain_core/keys/
record.rs

1use anyhow::{Context, Result, anyhow, ensure};
2use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
3use serde::{Deserialize, Serialize};
4
5const RECORD_DOMAIN: &[u8] = b"second-brain device record v1";
6
7#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
8pub struct DeviceRecord {
9    pub machine_id: String,
10    pub identity_tag: String,
11    pub version: u64,
12    pub name: String,
13    pub age_recipient: String,
14    pub ssh_public_key: String,
15    #[serde(with = "hex_array")]
16    pub signing_public_key: [u8; 32],
17    pub recovery_fingerprints: Vec<String>,
18    pub ssh_login: Option<String>,
19    pub ssh_port: Option<u16>,
20    pub ssh_host_key: Option<String>,
21}
22
23#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
24pub struct RecordSignature {
25    pub signer: String,
26    #[serde(with = "hex_array")]
27    pub signature: [u8; 64],
28}
29
30#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
31#[serde(try_from = "UncheckedSignedRecord")]
32pub struct SignedRecord {
33    pub record: DeviceRecord,
34    pub signatures: Vec<RecordSignature>,
35}
36
37#[derive(Deserialize)]
38struct UncheckedSignedRecord {
39    record: DeviceRecord,
40    signatures: Vec<RecordSignature>,
41}
42
43impl TryFrom<UncheckedSignedRecord> for SignedRecord {
44    type Error = anyhow::Error;
45
46    fn try_from(unchecked: UncheckedSignedRecord) -> Result<Self> {
47        let mut signers: Vec<&str> = unchecked
48            .signatures
49            .iter()
50            .map(|s| s.signer.as_str())
51            .collect();
52        signers.sort_unstable();
53        ensure!(
54            signers.windows(2).all(|pair| pair[0] != pair[1]),
55            "device record for machine {} carries more than one signature by one signer",
56            unchecked.record.machine_id
57        );
58        Ok(Self {
59            record: unchecked.record,
60            signatures: unchecked.signatures,
61        })
62    }
63}
64
65impl DeviceRecord {
66    pub fn signing_bytes(&self) -> Vec<u8> {
67        let mut out = Vec::with_capacity(256);
68        out.extend_from_slice(RECORD_DOMAIN);
69        put_str(&mut out, &self.machine_id);
70        put_str(&mut out, &self.identity_tag);
71        out.extend_from_slice(&self.version.to_be_bytes());
72        put_str(&mut out, &self.name);
73        put_str(&mut out, &self.age_recipient);
74        put_str(&mut out, &self.ssh_public_key);
75        out.extend_from_slice(&self.signing_public_key);
76        put_len(&mut out, self.recovery_fingerprints.len());
77        for fingerprint in &self.recovery_fingerprints {
78            put_str(&mut out, fingerprint);
79        }
80        match &self.ssh_login {
81            None => out.push(0),
82            Some(login) => {
83                out.push(1);
84                put_str(&mut out, login);
85            }
86        }
87        match self.ssh_port {
88            None => out.push(0),
89            Some(port) => {
90                out.push(1);
91                out.extend_from_slice(&port.to_be_bytes());
92            }
93        }
94        match &self.ssh_host_key {
95            None => out.push(0),
96            Some(host_key) => {
97                out.push(1);
98                put_str(&mut out, host_key);
99            }
100        }
101        out
102    }
103
104    pub fn signing_public_key(&self) -> Result<VerifyingKey> {
105        VerifyingKey::from_bytes(&self.signing_public_key).map_err(|_| {
106            anyhow!(
107                "device record for machine {} has an invalid signing public key",
108                self.machine_id
109            )
110        })
111    }
112
113    pub fn sign(self, signer: &str, key: &SigningKey) -> SignedRecord {
114        let signature = sign_record(&self, signer, key);
115        SignedRecord {
116            record: self,
117            signatures: vec![signature],
118        }
119    }
120
121    fn signed_message(&self, signer: &str) -> Vec<u8> {
122        let mut message = self.signing_bytes();
123        put_str(&mut message, signer);
124        message
125    }
126}
127
128impl SignedRecord {
129    pub fn countersign(&mut self, signer: &str, key: &SigningKey) {
130        let signature = sign_record(&self.record, signer, key);
131        match self.signatures.iter_mut().find(|s| s.signer == signer) {
132            Some(existing) => *existing = signature,
133            None => self.signatures.push(signature),
134        }
135    }
136
137    pub fn verify_by(&self, signer: &str, key: &VerifyingKey) -> Result<()> {
138        let found = self
139            .signatures
140            .iter()
141            .find(|s| s.signer == signer)
142            .ok_or_else(|| {
143                anyhow!(
144                    "device record for machine {} has no signature by {signer}",
145                    self.record.machine_id
146                )
147            })?;
148        let message = self.record.signed_message(signer);
149        key.verify_strict(&message, &Signature::from_bytes(&found.signature))
150            .map_err(|_| {
151                anyhow!(
152                    "signature by {signer} on the device record for machine {} does not verify",
153                    self.record.machine_id
154                )
155            })
156    }
157
158    pub fn verify_self(&self) -> Result<()> {
159        let key = self.record.signing_public_key()?;
160        self.verify_by(&self.record.machine_id, &key)
161    }
162
163    pub fn to_json(&self) -> Result<String> {
164        serde_json::to_string(self).context("encoding a signed device record")
165    }
166
167    pub fn from_json(text: &str) -> Result<Self> {
168        serde_json::from_str(text).context("decoding a signed device record")
169    }
170}
171
172pub fn check_update(current: &SignedRecord, incoming: &SignedRecord) -> Result<()> {
173    let stored = &current.record;
174    let update = &incoming.record;
175    ensure!(
176        update.machine_id == stored.machine_id,
177        "device record update names machine {} but the stored record is for machine {}",
178        update.machine_id,
179        stored.machine_id
180    );
181    ensure!(
182        update.identity_tag == stored.identity_tag,
183        "device record update for machine {} names identity {} but the stored record has identity {}",
184        update.machine_id,
185        update.identity_tag,
186        stored.identity_tag
187    );
188    ensure!(
189        update.version > stored.version,
190        "device record update for machine {} has version {}, not above the stored version {}",
191        update.machine_id,
192        update.version,
193        stored.version
194    );
195    ensure!(
196        update.signing_public_key == stored.signing_public_key,
197        "device record update for machine {} changes its signing key; a device rekeys under a new machine id",
198        update.machine_id
199    );
200    let key = stored.signing_public_key()?;
201    incoming
202        .verify_by(&stored.machine_id, &key)
203        .with_context(|| {
204            format!(
205                "device record update for machine {} is not signed by its current signing key",
206                stored.machine_id
207            )
208        })
209}
210
211fn sign_record(record: &DeviceRecord, signer: &str, key: &SigningKey) -> RecordSignature {
212    let signature: Signature = key.sign(&record.signed_message(signer));
213    RecordSignature {
214        signer: signer.to_string(),
215        signature: signature.to_bytes(),
216    }
217}
218
219pub(super) fn put_len(out: &mut Vec<u8>, len: usize) {
220    out.extend_from_slice(&u32::try_from(len).unwrap_or(u32::MAX).to_be_bytes());
221}
222
223pub(super) fn put_str(out: &mut Vec<u8>, text: &str) {
224    put_len(out, text.len());
225    out.extend_from_slice(text.as_bytes());
226}
227
228pub(super) mod hex_array {
229    use serde::de::Error;
230    use serde::{Deserialize, Deserializer, Serializer};
231
232    pub fn serialize<S: Serializer, const N: usize>(
233        bytes: &[u8; N],
234        serializer: S,
235    ) -> Result<S::Ok, S::Error> {
236        serializer.serialize_str(&crate::keys::hex(bytes))
237    }
238
239    pub fn deserialize<'de, D: Deserializer<'de>, const N: usize>(
240        deserializer: D,
241    ) -> Result<[u8; N], D::Error> {
242        let text = String::deserialize(deserializer)?;
243        crate::keys::unhex(&text)
244            .ok_or_else(|| D::Error::custom(format!("expected {N} bytes as hex")))
245    }
246}
247
248#[cfg(test)]
249mod tests {
250    use super::*;
251
252    fn key(seed: u8) -> SigningKey {
253        SigningKey::from_bytes(&[seed; 32])
254    }
255
256    fn record(signing: &SigningKey) -> DeviceRecord {
257        DeviceRecord {
258            machine_id: "machine-a".to_string(),
259            identity_tag: "identity-1".to_string(),
260            version: 3,
261            name: "laptop".to_string(),
262            age_recipient: "age1recipient".to_string(),
263            ssh_public_key: "ssh-ed25519 AAAAexample".to_string(),
264            signing_public_key: signing.verifying_key().to_bytes(),
265            recovery_fingerprints: vec!["fp-one".to_string(), "fp-two".to_string()],
266            ssh_login: Some("user".to_string()),
267            ssh_port: Some(22),
268            ssh_host_key: Some("ssh-ed25519 AAAAhost".to_string()),
269        }
270    }
271
272    fn self_signed(signing: &SigningKey) -> SignedRecord {
273        record(signing).sign("machine-a", signing)
274    }
275
276    fn message(result: Result<()>) -> String {
277        format!("{:#}", result.expect_err("expected an error"))
278    }
279
280    #[test]
281    fn a_self_signed_record_verifies() {
282        let signing = key(1);
283        let signed = self_signed(&signing);
284        signed.verify_self().unwrap();
285        signed
286            .verify_by("machine-a", &signing.verifying_key())
287            .unwrap();
288    }
289
290    #[test]
291    fn tampering_any_field_breaks_the_signature() {
292        let cases: [(&str, fn(&mut DeviceRecord)); 16] = [
293            ("machine id", |r: &mut DeviceRecord| {
294                r.machine_id = "machine-b".into()
295            }),
296            ("identity tag", |r: &mut DeviceRecord| {
297                r.identity_tag = "identity-2".into()
298            }),
299            ("version", |r: &mut DeviceRecord| r.version += 1),
300            ("name", |r: &mut DeviceRecord| r.name = "desktop".into()),
301            ("age recipient", |r: &mut DeviceRecord| {
302                r.age_recipient = "age1other".into()
303            }),
304            ("ssh key", |r: &mut DeviceRecord| {
305                r.ssh_public_key = "ssh-ed25519 BBBB".into()
306            }),
307            ("signing key", |r: &mut DeviceRecord| {
308                r.signing_public_key = key(2).verifying_key().to_bytes()
309            }),
310            ("recovery fingerprint changed", |r: &mut DeviceRecord| {
311                r.recovery_fingerprints[1] = "fp-three".into()
312            }),
313            ("recovery fingerprint added", |r: &mut DeviceRecord| {
314                r.recovery_fingerprints.push("fp-three".into())
315            }),
316            ("recovery fingerprints reordered", |r: &mut DeviceRecord| {
317                r.recovery_fingerprints.reverse()
318            }),
319            ("ssh login changed", |r: &mut DeviceRecord| {
320                r.ssh_login = Some("root".into())
321            }),
322            ("ssh login removed", |r: &mut DeviceRecord| {
323                r.ssh_login = None
324            }),
325            ("ssh port changed", |r: &mut DeviceRecord| {
326                r.ssh_port = Some(2222)
327            }),
328            ("ssh port removed", |r: &mut DeviceRecord| r.ssh_port = None),
329            ("ssh host key changed", |r: &mut DeviceRecord| {
330                r.ssh_host_key = Some("ssh-ed25519 AAAAother".into())
331            }),
332            ("ssh host key removed", |r: &mut DeviceRecord| {
333                r.ssh_host_key = None
334            }),
335        ];
336        let signing = key(1);
337        for (field, tamper) in cases {
338            let mut signed = self_signed(&signing);
339            tamper(&mut signed.record);
340            assert!(
341                signed
342                    .verify_by("machine-a", &signing.verifying_key())
343                    .is_err(),
344                "tampered {field} still verifies"
345            );
346        }
347    }
348
349    #[test]
350    fn signing_bytes_keep_field_boundaries() {
351        let signing = key(1);
352        let mut split = record(&signing);
353        split.recovery_fingerprints = vec!["ab".into(), "c".into()];
354        let mut shifted = record(&signing);
355        shifted.recovery_fingerprints = vec!["a".into(), "bc".into()];
356        assert_ne!(split.signing_bytes(), shifted.signing_bytes());
357
358        let mut name_long = record(&signing);
359        name_long.name = "laptopx".into();
360        name_long.age_recipient = "y".into();
361        let mut recipient_long = record(&signing);
362        recipient_long.name = "laptop".into();
363        recipient_long.age_recipient = "xy".into();
364        assert_ne!(name_long.signing_bytes(), recipient_long.signing_bytes());
365
366        assert!(split.signing_bytes().starts_with(RECORD_DOMAIN));
367    }
368
369    #[test]
370    fn a_signature_moved_to_another_signer_fails() {
371        let signing = key(1);
372        let mut signed = self_signed(&signing);
373        signed.signatures[0].signer = "machine-b".into();
374        let err = message(signed.verify_by("machine-b", &signing.verifying_key()));
375        assert!(err.contains("does not verify"), "{err}");
376    }
377
378    #[test]
379    fn verify_by_the_wrong_key_fails() {
380        let signed = self_signed(&key(1));
381        let err = message(signed.verify_by("machine-a", &key(2).verifying_key()));
382        assert!(err.contains("does not verify"), "{err}");
383    }
384
385    #[test]
386    fn verify_by_a_signer_with_no_signature_fails() {
387        let signed = self_signed(&key(1));
388        let err = message(signed.verify_by("machine-b", &key(1).verifying_key()));
389        assert!(err.contains("no signature by machine-b"), "{err}");
390    }
391
392    #[test]
393    fn countersign_adds_a_second_signature_and_replaces_its_own() {
394        let own = key(1);
395        let peer = key(3);
396        let mut signed = self_signed(&own);
397        signed.countersign("machine-b", &peer);
398        assert_eq!(signed.signatures.len(), 2);
399        signed.verify_self().unwrap();
400        signed
401            .verify_by("machine-b", &peer.verifying_key())
402            .unwrap();
403
404        let replacement = key(4);
405        signed.countersign("machine-b", &replacement);
406        assert_eq!(signed.signatures.len(), 2);
407        signed
408            .verify_by("machine-b", &replacement.verifying_key())
409            .unwrap();
410        assert!(
411            signed
412                .verify_by("machine-b", &peer.verifying_key())
413                .is_err()
414        );
415        signed.verify_self().unwrap();
416    }
417
418    #[test]
419    fn json_round_trip_keeps_verification() {
420        let own = key(1);
421        let mut signed = self_signed(&own);
422        signed.countersign("machine-b", &key(3));
423        let text = signed.to_json().unwrap();
424        let hex_key: String = own
425            .verifying_key()
426            .to_bytes()
427            .iter()
428            .map(|b| format!("{b:02x}"))
429            .collect();
430        assert!(text.contains(&hex_key), "{text}");
431
432        let back = SignedRecord::from_json(&text).unwrap();
433        assert_eq!(back, signed);
434        back.verify_self().unwrap();
435        back.verify_by("machine-b", &key(3).verifying_key())
436            .unwrap();
437    }
438
439    #[test]
440    fn json_with_a_malformed_hex_field_is_rejected() {
441        let text = self_signed(&key(1)).to_json().unwrap();
442        let value: serde_json::Value = serde_json::from_str(&text).unwrap();
443        let good = value["record"]["signing_public_key"]
444            .as_str()
445            .unwrap()
446            .to_string();
447        let bads = vec![
448            good[2..].to_string(),
449            "zz".to_string(),
450            format!("{good}00"),
451            format!("zz{}", &good[2..]),
452        ];
453        for bad in bads {
454            let mut edited = value.clone();
455            edited["record"]["signing_public_key"] = serde_json::Value::from(bad.clone());
456            assert!(
457                SignedRecord::from_json(&edited.to_string()).is_err(),
458                "accepted {bad}"
459            );
460        }
461    }
462
463    fn update(signing_public: &SigningKey, version: u64, signer: &SigningKey) -> SignedRecord {
464        let mut next = record(signing_public);
465        next.version = version;
466        next.name = "renamed laptop".into();
467        next.sign("machine-a", signer)
468    }
469
470    #[test]
471    fn check_update_accepts_a_higher_self_signed_version() {
472        let own = key(1);
473        let current = self_signed(&own);
474        check_update(&current, &update(&own, 4, &own)).unwrap();
475    }
476
477    #[test]
478    fn check_update_rejects_an_equal_or_lower_version() {
479        let own = key(1);
480        let current = self_signed(&own);
481        for version in [3, 2, 0] {
482            let err = message(check_update(&current, &update(&own, version, &own)));
483            assert!(err.contains("not above the stored version"), "{err}");
484        }
485    }
486
487    #[test]
488    fn check_update_rejects_another_machine() {
489        let own = key(1);
490        let other = key(5);
491        let current = self_signed(&own);
492        let mut foreign = record(&other);
493        foreign.machine_id = "machine-b".into();
494        foreign.version = 9;
495        let incoming = foreign.sign("machine-b", &other);
496        let err = message(check_update(&current, &incoming));
497        assert!(
498            err.contains("stored record is for machine machine-a"),
499            "{err}"
500        );
501    }
502
503    #[test]
504    fn check_update_rejects_another_identity() {
505        let own = key(1);
506        let current = self_signed(&own);
507        let mut moved = record(&own);
508        moved.identity_tag = "identity-2".into();
509        moved.version = 4;
510        let err = message(check_update(&current, &moved.sign("machine-a", &own)));
511        assert!(err.contains("names identity identity-2"), "{err}");
512    }
513
514    #[test]
515    fn a_signing_key_never_changes_for_a_machine() {
516        let old = key(1);
517        let new = key(2);
518        let current = self_signed(&old);
519        for signer in [&old, &new] {
520            let rotated = update(&new, 4, signer);
521            let err = message(check_update(&current, &rotated));
522            assert!(err.contains("changes its signing key"), "{err}");
523        }
524    }
525
526    #[test]
527    fn duplicate_signers_are_rejected_on_decode() {
528        let mut signed = self_signed(&key(1));
529        signed.signatures.push(signed.signatures[0].clone());
530        let text = serde_json::to_string(&signed).unwrap();
531        let err = format!("{:#}", SignedRecord::from_json(&text).unwrap_err());
532        assert!(err.contains("more than one signature"), "{err}");
533        let err = serde_json::from_str::<SignedRecord>(&text).unwrap_err();
534        assert!(err.to_string().contains("more than one signature"), "{err}");
535    }
536
537    #[test]
538    fn an_invalid_signing_public_key_is_an_error() {
539        let mut broken = record(&key(1));
540        let mut off_curve = [0u8; 32];
541        off_curve[0] = 2;
542        broken.signing_public_key = off_curve;
543        let err = format!("{:#}", broken.signing_public_key().unwrap_err());
544        assert!(err.contains("invalid signing public key"), "{err}");
545    }
546}