tunnet-core 0.7.0

Core mesh runtime for Tunnet (identity, routing, streams, sync)
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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
//! Tiered encryption at rest for agent secrets (identity, network PSK, tickets, auth).
//!
//! Layout:
//! - `state.enc` - AES-256-GCM ciphertext of [`SensitivePayload`]
//! - `state.enc.meta` - seal tier + wrapped DEK / salt
//!
//! Tiers (best available wins unless plaintext forced):
//! 1. `tpm` - Windows DPAPI (TPM-backed when present); Linux falls through today
//! 2. `keychain` - macOS System/login Keychain
//! 3. `derived` - HKDF from machine-id + boot-id + salt (offline-copy protection)
//! 4. `plaintext` - explicit `--no-encrypt-state` / `TUNNET_NO_ENCRYPT_STATE`

mod derived;
mod persist;
mod platform;

pub use persist::{load_agent, persist_agent};

use aes_gcm::aead::{Aead, AeadCore, KeyInit, OsRng};
use aes_gcm::{Aes256Gcm, Key, Nonce};
use anyhow::{Context, bail};
use serde::{Deserialize, Serialize};
use zeroize::{Zeroize, ZeroizeOnDrop};

use std::collections::BTreeMap;

use uuid::Uuid;

use crate::identity::AgentIdentity;
use crate::state::{CliAuthTokens, StatePaths};

const PAYLOAD_VERSION: u32 = 2;
const META_VERSION: u32 = 1;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SealTier {
    Tpm,
    Keychain,
    Derived,
    Plaintext,
}

impl SealTier {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Tpm => "tpm",
            Self::Keychain => "keychain",
            Self::Derived => "derived",
            Self::Plaintext => "plaintext",
        }
    }
}

/// Per-network sealed fields.
#[derive(Clone, Serialize, Deserialize)]
pub struct NetworkSecrets {
    pub network_secret: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub doc_ticket: Option<String>,
}

/// In-memory secrets held after unlock.
#[derive(Clone, Zeroize, ZeroizeOnDrop)]
pub struct AgentSecrets {
    pub identity_seed: [u8; 32],
    #[zeroize(skip)]
    pub networks: BTreeMap<Uuid, NetworkSecrets>,
    #[zeroize(skip)]
    pub auth: Option<CliAuthTokens>,
}

impl AgentSecrets {
    pub fn identity(&self) -> AgentIdentity {
        AgentIdentity::from_bytes(self.identity_seed)
    }

    pub fn from_identity(identity: &AgentIdentity) -> Self {
        Self {
            identity_seed: identity.secret_bytes,
            networks: BTreeMap::new(),
            auth: None,
        }
    }
}

#[derive(Serialize, Deserialize)]
struct SensitivePayload {
    version: u32,
    identity_seed_hex: String,
    #[serde(default)]
    networks: BTreeMap<Uuid, NetworkSecrets>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    auth: Option<CliAuthTokens>,
}

#[derive(Serialize, Deserialize)]
struct SealMeta {
    version: u32,
    tier: SealTier,
    /// Hex salt for derived tier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    salt_hex: Option<String>,
    /// Wrapped DEK (hex). Absent for keychain (DEK lives in Keychain) and plaintext.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    wrapped_dek_hex: Option<String>,
    /// Plaintext DEK hex - only for tier `plaintext`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    dek_hex: Option<String>,
}

/// Policy for selecting a seal tier when writing.
#[derive(Debug, Clone, Copy)]
pub struct SealPolicy {
    pub allow_encrypt: bool,
}

impl SealPolicy {
    pub fn from_env_and_flag(no_encrypt: bool) -> Self {
        let env_off = std::env::var("TUNNET_NO_ENCRYPT_STATE")
            .ok()
            .is_some_and(|v| matches!(v.as_str(), "1" | "true" | "yes"));
        Self {
            allow_encrypt: !(no_encrypt || env_off),
        }
    }

    pub fn pick_tier(self) -> SealTier {
        if !self.allow_encrypt {
            return SealTier::Plaintext;
        }
        platform::best_tier()
    }
}

