nordisk-pairing 0.5.2

The boxes of an estate find each other: a seed each box is installed with, a one-time join against the front, a tunnel (WireGuard by default) they meet inside, roles decided once, a pairing loop each box runs itself, and the signal it reports. Shared by gunnar and holger; the laptop's xtask only lays machines, writes seeds and reads the signal. Design: .nornir/pairing-design.md (2026-09-24).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! **The boxes of an estate find each other.**
//!
//! Until 2026-09-24 the laptop's xtask was the matchmaker of the gunnar.rs
//! estate: three machines booted knowing nothing of each other, and every
//! introduction — bootstrap the primary with the front's console key, enrol
//! the principals, confer the twin's role, sign its certificate — was one ssh
//! command from a laptop, run once, in order. Every one of them was a place
//! the chain broke (a box not listening yet, a killed run, a dropped packet),
//! and a laptop in the middle of an installation is a single point of failure
//! that has nothing to do with the estate.
//!
//! The owner's order (2026-09-24): the xtask does not pair. It starts the
//! machines with enough information for them to form a tunnel — WireGuard by
//! default; Tailscale, Mullvad, or none — and the boxes pair each other inside
//! it. gunnar and holger share this crate. Design: `Skidbladnir/.nornir/pairing-design.md`.
//!
//! The pieces, in the order a box meets them:
//!
//! 1. [`seed`] — what a MEDIUM is told at compose time, the same for every
//!    lay: the estate, the tunnel kind, the join door's fixed address, the
//!    installer CA and the bootstrap certificate. Nothing per box, nothing per
//!    lay — the medium is constant (2026-09-24 evening).
//! 2. [`tunnel`] — the driver trait and the `none` driver. Only the FRONT needs
//!    a known address; the others dial it, and the overlay addresses are ours.
//! 3. [`join`] — the one-time join against the front's door over mutual TLS:
//!    the box presents its tunnel public key and its capacity; the door admits
//!    it by the address it joins from, and answers with its name and overlay
//!    address, the peers (the front's tunnel first), the role, and the FEED.
//! 4. [`elect`] — the weakest gunnar box becomes the twin, decided ONCE on the
//!    front from two capacity reports, never re-decided.
//! 5. [`pair`] — the state machine each box runs: tunnel up → joined → role
//!    known → paired, every step idempotent and retried by the box itself.
//! 6. [`signal`] — where a box is, as one line and as a value; what the xtask
//!    (and an operator) READS instead of doing.
//!
//! Pure Rust, no shell (LAW). No driver here ever answers "up" for a tunnel it
//! did not bring up: `none` and `wireguard` work, `mullvad` works as each
//! box's EXIT beside the WireGuard mesh, and `tailscale` refuses by name
//! (`[tunnel-tailscale-unimplemented]`) — see [`tunnel`].

pub mod bootlog;
pub mod bootstrap;
pub mod door;
pub mod installer;
pub mod installer_link;
pub mod elect;
pub mod join;
pub mod mtls;
pub mod pair;
pub mod redact;
pub mod seed;
pub mod signal;
pub mod tunnel;
#[cfg(feature = "wireguard")]
pub mod wireguard;
#[cfg(feature = "mullvad")]
pub mod mullvad;
#[cfg(feature = "tailscale")]
pub mod tailscale;

use std::net::Ipv4Addr;

/// **The overlay addresses are a design constant, not a cloud fact.** The
/// front is `.1`; the two gunnar boxes are `.2` and `.3` and their ROLES are
/// decided by the election, so a seed names a box's address, never its role.
pub const OVERLAY_NET: (Ipv4Addr, u8) = (Ipv4Addr::new(10, 44, 0, 0), 24);
pub const OVERLAY_FRONT: Ipv4Addr = Ipv4Addr::new(10, 44, 0, 1);
pub const OVERLAY_BOX_A: Ipv4Addr = Ipv4Addr::new(10, 44, 0, 2);
pub const OVERLAY_BOX_B: Ipv4Addr = Ipv4Addr::new(10, 44, 0, 3);

/// The port the boxes' control planes listen on inside the tunnel — gunnar's
/// gRPC control port, unchanged.
pub const CONTROL_PORT: u16 = 50051;

/// The front's WireGuard relay (the estate's hub): udp/51820 on vm1.
pub const RELAY_PORT: u16 = 51820;

/// What a box IS in the estate once the election has spoken.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Role {
    Front,
    Primary,
    Twin,
}

impl Role {
    pub fn as_str(self) -> &'static str {
        match self {
            Role::Front => "front",
            Role::Primary => "primary",
            Role::Twin => "twin",
        }
    }
}

/// Is `ip` inside the overlay network?
pub fn in_overlay(ip: Ipv4Addr) -> bool {
    let (net, bits) = OVERLAY_NET;
    let mask = if bits == 0 { 0 } else { u32::MAX << (32 - bits) };
    (u32::from(ip) & mask) == (u32::from(net) & mask)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_overlay_is_ours_and_the_three_addresses_are_in_it() {
        assert!(in_overlay(OVERLAY_FRONT) && in_overlay(OVERLAY_BOX_A) && in_overlay(OVERLAY_BOX_B));
        assert!(!in_overlay(Ipv4Addr::new(10, 13, 8, 179)), "a UpCloud utility address is not overlay");
        assert_ne!(OVERLAY_BOX_A, OVERLAY_BOX_B);
    }
}