Skip to main content

qualia_client_core/identity_plane/
person.rs

1//! Natural-person principal — not a machine and not an OS login.
2//!
3//! At rest the secret material is sealed with the install vault key
4//! (XChaCha20-Poly1305 via `wrap_key`). Cleartext files from older builds are
5//! accepted once and rewritten sealed.
6
7use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
8use qualia_core_db::crypto::sanctuary_audit::{unwrap_key, wrap_key};
9use serde::{Deserialize, Serialize};
10use std::path::PathBuf;
11use std::time::{SystemTime, UNIX_EPOCH};
12
13const PERSON_AAD: &[u8] = b"qualia:person_identity:v1";
14const SEALED_FORMAT: &str = "qualia.person.sealed.v1";
15
16/// On-disk person principal (secret material).
17#[derive(Debug, Clone, Serialize, Deserialize)]
18pub struct PersonPrincipal {
19    /// Stable DID: `did:q42:person:{verifying_key_hex}`.
20    pub person_id: String,
21    /// Raw Ed25519 signing secret (32 bytes).
22    pub ed25519_secret: [u8; 32],
23    #[serde(default)]
24    pub created_at_unix: u64,
25    /// Optional preferred label (not a legal name).
26    #[serde(default)]
27    pub display_hint: String,
28}
29
30/// Public half of a person principal (safe to show in UI / share with peers).
31#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
32pub struct PersonPublic {
33    pub person_id: String,
34    pub verifying_key_hex: String,
35    #[serde(default)]
36    pub created_at_unix: u64,
37    #[serde(default)]
38    pub display_hint: String,
39}
40
41/// Portable bundle for installing the *same person* on another machine.
42///
43/// Treat like recovery material: never post publicly; import only on devices
44/// the person controls.
45#[derive(Debug, Clone, Serialize, Deserialize)]
46pub struct PersonTransferBundle {
47    pub format: String,
48    pub person: PersonPrincipal,
49}
50
51pub const PERSON_TRANSFER_FORMAT: &str = "qualia.person.transfer.v1";
52
53fn now_unix() -> u64 {
54    SystemTime::now()
55        .duration_since(UNIX_EPOCH)
56        .map(|d| d.as_secs())
57        .unwrap_or(0)
58}
59
60fn person_path() -> PathBuf {
61    crate::state::app_meta_dir().join("person_identity.json")
62}
63
64#[derive(Debug, Clone, Serialize, Deserialize)]
65struct SealedPersonFile {
66    format: String,
67    ciphertext_hex: String,
68}
69
70/// Derive a 32-byte wrapping key for person identity at rest.
71/// Prefers the install KeyVault when APP_STATE is live; otherwise a
72/// machine-local key file under app meta (so cold tools can still open).
73fn person_wrapping_key() -> Result<[u8; 32], String> {
74    if let Some(state) = crate::state::APP_STATE.get() {
75        if let Ok(vault) = state.key_vault.lock() {
76            if !vault.is_locked() {
77                return Ok(vault.derive_key("person_identity_v1").to_bytes());
78            }
79        }
80    }
81    // Fallback: dedicated local wrapping secret (not OS account).
82    let path = crate::state::app_meta_dir().join("person_wrap.key");
83    if path.exists() {
84        let bytes = std::fs::read(&path).map_err(|e| e.to_string())?;
85        if bytes.len() == 32 {
86            let mut k = [0u8; 32];
87            k.copy_from_slice(&bytes);
88            return Ok(k);
89        }
90    }
91    let mut k = [0u8; 32];
92    rand::fill(&mut k);
93    if let Some(parent) = path.parent() {
94        let _ = std::fs::create_dir_all(parent);
95    }
96    std::fs::write(&path, k).map_err(|e| e.to_string())?;
97    Ok(k)
98}
99
100impl PersonPrincipal {
101    /// Signing key.
102    pub fn signing_key(&self) -> SigningKey {
103        SigningKey::from_bytes(&self.ed25519_secret)
104    }
105
106    /// Verifying key as hex.
107    pub fn verifying_key_hex(&self) -> String {
108        hex::encode(VerifyingKey::from(&self.signing_key()).to_bytes())
109    }
110
111    /// Converts to public.
112    pub fn to_public(&self) -> PersonPublic {
113        PersonPublic {
114            person_id: self.person_id.clone(),
115            verifying_key_hex: self.verifying_key_hex(),
116            created_at_unix: self.created_at_unix,
117            display_hint: self.display_hint.clone(),
118        }
119    }
120
121    /// DID from verifying-key bytes.
122    pub fn did_from_verifying_key_bytes(vk: &[u8; 32]) -> String {
123        format!("did:q42:person:{}", hex::encode(vk))
124    }
125
126    /// Generates.
127    pub fn generate(display_hint: impl Into<String>) -> Result<Self, String> {
128        let mut secret = [0u8; 32];
129        rand::fill(&mut secret);
130        let sk = SigningKey::from_bytes(&secret);
131        let vk = VerifyingKey::from(&sk);
132        let person_id = Self::did_from_verifying_key_bytes(&vk.to_bytes());
133        Ok(Self {
134            person_id,
135            ed25519_secret: secret,
136            created_at_unix: now_unix(),
137            display_hint: display_hint.into(),
138        })
139    }
140
141    /// Load existing person identity, or mint a new one (first install).
142    pub fn load_or_create(display_hint: Option<&str>) -> Result<Self, String> {
143        let path = person_path();
144        if path.exists() {
145            let bytes = std::fs::read(&path)
146                .map_err(|e| format!("failed to read {}: {e}", path.display()))?;
147            if let Ok(person) = Self::load_from_bytes(&bytes) {
148                // Migrate cleartext → sealed if needed.
149                let _ = person.persist();
150                return Ok(person);
151            }
152        }
153        let person = Self::generate(display_hint.unwrap_or(""))?;
154        person.persist()?;
155        Ok(person)
156    }
157
158    fn load_from_bytes(bytes: &[u8]) -> Result<Self, String> {
159        if let Ok(sealed) = serde_json::from_slice::<SealedPersonFile>(bytes) {
160            if sealed.format == SEALED_FORMAT {
161                let wrap = person_wrapping_key()?;
162                let ct = hex::decode(&sealed.ciphertext_hex)
163                    .map_err(|e| format!("person ciphertext hex: {e}"))?;
164                let plain = unwrap_key(&wrap, &ct, PERSON_AAD)
165                    .map_err(|e| format!("person unwrap failed: {e:?}"))?;
166                let person: PersonPrincipal = serde_json::from_slice(&plain)
167                    .map_err(|e| format!("person plaintext parse: {e}"))?;
168                if person.person_id.starts_with("did:q42:person:")
169                    && person.ed25519_secret != [0u8; 32]
170                {
171                    return Ok(person);
172                }
173                return Err("sealed person identity failed integrity checks".into());
174            }
175        }
176        // Legacy cleartext
177        let person: PersonPrincipal =
178            serde_json::from_slice(bytes).map_err(|e| format!("person identity parse: {e}"))?;
179        if person.person_id.starts_with("did:q42:person:") && person.ed25519_secret != [0u8; 32] {
180            return Ok(person);
181        }
182        Err("invalid person identity file".into())
183    }
184
185    /// Persists.
186    pub fn persist(&self) -> Result<(), String> {
187        let path = person_path();
188        if let Some(parent) = path.parent() {
189            std::fs::create_dir_all(parent)
190                .map_err(|e| format!("failed to create {}: {e}", parent.display()))?;
191        }
192        let plain = serde_json::to_vec(self)
193            .map_err(|e| format!("failed to encode person identity: {e}"))?;
194        let wrap = person_wrapping_key()?;
195        let sealed = wrap_key(&wrap, &plain, PERSON_AAD)
196            .map_err(|e| format!("person seal failed: {e:?}"))?;
197        let file = SealedPersonFile {
198            format: SEALED_FORMAT.to_string(),
199            ciphertext_hex: hex::encode(sealed),
200        };
201        let json = serde_json::to_string_pretty(&file)
202            .map_err(|e| format!("failed to encode sealed person: {e}"))?;
203        std::fs::write(&path, json)
204            .map_err(|e| format!("failed to write {}: {e}", path.display()))?;
205        Ok(())
206    }
207
208    /// Sign a message with the person principal (for fleet job envelopes).
209    pub fn sign_message(&self, message: &[u8]) -> [u8; 64] {
210        self.signing_key().sign(message).to_bytes()
211    }
212
213    /// Verifies a message signature.
214    pub fn verify_message(
215        person_id: &str,
216        verifying_key_hex: &str,
217        message: &[u8],
218        sig: &[u8; 64],
219    ) -> Result<(), String> {
220        let key_hex = verifying_key_hex.trim().to_ascii_lowercase();
221        let expected = format!("did:q42:person:{key_hex}");
222        if person_id != expected {
223            return Err("person_id does not match verifying key".into());
224        }
225        let bytes = hex::decode(&key_hex).map_err(|e| format!("verifying key hex: {e}"))?;
226        if bytes.len() != 32 {
227            return Err("verifying key must be 32 bytes".into());
228        }
229        let mut arr = [0u8; 32];
230        arr.copy_from_slice(&bytes);
231        let vk = VerifyingKey::from_bytes(&arr).map_err(|e| format!("verifying key: {e}"))?;
232        let signature = Signature::from_bytes(sig);
233        vk.verify(message, &signature)
234            .map_err(|_| "person signature invalid".to_string())
235    }
236
237    /// Replaces with another.
238    pub fn replace_with(person: PersonPrincipal) -> Result<PersonPrincipal, String> {
239        if !person.person_id.starts_with("did:q42:person:") {
240            return Err("person_id must be a did:q42:person:… identifier".into());
241        }
242        let expected = Self::did_from_verifying_key_bytes(
243            &VerifyingKey::from(&person.signing_key()).to_bytes(),
244        );
245        if person.person_id != expected {
246            return Err("person_id does not match signing key material".into());
247        }
248        person.persist()?;
249        Ok(person)
250    }
251
252    /// Transfer bundle.
253    pub fn transfer_bundle(&self) -> PersonTransferBundle {
254        PersonTransferBundle {
255            format: PERSON_TRANSFER_FORMAT.to_string(),
256            person: self.clone(),
257        }
258    }
259
260    /// Constructs from transfer-bundle.
261    pub fn from_transfer_bundle(bundle: PersonTransferBundle) -> Result<Self, String> {
262        if bundle.format != PERSON_TRANSFER_FORMAT {
263            return Err(format!(
264                "unsupported person transfer format: {}",
265                bundle.format
266            ));
267        }
268        Self::replace_with(bundle.person)
269    }
270}
271
272#[cfg(test)]
273mod tests {
274    use super::*;
275
276    #[test]
277    fn person_id_is_not_an_os_username() {
278        let p = PersonPrincipal::generate("").unwrap();
279        assert!(p.person_id.starts_with("did:q42:person:"));
280        assert!(!p.person_id.contains('\\'));
281        assert_ne!(p.person_id, whoami_username_fallback());
282    }
283
284    fn whoami_username_fallback() -> String {
285        std::env::var("USERNAME")
286            .or_else(|_| std::env::var("USER"))
287            .unwrap_or_default()
288    }
289
290    #[test]
291    fn public_half_exposes_no_secret() {
292        let p = PersonPrincipal::generate("Ada").unwrap();
293        let pub_ = p.to_public();
294        let json = serde_json::to_string(&pub_).unwrap();
295        assert!(!json.contains("ed25519_secret"));
296        assert_eq!(pub_.person_id, p.person_id);
297        assert_eq!(pub_.verifying_key_hex.len(), 64);
298    }
299}