use std::fs;
use std::io::Write;
use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
use std::path::{Path, PathBuf};
use anyhow::{Context, Result, anyhow, bail, ensure};
use base64::Engine;
use base64::engine::general_purpose::STANDARD as B64;
use chacha20poly1305::aead::{Aead, KeyInit, OsRng, Payload};
use chacha20poly1305::{XChaCha20Poly1305, XNonce};
use rand_core::RngCore;
use second_brain_core::keys::{Epoch, IdentityKey, KeyGuard, KeyId, Subkey, derive_subkey};
const KEY_LEN: usize = 32;
const NONCE_LEN: usize = 24;
const MAGIC_PLAINTEXT: u8 = 0x00;
const MAGIC_XCHACHA: u8 = 0x01;
const MAGIC_EPOCH: u8 = 0x02;
const EPOCH_PREFIX_LEN: usize = 1 + 4 + 8;
pub trait SyncEncryptor: Send + Sync {
fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>>;
fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>>;
}
pub struct PassthroughEncryptor;
impl SyncEncryptor for PassthroughEncryptor {
fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
Ok(plaintext.to_vec())
}
fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>> {
Ok(ciphertext.to_vec())
}
}
pub struct XChaChaEncryptor {
key: [u8; KEY_LEN],
}
impl XChaChaEncryptor {
pub fn new(key: [u8; KEY_LEN]) -> Self {
Self { key }
}
pub fn key_base64(&self) -> String {
B64.encode(self.key)
}
fn cipher(&self) -> XChaCha20Poly1305 {
XChaCha20Poly1305::new((&self.key).into())
}
}
impl SyncEncryptor for XChaChaEncryptor {
fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
let mut nonce_bytes = [0u8; NONCE_LEN];
OsRng.fill_bytes(&mut nonce_bytes);
let nonce = XNonce::from_slice(&nonce_bytes);
let ct = self
.cipher()
.encrypt(nonce, plaintext)
.map_err(|e| anyhow!("xchacha20poly1305 encrypt failed: {e}"))?;
let mut framed = Vec::with_capacity(1 + NONCE_LEN + ct.len());
framed.push(MAGIC_XCHACHA);
framed.extend_from_slice(&nonce_bytes);
framed.extend_from_slice(&ct);
Ok(framed)
}
fn decrypt(&self, framed: &[u8]) -> Result<Vec<u8>> {
match framed.first() {
None => bail!("empty sync payload"),
Some(&MAGIC_PLAINTEXT) => bail!("refusing an unencrypted sync payload"),
Some(&MAGIC_XCHACHA) => {
if framed.len() < 1 + NONCE_LEN {
bail!("encrypted payload too short to contain a nonce");
}
let nonce = XNonce::from_slice(&framed[1..1 + NONCE_LEN]);
let ct = &framed[1 + NONCE_LEN..];
self.cipher().decrypt(nonce, ct).map_err(|e| {
anyhow!("xchacha20poly1305 decrypt failed (bad key or tampered payload): {e}")
})
}
Some(other) => bail!("unknown sync payload magic byte: {other:#x}"),
}
}
}
pub struct WireKey {
epoch: Epoch,
key: KeyGuard<[u8; KEY_LEN]>,
}
impl WireKey {
pub fn derive(identity: &IdentityKey, epoch: &Epoch) -> Result<Self> {
Ok(Self {
epoch: *epoch,
key: derive_subkey(identity, epoch, Subkey::Wire)?,
})
}
pub fn epoch(&self) -> &Epoch {
&self.epoch
}
fn cipher(&self) -> XChaCha20Poly1305 {
XChaCha20Poly1305::new(self.key.expose().into())
}
}
pub struct EpochSealer {
keys: Vec<WireKey>,
seal_with: Option<Epoch>,
}
impl EpochSealer {
pub fn new(keys: Vec<WireKey>, seal_with: Option<Epoch>) -> Result<Self> {
if let Some(epoch) = &seal_with {
ensure!(
keys.iter().any(|k| k.epoch == *epoch),
"no wire key held for epoch {} (key id {})",
epoch.number,
epoch.key_id
);
}
Ok(Self { keys, seal_with })
}
pub fn sealing_epoch(&self) -> Option<&Epoch> {
self.seal_with.as_ref()
}
fn key(&self, epoch: &Epoch) -> Option<&WireKey> {
self.keys.iter().find(|k| k.epoch == *epoch)
}
}
pub fn frame_epoch(framed: &[u8]) -> Option<Epoch> {
let prefix = framed.get(..EPOCH_PREFIX_LEN)?;
if prefix[0] != MAGIC_EPOCH {
return None;
}
let mut number = [0u8; 4];
number.copy_from_slice(&prefix[1..5]);
let mut key_id = [0u8; 8];
key_id.copy_from_slice(&prefix[5..]);
Some(Epoch {
number: u32::from_be_bytes(number),
key_id: KeyId(key_id),
})
}
pub fn line_epoch(line: &str) -> Option<Epoch> {
frame_epoch(&B64.decode(line.trim()).ok()?)
}
fn epoch_prefix(epoch: &Epoch) -> [u8; EPOCH_PREFIX_LEN] {
let mut prefix = [0u8; EPOCH_PREFIX_LEN];
prefix[0] = MAGIC_EPOCH;
prefix[1..5].copy_from_slice(&epoch.number.to_be_bytes());
prefix[5..].copy_from_slice(&epoch.key_id.0);
prefix
}
impl SyncEncryptor for EpochSealer {
fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
let epoch = self
.seal_with
.as_ref()
.context("this sync key set only opens frames; it has no epoch to seal under")?;
let key = self
.key(epoch)
.context("the sealing epoch's key vanished")?;
let prefix = epoch_prefix(epoch);
let mut nonce_bytes = [0u8; NONCE_LEN];
OsRng.fill_bytes(&mut nonce_bytes);
let ct = key
.cipher()
.encrypt(
XNonce::from_slice(&nonce_bytes),
Payload {
msg: plaintext,
aad: &prefix,
},
)
.map_err(|e| anyhow!("xchacha20poly1305 encrypt failed: {e}"))?;
let mut framed = Vec::with_capacity(EPOCH_PREFIX_LEN + NONCE_LEN + ct.len());
framed.extend_from_slice(&prefix);
framed.extend_from_slice(&nonce_bytes);
framed.extend_from_slice(&ct);
Ok(framed)
}
fn decrypt(&self, framed: &[u8]) -> Result<Vec<u8>> {
match framed.first() {
None => bail!("empty sync payload"),
Some(&MAGIC_PLAINTEXT) => bail!("refusing an unencrypted sync payload"),
Some(&MAGIC_XCHACHA) => {
bail!("refusing a payload sealed with a sync.key by sync protocol 3 or older")
}
Some(&MAGIC_EPOCH) => {
if framed.len() < EPOCH_PREFIX_LEN + NONCE_LEN {
bail!("encrypted payload too short to contain its epoch and nonce");
}
let epoch = frame_epoch(framed).context("frame has no epoch prefix")?;
let (prefix, rest) = framed.split_at(EPOCH_PREFIX_LEN);
let key = self.key(&epoch).with_context(|| {
format!(
"the payload is sealed under identity key epoch {} (key id {}), which this \
device does not hold; if the sender belongs to another identity, pair it \
with `sb pair`",
epoch.number, epoch.key_id
)
})?;
let (nonce, ct) = rest.split_at(NONCE_LEN);
key.cipher()
.decrypt(
XNonce::from_slice(nonce),
Payload {
msg: ct,
aad: prefix,
},
)
.map_err(|e| {
anyhow!(
"xchacha20poly1305 decrypt failed under epoch {} (tampered payload): {e}",
epoch.number
)
})
}
Some(other) => bail!("unknown sync payload magic byte: {other:#x}"),
}
}
}
pub fn seal_line(enc: &dyn SyncEncryptor, plaintext: &[u8]) -> Result<String> {
let framed = enc.encrypt(plaintext)?;
Ok(B64.encode(framed))
}
pub fn open_line(enc: &dyn SyncEncryptor, line: &str) -> Result<Vec<u8>> {
let framed = B64
.decode(line.trim())
.context("not an encrypted sync line (plaintext lines are refused)")?;
enc.decrypt(&framed)
}
#[cfg(test)]
pub(crate) fn frame_format() -> String {
format!(
"base64({MAGIC_EPOCH:#04x} | epoch u32 be | key id[8] | nonce[{NONCE_LEN}] | \
xchacha20poly1305 ciphertext, aad = first {EPOCH_PREFIX_LEN} bytes)"
)
}
pub fn default_key_path() -> Result<PathBuf> {
let home = dirs::home_dir().context("cannot determine home directory")?;
Ok(home.join(".second-brain").join("sync.key"))
}
pub fn load_or_create_key(path: &Path) -> Result<[u8; KEY_LEN]> {
if let Some(key) = read_key(path)? {
return Ok(key);
}
let mut key = [0u8; KEY_LEN];
OsRng.fill_bytes(&mut key);
if create_key(path, &key)? {
return Ok(key);
}
read_key(path)?.with_context(|| {
format!(
"{} exists but reads as missing; is it a dangling symlink?",
path.display()
)
})
}
pub fn read_key_file(path: &Path) -> Result<Option<[u8; KEY_LEN]>> {
read_key(path)
}
fn read_key(path: &Path) -> Result<Option<[u8; KEY_LEN]>> {
let contents = match fs::read_to_string(path) {
Ok(contents) => contents,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(e).context("reading sync key"),
};
let raw = B64
.decode(contents.trim())
.context("decoding base64 sync key")?;
let key: [u8; KEY_LEN] = raw
.as_slice()
.try_into()
.map_err(|_| anyhow!("sync key must decode to {KEY_LEN} bytes, got {}", raw.len()))?;
fs::set_permissions(path, fs::Permissions::from_mode(0o600))
.context("tightening sync key permissions to 0600")?;
Ok(Some(key))
}
fn create_key(path: &Path, key: &[u8; KEY_LEN]) -> Result<bool> {
if let Some(parent) = path.parent()
&& !parent.as_os_str().is_empty()
{
fs::create_dir_all(parent).context("creating sync key parent dir")?;
}
let mut staged = path.as_os_str().to_owned();
staged.push(format!(".{:016x}.tmp", OsRng.next_u64()));
let staged = PathBuf::from(staged);
let mut file = fs::OpenOptions::new()
.write(true)
.create_new(true)
.mode(0o600)
.open(&staged)
.context("staging the sync key")?;
let written = file
.write_all(format!("{}\n", B64.encode(key)).as_bytes())
.and_then(|()| file.sync_all());
drop(file);
if let Err(e) = written {
let left = match fs::remove_file(&staged) {
Ok(()) => String::new(),
Err(cleanup) => format!("; {} was left behind: {cleanup}", staged.display()),
};
return Err(e).context(format!("writing sync key{left}"));
}
let linked = fs::hard_link(&staged, path);
if let Err(e) = fs::remove_file(&staged) {
tracing::warn!("could not remove {}: {e}", staged.display());
}
match linked {
Ok(()) => Ok(true),
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(false),
Err(e) => Err(e).context("linking the sync key into place"),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn test_key(seed: u8) -> [u8; KEY_LEN] {
[seed; KEY_LEN]
}
#[test]
fn round_trip_returns_plaintext() {
let enc = XChaChaEncryptor::new(test_key(7));
let plaintext = b"sensitive memory line as jsonl";
let ct = enc.encrypt(plaintext).unwrap();
assert_ne!(
ct.as_slice(),
plaintext,
"ciphertext must differ from plaintext"
);
let pt = enc.decrypt(&ct).unwrap();
assert_eq!(pt, plaintext);
}
#[test]
fn nonce_is_random_per_message() {
let enc = XChaChaEncryptor::new(test_key(3));
let a = enc.encrypt(b"same input").unwrap();
let b = enc.encrypt(b"same input").unwrap();
assert_ne!(a, b, "fresh random nonce must yield distinct ciphertext");
}
#[test]
fn decrypt_with_wrong_key_fails() {
let enc = XChaChaEncryptor::new(test_key(1));
let other = XChaChaEncryptor::new(test_key(2));
let ct = enc.encrypt(b"secret").unwrap();
assert!(
other.decrypt(&ct).is_err(),
"AEAD must reject a payload sealed under a different key"
);
}
#[test]
fn flipped_ciphertext_byte_fails() {
let enc = XChaChaEncryptor::new(test_key(9));
let mut ct = enc.encrypt(b"tamper me").unwrap();
let last = ct.len() - 1;
ct[last] ^= 0x01;
assert!(
enc.decrypt(&ct).is_err(),
"Poly1305 tag must reject a single flipped byte"
);
}
#[test]
fn legacy_plaintext_frame_is_rejected() {
let enc = XChaChaEncryptor::new(test_key(5));
let mut legacy = vec![MAGIC_PLAINTEXT];
legacy.extend_from_slice(b"{\"local_seq\":1}");
assert!(enc.decrypt(&legacy).is_err());
}
#[test]
fn empty_frame_is_rejected() {
let enc = XChaChaEncryptor::new(test_key(5));
assert!(enc.decrypt(&[]).is_err());
}
#[test]
fn seal_open_line_round_trips() {
let enc = XChaChaEncryptor::new(test_key(4));
let record = b"{\"local_seq\":42,\"op\":\"Create\"}";
let line = seal_line(&enc, record).unwrap();
assert!(!line.contains('\n'), "wire line must be single-line");
let out = open_line(&enc, &line).unwrap();
assert_eq!(out, record);
}
#[test]
fn open_line_rejects_legacy_jsonl() {
let enc = XChaChaEncryptor::new(test_key(4));
let legacy = "{\"local_seq\":1,\"op\":\"Create\"}";
let err = open_line(&enc, legacy).unwrap_err();
assert!(
err.to_string().contains("not an encrypted sync line"),
"unexpected error: {err:#}"
);
}
#[test]
fn open_line_rejects_base64_of_a_plaintext_frame() {
let enc = XChaChaEncryptor::new(test_key(4));
let mut legacy = vec![MAGIC_PLAINTEXT];
legacy.extend_from_slice(b"{\"local_seq\":1}");
assert!(open_line(&enc, &B64.encode(legacy)).is_err());
}
#[test]
fn load_or_create_key_creates_0600_and_is_idempotent() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("nested").join("sync.key");
let first = load_or_create_key(&path).unwrap();
let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777;
assert_eq!(mode, 0o600, "key file must be 0600");
let second = load_or_create_key(&path).unwrap();
assert_eq!(
first, second,
"second load must return the same persisted key"
);
}
#[test]
fn a_dangling_key_symlink_is_an_error_naming_the_path() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("sync.key");
std::os::unix::fs::symlink(dir.path().join("gone"), &path).unwrap();
let error = load_or_create_key(&path).unwrap_err();
assert!(format!("{error:#}").contains("sync.key"), "{error:#}");
}
#[test]
fn callers_creating_the_key_at_once_all_get_the_one_on_disk() {
for _ in 0..50 {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("sync.key");
let start = std::sync::Arc::new(std::sync::Barrier::new(16));
let keys: Vec<[u8; KEY_LEN]> = (0..16)
.map(|_| {
let path = path.clone();
let start = start.clone();
std::thread::spawn(move || {
start.wait();
load_or_create_key(&path).unwrap()
})
})
.collect::<Vec<_>>()
.into_iter()
.map(|handle| handle.join().unwrap())
.collect();
let on_disk = load_or_create_key(&path).unwrap();
assert!(keys.iter().all(|key| *key == on_disk));
assert_eq!(fs::read_dir(dir.path()).unwrap().count(), 1);
}
}
fn identity(seed: u8) -> IdentityKey {
IdentityKey::from_bytes(KeyGuard::new([seed; KEY_LEN]))
}
fn wire(seed: u8, number: u32) -> WireKey {
let key = identity(seed);
let epoch = Epoch {
number,
key_id: key.key_id(),
};
WireKey::derive(&key, &epoch).unwrap()
}
#[test]
fn an_epoch_frame_opens_with_any_holder_of_its_epoch() {
let one = wire(1, 1);
let epoch = *one.epoch();
let sealer = EpochSealer::new(vec![wire(0, 0), one], Some(epoch)).unwrap();
let opener = EpochSealer::new(vec![wire(1, 1), wire(0, 0)], None).unwrap();
let line = seal_line(&sealer, b"record").unwrap();
assert_eq!(open_line(&opener, &line).unwrap(), b"record");
let framed = B64.decode(&line).unwrap();
assert_eq!(framed[0], MAGIC_EPOCH);
assert_eq!(&framed[1..5], &1u32.to_be_bytes());
assert_eq!(&framed[5..13], &epoch.key_id.0);
}
#[test]
fn a_frame_under_an_epoch_not_held_names_the_epoch_and_pairing() {
let sealer = EpochSealer::new(vec![wire(1, 0)], Some(*wire(1, 0).epoch())).unwrap();
let opener = EpochSealer::new(vec![wire(2, 0)], None).unwrap();
let line = seal_line(&sealer, b"record").unwrap();
let err = format!("{:#}", open_line(&opener, &line).unwrap_err());
assert!(err.contains("epoch 0"), "{err}");
assert!(err.contains("sb pair"), "{err}");
assert!(!err.contains("decrypt failed"), "{err}");
}
#[test]
fn a_relabelled_epoch_header_fails_authentication() {
let a = wire(1, 1);
let mut relabelled = wire(1, 1);
relabelled.epoch.number = 2;
let a_epoch = *a.epoch();
let sealer = EpochSealer::new(vec![a], Some(a_epoch)).unwrap();
let mut framed = sealer.encrypt(b"record").unwrap();
framed[1..5].copy_from_slice(&2u32.to_be_bytes());
let opener = EpochSealer::new(vec![relabelled], None).unwrap();
let err = format!("{:#}", opener.decrypt(&framed).unwrap_err());
assert!(err.contains("tampered"), "{err}");
}
#[test]
fn an_opener_only_set_refuses_to_seal_and_a_sync_key_frame_is_refused() {
let opener = EpochSealer::new(vec![wire(1, 0)], None).unwrap();
assert!(opener.encrypt(b"x").is_err());
let legacy = XChaChaEncryptor::new(test_key(1)).encrypt(b"x").unwrap();
let err = format!("{:#}", opener.decrypt(&legacy).unwrap_err());
assert!(err.contains("protocol 3 or older"), "{err}");
assert!(EpochSealer::new(vec![wire(1, 0)], Some(*wire(2, 0).epoch())).is_err());
}
}