pub fn secrets_exist(paths: &StatePaths) -> bool {
    paths.secrets_file().exists()
}

/// Save secrets using the best available tier (or plaintext if policy says so).
pub fn save_secrets(
    paths: &StatePaths,
    secrets: &AgentSecrets,
    policy: SealPolicy,
) -> anyhow::Result<SealTier> {
    paths.ensure()?;
    let tier = policy.pick_tier();
    let payload = SensitivePayload {
        version: PAYLOAD_VERSION,
        identity_seed_hex: hex::encode(secrets.identity_seed),
        networks: secrets.networks.clone(),
        auth: secrets.auth.clone(),
    };
    let plain = serde_json::to_vec(&payload).context("serialize sensitive payload")?;

    let mut dek = Aes256Gcm::generate_key(OsRng);
    let cipher = Aes256Gcm::new(&dek);
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
    let ciphertext = cipher
        .encrypt(&nonce, plain.as_ref())
        .map_err(|_| anyhow::anyhow!("AES-GCM encrypt failed"))?;

    // state.enc = nonce(12) || ciphertext+tag
    let mut blob = Vec::with_capacity(12 + ciphertext.len());
    blob.extend_from_slice(&nonce);
    blob.extend_from_slice(&ciphertext);
    std::fs::write(paths.secrets_file(), &blob)
        .with_context(|| format!("write {}", paths.secrets_file().display()))?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let _ =
            std::fs::set_permissions(paths.secrets_file(), std::fs::Permissions::from_mode(0o600));
    }

    let meta = match tier {
        SealTier::Plaintext => SealMeta {
            version: META_VERSION,
            tier,
            salt_hex: None,
            wrapped_dek_hex: None,
            dek_hex: Some(hex::encode(dek.as_slice())),
        },
        SealTier::Derived => {
            let salt = random_salt();
            let wrap_key = derived::derive_wrap_key(&salt)?;
            let wrapped = wrap_dek(&wrap_key, dek.as_slice())?;
            SealMeta {
                version: META_VERSION,
                tier,
                salt_hex: Some(hex::encode(salt)),
                wrapped_dek_hex: Some(hex::encode(wrapped)),
                dek_hex: None,
            }
        }
        SealTier::Keychain => {
            platform::store_dek_keychain(dek.as_slice())?;
            SealMeta {
                version: META_VERSION,
                tier,
                salt_hex: None,
                wrapped_dek_hex: None,
                dek_hex: None,
            }
        }
        SealTier::Tpm => {
            let wrapped = platform::wrap_dek_tpm(dek.as_slice())?;
            SealMeta {
                version: META_VERSION,
                tier,
                salt_hex: None,
                wrapped_dek_hex: Some(hex::encode(wrapped)),
                dek_hex: None,
            }
        }
    };

    let meta_json = serde_json::to_vec_pretty(&meta).context("serialize seal meta")?;
    std::fs::write(paths.secrets_meta_file(), meta_json)
        .with_context(|| format!("write {}", paths.secrets_meta_file().display()))?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let _ = std::fs::set_permissions(
            paths.secrets_meta_file(),
            std::fs::Permissions::from_mode(0o600),
        );
    }

    dek.zeroize();
    tracing::info!(tier = %tier.as_str(), "agent secrets sealed");
    Ok(tier)
}

