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#[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
47pub 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 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 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 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 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 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 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 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 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 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}