second-brain-sync 0.13.3

Bidirectional sync for second-brain: SSH transport, JSONL change log, conflict resolution
Documentation
use std::collections::{BTreeMap, BTreeSet};
use std::path::Path;

use age::x25519::Recipient;
use anyhow::{Context, Result, anyhow, bail, ensure};
use second_brain_core::keys::{
    DeviceRecord, Epoch, IdentityTag, PriorIdentity, Revocation, admit_device,
    check_own_paired_row, listed_signing_key, recovery_fingerprint, revoked_by,
    take_own_paired_row, take_paired_rows, wrap_for_recovery,
};
use second_brain_core::sqlite_store::SqliteStore;

use super::Keyring;
use crate::pairing::{Admission, JoinRequest, SshServer};
use crate::protocol::SYNC_PROTOCOL_VERSION;

/// What a joining device took from its admission.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Joined {
    pub identity: IdentityTag,
    /// The epochs this device now opens.
    pub epochs: Vec<Epoch>,
    /// This device held no identity before.
    pub first: bool,
    /// This device held another identity before.
    pub moved: bool,
    /// Other devices of the identity now in this store.
    pub devices: usize,
}

impl Keyring<'_> {
    /// What this device sends a pairing device once the code is proven.
    pub fn join_request(
        &self,
        name: &str,
        ssh: Option<SshServer>,
        addresses: Vec<String>,
    ) -> Result<JoinRequest> {
        Ok(JoinRequest {
            machine_id: self.own().to_string(),
            name: name.to_string(),
            age_recipient: self.device.age_recipient().to_string(),
            ssh_public_key: self.device.ssh_public_key(),
            signing_public_key: hex(&self.device.verifying_key().to_bytes()),
            ssh,
            addresses,
            sync_protocol: SYNC_PROTOCOL_VERSION,
            schema_version: self.store.schema_version()?,
        })
    }

    /// Signs the joining device's first row into this identity and answers
    /// with every epoch wrapped for it, the device list, the revocations
    /// behind the epochs and this device's recovery recipients.
    pub fn admit(
        &self,
        request: &JoinRequest,
        name: &str,
        ssh: Option<SshServer>,
        addresses: Vec<String>,
    ) -> Result<Admission> {
        let tag = self
            .identity
            .as_ref()
            .context("this device has no sync identity to pair a device into")?;
        ensure!(!self.is_removed()?, REMOVED);
        let schema_version = self.store.schema_version()?;
        if (request.sync_protocol, request.schema_version)
            != (SYNC_PROTOCOL_VERSION, schema_version)
        {
            bail!(
                "{} runs sync protocol {} on schema {} and this device runs protocol {} on schema \
                 {}; upgrade the older one, then pair again",
                request.name,
                request.sync_protocol,
                request.schema_version,
                SYNC_PROTOCOL_VERSION,
                schema_version
            );
        }
        ensure!(
            !self.held.is_empty(),
            "this device opens no epoch of its identity, so it has nothing to hand over"
        );
        let recovery = self.store.recovery_recipients(tag)?;
        let record = DeviceRecord {
            machine_id: request.machine_id.clone(),
            identity_tag: tag.as_str().to_string(),
            version: 1,
            name: request.name.clone(),
            age_recipient: request.age_recipient.clone(),
            ssh_public_key: request.ssh_public_key.clone(),
            signing_public_key: unhex32(&request.signing_public_key)
                .context("the joining device sent a signing key that is not 64 hex digits")?,
            recovery_fingerprints: recovery
                .iter()
                .map(|r| recovery_fingerprint(&r.to_string()))
                .collect(),
            ssh_login: request.ssh.as_ref().and_then(|s| s.login.clone()),
            ssh_port: request.ssh.as_ref().map(|s| s.port),
            ssh_host_key: request
                .ssh
                .as_ref()
                .and_then(|s| s.row_host_key().map(str::to_string)),
        };
        admit_device(self.store, &self.device, record)?;
        ensure!(
            self.active_row(&request.machine_id)?.is_some(),
            "{} is not an active device of this identity after its row was stored, so no epoch \
             can be wrapped for it",
            request.name
        );
        let keys = self.handshake_for(&request.machine_id, Some(&[]))?;
        let unwrapped: Vec<u32> = self
            .held
            .iter()
            .map(|(epoch, _)| epoch)
            .filter(|epoch| !keys.envelopes.iter().any(|e| e.epoch == **epoch))
            .map(|epoch| epoch.number)
            .collect();
        ensure!(
            unwrapped.is_empty(),
            "epochs {unwrapped:?} were not wrapped for {}",
            request.name
        );
        Ok(Admission {
            machine_id: self.own().to_string(),
            name: name.to_string(),
            keys,
            recovery_recipients: recovery.iter().map(ToString::to_string).collect(),
            ssh,
            addresses,
            sync_protocol: SYNC_PROTOCOL_VERSION,
            schema_version,
        })
    }
}