/// Load and decrypt secrets from `state.enc`.
pub fn load_secrets(paths: &StatePaths) -> anyhow::Result<(AgentSecrets, SealTier)> {
    let meta_bytes = std::fs::read(paths.secrets_meta_file())
        .with_context(|| format!("read {}", paths.secrets_meta_file().display()))?;
    let meta: SealMeta = serde_json::from_slice(&meta_bytes).context("parse state.enc.meta")?;
    let blob = std::fs::read(paths.secrets_file())
        .with_context(|| format!("read {}", paths.secrets_file().display()))?;
    if blob.len() < 12 + 16 {
        bail!("state.enc too short");
    }

    let mut dek = resolve_dek(&meta)?;
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(&dek));
    let nonce = Nonce::from_slice(&blob[..12]);
    let plain = cipher
        .decrypt(nonce, &blob[12..])
        .map_err(|_| anyhow::anyhow!("failed to decrypt state.enc (wrong machine or corrupt?)"))?;
    dek.zeroize();

    let payload: SensitivePayload =
        serde_json::from_slice(&plain).context("parse decrypted sensitive payload")?;
    if payload.version != PAYLOAD_VERSION {
        bail!("unsupported sensitive payload version {}", payload.version);
    }
    let seed = hex::decode(&payload.identity_seed_hex).context("identity seed hex")?;
    if seed.len() != 32 {
        bail!("identity seed must be 32 bytes");
    }
    let mut arr = [0u8; 32];
    arr.copy_from_slice(&seed);

    Ok((
        AgentSecrets {
            identity_seed: arr,
            networks: payload.networks,
            auth: payload.auth,
        },
        meta.tier,
    ))
}

fn resolve_dek(meta: &SealMeta) -> anyhow::Result<[u8; 32]> {
    match meta.tier {
        SealTier::Plaintext => {
            let hex = meta
                .dek_hex
                .as_deref()
                .context("plaintext tier missing dek_hex")?;
            decode_dek32(hex)
        }
        SealTier::Derived => {
            let salt_hex = meta
                .salt_hex
                .as_deref()
                .context("derived tier missing salt")?;
            let salt = hex::decode(salt_hex).context("salt hex")?;
            let wrapped_hex = meta
                .wrapped_dek_hex
                .as_deref()
                .context("derived tier missing wrapped_dek")?;
            let wrapped = hex::decode(wrapped_hex).context("wrapped dek hex")?;
            let wrap_key = derived::derive_wrap_key(&salt)?;
            unwrap_dek(&wrap_key, &wrapped)
        }
        SealTier::Keychain => platform::load_dek_keychain(),
        SealTier::Tpm => {
            let wrapped_hex = meta
                .wrapped_dek_hex
                .as_deref()
                .context("tpm tier missing wrapped_dek")?;
            let wrapped = hex::decode(wrapped_hex).context("wrapped dek hex")?;
            platform::unwrap_dek_tpm(&wrapped)
        }
    }
}

fn decode_dek32(hex_str: &str) -> anyhow::Result<[u8; 32]> {
    let v = hex::decode(hex_str).context("dek hex")?;
    if v.len() != 32 {
        bail!("dek must be 32 bytes");
    }
    let mut out = [0u8; 32];
    out.copy_from_slice(&v);
    Ok(out)
}

fn wrap_dek(wrap_key: &[u8; 32], dek: &[u8]) -> anyhow::Result<Vec<u8>> {
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrap_key));
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
    let ct = cipher
        .encrypt(&nonce, dek)
        .map_err(|_| anyhow::anyhow!("wrap DEK failed"))?;
    let mut out = Vec::with_capacity(12 + ct.len());
    out.extend_from_slice(&nonce);
    out.extend_from_slice(&ct);
    Ok(out)
}

fn unwrap_dek(wrap_key: &[u8; 32], wrapped: &[u8]) -> anyhow::Result<[u8; 32]> {
    if wrapped.len() < 12 + 16 {
        bail!("wrapped DEK too short");
    }
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrap_key));
    let nonce = Nonce::from_slice(&wrapped[..12]);
    let plain = cipher
        .decrypt(nonce, &wrapped[12..])
        .map_err(|_| anyhow::anyhow!("unwrap DEK failed"))?;
    if plain.len() != 32 {
        bail!("unwrapped DEK wrong length");
    }
    let mut out = [0u8; 32];
    out.copy_from_slice(&plain);
    Ok(out)
}

fn random_salt() -> [u8; 16] {
    use aes_gcm::aead::rand_core::RngCore;
    use std::mem::MaybeUninit;

    let mut salt = MaybeUninit::<[u8; 16]>::uninit();
    // SAFETY: OsRng fills all 16 bytes before assume_init.
    unsafe {
        OsRng.fill_bytes(&mut *salt.as_mut_ptr());
        salt.assume_init()
    }
}

