Skip to main content

second_brain_core/keys/
retirement.rs

1use std::collections::BTreeSet;
2
3use anyhow::{Context, Result, anyhow, ensure};
4use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
5use rusqlite::{Connection, OptionalExtension, params};
6use serde::{Deserialize, Serialize};
7
8use super::identity::{Epoch, IdentityTag};
9use super::record::put_str;
10use super::recovery_fingerprint;
11use super::revocation::EpochCause;
12use super::tables::query_envelopes;
13use crate::sqlite_store::SqliteStore;
14
15const RETIREMENT_DOMAIN: &[u8] = b"second-brain recovery retirement v1";
16const RETIRED_PREFIX: &str = "recovery_retired:";
17const RETIRED_END: &str = "recovery_retired;";
18const FINGERPRINT_LEN: usize = 16;
19
20/// "The recovery phrase with `fingerprint` is retired", signed by `retirer`.
21/// No device wraps an epoch to it once it holds this, and the first
22/// retirement stored for a fingerprint stays.
23#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
24pub struct Retirement {
25    pub identity_tag: String,
26    pub retirer: String,
27    pub fingerprint: String,
28    pub created_at_micros: i64,
29}
30
31#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
32pub struct SignedRetirement {
33    pub retirement: Retirement,
34    #[serde(with = "super::record::hex_array")]
35    pub signature: [u8; 64],
36}
37
38#[derive(Serialize, Deserialize)]
39struct StoredRetirement {
40    identity_tag: String,
41    fingerprint: String,
42    signed: Option<SignedRetirement>,
43    #[serde(default)]
44    rotates: bool,
45}
46
47/// True for the 16 lowercase hex characters `recovery_fingerprint` makes.
48pub fn valid_fingerprint(text: &str) -> bool {
49    text.len() == FINGERPRINT_LEN
50        && text
51            .bytes()
52            .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
53}
54
55impl Retirement {
56    pub fn signing_bytes(&self) -> Vec<u8> {
57        let mut out = Vec::with_capacity(96);
58        out.extend_from_slice(RETIREMENT_DOMAIN);
59        put_str(&mut out, &self.identity_tag);
60        put_str(&mut out, &self.retirer);
61        put_str(&mut out, &self.fingerprint);
62        out.extend_from_slice(&self.created_at_micros.to_be_bytes());
63        out
64    }
65
66    pub fn sign(self, key: &SigningKey) -> SignedRetirement {
67        let signature: Signature = key.sign(&self.signing_bytes());
68        SignedRetirement {
69            retirement: self,
70            signature: signature.to_bytes(),
71        }
72    }
73}
74
75impl SignedRetirement {
76    pub fn verify(&self, retirer_key: &VerifyingKey) -> Result<()> {
77        retirer_key
78            .verify_strict(
79                &self.retirement.signing_bytes(),
80                &Signature::from_bytes(&self.signature),
81            )
82            .map_err(|_| {
83                anyhow!(
84                    "the retirement of recovery phrase {} by {} does not verify under the \
85                     retirer's key",
86                    self.retirement.fingerprint,
87                    self.retirement.retirer
88                )
89            })
90    }
91}
92
93impl SqliteStore {
94    /// Keeps a retirement verified under its retirer's key. Which retirers
95    /// count is the caller's rule. A fingerprint so far retired only by an
96    /// epoch's cause gains the signed record; otherwise the first stored
97    /// under its identity stays and this returns false.
98    pub fn put_retirement(
99        &self,
100        signed: &SignedRetirement,
101        retirer_key: &VerifyingKey,
102    ) -> Result<bool> {
103        signed.verify(retirer_key)?;
104        let retirement = &signed.retirement;
105        ensure!(
106            valid_fingerprint(&retirement.fingerprint),
107            "{:?} is not a recovery phrase fingerprint",
108            retirement.fingerprint
109        );
110        let key = retired_key(&retirement.identity_tag, &retirement.fingerprint);
111        self.with_txn(|tx| {
112            let mut stored = match read_retirement(tx, &key)? {
113                Some(stored) if stored.signed.is_some() => return Ok(false),
114                Some(stored) => stored,
115                None => StoredRetirement {
116                    identity_tag: retirement.identity_tag.clone(),
117                    fingerprint: retirement.fingerprint.clone(),
118                    signed: None,
119                    rotates: false,
120                },
121            };
122            stored.signed = Some(signed.clone());
123            write_retirement(tx, &key, &stored)?;
124            Ok(true)
125        })
126    }
127
128    /// Records each well-formed fingerprint an epoch cause of `tag` names
129    /// that no retirement here covers yet, unsigned: the epoch was taken, so
130    /// the phrase must open nothing here even when the signed retirement
131    /// cannot be verified. Returns the fingerprints recorded.
132    pub fn note_named_retirements(&self, tag: &IdentityTag) -> Result<Vec<String>> {
133        let named: BTreeSet<String> = self
134            .key_epochs(tag)?
135            .into_iter()
136            .map(|stored| EpochCause::from_stored(stored.cause.as_deref()))
137            .collect::<Result<Vec<_>>>()?
138            .into_iter()
139            .flat_map(|cause| cause.retirements)
140            .filter(|fingerprint| valid_fingerprint(fingerprint))
141            .collect();
142        self.with_txn(|tx| {
143            let mut noted = Vec::new();
144            for fingerprint in named {
145                let key = retired_key(tag.as_str(), &fingerprint);
146                if read_retirement(tx, &key)?.is_some() {
147                    continue;
148                }
149                let stored = StoredRetirement {
150                    identity_tag: tag.as_str().to_string(),
151                    fingerprint: fingerprint.clone(),
152                    signed: None,
153                    rotates: false,
154                };
155                write_retirement(tx, &key, &stored)?;
156                noted.push(fingerprint);
157            }
158            Ok(noted)
159        })
160    }
161
162    /// The signed retirements stored under `tag`, by fingerprint.
163    pub fn retirements(&self, tag: &IdentityTag) -> Result<Vec<SignedRetirement>> {
164        Ok(self
165            .retired_under(tag)?
166            .into_iter()
167            .filter_map(|(_, signed)| signed)
168            .collect())
169    }
170
171    /// Every fingerprint retired under `tag`, with its signed retirement
172    /// when one was verified here; None for one only an epoch's cause named.
173    pub fn retired_under(
174        &self,
175        tag: &IdentityTag,
176    ) -> Result<Vec<(String, Option<SignedRetirement>)>> {
177        Ok(read_retirements(&self.reader())?
178            .into_iter()
179            .filter(|stored| stored.identity_tag == tag.as_str())
180            .map(|stored| (stored.fingerprint, stored.signed))
181            .collect())
182    }
183
184    /// Every retired fingerprint, under any identity.
185    pub fn retired_fingerprints(&self) -> Result<BTreeSet<String>> {
186        Ok(read_retirements(&self.reader())?
187            .into_iter()
188            .map(|stored| stored.fingerprint)
189            .collect())
190    }
191
192    /// The fingerprints retired under `tag` whose retirement calls for a new
193    /// epoch and a new store key.
194    pub fn rotating_retirements(&self, tag: &IdentityTag) -> Result<BTreeSet<String>> {
195        Ok(read_retirements(&self.reader())?
196            .into_iter()
197            .filter(|stored| stored.rotates && stored.identity_tag == tag.as_str())
198            .map(|stored| stored.fingerprint)
199            .collect())
200    }
201
202    /// Marks the retirements under `tag`, signed or named by a cause, whose
203    /// phrase a device of `tag` not revoked lists in its row, or this device
204    /// still wraps to, as calling for rotation; the mark is sticky. Made-up
205    /// fingerprints listed by no one are kept but rotate nothing. Run before
206    /// `delete_retired_envelopes`. Returns the newly marked fingerprints.
207    pub fn mark_rotating_retirements(&self, tag: &IdentityTag) -> Result<Vec<String>> {
208        let listed: BTreeSet<String> = self
209            .device_records()?
210            .into_iter()
211            .filter(|row| !row.revoked && row.current.record.identity_tag == tag.as_str())
212            .flat_map(|row| row.current.record.recovery_fingerprints)
213            .collect();
214        let trusted = self.recovery_fingerprints_wrapped_to()?;
215        self.with_txn(|tx| {
216            let mut newly = Vec::new();
217            for mut stored in read_retirements(tx)? {
218                if stored.rotates
219                    || stored.identity_tag != tag.as_str()
220                    || !(listed.contains(&stored.fingerprint)
221                        || trusted.contains(&stored.fingerprint))
222                {
223                    continue;
224                }
225                stored.rotates = true;
226                write_retirement(
227                    tx,
228                    &retired_key(&stored.identity_tag, &stored.fingerprint),
229                    &stored,
230                )?;
231                newly.push(stored.fingerprint);
232            }
233            Ok(newly)
234        })
235    }
236
237    /// The epochs of `tag` this store holds an envelope for to a retired
238    /// recovery recipient.
239    pub fn epochs_wrapped_to_retired(&self, tag: &IdentityTag) -> Result<Vec<Epoch>> {
240        let retired = self.retired_fingerprints()?;
241        let envelopes = query_envelopes(
242            &self.reader(),
243            "identity_tag = ?1 AND machine_id IS NULL",
244            params![tag.as_str()],
245        )?;
246        let mut epochs = Vec::new();
247        for envelope in envelopes {
248            if retired.contains(&recovery_fingerprint(&envelope.recipient))
249                && !epochs.contains(&envelope.epoch)
250            {
251                epochs.push(envelope.epoch);
252            }
253        }
254        Ok(epochs)
255    }
256
257    /// Deletes every envelope, under any identity, wrapped to a retired
258    /// recovery recipient. Returns how many went.
259    pub fn delete_retired_envelopes(&self) -> Result<usize> {
260        let retired = self.retired_fingerprints()?;
261        if retired.is_empty() {
262            return Ok(0);
263        }
264        let recipients = self.recovery_recipient_texts()?;
265        self.with_txn(|tx| {
266            let mut deleted = 0;
267            for recipient in recipients
268                .iter()
269                .filter(|r| retired.contains(&recovery_fingerprint(r)))
270            {
271                deleted += tx.execute(
272                    "DELETE FROM key_envelopes WHERE recipient = ?1 AND machine_id IS NULL",
273                    params![recipient],
274                )?;
275            }
276            Ok(deleted)
277        })
278    }
279
280    fn recovery_fingerprints_wrapped_to(&self) -> Result<BTreeSet<String>> {
281        Ok(self
282            .recovery_recipient_texts()?
283            .iter()
284            .map(|r| recovery_fingerprint(r))
285            .collect())
286    }
287
288    fn recovery_recipient_texts(&self) -> Result<Vec<String>> {
289        let conn = self.reader();
290        let mut stmt =
291            conn.prepare("SELECT DISTINCT recipient FROM key_envelopes WHERE machine_id IS NULL")?;
292        let texts = stmt
293            .query_map([], |r| r.get::<_, String>(0))?
294            .collect::<rusqlite::Result<Vec<_>>>()?;
295        Ok(texts)
296    }
297}
298
299fn retired_key(identity_tag: &str, fingerprint: &str) -> String {
300    format!("{RETIRED_PREFIX}{identity_tag}:{fingerprint}")
301}
302
303fn read_retirement(conn: &Connection, key: &str) -> Result<Option<StoredRetirement>> {
304    let value: Option<String> = conn
305        .query_row(
306            "SELECT value FROM index_meta WHERE key = ?1",
307            params![key],
308            |r| r.get(0),
309        )
310        .optional()?;
311    value
312        .map(|text| serde_json::from_str(&text).with_context(|| format!("decoding stored {key}")))
313        .transpose()
314}
315
316fn write_retirement(conn: &Connection, key: &str, stored: &StoredRetirement) -> Result<()> {
317    conn.execute(
318        "INSERT OR REPLACE INTO index_meta (key, value) VALUES (?1, ?2)",
319        params![key, serde_json::to_string(stored)?],
320    )?;
321    Ok(())
322}
323
324fn read_retirements(conn: &Connection) -> Result<Vec<StoredRetirement>> {
325    let mut stmt = conn
326        .prepare("SELECT key, value FROM index_meta WHERE key >= ?1 AND key < ?2 ORDER BY key")?;
327    let rows = stmt.query_map(params![RETIRED_PREFIX, RETIRED_END], |r| {
328        Ok((r.get::<_, String>(0)?, r.get::<_, String>(1)?))
329    })?;
330    let mut out = Vec::new();
331    for row in rows {
332        let (key, value) = row?;
333        out.push(serde_json::from_str(&value).with_context(|| format!("decoding stored {key}"))?);
334    }
335    Ok(out)
336}
337
338#[cfg(test)]
339mod tests {
340    use super::*;
341    use crate::keys::{DeviceKeys, IdentityKey, RecoveryPhrase, wrap, wrap_for_recovery};
342
343    const TAG: &str = "f-tag";
344
345    fn key(seed: u8) -> SigningKey {
346        SigningKey::from_bytes(&[seed; 32])
347    }
348
349    fn retirement(fingerprint: &str) -> Retirement {
350        Retirement {
351            identity_tag: TAG.to_string(),
352            retirer: "a".to_string(),
353            fingerprint: fingerprint.to_string(),
354            created_at_micros: 1_000,
355        }
356    }
357
358    fn tag() -> IdentityTag {
359        IdentityTag::from(TAG.to_string())
360    }
361
362    #[test]
363    fn a_signed_retirement_verifies_and_tampering_any_field_breaks_it() {
364        let signed = retirement("0123456789abcdef").sign(&key(1));
365        signed.verify(&key(1).verifying_key()).unwrap();
366        assert!(signed.verify(&key(2).verifying_key()).is_err());
367        let cases: [(&str, fn(&mut Retirement)); 4] = [
368            ("identity", |r| r.identity_tag = "f-other".into()),
369            ("retirer", |r| r.retirer = "b".into()),
370            ("fingerprint", |r| r.fingerprint = "0123456789abcdee".into()),
371            ("time", |r| r.created_at_micros += 1),
372        ];
373        for (field, tamper) in cases {
374            let mut edited = signed.clone();
375            tamper(&mut edited.retirement);
376            assert!(
377                edited.verify(&key(1).verifying_key()).is_err(),
378                "tampered {field} still verifies"
379            );
380        }
381        let text = serde_json::to_string(&signed).unwrap();
382        assert_eq!(
383            serde_json::from_str::<SignedRetirement>(&text).unwrap(),
384            signed
385        );
386    }
387
388    #[test]
389    fn only_a_fingerprint_shape_is_accepted() {
390        for (text, valid) in [
391            ("0123456789abcdef", true),
392            ("0123456789ABCDEF", false),
393            ("0123456789abcde", false),
394            ("0123456789abcdefa", false),
395            ("0123456789abcdeg", false),
396        ] {
397            assert_eq!(valid_fingerprint(text), valid, "{text}");
398        }
399        let store = SqliteStore::in_memory("a".to_string()).unwrap();
400        let bad = retirement("not-hex").sign(&key(1));
401        assert!(store.put_retirement(&bad, &key(1).verifying_key()).is_err());
402        assert!(store.retired_fingerprints().unwrap().is_empty());
403    }
404
405    #[test]
406    fn the_first_retirement_of_a_fingerprint_stays() {
407        let store = SqliteStore::in_memory("a".to_string()).unwrap();
408        let first = retirement("0123456789abcdef").sign(&key(1));
409        assert!(
410            store
411                .put_retirement(&first, &key(9).verifying_key())
412                .is_err()
413        );
414        assert!(
415            store
416                .put_retirement(&first, &key(1).verifying_key())
417                .unwrap()
418        );
419        let again = Retirement {
420            retirer: "b".to_string(),
421            ..retirement("0123456789abcdef")
422        }
423        .sign(&key(2));
424        assert!(
425            !store
426                .put_retirement(&again, &key(2).verifying_key())
427                .unwrap()
428        );
429        assert_eq!(store.retirements(&tag()).unwrap(), vec![first]);
430        assert!(
431            store
432                .retirements(&IdentityTag::from("f-other".to_string()))
433                .unwrap()
434                .is_empty()
435        );
436        assert_eq!(
437            store.retired_fingerprints().unwrap(),
438            BTreeSet::from(["0123456789abcdef".to_string()])
439        );
440    }
441
442    #[test]
443    fn a_fingerprint_a_cause_names_is_retired_unsigned_until_its_retirement_arrives() {
444        let store = SqliteStore::in_memory("a".to_string()).unwrap();
445        let tag = tag();
446        let identity = IdentityKey::generate().unwrap();
447        let epoch = Epoch {
448            number: 2,
449            key_id: identity.key_id(),
450        };
451        let named = "0123456789abcdef";
452        let cause = EpochCause {
453            retirements: [named.to_string(), "junk".to_string()].into(),
454            ..Default::default()
455        };
456        store
457            .put_key_epoch(&tag, &epoch, Some(&cause.to_json().unwrap()), 1)
458            .unwrap();
459        assert_eq!(store.note_named_retirements(&tag).unwrap(), vec![named]);
460        assert!(store.note_named_retirements(&tag).unwrap().is_empty());
461        assert_eq!(
462            store.retired_fingerprints().unwrap(),
463            BTreeSet::from([named.to_string()]),
464            "a malformed fingerprint is dropped"
465        );
466        assert_eq!(
467            store.retired_under(&tag).unwrap(),
468            vec![(named.to_string(), None)]
469        );
470        assert!(store.retirements(&tag).unwrap().is_empty());
471
472        let signed = retirement(named).sign(&key(1));
473        assert!(
474            store
475                .put_retirement(&signed, &key(1).verifying_key())
476                .unwrap()
477        );
478        assert_eq!(store.retirements(&tag).unwrap(), vec![signed]);
479    }
480
481    #[test]
482    fn a_fingerprint_retired_under_an_earlier_identity_is_retired_again_under_the_next() {
483        let store = SqliteStore::in_memory("a".to_string()).unwrap();
484        let earlier = Retirement {
485            identity_tag: "f-earlier".to_string(),
486            ..retirement("0123456789abcdef")
487        }
488        .sign(&key(1));
489        store
490            .put_retirement(&earlier, &key(1).verifying_key())
491            .unwrap();
492        let now = retirement("0123456789abcdef").sign(&key(1));
493        assert!(store.put_retirement(&now, &key(1).verifying_key()).unwrap());
494        assert_eq!(store.retirements(&tag()).unwrap(), vec![now]);
495    }
496
497    #[test]
498    fn a_retired_phrase_is_trusted_by_no_wrap_and_its_envelopes_go() {
499        let store = SqliteStore::in_memory("a".to_string()).unwrap();
500        let identity = IdentityKey::generate().unwrap();
501        let tag = tag();
502        let epoch = Epoch {
503            number: 1,
504            key_id: identity.key_id(),
505        };
506        let device = DeviceKeys::generate().unwrap();
507        store
508            .put_envelope(
509                &wrap(
510                    &identity,
511                    1,
512                    &tag,
513                    &device.age_recipient(),
514                    Some("a".into()),
515                )
516                .unwrap(),
517            )
518            .unwrap();
519        let (kept, retired) = (
520            RecoveryPhrase::generate().unwrap(),
521            RecoveryPhrase::generate().unwrap(),
522        );
523        let recipients = [kept.recipient().unwrap(), retired.recipient().unwrap()];
524        let held = [(epoch, &identity)];
525        assert_eq!(
526            wrap_for_recovery(&store, &tag, &held, &recipients).unwrap(),
527            2
528        );
529
530        let signed = retirement(&retired.fingerprint().unwrap()).sign(&key(1));
531        store
532            .put_retirement(&signed, &key(1).verifying_key())
533            .unwrap();
534        assert_eq!(store.epochs_wrapped_to_retired(&tag).unwrap(), vec![epoch]);
535        assert_eq!(
536            store.recovery_recipients(&tag).unwrap(),
537            vec![kept.recipient().unwrap()],
538            "a retired phrase leaves the trusted set at once"
539        );
540        assert_eq!(store.delete_retired_envelopes().unwrap(), 1);
541        assert!(store.epochs_wrapped_to_retired(&tag).unwrap().is_empty());
542        assert!(
543            store
544                .recovery_envelopes(&retired.recipient().unwrap())
545                .unwrap()
546                .is_empty()
547        );
548        assert_eq!(store.envelopes_for_machine("a").unwrap().len(), 1);
549
550        let second = Epoch {
551            number: 2,
552            key_id: identity.key_id(),
553        };
554        let held = [(second, &identity)];
555        assert_eq!(
556            wrap_for_recovery(&store, &tag, &held, &recipients).unwrap(),
557            1,
558            "only the phrase still trusted"
559        );
560        assert!(
561            store
562                .recovery_envelopes(&retired.recipient().unwrap())
563                .unwrap()
564                .is_empty()
565        );
566    }
567
568    #[test]
569    fn a_retirement_rotates_once_listed_or_trusted_and_stays_marked() {
570        let store = SqliteStore::in_memory("a".to_string()).unwrap();
571        let tag = tag();
572        let identity = IdentityKey::generate().unwrap();
573        let trusted = RecoveryPhrase::generate().unwrap();
574        let epoch = Epoch {
575            number: 1,
576            key_id: identity.key_id(),
577        };
578        wrap_for_recovery(
579            &store,
580            &tag,
581            &[(epoch, &identity)],
582            &[trusted.recipient().unwrap()],
583        )
584        .unwrap();
585        let made_up = "0123456789abcdef";
586        for fingerprint in [made_up.to_string(), trusted.fingerprint().unwrap()] {
587            store
588                .put_retirement(
589                    &retirement(&fingerprint).sign(&key(1)),
590                    &key(1).verifying_key(),
591                )
592                .unwrap();
593        }
594        assert_eq!(
595            store.mark_rotating_retirements(&tag).unwrap(),
596            vec![trusted.fingerprint().unwrap()]
597        );
598        store.delete_retired_envelopes().unwrap();
599        assert!(store.mark_rotating_retirements(&tag).unwrap().is_empty());
600        assert_eq!(
601            store.rotating_retirements(&tag).unwrap(),
602            BTreeSet::from([trusted.fingerprint().unwrap()]),
603            "the mark outlives the envelopes it was decided by"
604        );
605    }
606}