/// On the joining device: takes the row the pairing device signed for it,
/// the device list it vouched for over the channel, the epochs wrapped for
/// it and its recovery recipients, adding them to the recipients this
/// device trusted under an identity it leaves. Everything is checked before
/// the first write, so a refused admission leaves this device as it was.
/// Safe to rerun with the same admission.
pub fn take_admission(
    store: &SqliteStore,
    data_dir: &Path,
    admission: &Admission,
    now_micros: i64,
) -> Result<Joined> {
    let host = &admission.machine_id;
    let keys = &admission.keys;
    let tag = keys
        .identity_tag
        .clone()
        .context("the pairing device sent no identity")?;
    let rows = &keys.devices;
    let own = store.machine_id();
    let own_row = rows
        .iter()
        .filter(|row| row.record.machine_id == own && row.record.identity_tag == tag.as_str())
        .min_by_key(|row| row.record.version)
        .context("the pairing device sent no row for this device")?;
    let host_key = listed_signing_key(rows, host)?;
    let before = Keyring::load(store, data_dir)?;
    check_own_paired_row(own, &before.device, own_row, host, &host_key)?;
    let mut recovery = admission
        .recovery_recipients
        .iter()
        .map(|text| {
            text.parse::<Recipient>()
                .map_err(|e| anyhow!("the pairing device sent an invalid recovery recipient: {e}"))
        })
        .collect::<Result<Vec<_>>>()?;
    check_not_revoked(store, &tag, admission)?;
    before.check_envelopes_open(&tag, admission)?;
    if let Some(earlier) = before.identity.as_ref().filter(|earlier| **earlier != tag) {
        for recipient in store.recovery_recipients(earlier)? {
            if !recovery
                .iter()
                .any(|r| r.to_string() == recipient.to_string())
            {
                recovery.push(recipient);
            }
        }
    }

    let prior = take_own_paired_row(store, &before.device, own_row, host, &host_key)?;
    let devices = take_paired_rows(store, &tag, &keys.epochs, host, rows)?;
    if prior != PriorIdentity::Same {
        store.reset_floor_for_new_identity(&tag)?;
    }
    store.apply_revocations(&tag)?;

    Keyring::load(store, data_dir)?.accept(host, keys, now_micros)?;
    let keyring = Keyring::load(store, data_dir)?;
    ensure!(
        !keyring.held.is_empty(),
        "the pairing device's envelopes did not open on this device"
    );
    keyring.list_recovery_fingerprints(&recovery)?;
    let held: Vec<_> = keyring
        .held
        .iter()
        .map(|(epoch, key)| (*epoch, key))
        .collect();
    wrap_for_recovery(store, &tag, &held, &recovery)?;
    keyring.fill_recovery_envelopes()?;
    Ok(Joined {
        identity: tag,
        epochs: keyring.held_epochs(),
        first: prior == PriorIdentity::None,
        moved: matches!(prior, PriorIdentity::Other(_)),
        devices,
    })
}

pub const REMOVED: &str = "this device was removed from its sync identity, so it cannot add devices; \
                       join another device's identity with `sb pair <code>` on this device";