/// Delete sealed secret files.
pub fn clear_secrets(paths: &StatePaths) -> anyhow::Result<()> {
    for p in [paths.secrets_file(), paths.secrets_meta_file()] {
        if p.exists() {
            std::fs::remove_file(&p).with_context(|| format!("remove {}", p.display()))?;
        }
    }
    let _ = platform::delete_dek_keychain();
    Ok(())
}

pub fn load_or_create_secrets(
    paths: &StatePaths,
    policy: SealPolicy,
) -> anyhow::Result<(AgentSecrets, SealTier)> {
    if secrets_exist(paths) {
        return load_secrets(paths);
    }
    let identity = AgentIdentity::generate();
    let secrets = AgentSecrets::from_identity(&identity);
    let tier = save_secrets(paths, &secrets, policy)?;
    Ok((secrets, tier))
}

/// Store management OAuth tokens in `state.enc`.
pub fn store_auth(paths: &StatePaths, auth: CliAuthTokens) -> anyhow::Result<()> {
    let policy = SealPolicy::from_env_and_flag(false);
    let (mut secrets, _) = if secrets_exist(paths) {
        load_secrets(paths)?
    } else {
        load_or_create_secrets(paths, policy)?
    };
    secrets.auth = Some(auth);
    save_secrets(paths, &secrets, policy)?;
    Ok(())
}

pub fn load_auth(paths: &StatePaths) -> anyhow::Result<Option<CliAuthTokens>> {
    if !secrets_exist(paths) {
        return Ok(None);
    }
    let (secrets, _) = load_secrets(paths)?;
    Ok(secrets.auth.clone())
}

pub fn clear_auth(paths: &StatePaths) -> anyhow::Result<()> {
    if !secrets_exist(paths) {
        return Ok(());
    }
    let policy = SealPolicy::from_env_and_flag(false);
    let (mut secrets, _) = load_secrets(paths)?;
    secrets.auth = None;
    save_secrets(paths, &secrets, policy)?;
    Ok(())
}

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

    fn test_paths() -> (TempDir, StatePaths) {
        let dir = TempDir::new().unwrap();
        let paths = StatePaths {
            dir: dir.path().to_path_buf(),
        };
        (dir, paths)
    }

    #[test]
    fn roundtrip_derived() {
        let (_tmp, paths) = test_paths();
        paths.ensure().unwrap();
        let id = AgentIdentity::generate();
        let nid = Uuid::from_u128(42);
        let secrets = AgentSecrets {
            identity_seed: id.secret_bytes,
            networks: BTreeMap::from([(
                nid,
                NetworkSecrets {
                    network_secret: "deadbeef".into(),
                    doc_ticket: Some("ticket".into()),
                },
            )]),
            auth: None,
        };
        let policy = SealPolicy {
            allow_encrypt: true,
        };
        let tier = save_secrets(
            &paths,
            &secrets,
            SealPolicy {
                allow_encrypt: false,
            },
        )
        .unwrap();
        assert_eq!(tier, SealTier::Plaintext);
        let (loaded, t) = load_secrets(&paths).unwrap();
        assert_eq!(t, SealTier::Plaintext);
        assert_eq!(loaded.identity_seed, secrets.identity_seed);
        let ns = loaded.networks.get(&nid).unwrap();
        assert_eq!(ns.network_secret, "deadbeef");
        assert_eq!(ns.doc_ticket.as_deref(), Some("ticket"));
        let _ = policy;
    }

    #[test]
    fn derived_wrap_roundtrip() {
        let salt = random_salt();
        let key = derived::derive_wrap_key(&salt).unwrap();
        let dek = Aes256Gcm::generate_key(OsRng);
        let wrapped = wrap_dek(&key, dek.as_slice()).unwrap();
        let out = unwrap_dek(&key, &wrapped).unwrap();
        assert_eq!(out.as_slice(), dek.as_slice());
    }
}