Skip to main content

second_brain_core/keys/
device.rs

1use std::fmt;
2use std::fs::{self, OpenOptions};
3use std::io::{ErrorKind, Write};
4use std::path::Path;
5
6use age::secrecy::ExposeSecret;
7use age::x25519::{Identity, Recipient};
8use anyhow::{Context, Result, anyhow, bail};
9use base64::Engine;
10use base64::prelude::BASE64_STANDARD;
11use ed25519_dalek::{SigningKey, VerifyingKey};
12use zeroize::Zeroizing;
13
14use super::{KeyGuard, hex};
15#[cfg(unix)]
16use crate::private_files::{PRIVATE_DIR_MODE, PRIVATE_FILE_MODE};
17
18pub const DEVICE_KEY_FILE: &str = "device.key";
19
20const SECRET_MAGIC: &[u8; 4] = b"SBDK";
21const SECRET_VERSION: u8 = 1;
22const SEED_LEN: usize = 32;
23const SSH_KEY_TYPE: &[u8] = b"ssh-ed25519";
24
25pub struct DeviceKeys {
26    age_identity: Identity,
27    ssh_key: SigningKey,
28    signing_key: SigningKey,
29}
30
31impl DeviceKeys {
32    pub fn generate() -> Result<Self> {
33        let ssh_seed = KeyGuard::<[u8; SEED_LEN]>::random()?;
34        let signing_seed = KeyGuard::<[u8; SEED_LEN]>::random()?;
35        Ok(Self {
36            age_identity: Identity::generate(),
37            ssh_key: SigningKey::from_bytes(ssh_seed.expose()),
38            signing_key: SigningKey::from_bytes(signing_seed.expose()),
39        })
40    }
41
42    pub fn age_identity(&self) -> &Identity {
43        &self.age_identity
44    }
45
46    pub fn age_recipient(&self) -> Recipient {
47        self.age_identity.to_public()
48    }
49
50    pub fn ssh_signing_key(&self) -> &SigningKey {
51        &self.ssh_key
52    }
53
54    pub fn ssh_public_key(&self) -> String {
55        ssh_public_line(&self.ssh_key.verifying_key())
56    }
57
58    pub fn signing_key(&self) -> &SigningKey {
59        &self.signing_key
60    }
61
62    pub fn verifying_key(&self) -> VerifyingKey {
63        self.signing_key.verifying_key()
64    }
65
66    pub fn to_secret_bytes(&self) -> Result<KeyGuard<Vec<u8>>> {
67        let age_secret = self.age_identity.to_string();
68        let age = age_secret.expose_secret().as_bytes();
69        let age_len = u16::try_from(age.len()).context("age identity string is too long")?;
70        let total = SECRET_MAGIC.len() + 1 + 2 + age.len() + 2 * SEED_LEN;
71        let mut out = KeyGuard::new(Vec::with_capacity(total));
72        let buf = out.expose_mut();
73        buf.extend_from_slice(SECRET_MAGIC);
74        buf.push(SECRET_VERSION);
75        buf.extend_from_slice(&age_len.to_be_bytes());
76        buf.extend_from_slice(age);
77        buf.extend_from_slice(self.ssh_key.as_bytes());
78        buf.extend_from_slice(self.signing_key.as_bytes());
79        Ok(out)
80    }
81
82    pub fn from_secret_bytes(bytes: &[u8]) -> Result<Self> {
83        let truncated = || anyhow!("device key blob is truncated");
84        let rest = bytes
85            .strip_prefix(SECRET_MAGIC)
86            .ok_or_else(|| anyhow!("not a device key blob"))?;
87        let (&version, rest) = rest.split_first().ok_or_else(truncated)?;
88        if version != SECRET_VERSION {
89            bail!("device key blob has unsupported version {version}");
90        }
91        let (age_len, rest) = rest.split_first_chunk::<2>().ok_or_else(truncated)?;
92        let age_len = usize::from(u16::from_be_bytes(*age_len));
93        if rest.len() != age_len + 2 * SEED_LEN {
94            bail!("device key blob has the wrong length");
95        }
96        let (age, seeds) = rest.split_at(age_len);
97        let (ssh_seed, signing_seed) = seeds
98            .split_first_chunk::<SEED_LEN>()
99            .ok_or_else(truncated)?;
100        let signing_seed: &[u8; SEED_LEN] = signing_seed.try_into().map_err(|_| truncated())?;
101        let age = std::str::from_utf8(age)
102            .map_err(|_| anyhow!("device key blob holds a non-UTF-8 age identity"))?;
103        let age_identity = age
104            .parse::<Identity>()
105            .map_err(|e| anyhow!("device key blob holds an invalid age identity: {e}"))?;
106        Ok(Self {
107            age_identity,
108            ssh_key: SigningKey::from_bytes(ssh_seed),
109            signing_key: SigningKey::from_bytes(signing_seed),
110        })
111    }
112
113    pub fn load(path: &Path) -> Result<Option<Self>> {
114        read_key_file(path)
115    }
116
117    /// Never replaces an existing file: an unreadable or corrupt key file is
118    /// an error, because minting new keys would silently change identity.
119    pub fn load_or_create(path: &Path) -> Result<(Self, bool)> {
120        if let Some(keys) = read_key_file(path)? {
121            return Ok((keys, false));
122        }
123        let keys = Self::generate()?;
124        let dir = parent_dir(path);
125        create_private_dir(dir)?;
126        let secret = keys.to_secret_bytes()?;
127        if install_if_absent(dir, path, secret.expose())? {
128            return Ok((keys, true));
129        }
130        let existing = read_key_file(path)?
131            .ok_or_else(|| anyhow!("device key file {} vanished after creation", path.display()))?;
132        Ok((existing, false))
133    }
134}
135
136impl fmt::Debug for DeviceKeys {
137    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
138        f.debug_struct("DeviceKeys")
139            .field("age_recipient", &self.age_recipient().to_string())
140            .field("ssh_public_key", &self.ssh_public_key())
141            .field("signing_public_key", &hex(self.verifying_key().as_bytes()))
142            .finish()
143    }
144}
145
146fn read_key_file(path: &Path) -> Result<Option<DeviceKeys>> {
147    let bytes = match fs::read(path) {
148        Ok(bytes) => Zeroizing::new(bytes),
149        Err(e) if e.kind() == ErrorKind::NotFound => return Ok(None),
150        Err(e) => {
151            return Err(e).with_context(|| format!("reading device key file {}", path.display()));
152        }
153    };
154    DeviceKeys::from_secret_bytes(&bytes)
155        .map(Some)
156        .with_context(|| format!("device key file {} is corrupt", path.display()))
157}
158
159fn parent_dir(path: &Path) -> &Path {
160    match path.parent() {
161        Some(dir) if !dir.as_os_str().is_empty() => dir,
162        _ => Path::new("."),
163    }
164}
165
166pub(super) fn create_private_dir(dir: &Path) -> Result<()> {
167    let mut builder = fs::DirBuilder::new();
168    builder.recursive(true);
169    #[cfg(unix)]
170    std::os::unix::fs::DirBuilderExt::mode(&mut builder, PRIVATE_DIR_MODE);
171    builder
172        .create(dir)
173        .with_context(|| format!("creating key directory {}", dir.display()))
174}
175
176pub(super) fn install_if_absent(dir: &Path, path: &Path, bytes: &[u8]) -> Result<bool> {
177    let name = path
178        .file_name()
179        .ok_or_else(|| anyhow!("device key path {} has no file name", path.display()))?;
180    let temp = dir.join(format!(
181        ".{}.{}.tmp",
182        name.to_string_lossy(),
183        uuid::Uuid::new_v4().simple()
184    ));
185    if let Err(e) = write_private_file(&temp, bytes) {
186        return Err(with_temp_removed(e, &temp));
187    }
188    let linked = fs::hard_link(&temp, path);
189    fs::remove_file(&temp)
190        .with_context(|| format!("removing temporary key file {}", temp.display()))?;
191    match linked {
192        Ok(()) => {
193            sync_dir(dir)?;
194            Ok(true)
195        }
196        Err(e) if e.kind() == ErrorKind::AlreadyExists => Ok(false),
197        Err(e) => Err(e).with_context(|| format!("installing device key file {}", path.display())),
198    }
199}
200
201pub(super) fn write_private_file(path: &Path, bytes: &[u8]) -> Result<()> {
202    let mut options = OpenOptions::new();
203    options.write(true).create_new(true);
204    #[cfg(unix)]
205    std::os::unix::fs::OpenOptionsExt::mode(&mut options, PRIVATE_FILE_MODE);
206    let mut file = options
207        .open(path)
208        .with_context(|| format!("creating temporary key file {}", path.display()))?;
209    file.write_all(bytes)
210        .and_then(|()| file.sync_all())
211        .with_context(|| format!("writing temporary key file {}", path.display()))
212}
213
214fn with_temp_removed(error: anyhow::Error, temp: &Path) -> anyhow::Error {
215    match fs::remove_file(temp) {
216        Ok(()) => error,
217        Err(e) if e.kind() == ErrorKind::NotFound => error,
218        Err(e) => error.context(format!(
219            "also failed to remove temporary key file {}: {e}",
220            temp.display()
221        )),
222    }
223}
224
225#[cfg(unix)]
226pub(super) fn sync_dir(dir: &Path) -> Result<()> {
227    fs::File::open(dir)
228        .and_then(|d| d.sync_all())
229        .with_context(|| format!("syncing key directory {}", dir.display()))
230}
231
232#[cfg(not(unix))]
233pub(super) fn sync_dir(_dir: &Path) -> Result<()> {
234    Ok(())
235}
236
237fn ssh_public_line(key: &VerifyingKey) -> String {
238    let public = key.as_bytes();
239    let mut blob = Vec::with_capacity(8 + SSH_KEY_TYPE.len() + public.len());
240    blob.extend_from_slice(&(SSH_KEY_TYPE.len() as u32).to_be_bytes());
241    blob.extend_from_slice(SSH_KEY_TYPE);
242    blob.extend_from_slice(&(public.len() as u32).to_be_bytes());
243    blob.extend_from_slice(public);
244    format!("ssh-ed25519 {}", BASE64_STANDARD.encode(&blob))
245}
246
247#[cfg(test)]
248mod tests {
249    use super::*;
250
251    fn assert_zod<T: zeroize::ZeroizeOnDrop>() {}
252
253    fn public_parts(keys: &DeviceKeys) -> (String, String, [u8; 32]) {
254        (
255            keys.age_recipient().to_string(),
256            keys.ssh_public_key(),
257            keys.verifying_key().to_bytes(),
258        )
259    }
260
261    fn file_mode(path: &Path) -> u32 {
262        use std::os::unix::fs::PermissionsExt;
263        fs::metadata(path).unwrap().permissions().mode() & 0o777
264    }
265
266    #[test]
267    fn ssh_line_for_rfc8032_key_matches_openssh_encoding() {
268        let seed: [u8; 32] = [
269            0x9d, 0x61, 0xb1, 0x9d, 0xef, 0xfd, 0x5a, 0x60, 0xba, 0x84, 0x4a, 0xf4, 0x92, 0xec,
270            0x2c, 0xc4, 0x44, 0x49, 0xc5, 0x69, 0x7b, 0x32, 0x69, 0x19, 0x70, 0x3b, 0xac, 0x03,
271            0x1c, 0xae, 0x7f, 0x60,
272        ];
273        let key = SigningKey::from_bytes(&seed).verifying_key();
274        assert_eq!(
275            ssh_public_line(&key),
276            "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINdamAGCsQq31Uv+08lkBzoO4XLz2qYjJa8CGmj3B1Ea"
277        );
278    }
279
280    #[test]
281    fn ssh_public_key_is_an_openssh_ed25519_line() {
282        let keys = DeviceKeys::generate().unwrap();
283        let line = keys.ssh_public_key();
284        let encoded = line.strip_prefix("ssh-ed25519 ").unwrap();
285        assert!(encoded.starts_with("AAAAC3NzaC1lZDI1NTE5AAAAI"), "{line}");
286        assert_eq!(encoded.len(), 68);
287        assert!(!encoded.contains(' ') && !encoded.contains('='));
288    }
289
290    #[test]
291    fn secret_bytes_round_trip_keeps_public_keys() {
292        let keys = DeviceKeys::generate().unwrap();
293        let secret = keys.to_secret_bytes().unwrap();
294        assert_eq!(secret.expose().len(), secret.expose().capacity());
295        let restored = DeviceKeys::from_secret_bytes(secret.expose()).unwrap();
296        assert_eq!(public_parts(&restored), public_parts(&keys));
297        assert_eq!(
298            restored.ssh_signing_key().to_bytes(),
299            keys.ssh_signing_key().to_bytes()
300        );
301        assert_eq!(
302            restored.signing_key().to_bytes(),
303            keys.signing_key().to_bytes()
304        );
305    }
306
307    #[test]
308    fn the_three_device_keys_are_distinct() {
309        let keys = DeviceKeys::generate().unwrap();
310        assert_ne!(keys.ssh_signing_key().verifying_key(), keys.verifying_key());
311        assert_ne!(
312            keys.age_identity().to_public().to_string(),
313            DeviceKeys::generate().unwrap().age_recipient().to_string()
314        );
315        assert_ne!(
316            keys.ssh_signing_key().to_bytes(),
317            keys.signing_key().to_bytes()
318        );
319    }
320
321    #[test]
322    fn secret_blob_is_parsed_strictly() {
323        let keys = DeviceKeys::generate().unwrap();
324        let good = keys.to_secret_bytes().unwrap().expose().clone();
325
326        let mut wrong_magic = good.clone();
327        wrong_magic[0] = b'X';
328        let mut wrong_version = good.clone();
329        wrong_version[4] = 2;
330        let mut wrong_len_field = good.clone();
331        wrong_len_field[6] = wrong_len_field[6].wrapping_add(1);
332        let mut extra = good.clone();
333        extra.push(0);
334        let mut bad_age = good.clone();
335        bad_age[7] = b'?';
336
337        let cases: [(&str, &[u8]); 8] = [
338            ("empty", &[]),
339            ("magic only", &good[..4]),
340            ("truncated", &good[..good.len() - 1]),
341            ("wrong magic", wrong_magic.as_slice()),
342            ("wrong version", wrong_version.as_slice()),
343            ("wrong length field", wrong_len_field.as_slice()),
344            ("trailing byte", extra.as_slice()),
345            ("bad age string", bad_age.as_slice()),
346        ];
347        let age_secret = keys.age_identity().to_string();
348        for (name, bytes) in cases {
349            let err = DeviceKeys::from_secret_bytes(bytes).unwrap_err();
350            let shown = format!("{err:#}");
351            assert!(
352                !shown.contains(age_secret.expose_secret()),
353                "{name} leaks the secret"
354            );
355        }
356    }
357
358    #[test]
359    fn debug_shows_only_public_parts() {
360        let keys = DeviceKeys::generate().unwrap();
361        let shown = format!("{keys:?}");
362        assert!(shown.contains(&keys.age_recipient().to_string()));
363        assert!(shown.contains(&keys.ssh_public_key()));
364        assert!(!shown.contains("AGE-SECRET-KEY-"));
365        assert!(!shown.contains(&hex(keys.ssh_signing_key().as_bytes())));
366        assert!(!shown.contains(&hex(keys.signing_key().as_bytes())));
367    }
368
369    #[test]
370    fn load_or_create_creates_once_then_reloads() {
371        let dir = tempfile::tempdir().unwrap();
372        let path = dir.path().join(DEVICE_KEY_FILE);
373
374        let (created, was_created) = DeviceKeys::load_or_create(&path).unwrap();
375        assert!(was_created);
376        assert_eq!(file_mode(&path), 0o600);
377        let on_disk = fs::read(&path).unwrap();
378
379        let (loaded, was_created) = DeviceKeys::load_or_create(&path).unwrap();
380        assert!(!was_created);
381        assert_eq!(public_parts(&loaded), public_parts(&created));
382        assert_eq!(fs::read(&path).unwrap(), on_disk);
383
384        let names: Vec<String> = fs::read_dir(dir.path())
385            .unwrap()
386            .map(|e| e.unwrap().file_name().into_string().unwrap())
387            .collect();
388        assert_eq!(names, [DEVICE_KEY_FILE]);
389    }
390
391    #[test]
392    fn load_or_create_makes_a_private_parent_dir() {
393        let dir = tempfile::tempdir().unwrap();
394        let nested = dir.path().join("data");
395        let path = nested.join(DEVICE_KEY_FILE);
396        let (_, was_created) = DeviceKeys::load_or_create(&path).unwrap();
397        assert!(was_created);
398        assert_eq!(file_mode(&nested), 0o700);
399        assert_eq!(file_mode(&path), 0o600);
400    }
401
402    #[test]
403    fn load_or_create_refuses_a_corrupt_file_and_leaves_it() {
404        let good = DeviceKeys::generate()
405            .unwrap()
406            .to_secret_bytes()
407            .unwrap()
408            .expose()
409            .clone();
410        let mut wrong_magic = good.clone();
411        wrong_magic[..4].copy_from_slice(b"NOPE");
412        for contents in [good[..good.len() / 2].to_vec(), wrong_magic, Vec::new()] {
413            let dir = tempfile::tempdir().unwrap();
414            let path = dir.path().join(DEVICE_KEY_FILE);
415            fs::write(&path, &contents).unwrap();
416            let err = DeviceKeys::load_or_create(&path).unwrap_err();
417            assert!(format!("{err:#}").contains("corrupt"), "{err:#}");
418            assert_eq!(fs::read(&path).unwrap(), contents);
419            assert_eq!(fs::read_dir(dir.path()).unwrap().count(), 1);
420        }
421    }
422
423    #[test]
424    fn install_keeps_a_file_that_appeared_first() {
425        let dir = tempfile::tempdir().unwrap();
426        let path = dir.path().join(DEVICE_KEY_FILE);
427        let winner = DeviceKeys::generate().unwrap();
428        fs::write(&path, winner.to_secret_bytes().unwrap().expose()).unwrap();
429
430        let loser = DeviceKeys::generate().unwrap();
431        let installed =
432            install_if_absent(dir.path(), &path, loser.to_secret_bytes().unwrap().expose())
433                .unwrap();
434        assert!(!installed);
435        assert_eq!(fs::read_dir(dir.path()).unwrap().count(), 1);
436
437        let (loaded, was_created) = DeviceKeys::load_or_create(&path).unwrap();
438        assert!(!was_created);
439        assert_eq!(public_parts(&loaded), public_parts(&winner));
440    }
441
442    #[test]
443    fn secrets_live_in_zeroize_on_drop_types() {
444        assert_zod::<SigningKey>();
445        assert_zod::<KeyGuard<Vec<u8>>>();
446    }
447}