ma_core/
identity.rs

1//! Identity bootstrap helpers.
2//!
3//! - DID generation from secrets (via `generate_identity`, `generate_identity_from_secret`)
4//! - Persisted 32-byte secret key management for endpoint identity across restarts
5
6use std::fs;
7use std::net::{IpAddr, SocketAddr};
8use std::path::Path;
9
10use libp2p_identity::PeerId;
11
12use crate::error::{Error, Result};
13use crate::{Did, Document, EncryptionKey, MaError, SigningKey, VerificationMethod};
14
15// ─── DID identity generation (from ma-did) ──────────────────────────────────
16
17/// A generated DID identity with keys and a signed document.
18///
19/// Private keys are hex-encoded for storage. Use [`SigningKey::from_private_key_bytes`]
20/// and [`EncryptionKey::from_private_key_bytes`] to reconstruct key objects.
21#[derive(Debug, Clone)]
22pub struct GeneratedIdentity {
23    pub subject_url: Did,
24    pub document: Document,
25    pub signing_private_key_hex: String,
26    pub encryption_private_key_hex: String,
27}
28
29fn build_identity(ipns: &str) -> Result<GeneratedIdentity> {
30    let subject_url = Did::new_url(ipns, None::<String>).map_err(Error::Validation)?;
31    let sign_url = Did::new_url(ipns, None::<String>).map_err(Error::Validation)?;
32    let enc_url = Did::new_url(ipns, None::<String>).map_err(Error::Validation)?;
33
34    let signing_key = SigningKey::generate(sign_url).map_err(Error::Validation)?;
35    let encryption_key = EncryptionKey::generate(enc_url).map_err(Error::Validation)?;
36
37    let mut document = Document::new(&subject_url, &subject_url);
38
39    let assertion_vm = VerificationMethod::new(
40        subject_url.base_id(),
41        subject_url.base_id(),
42        signing_key.key_type.clone(),
43        signing_key.did.fragment.as_deref().unwrap_or_default(),
44        signing_key.public_key_multibase.clone(),
45    )
46    .map_err(Error::Validation)?;
47
48    let key_agreement_vm = VerificationMethod::new(
49        subject_url.base_id(),
50        subject_url.base_id(),
51        encryption_key.key_type.clone(),
52        encryption_key.did.fragment.as_deref().unwrap_or_default(),
53        encryption_key.public_key_multibase.clone(),
54    )
55    .map_err(Error::Validation)?;
56
57    let assertion_vm_id = assertion_vm.id.clone();
58    document
59        .add_verification_method(assertion_vm.clone())
60        .map_err(Error::Validation)?;
61    document
62        .add_verification_method(key_agreement_vm.clone())
63        .map_err(Error::Validation)?;
64    document.assertion_method = vec![assertion_vm_id];
65    document.key_agreement = vec![key_agreement_vm.id.clone()];
66    document
67        .sign(&signing_key, &assertion_vm)
68        .map_err(Error::Validation)?;
69
70    Ok(GeneratedIdentity {
71        subject_url,
72        document,
73        signing_private_key_hex: hex::encode(signing_key.private_key_bytes()),
74        encryption_private_key_hex: hex::encode(encryption_key.private_key_bytes()),
75    })
76}
77
78/// Derive the `did:ma` IPNS identifier from a caller-managed Ed25519 secret.
79pub fn ipns_from_secret(secret: [u8; 32]) -> Result<String> {
80    let keypair = libp2p_identity::Keypair::ed25519_from_bytes(secret)
81        .map_err(|_| Error::Validation(MaError::InvalidIdentitySecret))?;
82    let peer_id = PeerId::from_public_key(&keypair.public());
83    Ok(peer_id.to_string())
84}
85
86/// Generate a base DID identity with keys and a signed document.
87pub fn generate_identity(ipns: &str) -> Result<GeneratedIdentity> {
88    build_identity(ipns)
89}
90
91/// Generate a base DID identity where the `did:ma` IPNS identifier is derived
92/// from a caller-managed Ed25519 secret.
93pub fn generate_identity_from_secret(secret: [u8; 32]) -> Result<GeneratedIdentity> {
94    let ipns = ipns_from_secret(secret)?;
95    build_identity(&ipns)
96}
97
98// ─── Secret key file helpers ─────────────────────────────────────────────────
99
100/// Load a secret key from a 32-byte file on disk.
101///
102/// Returns `Ok(None)` if the file does not exist.
103pub fn load_secret_key_bytes(path: &Path) -> Result<Option<[u8; 32]>> {
104    if !path.exists() {
105        return Ok(None);
106    }
107
108    let bytes = fs::read(path).map_err(|e| Error::SecretKey(e.to_string()))?;
109    let key_bytes: [u8; 32] = bytes
110        .as_slice()
111        .try_into()
112        .map_err(|_| Error::SecretKey(format!("invalid key file length in {}", path.display())))?;
113
114    Ok(Some(key_bytes))
115}
116
117/// Generate a new random 32-byte secret key and write it to disk.
118///
119/// Fails if the file already exists (to prevent accidental overwrites).
120/// Uses OS-level secure file permissions via `crate::secure_fs` when
121/// compiled as part of a crate that provides it, otherwise writes directly.
122pub fn generate_secret_key_file(path: &Path) -> Result<[u8; 32]> {
123    if path.exists() {
124        return Err(Error::SecretKey(format!(
125            "secret key already exists at {}",
126            path.display()
127        )));
128    }
129
130    let mut key_bytes = [0u8; 32];
131    use rand::RngCore;
132    rand::rngs::OsRng.fill_bytes(&mut key_bytes);
133
134    // Ensure parent directory exists
135    if let Some(parent) = path.parent() {
136        fs::create_dir_all(parent).map_err(|e| {
137            Error::SecretKey(format!("failed to create dir {}: {}", parent.display(), e))
138        })?;
139    }
140
141    fs::write(path, key_bytes)
142        .map_err(|e| Error::SecretKey(format!("failed to write {}: {}", path.display(), e)))?;
143
144    // Best-effort permission hardening on Unix
145    #[cfg(unix)]
146    {
147        use std::os::unix::fs::PermissionsExt;
148        let _ = fs::set_permissions(path, fs::Permissions::from_mode(0o400));
149    }
150
151    Ok(key_bytes)
152}
153
154/// Convert a socket address to a multiaddr string (QUIC-v1 over UDP).
155pub fn socket_addr_to_multiaddr(addr: &SocketAddr) -> String {
156    match addr.ip() {
157        IpAddr::V4(ip) => format!("/ip4/{}/udp/{}/quic-v1", ip, addr.port()),
158        IpAddr::V6(ip) => format!("/ip6/{}/udp/{}/quic-v1", ip, addr.port()),
159    }
160}
161
162#[cfg(test)]
163mod tests {
164    use super::*;
165    use std::net::{Ipv4Addr, Ipv6Addr};
166    use std::path::PathBuf;
167
168    fn test_tmp_file(name: &str) -> PathBuf {
169        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
170            .join("tmp")
171            .join("identity-tests");
172        fs::create_dir_all(&root).expect("failed creating test tmp directory");
173        root.join(name)
174    }
175
176    #[test]
177    fn multiaddr_ipv4() {
178        let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 4433);
179        assert_eq!(
180            socket_addr_to_multiaddr(&addr),
181            "/ip4/127.0.0.1/udp/4433/quic-v1"
182        );
183    }
184
185    #[test]
186    fn multiaddr_ipv6() {
187        let addr = SocketAddr::new(IpAddr::V6(Ipv6Addr::LOCALHOST), 5555);
188        assert_eq!(socket_addr_to_multiaddr(&addr), "/ip6/::1/udp/5555/quic-v1");
189    }
190
191    #[test]
192    fn load_missing_returns_none() {
193        let path = test_tmp_file("nonexistent-key");
194        let _ = fs::remove_file(&path);
195        assert!(load_secret_key_bytes(&path).unwrap().is_none());
196    }
197
198    #[test]
199    fn generate_and_load_round_trip() {
200        let path = test_tmp_file("round-trip-key");
201        let _ = fs::remove_file(&path);
202
203        let generated = generate_secret_key_file(&path).unwrap();
204        let loaded = load_secret_key_bytes(&path).unwrap().unwrap();
205        assert_eq!(generated, loaded);
206
207        // Cleanup
208        let _ = fs::remove_file(&path);
209    }
210
211    #[test]
212    fn generate_refuses_overwrite() {
213        let path = test_tmp_file("no-overwrite-key");
214        let _ = fs::remove_file(&path);
215
216        generate_secret_key_file(&path).unwrap();
217        let err = generate_secret_key_file(&path).unwrap_err();
218        assert!(matches!(err, crate::error::Error::SecretKey(_)));
219
220        // Cleanup
221        let _ = fs::remove_file(&path);
222    }
223}
ma_core/identity.rs

ma_core/
identity.rs