/// Refuses an admission when the revocations it carries or this store
/// holds reach the pairing device or this one, counting the first-row
/// signatures it carries, those stored, and the pairer's on this device's
/// row: taking it would leave this device revoked. This device is named as
/// the removed one only when it is reached without the pairer's signature.
fn check_not_revoked(store: &SqliteStore, tag: &IdentityTag, admission: &Admission) -> Result<()> {
    let keys = &admission.keys;
    let own = store.machine_id();
    let mut firsts: BTreeMap<String, (u64, BTreeSet<String>)> = BTreeMap::new();
    for row in keys
        .devices
        .iter()
        .filter(|r| r.record.identity_tag == tag.as_str())
    {
        let id = &row.record.machine_id;
        let signers = row
            .signatures
            .iter()
            .map(|s| s.signer.clone())
            .filter(|signer| signer != id)
            .collect();
        let earlier = firsts
            .get(id)
            .is_some_and(|(version, _)| *version <= row.record.version);
        if !earlier {
            firsts.insert(id.clone(), (row.record.version, signers));
        }
    }
    let mut first_signers: BTreeMap<String, BTreeSet<String>> = firsts
        .into_iter()
        .map(|(id, (_, signers))| (id, signers))
        .collect();
    for row in store.device_records()? {
        if row.first.record.identity_tag != tag.as_str() {
            continue;
        }
        let id = row.first.record.machine_id.clone();
        first_signers.entry(id.clone()).or_default().extend(
            row.first
                .signatures
                .into_iter()
                .map(|s| s.signer)
                .filter(|signer| *signer != id),
        );
    }
    let stored = store.revocations(tag)?;
    let rules: Vec<&Revocation> = keys
        .revocations
        .iter()
        .chain(&stored)
        .map(|signed| &signed.revocation)
        .filter(|r| r.identity_tag == tag.as_str())
        .collect();
    let mut without_pairer = first_signers.clone();
    if let Some(signers) = without_pairer.get_mut(own) {
        signers.remove(&admission.machine_id);
    }
    ensure!(
        !revoked_by(&without_pairer, &rules).contains(own),
        "this device was removed from {}'s sync identity, so it cannot rejoin it under this \
         machine id; nothing was changed",
        admission.name
    );
    first_signers
        .entry(own.to_string())
        .or_default()
        .insert(admission.machine_id.clone());
    let reached = revoked_by(&first_signers, &rules);
    ensure!(
        !reached.contains(&admission.machine_id) && !reached.contains(own),
        "{} was removed from its sync identity, so joining through it would leave this device \
         removed too; nothing was changed. Pair from a device still in the identity",
        admission.name
    );
    Ok(())
}

impl Keyring<'_> {
    /// True once a revocation this device holds reaches it.
    pub fn is_removed(&self) -> Result<bool> {
        self.is_revoked(self.own())
    }

    /// At least one envelope in the admission is for this device, opens
    /// under its key, and has every revocation its epoch's cause names in
    /// the admission too, so taking it cannot strand this device keyless.
    fn check_envelopes_open(&self, tag: &IdentityTag, admission: &Admission) -> Result<()> {
        let keys = &admission.keys;
        let sent: BTreeSet<String> = keys.revocations.iter().map(|r| r.id()).collect();
        let recipient = self.device.age_recipient().to_string();
        let usable = keys.envelopes.iter().any(|envelope| {
            let cause_held = keys
                .causes
                .iter()
                .find(|(epoch, _)| *epoch == envelope.epoch)
                .is_none_or(|(_, cause)| cause.revocations.is_subset(&sent));
            envelope.identity_tag == *tag
                && envelope.recipient == recipient
                && envelope.machine_id.as_deref() == Some(self.own())
                && cause_held
                && envelope.open(self.device.age_identity()).is_ok()
        });
        ensure!(
            usable,
            "none of the epochs {} sent opens on this device; nothing was changed",
            admission.name
        );
        Ok(())
    }

    /// Lists in this device's own row the fingerprints of `recovery` it does
    /// not list yet and that are not retired, under its own signature.
    fn list_recovery_fingerprints(&self, recovery: &[Recipient]) -> Result<()> {
        let retired = self.store.retired_fingerprints()?;
        self.update_own_row(|record| {
            for recipient in recovery {
                let fingerprint = recovery_fingerprint(&recipient.to_string());
                if !retired.contains(&fingerprint)
                    && !record.recovery_fingerprints.contains(&fingerprint)
                {
                    record.recovery_fingerprints.push(fingerprint);
                }
            }
        })?;
        Ok(())
    }
}

fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|b| format!("{b:02x}")).collect()
}

fn unhex32(text: &str) -> Option<[u8; 32]> {
    let digits = text.as_bytes();
    if digits.len() != 64 {
        return None;
    }
    let mut out = [0u8; 32];
    for (byte, pair) in out.iter_mut().zip(digits.chunks_exact(2)) {
        let high = char::from(pair[0]).to_digit(16)?;
        let low = char::from(pair[1]).to_digit(16)?;
        *byte = u8::try_from((high << 4) | low).ok()?;
    }
    Some(out)
}