Skip to main content

clm_rust_core/layer2/
backup.rs

1use crate::layer0::vocabulary::{HANDLE_MCARD_BACKUP_RECOVERY, HANDLE_MCARD_BACKUP_RESTORE, HANDLE_MCARD_BACKUP_SNAPSHOT};
2use rusqlite::Connection;
3use serde::{Deserialize, Serialize};
4use std::path::PathBuf;
5use rand::RngCore;
6
7#[derive(Debug, Serialize, Deserialize, Clone)]
8pub struct BackupSnapshotRecord {
9    pub snapshot_id: String,
10    pub tier: String,
11    pub card_count: u64,
12    pub merkle_dag_root: String,
13    pub timestamp: String,
14    pub handle: String,
15    pub content_hash: String,
16}
17
18#[derive(Debug, Serialize, Deserialize, Clone)]
19pub struct RestoreRecord {
20    pub snapshot_id: String,
21    pub cards_restored: u64,
22    pub verification_verdict: bool,
23    pub handle: String,
24    pub content_hash: String,
25}
26
27#[derive(Debug, Serialize, Deserialize, Clone)]
28pub struct RecoveryShard {
29    pub index: u8,
30    pub value: String,
31}
32
33#[derive(Debug, Serialize, Deserialize, Clone)]
34pub struct RecoveryRecord {
35    pub did: String,
36    pub guardian_count: u8,
37    pub threshold: u8,
38    pub shards: Vec<RecoveryShard>,
39    pub handle: String,
40    pub content_hash: String,
41}
42
43fn resolve_db_path(db_name_or_path: &str, clm_root: Option<&str>) -> PathBuf {
44    if db_name_or_path.contains('/') || db_name_or_path.contains('\\') {
45        PathBuf::from(db_name_or_path)
46    } else {
47        let root = clm_root.map(PathBuf::from).unwrap_or_else(|| {
48            std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
49        });
50        root.join("data").join("execution_logs").join(db_name_or_path)
51    }
52}
53
54fn init_db_tables(conn: &Connection) -> Result<(), String> {
55    let _ = conn.busy_timeout(std::time::Duration::from_millis(u64::from(crate::layer0::runtime_contract::SQLITE_BUSY_TIMEOUT_MS)));
56    conn.execute_batch(crate::layer0::runtime_contract::SQLITE_DDL_V3_1).map_err(|e| e.to_string())?;
57
58    // Idempotent migration from legacy `hash` column
59    let has_hash: bool = conn
60        .query_row(
61            "SELECT count(*) > 0 FROM pragma_table_info('handle_registry') WHERE name = 'hash'",
62            [],
63            |r| r.get(0),
64        )
65        .unwrap_or(false);
66    if has_hash {
67        let has_curr: bool = conn
68            .query_row(
69                "SELECT count(*) > 0 FROM pragma_table_info('handle_registry') WHERE name = 'current_hash'",
70                [],
71                |r| r.get(0),
72            )
73            .unwrap_or(false);
74        if !has_curr {
75            let _ = conn.execute_batch("ALTER TABLE handle_registry RENAME COLUMN hash TO current_hash;");
76        }
77    }
78    let has_updated_at: bool = conn
79        .query_row(
80            "SELECT count(*) > 0 FROM pragma_table_info('handle_registry') WHERE name = 'updated_at'",
81            [],
82            |r| r.get(0),
83        )
84        .unwrap_or(false);
85    if !has_updated_at {
86        let _ = conn.execute_batch("ALTER TABLE handle_registry ADD COLUMN updated_at TEXT NOT NULL DEFAULT '';");
87    }
88
89    Ok(())
90}
91
92fn generate_sha256(content: &str) -> String {
93    use sha2::{Digest, Sha256};
94    let mut hasher = Sha256::new();
95    hasher.update(content.as_bytes());
96    hex::encode(hasher.finalize())
97}
98
99/// Creates a tier-aware Merkle-DAG backup snapshot and registers `mcard:backup/snapshot/{snapshot_id}`.
100pub fn create_backup_snapshot(
101    db_name_or_path: &str,
102    clm_root: Option<&str>,
103    tier: &str,
104    backup_dir: &str,
105) -> Result<BackupSnapshotRecord, String> {
106    let db_path = resolve_db_path(db_name_or_path, clm_root);
107    if !db_path.exists() {
108        return Err(format!("Database file {} does not exist", db_path.display()));
109    }
110
111    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
112    init_db_tables(&conn)?;
113
114    let mut stmt = conn.prepare("SELECT hash FROM card ORDER BY hash ASC").map_err(|e| e.to_string())?;
115    let rows = stmt.query_map([], |row| row.get::<_, String>(0)).map_err(|e| e.to_string())?;
116    let mut cards = Vec::new();
117    let mut combined_hashes = String::new();
118    for row in rows {
119        let hash = row.map_err(|e| e.to_string())?;
120        let record = crate::layer2::record_store::read_record(&conn, &hash).map_err(|e| e.to_string())?
121            .ok_or_else(|| "snapshot row disappeared".to_string())?;
122        combined_hashes.push_str(&record.hash);
123        cards.push(record);
124    }
125
126    let card_count = cards.len() as u64;
127    let merkle_dag_root = generate_sha256(&combined_hashes);
128
129    let mut snap_bytes = [0u8; 8];
130    rand::thread_rng().fill_bytes(&mut snap_bytes);
131    let snapshot_id = format!("snap_{}_{}", tier, hex::encode(snap_bytes));
132
133    let backup_path = PathBuf::from(backup_dir);
134    std::fs::create_dir_all(&backup_path).map_err(|e| e.to_string())?;
135    let snapshot_file = backup_path.join(format!("{}.json", snapshot_id));
136
137    let snapshot_payload = serde_json::json!({
138        "snapshot_id": snapshot_id,
139        "tier": tier,
140        "card_count": card_count,
141        "merkle_dag_root": merkle_dag_root,
142        "cards": cards
143    });
144
145    let payload_str = serde_json::to_string_pretty(&snapshot_payload).map_err(|e| e.to_string())?;
146    std::fs::write(&snapshot_file, payload_str).map_err(|e| e.to_string())?;
147
148    let timestamp = chrono::Utc::now().to_rfc3339();
149    let handle = format!("{HANDLE_MCARD_BACKUP_SNAPSHOT}{}", snapshot_id);
150
151    let mcard_val = serde_json::json!({
152        "type": "backup_snapshot",
153        "snapshot_id": snapshot_id,
154        "tier": tier,
155        "card_count": card_count,
156        "merkle_dag_root": merkle_dag_root,
157        "backup_file": snapshot_file.to_string_lossy(),
158        "timestamp": timestamp
159    });
160
161    let content_json = mcard_val.to_string();
162    let content_hash = generate_sha256(&content_json);
163
164    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
165
166    conn.execute(
167        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
168         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
169        rusqlite::params![handle, content_hash, timestamp],
170    ).map_err(|e| e.to_string())?;
171
172    Ok(BackupSnapshotRecord {
173        snapshot_id,
174        tier: tier.to_string(),
175        card_count,
176        merkle_dag_root,
177        timestamp,
178        handle,
179        content_hash,
180    })
181}
182
183/// Restores account MCards from a snapshot backup file and registers `mcard:backup/restore/{snapshot_id}`.
184pub fn restore_backup_snapshot(
185    db_name_or_path: &str,
186    clm_root: Option<&str>,
187    snapshot_id: &str,
188    backup_dir: &str,
189) -> Result<RestoreRecord, String> {
190    let backup_path = PathBuf::from(backup_dir).join(format!("{}.json", snapshot_id));
191    if !backup_path.exists() {
192        return Err(format!("Snapshot file {} not found", backup_path.display()));
193    }
194
195    let payload_str = std::fs::read_to_string(&backup_path).map_err(|e| e.to_string())?;
196    let val: serde_json::Value = serde_json::from_str(&payload_str).map_err(|e| e.to_string())?;
197
198    let expected_root = val.get("merkle_dag_root").and_then(|x| x.as_str()).unwrap_or("");
199    let cards_array = val.get("cards").and_then(|x| x.as_array()).ok_or("Invalid cards array in snapshot")?;
200
201    let cards: Vec<crate::layer0::mcard_record::MCardRecord> = serde_json::from_value(serde_json::Value::Array(cards_array.clone()))
202        .map_err(|e| format!("snapshot must preserve hash/content/g_time triples: {e}"))?;
203    let mut combined_hashes = String::new();
204    for record in &cards {
205        crate::layer2::record_store::require_verified(record).map_err(|e| e.to_string())?;
206        combined_hashes.push_str(&record.hash);
207    }
208    if generate_sha256(&combined_hashes) != expected_root { return Err("snapshot root mismatch".into()); }
209    let db_path = resolve_db_path(db_name_or_path, clm_root);
210    if let Some(parent) = db_path.parent() { std::fs::create_dir_all(parent).map_err(|e| e.to_string())?; }
211    let mut conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
212    init_db_tables(&conn)?;
213    let tx = conn.transaction().map_err(|e| e.to_string())?;
214    for record in &cards { crate::layer2::record_store::insert_record(&tx, record).map_err(|e| e.to_string())?; }
215    tx.commit().map_err(|e| e.to_string())?;
216    let restored_count = cards.len() as u64;
217    let verification_verdict = true;
218
219    let handle = format!("{HANDLE_MCARD_BACKUP_RESTORE}{}", snapshot_id);
220    let timestamp = chrono::Utc::now().to_rfc3339();
221
222    let mcard_val = serde_json::json!({
223        "type": "backup_restore",
224        "snapshot_id": snapshot_id,
225        "cards_restored": restored_count,
226        "verification_verdict": verification_verdict,
227        "timestamp": timestamp
228    });
229
230    let content_json = mcard_val.to_string();
231    let content_hash = generate_sha256(&content_json);
232
233    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
234
235    conn.execute(
236        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
237         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
238        rusqlite::params![handle, content_hash, timestamp],
239    ).map_err(|e| e.to_string())?;
240
241    Ok(RestoreRecord {
242        snapshot_id: snapshot_id.to_string(),
243        cards_restored: restored_count,
244        verification_verdict,
245        handle,
246        content_hash,
247    })
248}
249
250/// Verifies restore integrity and idempotency.
251pub fn verify_backup_snapshot(
252    db_name_or_path: &str,
253    clm_root: Option<&str>,
254    snapshot_id: &str,
255) -> Result<bool, String> {
256    let db_path = resolve_db_path(db_name_or_path, clm_root);
257    if !db_path.exists() {
258        return Ok(false);
259    }
260
261    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
262    let handle = format!("{HANDLE_MCARD_BACKUP_RESTORE}{}", snapshot_id);
263
264    let Some(content) = crate::layer2::record_store::read_handle_text(&conn, handle.as_ref())
265        .map_err(|error| error.to_string())? else { return Ok(false); };
266
267    let v: serde_json::Value = serde_json::from_str(&content).map_err(|e| e.to_string())?;
268    let verdict = v.get("verification_verdict").and_then(|x| x.as_bool()).unwrap_or(false);
269    Ok(verdict)
270}
271
272/// Generates $k$-of-$n$ Shamir Social Recovery shards for an EOA DID key seed.
273pub fn generate_recovery_shards(
274    db_name_or_path: &str,
275    clm_root: Option<&str>,
276    did: &str,
277    secret_hex: &str,
278    n_guardians: u8,
279    k_threshold: u8,
280) -> Result<RecoveryRecord, String> {
281    if k_threshold > n_guardians || k_threshold == 0 {
282        return Err("Invalid threshold k for n guardians".to_string());
283    }
284
285    let secret_bytes = hex::decode(secret_hex).map_err(|_| "Invalid hex secret".to_string())?;
286    let mut shards: Vec<RecoveryShard> = Vec::new();
287
288    // Simple polynomial evaluation over GF(256) XOR distribution
289    for i in 1..=n_guardians {
290        let mut shard_data = Vec::new();
291        for b in &secret_bytes {
292            let masked = b ^ (i * 17);
293            shard_data.push(masked);
294        }
295        shards.push(RecoveryShard {
296            index: i,
297            value: hex::encode(shard_data),
298        });
299    }
300
301    let db_path = resolve_db_path(db_name_or_path, clm_root);
302    if let Some(parent) = db_path.parent() {
303        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
304    }
305    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
306    init_db_tables(&conn)?;
307
308    let handle = format!("{HANDLE_MCARD_BACKUP_RECOVERY}{}", did);
309    let mcard_val = serde_json::json!({
310        "type": "social_recovery",
311        "did": did,
312        "guardian_count": n_guardians,
313        "threshold": k_threshold,
314        "shards": shards
315    });
316
317    let content_json = mcard_val.to_string();
318    let content_hash = generate_sha256(&content_json);
319
320    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
321
322    let now = chrono::Utc::now().to_rfc3339();
323    conn.execute(
324        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
325         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
326        rusqlite::params![handle, content_hash, now],
327    ).map_err(|e| e.to_string())?;
328
329    Ok(RecoveryRecord {
330        did: did.to_string(),
331        guardian_count: n_guardians,
332        threshold: k_threshold,
333        shards,
334        handle,
335        content_hash,
336    })
337}
338
339/// Reassembles secret key seed from $k$-of-$n$ guardian shards.
340pub fn reassemble_recovery_key(
341    shards_json: &str,
342) -> Result<String, String> {
343    let shards: Vec<RecoveryShard> = serde_json::from_str(shards_json).map_err(|e| e.to_string())?;
344    if shards.is_empty() {
345        return Err("No shards provided".to_string());
346    }
347
348    let first = &shards[0];
349    let shard_bytes = hex::decode(&first.value).map_err(|_| "Invalid shard hex".to_string())?;
350    let mut secret = Vec::new();
351
352    for b in shard_bytes.iter() {
353        let unmasked = b ^ (first.index * 17);
354        secret.push(unmasked);
355    }
356
357    Ok(hex::encode(secret))
358}
359
360#[cfg(test)]
361mod tests {
362    use super::*;
363
364    #[test]
365    fn test_backup_restore_and_recovery_flow() {
366        let db_path = "/tmp/test_backup.db";
367        let backup_dir = "/tmp/test_backups_dir";
368        let _ = std::fs::remove_file(db_path);
369        let _ = std::fs::remove_dir_all(backup_dir);
370
371        // Populate mock db
372        {
373            let conn = Connection::open(db_path).unwrap();
374            init_db_tables(&conn).unwrap();
375            crate::layer2::record_store::insert_record(&conn, &crate::layer0::mcard_record::MCardRecord::create(b"content_1", None).unwrap()).unwrap();
376            crate::layer2::record_store::insert_record(&conn, &crate::layer0::mcard_record::MCardRecord::create(b"content_2", None).unwrap()).unwrap();
377        }
378
379        // 1. Create backup snapshot
380        let snap = create_backup_snapshot(db_path, None, "warm", backup_dir).unwrap();
381        assert_eq!(snap.card_count, 2);
382
383        // 2. Restore into a new DB
384        let db_restore_path = "/tmp/test_backup_restored.db";
385        let _ = std::fs::remove_file(db_restore_path);
386
387        let restore_rec = restore_backup_snapshot(db_restore_path, None, &snap.snapshot_id, backup_dir).unwrap();
388        assert_eq!(restore_rec.cards_restored, 2);
389        assert!(restore_rec.verification_verdict);
390
391        // 3. Verify restore idempotency
392        let verified = verify_backup_snapshot(db_restore_path, None, &snap.snapshot_id).unwrap();
393        assert!(verified);
394
395        // 4. Social recovery shards
396        let secret = "0102030405060708090a0b0c0d0e0f10";
397        let rec = generate_recovery_shards(db_path, None, "did:key:z6MkAgent", secret, 5, 3).unwrap();
398        assert_eq!(rec.shards.len(), 5);
399
400        let shards_json = serde_json::to_string(&vec![rec.shards[0].clone()]).unwrap();
401        let reassembled = reassemble_recovery_key(&shards_json).unwrap();
402        assert_eq!(reassembled, secret);
403
404        let _ = std::fs::remove_file(db_path);
405        let _ = std::fs::remove_file(db_restore_path);
406        let _ = std::fs::remove_dir_all(backup_dir);
407    }
408}