Skip to main content

second_brain_sync/
pairing.rs

1use std::time::Duration;
2
3use second_brain_core::keys::Envelope;
4use serde::{Deserialize, Serialize};
5
6use crate::protocol::HandshakeKeys;
7
8mod channel;
9mod code;
10mod host;
11mod join;
12
13pub use channel::{Accepted, Channel, ChannelClosed, IO_TIMEOUT};
14pub use code::{CODE_WORDS, CodeKind, HostSecrets, JoinCode, pairing_address};
15pub use host::{HostOutcome, HostStatus, PairingHost};
16pub use join::{Taken, fetch_keys, join, reachable};
17
18/// The pairing listener's port when nothing else holds it.
19pub const PAIR_PORT: u16 = 7201;
20/// How long `sb pair` keeps a listener open.
21pub const PAIR_LIFETIME: Duration = Duration::from_secs(10 * 60);
22/// Wrong codes a listener takes before it retires its code for a new one.
23pub const MAX_WRONG_TRIES: u32 = 3;
24/// A file in the data dir that `sb setup` writes before the daemon first
25/// starts when the user chose to join an identity. The daemon reads it once
26/// at start: an empty store waits for its bootstrap instead of ingesting.
27pub const JOIN_PENDING_FILE: &str = "pair-join-pending";
28
29/// What the joining device sends once the code is proven.
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
31pub struct JoinRequest {
32    pub machine_id: String,
33    pub name: String,
34    pub age_recipient: String,
35    pub ssh_public_key: String,
36    /// Hex of the ed25519 key that signs the rows this device authors.
37    pub signing_public_key: String,
38    #[serde(default)]
39    pub ssh: Option<SshServer>,
40    #[serde(default)]
41    pub addresses: Vec<String>,
42    pub sync_protocol: u32,
43    pub schema_version: i64,
44}
45
46/// A device's sshd as its peers would reach it.
47#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
48pub struct SshServer {
49    pub login: Option<String>,
50    pub port: u16,
51    /// OpenSSH public key lines (`type base64`), ed25519 first.
52    pub host_keys: Vec<String>,
53}
54
55impl SshServer {
56    /// The host key a device row carries: the first, so ed25519 when the
57    /// sshd has one.
58    pub fn row_host_key(&self) -> Option<&str> {
59        self.host_keys.first().map(String::as_str)
60    }
61}
62
63/// The pairing device's answer to a proven join.
64#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
65#[serde(rename_all = "snake_case")]
66pub enum HostReply {
67    Admitted(Box<Admission>),
68    Refused { reason: String },
69    KeysHandedOver(Box<KeyHandover>),
70}
71
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
73#[serde(rename_all = "snake_case")]
74pub enum KeyPurpose {
75    RestoreKeys,
76}
77
78/// What a device restoring a backup sends a device running
79/// `sb pair --restore-keys` once the code is proven. It asks to be admitted
80/// to no identity.
81#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
82pub struct KeyRequest {
83    pub purpose: KeyPurpose,
84    pub name: String,
85    pub age_recipient: String,
86}
87
88/// Every epoch of `K_id` the handing device holds, of any identity, wrapped
89/// for the restoring device. No device row is written for it.
90#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
91pub struct KeyHandover {
92    pub machine_id: String,
93    pub name: String,
94    pub envelopes: Vec<Envelope>,
95}
96
97#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
98pub struct Admission {
99    pub machine_id: String,
100    pub name: String,
101    /// The identity, every epoch wrapped for the joiner, the device list
102    /// with the joiner's first row signed by this device, and the
103    /// revocations behind the epochs.
104    pub keys: HandshakeKeys,
105    /// The recovery recipients this device trusts, which the joiner adds to
106    /// its own trusted set.
107    #[serde(default)]
108    pub recovery_recipients: Vec<String>,
109    #[serde(default)]
110    pub ssh: Option<SshServer>,
111    #[serde(default)]
112    pub addresses: Vec<String>,
113    pub sync_protocol: u32,
114    pub schema_version: i64,
115}
116
117/// The joiner's last frame: whether it stored what it was sent.
118#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
119#[serde(rename_all = "snake_case")]
120pub enum JoinerAck {
121    Joined,
122    Failed { reason: String },
123}