Skip to main content

clm_rust_core/
hash.rs

1//! Central content-hash module — upgradable hash function abstraction (INV-02).
2//!
3//! All content hashing in CLM must route through this module. The current default
4//! algorithm is SHA-256, but the `HashProvider` trait allows any conforming
5//! implementation to be substituted without changing call sites. Stored hash
6//! values carry an algorithm prefix (e.g. `sha256:<hex>`) so multiple algorithms
7//! can coexist in the same namespace.
8//!
9//! # Architecture
10//!
11//! ```text
12//! ┌─────────────────────────────────────────────────────────┐
13//! │                    HashConfig                            │
14//! │  active_algorithm: "sha256:"                             │
15//! │  collision_threshold: 2                                  │
16//! │  fallback_order: ["sha256:", "sha3-256:"]               │
17//! └──────────────────────┬──────────────────────────────────┘
18//!                        │
19//!                        ▼
20//! ┌─────────────────────────────────────────────────────────┐
21//! │               ProviderRegistry                           │
22//! │  "sha256:"    → Sha256Provider                           │
23//! │  "sha3-256:"  → Sha3_256Provider (future)               │
24//! └──────────────────────┬──────────────────────────────────┘
25//!                        │
26//!         ┌──────────────┼──────────────┐
27//!         ▼              ▼              ▼
28//!    raw_hash_*    prefixed_hash_*   verify_hash
29//!    (compute)     (compute+prefix)  (dispatch by prefix)
30//! ```
31//!
32//! Common function signature (matches Python `clm_hash_string`):
33//!   `fn(content: &[u8]) -> String`  →  raw hex digest, no prefix
34//!
35//! To get a prefixed hash (for storage), use `prefixed_hash_bytes` / `prefixed_hash_string`.
36
37use md5::Md5;
38use sha1::Sha1;
39use sha2::{Digest, Sha256, Sha512};
40use sha3::{Shake256, digest::{ExtendableOutput, XofReader}};
41use std::sync::{Mutex, OnceLock};
42
43// ── Constants ─────────────────────────────────────────────────────────────
44
45/// Algorithm prefix for BLAKE3 hash provider (INV-02).
46pub const BLAKE3_HASH_PREFIX: &str = "blake3:";
47
48/// Algorithm prefix for legacy SHA-256 hash provider.
49pub const SHA256_HASH_PREFIX: &str = "sha256:";
50
51/// Algorithm prefix for the default hash provider (BLAKE3 is default).
52pub const DEFAULT_HASH_PREFIX: &str = BLAKE3_HASH_PREFIX;
53
54/// Default collision threshold before triggering an algorithm upgrade.
55pub const DEFAULT_COLLISION_THRESHOLD: u32 = 2;
56
57// ── HashProvider trait ────────────────────────────────────────────────────
58
59/// Trait for pluggable content-hash algorithms.
60///
61/// Any type implementing this trait can serve as CLM's content hash function.
62/// The trait is intentionally minimal: `hash` returns the raw hex digest,
63/// and `prefix` returns the algorithm tag used in prefixed storage format.
64pub trait HashProvider: Send + Sync {
65    /// Compute the raw hex digest of `content`.
66    fn hash(&self, content: &[u8]) -> String;
67
68    /// Algorithm prefix (e.g. `"blake3:"`, `"sha256:"`).
69    fn prefix(&self) -> &'static str;
70
71    /// Compute the raw digest as a fixed-size byte array (for Merkle trees, etc.).
72    /// Default implementation parses the hex digest; providers may override
73    /// for efficiency.
74    fn hash_bytes(&self, content: &[u8]) -> [u8; 32] {
75        let hex = self.hash(content);
76        let mut out = [0u8; 32];
77        let bytes = hex.as_bytes();
78        for i in 0..32 {
79            out[i] = u8::from_str_radix(
80                std::str::from_utf8(&bytes[i * 2..i * 2 + 2]).unwrap_or("00"),
81                16,
82            )
83            .unwrap_or(0);
84        }
85        out
86    }
87}
88
89// ── Built-in providers ────────────────────────────────────────────────────
90
91/// Default BLAKE3 hash provider (INV-02: high-performance, tree-hashable 256-bit).
92pub struct Blake3Provider;
93
94impl HashProvider for Blake3Provider {
95    fn hash(&self, content: &[u8]) -> String {
96        blake3::hash(content).to_hex().to_string()
97    }
98
99    fn prefix(&self) -> &'static str {
100        BLAKE3_HASH_PREFIX
101    }
102
103    fn hash_bytes(&self, content: &[u8]) -> [u8; 32] {
104        *blake3::hash(content).as_bytes()
105    }
106}
107
108/// Legacy SHA-256 hash provider.
109pub struct Sha256Provider;
110
111impl HashProvider for Sha256Provider {
112    fn hash(&self, content: &[u8]) -> String {
113        let mut hasher = Sha256::new();
114        hasher.update(content);
115        format!("{:x}", hasher.finalize())
116    }
117
118    fn prefix(&self) -> &'static str {
119        SHA256_HASH_PREFIX
120    }
121
122    fn hash_bytes(&self, content: &[u8]) -> [u8; 32] {
123        let mut hasher = Sha256::new();
124        hasher.update(content);
125        hasher.finalize().into()
126    }
127}
128
129/// MD5 hash provider (weakest in the hierarchy, for legacy compatibility).
130pub struct Md5Provider;
131
132impl HashProvider for Md5Provider {
133    fn hash(&self, content: &[u8]) -> String {
134        let mut hasher = Md5::new();
135        hasher.update(content);
136        format!("{:x}", hasher.finalize())
137    }
138
139    fn prefix(&self) -> &'static str {
140        "md5:"
141    }
142}
143
144/// SHA-1 hash provider (legacy, for migration path compatibility).
145pub struct Sha1Provider;
146
147impl HashProvider for Sha1Provider {
148    fn hash(&self, content: &[u8]) -> String {
149        let mut hasher = Sha1::new();
150        hasher.update(content);
151        format!("{:x}", hasher.finalize())
152    }
153
154    fn prefix(&self) -> &'static str {
155        "sha1:"
156    }
157}
158
159/// SHA-512 hash provider (stronger than SHA-256).
160pub struct Sha512Provider;
161
162impl HashProvider for Sha512Provider {
163    fn hash(&self, content: &[u8]) -> String {
164        let mut hasher = Sha512::new();
165        hasher.update(content);
166        format!("{:x}", hasher.finalize())
167    }
168
169    fn prefix(&self) -> &'static str {
170        "sha512:"
171    }
172}
173
174/// Keccak SHAKE-256 provider with configurable output bit-length (`custom-N`).
175///
176/// Uses the SHAKE-256 extendable-output function (XOF) to produce a digest
177/// of `N` bits. The prefix is `custom-N:` (e.g. `custom-1024:`).
178/// This provides future-proofing: if `custom-N` is exhausted, upgrade to
179/// `custom-2N` by registering a new provider with doubled bit-length.
180pub struct Shake256Provider {
181    bits: usize,
182    prefix_str: &'static str,
183}
184
185impl Shake256Provider {
186    /// Create a new `custom-N` provider for the given bit-length.
187    ///
188    /// `bits` must be > 0. The byte-length of the digest is `(bits + 7) / 8`.
189    pub fn new(bits: usize) -> Self {
190        let prefix_str: &'static str = Box::leak(
191            format!("custom-{}:", bits).into_boxed_str(),
192        );
193        Self { bits, prefix_str }
194    }
195
196    fn byte_len(&self) -> usize {
197        self.bits.div_ceil(8)
198    }
199}
200
201impl HashProvider for Shake256Provider {
202    fn hash(&self, content: &[u8]) -> String {
203        let mut hasher = Shake256::default();
204        sha3::digest::Update::update(&mut hasher, content);
205        let mut reader = hasher.finalize_xof();
206        let byte_len = self.byte_len();
207        let mut buf = vec![0u8; byte_len];
208        reader.read(&mut buf);
209        hex::encode(&buf)
210    }
211
212    fn prefix(&self) -> &'static str {
213        self.prefix_str
214    }
215}
216
217// ── Provider registry (Step 2) ────────────────────────────────────────────
218
219/// Registry of available hash providers, keyed by algorithm prefix.
220///
221/// The registry allows multiple algorithms to coexist. New providers can be
222/// registered at startup or at runtime. The active algorithm (used for new
223/// content) is determined by `HashConfig.active_algorithm`.
224pub struct ProviderRegistry {
225    providers: Vec<(&'static str, Box<dyn HashProvider>)>,
226}
227
228impl ProviderRegistry {
229    fn new() -> Self {
230        Self {
231            providers: Vec::new(),
232        }
233    }
234
235    /// Register a new hash provider under its algorithm prefix.
236    pub fn register(&mut self, provider: Box<dyn HashProvider>) {
237        let prefix = provider.prefix();
238        self.providers.push((prefix, provider));
239    }
240
241    /// Look up a provider by algorithm prefix.
242    pub fn get(&self, prefix: &str) -> Option<&dyn HashProvider> {
243        self.providers
244            .iter()
245            .find(|(p, _)| *p == prefix)
246            .map(|(_, provider)| provider.as_ref())
247    }
248
249    /// Get the active provider (determined by `HashConfig`).
250    pub fn active(&self, active_prefix: &str) -> &dyn HashProvider {
251        self.get(active_prefix)
252            .unwrap_or_else(|| self.get(DEFAULT_HASH_PREFIX).expect("default provider must be registered"))
253    }
254
255    /// List all registered algorithm prefixes.
256    pub fn algorithms(&self) -> Vec<&'static str> {
257        self.providers.iter().map(|(p, _)| *p).collect()
258    }
259}
260
261pub fn global_registry() -> &'static Mutex<ProviderRegistry> {
262    static REGISTRY: OnceLock<Mutex<ProviderRegistry>> = OnceLock::new();
263    REGISTRY.get_or_init(|| {
264        let mut reg = ProviderRegistry::new();
265        reg.register(Box::new(Blake3Provider));
266        reg.register(Box::new(Sha256Provider));
267        reg.register(Box::new(Md5Provider));
268        reg.register(Box::new(Sha1Provider));
269        reg.register(Box::new(Sha512Provider));
270        Mutex::new(reg)
271    })
272}
273
274/// Register an additional hash provider at runtime.
275pub fn register_provider(provider: Box<dyn HashProvider>) {
276    let mut reg = global_registry().lock().unwrap();
277    reg.register(provider);
278}
279
280/// Register a `custom-N` (SHAKE-256) provider with the given bit-length.
281///
282/// Convenience wrapper around `register_provider` for the `custom-N` family.
283/// Example: `register_custom_provider(1024)` registers a `custom-1024:` provider.
284pub fn register_custom_provider(bits: usize) {
285    register_provider(Box::new(Shake256Provider::new(bits)));
286}
287
288/// Algorithm strength hierarchy (weakest → strongest).
289///
290/// Used by the collision remediation system to determine the next algorithm
291/// when the current one exceeds its collision threshold. For `custom-N`,
292/// the upgrade path is `custom-2N` (recursive doubling).
293pub const STRENGTH_HIERARCHY: &[&str] = &[
294    "md5:",
295    "sha1:",
296    "sha256:",
297    "blake3:",
298    "sha512:",
299    "custom-1024:",
300];
301
302/// Recommend the next stronger algorithm in the hierarchy.
303///
304/// If the current algorithm is `custom-N`, returns `custom-2N` (recursive doubling).
305/// If the current algorithm is not in the hierarchy, returns `blake3:` as a safe default.
306pub fn next_stronger_algorithm(current: &str) -> &'static str {
307    // Handle custom-N recursive doubling
308    if let Some(rest) = current.strip_prefix("custom-")
309        && let Some(num_str) = rest.strip_suffix(':')
310            && let Ok(n) = num_str.parse::<usize>() {
311                let doubled = n * 2;
312                return Box::leak(format!("custom-{}:", doubled).into_boxed_str());
313            }
314    // Find current in the standard hierarchy
315    let pos = STRENGTH_HIERARCHY.iter().position(|&algo| algo == current);
316    match pos {
317        Some(i) if i + 1 < STRENGTH_HIERARCHY.len() => STRENGTH_HIERARCHY[i + 1],
318        _ => DEFAULT_HASH_PREFIX,
319    }
320}
321
322/// List all registered algorithm prefixes.
323pub fn list_algorithms() -> Vec<&'static str> {
324    let reg = global_registry().lock().unwrap();
325    reg.algorithms()
326}
327
328// ── Hash configuration policy (Step 4) ────────────────────────────────────
329
330/// Configuration policy for hash algorithm selection and collision handling.
331///
332/// This struct governs:
333/// - Which algorithm is used for **new** content (`active_algorithm`)
334/// - How many collisions trigger an automatic upgrade (`collision_threshold`)
335/// - The order of fallback algorithms if the active one is compromised
336///
337/// The config is stored in a global `OnceLock` and can be loaded from a
338/// configuration file or environment variable at startup.
339#[derive(Debug, Clone)]
340pub struct HashConfig {
341    /// Algorithm prefix for new content (e.g. `"blake3:"`, `"sha256:"`).
342    pub active_algorithm: &'static str,
343    /// Number of collisions before triggering an upgrade.
344    pub collision_threshold: u32,
345    /// Ordered list of fallback algorithm prefixes.
346    /// If the active algorithm is compromised, the first available fallback
347    /// becomes the new active algorithm.
348    pub fallback_order: Vec<&'static str>,
349}
350
351impl Default for HashConfig {
352    fn default() -> Self {
353        Self {
354            active_algorithm: DEFAULT_HASH_PREFIX,
355            collision_threshold: DEFAULT_COLLISION_THRESHOLD,
356            fallback_order: vec![DEFAULT_HASH_PREFIX, SHA256_HASH_PREFIX],
357        }
358    }
359}
360
361impl HashConfig {
362    /// Load hash configuration from environment variables.
363    ///
364    /// Checks in order:
365    /// 1. `CLM_HASH_CONFIG`: `active_algorithm|collision_threshold|fallback1,fallback2,...`
366    ///    Example: `blake3:|2|blake3:,sha256:`
367    /// 2. `CLM_HASH_ALGO` / `MCARD_HASH_ALGORITHM`: simple string override (e.g. `blake3` or `sha256`)
368    ///
369    /// If unset or invalid, returns the default config (BLAKE3).
370    pub fn from_env() -> Self {
371        if let Ok(raw) = std::env::var("CLM_HASH_CONFIG") {
372            Self::parse_config(&raw)
373        } else if let Ok(algo) = std::env::var("CLM_HASH_ALGO")
374            .or_else(|_| std::env::var("MCARD_HASH_ALGORITHM"))
375        {
376            let trimmed = algo.trim();
377            let prefix = if trimmed.ends_with(':') {
378                trimmed.to_string()
379            } else {
380                format!("{}:", trimmed)
381            };
382            let leaked_prefix: &'static str = Box::leak(prefix.into_boxed_str());
383            Self {
384                active_algorithm: leaked_prefix,
385                collision_threshold: DEFAULT_COLLISION_THRESHOLD,
386                fallback_order: vec![leaked_prefix, SHA256_HASH_PREFIX],
387            }
388        } else {
389            Self::default()
390        }
391    }
392
393    fn parse_config(raw: &str) -> Self {
394        let parts: Vec<&str> = raw.splitn(3, '|').collect();
395        if parts.len() < 2 {
396            return Self::default();
397        }
398        let active = if parts[0].is_empty() {
399            DEFAULT_HASH_PREFIX
400        } else {
401            Box::leak(parts[0].to_string().into_boxed_str())
402        };
403        let threshold = parts[1].parse::<u32>().unwrap_or(DEFAULT_COLLISION_THRESHOLD);
404        let fallbacks: Vec<&'static str> = if parts.len() == 3 && !parts[2].is_empty() {
405            parts[2]
406                .split(',')
407                .map(|s| {
408                    if s.is_empty() {
409                        DEFAULT_HASH_PREFIX
410                    } else {
411                        Box::leak(s.to_string().into_boxed_str())
412                    }
413                })
414                .collect()
415        } else {
416            vec![active]
417        };
418        Self {
419            active_algorithm: active,
420            collision_threshold: threshold,
421            fallback_order: fallbacks,
422        }
423    }
424}
425
426fn global_config() -> &'static HashConfig {
427    static CONFIG: OnceLock<HashConfig> = OnceLock::new();
428    CONFIG.get_or_init(HashConfig::from_env)
429}
430
431/// Get the current hash configuration.
432pub fn config() -> &'static HashConfig {
433    global_config()
434}
435
436// ── Prefix-based dispatch (Step 3) ────────────────────────────────────────
437
438/// Extract the algorithm prefix from a stored hash string.
439///
440/// Returns `Some(prefix)` if the string contains a `:` separator,
441/// `None` if there is no prefix (assumed to be the default algorithm).
442pub fn extract_prefix(prefixed: &str) -> Option<&str> {
443    prefixed.find(':').map(|pos| &prefixed[..=pos])
444}
445
446/// Verify a stored hash against content by dispatching to the correct provider.
447///
448/// This function parses the algorithm prefix from `stored_hash`, looks up
449/// the corresponding provider in the registry, and checks whether the
450/// content matches.
451///
452/// Returns `Ok(())` if the hash matches, `Err(message)` if it doesn't
453/// or the provider is unknown.
454pub fn verify_hash(stored_hash: &str, content: &[u8]) -> Result<(), String> {
455    let prefix = extract_prefix(stored_hash).unwrap_or(DEFAULT_HASH_PREFIX);
456    let reg = global_registry().lock().unwrap();
457    let provider = reg.get(prefix).ok_or_else(|| {
458        format!("Unknown hash algorithm prefix: {} (registered: {:?})", prefix, reg.algorithms())
459    })?;
460    let computed = provider.hash(content);
461    let stored_raw = strip_prefix(stored_hash);
462    if computed == stored_raw {
463        Ok(())
464    } else {
465        Err(format!(
466            "Hash mismatch: expected {}..., got {}...",
467            &stored_raw[..stored_raw.len().min(16)],
468            &computed[..computed.len().min(16)]
469        ))
470    }
471}
472
473// ── Collision detection (Step 5) ──────────────────────────────────────────
474
475/// Result of a collision check.
476#[derive(Debug, Clone, PartialEq, Eq)]
477pub enum CollisionCheckResult {
478    /// No collision — the hash is unique.
479    NoCollision,
480    /// Collision detected — the same hash already exists with different content.
481    Collision { hash: String, collision_count: u32 },
482    /// Threshold exceeded — the active algorithm should be upgraded.
483    ThresholdExceeded {
484        hash: String,
485        collision_count: u32,
486        recommended_algorithm: &'static str,
487    },
488}
489
490/// Check whether a hash collision has occurred and whether the threshold
491/// for algorithm upgrade has been exceeded.
492///
493/// Callers should invoke this *before* inserting a new card into the database.
494/// If `existing_content` is `Some` and differs from `new_content`, a collision
495/// is recorded. When the collision count for the active algorithm reaches
496/// `config().collision_threshold`, a `ThresholdExceeded` result is returned
497/// with the recommended fallback algorithm.
498pub fn check_collision(
499    hash: &str,
500    new_content: &[u8],
501    existing_content: Option<&[u8]>,
502    collision_count: u32,
503) -> CollisionCheckResult {
504    match existing_content {
505        None => CollisionCheckResult::NoCollision,
506        Some(existing) if existing == new_content => CollisionCheckResult::NoCollision,
507        Some(_) => {
508            let count = collision_count + 1;
509            let cfg = config();
510            if count >= cfg.collision_threshold {
511                // Find the first fallback that isn't the current active algorithm
512                let recommended = cfg
513                    .fallback_order
514                    .iter()
515                    .find(|&&algo| algo != cfg.active_algorithm)
516                    .copied()
517                    .unwrap_or(cfg.active_algorithm);
518                CollisionCheckResult::ThresholdExceeded {
519                    hash: hash.to_string(),
520                    collision_count: count,
521                    recommended_algorithm: recommended,
522                }
523            } else {
524                CollisionCheckResult::Collision {
525                    hash: hash.to_string(),
526                    collision_count: count,
527                }
528            }
529        }
530    }
531}
532
533// ── Convenience functions (delegate to the active provider) ──────────────
534
535/// Compute the raw hex digest of bytes using the active provider (no prefix).
536///
537/// This is the canonical "common function signature" shared with Python's
538/// `clm_hash_string`: `fn(content: &[u8]) -> String`.
539pub fn raw_hash_bytes(content: &[u8]) -> String {
540    let reg = global_registry().lock().unwrap();
541    reg.active(config().active_algorithm).hash(content)
542}
543
544/// Compute the raw hex digest of a string using the active provider (no prefix).
545pub fn raw_hash_string(s: &str) -> String {
546    raw_hash_bytes(s.as_bytes())
547}
548
549/// Compute the raw digest as a 32-byte array using the active provider.
550///
551/// Used by Merkle tree and type lattice code that needs the raw bytes
552/// rather than a hex string.
553pub fn raw_hash_bytes_32(content: &[u8]) -> [u8; 32] {
554    let reg = global_registry().lock().unwrap();
555    reg.active(config().active_algorithm).hash_bytes(content)
556}
557
558/// Compute the prefixed hash of bytes (e.g. `"sha256:<hex>"`).
559pub fn prefixed_hash_bytes(content: &[u8]) -> String {
560    let reg = global_registry().lock().unwrap();
561    let provider = reg.active(config().active_algorithm);
562    format!("{}{}", provider.prefix(), provider.hash(content))
563}
564
565/// Compute the prefixed hash of a string (e.g. `"sha256:<hex>"`).
566pub fn prefixed_hash_string(s: &str) -> String {
567    prefixed_hash_bytes(s.as_bytes())
568}
569
570/// Prepend the active algorithm prefix to an already-computed raw hex digest.
571pub fn prefixed(raw_hex: &str) -> String {
572    format!("{}{}", config().active_algorithm, raw_hex)
573}
574
575/// Strip a known algorithm prefix from a hash string.
576///
577/// If the hash starts with a known algorithm prefix (or any `<algo>:` pattern),
578/// the unprefixed hex is returned. Otherwise the input is returned as-is.
579pub fn strip_prefix(prefixed: &str) -> &str {
580    // Try the active algorithm prefix first
581    let active = config().active_algorithm;
582    if let Some(rest) = prefixed.strip_prefix(active) {
583        return rest;
584    }
585    // Try the default prefix
586    if let Some(rest) = prefixed.strip_prefix(DEFAULT_HASH_PREFIX) {
587        return rest;
588    }
589    // Generic fallback: strip any `<algo>:` prefix
590    if let Some(pos) = prefixed.find(':')
591        && pos + 1 < prefixed.len() {
592            return &prefixed[pos + 1..];
593        }
594    prefixed
595}
596
597/// Returns the default hash provider (currently `Blake3Provider`).
598///
599/// Kept for backward compatibility — prefer `raw_hash_bytes` / `raw_hash_string`.
600pub fn default_provider() -> impl HashProvider {
601    Blake3Provider
602}
603
604// ── Content-equivalence operator (Gap 2) ──────────────────────────────────
605
606/// Check whether two hashes point to the same content in the CAS.
607///
608/// This is the Rust equivalent of the shell `clm_content_equivalent` operator.
609/// Two hashes generated by different algorithms (e.g. `sha256:abc` and
610/// `sha512:def`) will never match as strings, but they may point to the same
611/// underlying content. This function resolves both hashes to their stored
612/// content and compares the raw bytes.
613///
614/// Returns `Ok(true)` if both hashes exist and point to identical content,
615/// `Ok(false)` if they differ or one is not found, `Err` on DB error.
616#[cfg(feature = "native")]
617pub fn content_equivalent(
618    conn: &rusqlite::Connection,
619    hash_a: &str,
620    hash_b: &str,
621) -> Result<bool, String> {
622    if hash_a == hash_b {
623        return Ok(true);
624    }
625    let content_a: Option<Vec<u8>> = conn
626        .query_row(
627            "SELECT content FROM card WHERE hash = ?",
628            rusqlite::params![hash_a],
629            |row| row.get(0),
630        )
631        .ok();
632    let content_b: Option<Vec<u8>> = conn
633        .query_row(
634            "SELECT content FROM card WHERE hash = ?",
635            rusqlite::params![hash_b],
636            |row| row.get(0),
637        )
638        .ok();
639    match (content_a, content_b) {
640        (Some(a), Some(b)) => Ok(a == b),
641        _ => Ok(false),
642    }
643}
644
645// ── Handle migration lifecycle (Gap 3) ────────────────────────────────────
646
647/// Migrate a handle to use a different hash algorithm.
648///
649/// This is the Rust equivalent of the shell `clm_migrate_handle_hash` operator.
650/// It resolves the handle to its current hash, retrieves the content from the
651/// CAS, computes a new hash under the target algorithm, and transactionally
652/// inserts the new card, records handle history, and updates the handle pointer.
653///
654/// # Arguments
655/// * `conn` - SQLite connection to the content_memory database.
656/// * `handle` - The handle name to migrate (e.g. `"test:migration_handle"`).
657/// * `target_algo` - Target algorithm prefix (e.g. `"sha256:"`, `"custom-1024:"`).
658///   Must be a registered provider.
659///
660/// Returns `Ok(new_hash)` on success, `Err(message)` on failure.
661#[cfg(feature = "native")]
662pub fn migrate_handle_hash(
663    conn: &mut rusqlite::Connection,
664    handle: &str,
665    target_algo: &str,
666) -> Result<String, String> {
667    // Validate target algorithm is registered
668    {
669        let reg = global_registry().lock().unwrap();
670        if reg.get(target_algo).is_none() {
671            return Err(format!(
672                "Unsupported target algorithm: '{}' (registered: {:?})",
673                target_algo,
674                reg.algorithms()
675            ));
676        }
677    }
678
679    // 1. Resolve handle to get current hash
680    let current_hash: String = conn
681        .query_row(
682            "SELECT current_hash FROM handle_registry WHERE handle = ?",
683            rusqlite::params![handle],
684            |row| row.get(0),
685        )
686        .map_err(|_| format!("Handle '{}' not found in handle_registry", handle))?;
687
688    // 2. Retrieve existing content
689    let content: Vec<u8> = conn
690        .query_row(
691            "SELECT content FROM card WHERE hash = ?",
692            rusqlite::params![current_hash],
693            |row| row.get(0),
694        )
695        .map_err(|_| {
696            format!(
697                "Content not found in CAS for hash '{}'",
698                current_hash
699            )
700        })?;
701
702    // 3. Compute new hash under target algorithm
703    let reg = global_registry().lock().unwrap();
704    let provider = reg.get(target_algo).ok_or_else(|| {
705        format!("Provider not found for algorithm '{}'", target_algo)
706    })?;
707    let new_raw_hash = provider.hash(&content);
708    let new_hash = format!("{}{}", provider.prefix(), new_raw_hash);
709    drop(reg); // Release the lock before DB transaction
710
711    // 4. Transactional update with retry for WAL lock contention
712    let now_utc = chrono::Utc::now().to_rfc3339();
713    let algo_name = target_algo.trim_end_matches(':');
714    let g_time = format!("{}|{}|UTC", algo_name, now_utc);
715
716    let max_attempts = 3;
717    let mut last_err = String::new();
718    for attempt in 0..max_attempts {
719        let tx = match conn.transaction() {
720            Ok(tx) => tx,
721            Err(e) => {
722                last_err = e.to_string();
723                std::thread::sleep(std::time::Duration::from_millis(200));
724                continue;
725            }
726        };
727        let result = (|| {
728            tx.execute(
729                "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?, ?, ?)",
730                rusqlite::params![new_hash, &content, &g_time],
731            )
732            .map_err(|e| e.to_string())?;
733            tx.execute(
734                "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?, ?, ?)",
735                rusqlite::params![handle, &current_hash, &now_utc],
736            )
737            .map_err(|e| e.to_string())?;
738            tx.execute(
739                "UPDATE handle_registry SET current_hash = ?, updated_at = ? WHERE handle = ?",
740                rusqlite::params![&new_hash, &now_utc, handle],
741            )
742            .map_err(|e| e.to_string())?;
743            tx.commit().map_err(|e| e.to_string())
744        })();
745
746        match result {
747            Ok(()) => return Ok(new_hash),
748            Err(e) => {
749                last_err = e;
750                if attempt + 1 < max_attempts {
751                    std::thread::sleep(std::time::Duration::from_millis(200));
752                }
753            }
754        }
755    }
756
757    Err(format!("Transaction failed after {} attempts: {}", max_attempts, last_err))
758}
759
760#[cfg(test)]
761mod tests {
762    use super::*;
763
764    #[test]
765    fn test_raw_hash_bytes() {
766        // Default active algorithm is blake3:
767        assert_eq!(
768            raw_hash_bytes(b"hello"),
769            "ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f"
770        );
771    }
772
773    #[test]
774    fn test_sha256_provider() {
775        let provider = Sha256Provider;
776        assert_eq!(
777            provider.hash(b"hello"),
778            "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
779        );
780    }
781
782    #[test]
783    fn test_raw_hash_string() {
784        assert_eq!(
785            raw_hash_string("hello"),
786            "ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f"
787        );
788    }
789
790    #[test]
791    fn test_raw_hash_bytes_32() {
792        let expected = [
793            0xea, 0x8f, 0x16, 0x3d, 0xb3, 0x86, 0x82, 0x92, 0x5e, 0x44, 0x91, 0xc5, 0xe5, 0x8d,
794            0x4b, 0xb3, 0x50, 0x6e, 0xf8, 0xc1, 0x4e, 0xb7, 0x8a, 0x86, 0xe9, 0x08, 0xc5, 0x62,
795            0x4a, 0x67, 0x20, 0x0f,
796        ];
797        assert_eq!(raw_hash_bytes_32(b"hello"), expected);
798    }
799
800    #[test]
801    fn test_prefixed_hash_string() {
802        let h = prefixed_hash_string("hello");
803        assert!(h.starts_with("blake3:"));
804        assert_eq!(
805            h,
806            "blake3:ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f"
807        );
808    }
809
810    #[test]
811    fn test_strip_prefix() {
812        assert_eq!(strip_prefix("sha256:abcdef"), "abcdef");
813        assert_eq!(strip_prefix("sha3-256:abcdef"), "abcdef");
814        assert_eq!(strip_prefix("noprefix"), "noprefix");
815    }
816
817    #[test]
818    fn test_extract_prefix() {
819        assert_eq!(extract_prefix("sha256:abc"), Some("sha256:"));
820        assert_eq!(extract_prefix("sha3-256:abc"), Some("sha3-256:"));
821        assert_eq!(extract_prefix("noprefix"), None);
822    }
823
824    #[test]
825    fn test_verify_hash_match() {
826        let content = b"hello";
827        let stored = prefixed_hash_bytes(content);
828        assert!(verify_hash(&stored, content).is_ok());
829    }
830
831    #[test]
832    fn test_verify_hash_mismatch() {
833        let stored = prefixed_hash_bytes(b"hello");
834        assert!(verify_hash(&stored, b"world").is_err());
835    }
836
837    #[test]
838    fn test_verify_hash_unknown_prefix() {
839        assert!(verify_hash("unknown:abc", b"hello").is_err());
840    }
841
842    #[test]
843    fn test_provider_registry() {
844        let algorithms = list_algorithms();
845        assert!(algorithms.contains(&"sha256:"));
846    }
847
848    #[test]
849    fn test_collision_no_collision() {
850        let result = check_collision("abc", b"hello", None, 0);
851        assert_eq!(result, CollisionCheckResult::NoCollision);
852    }
853
854    #[test]
855    fn test_collision_same_content() {
856        let result = check_collision("abc", b"hello", Some(b"hello"), 0);
857        assert_eq!(result, CollisionCheckResult::NoCollision);
858    }
859
860    #[test]
861    fn test_collision_detected() {
862        let result = check_collision("abc", b"hello", Some(b"world"), 0);
863        assert_eq!(
864            result,
865            CollisionCheckResult::Collision {
866                hash: "abc".to_string(),
867                collision_count: 1
868            }
869        );
870    }
871
872    #[test]
873    fn test_collision_threshold_exceeded() {
874        let result = check_collision("abc", b"hello", Some(b"world"), 1);
875        match result {
876            CollisionCheckResult::ThresholdExceeded {
877                recommended_algorithm,
878                ..
879            } => {
880                // With default config, fallback order is ["blake3:", "sha256:"], so recommended == sha256:
881                assert_eq!(recommended_algorithm, "sha256:");
882            }
883            other => panic!("Expected ThresholdExceeded, got {:?}", other),
884        }
885    }
886
887    #[test]
888    fn test_hash_config_default() {
889        let cfg = HashConfig::default();
890        assert_eq!(cfg.active_algorithm, DEFAULT_HASH_PREFIX);
891        assert_eq!(cfg.collision_threshold, DEFAULT_COLLISION_THRESHOLD);
892    }
893
894    #[test]
895    fn test_hash_config_parse() {
896        let cfg = HashConfig::parse_config("sha256:|3|sha256:,sha3-256:");
897        assert_eq!(cfg.active_algorithm, "sha256:");
898        assert_eq!(cfg.collision_threshold, 3);
899        assert_eq!(cfg.fallback_order, vec!["sha256:", "sha3-256:"]);
900    }
901
902    #[test]
903    fn test_shake256_provider() {
904        let provider = Shake256Provider::new(256);
905        let h = provider.hash(b"hello");
906        // 256 bits = 32 bytes = 64 hex chars
907        assert_eq!(h.len(), 64);
908        assert_eq!(provider.prefix(), "custom-256:");
909    }
910
911    #[test]
912    fn test_shake256_provider_1024() {
913        let provider = Shake256Provider::new(1024);
914        let h = provider.hash(b"hello");
915        // 1024 bits = 128 bytes = 256 hex chars
916        assert_eq!(h.len(), 256);
917        assert_eq!(provider.prefix(), "custom-1024:");
918    }
919
920    #[test]
921    fn test_register_custom_provider() {
922        register_custom_provider(512);
923        let algorithms = list_algorithms();
924        assert!(algorithms.contains(&"custom-512:"));
925    }
926
927    #[test]
928    fn test_next_stronger_algorithm() {
929        assert_eq!(next_stronger_algorithm("md5:"), "sha1:");
930        assert_eq!(next_stronger_algorithm("sha1:"), "sha256:");
931        assert_eq!(next_stronger_algorithm("sha256:"), "blake3:");
932        assert_eq!(next_stronger_algorithm("blake3:"), "sha512:");
933        assert_eq!(next_stronger_algorithm("sha512:"), "custom-1024:");
934    }
935
936    #[test]
937    fn test_next_stronger_custom_doubling() {
938        assert_eq!(next_stronger_algorithm("custom-1024:"), "custom-2048:");
939        assert_eq!(next_stronger_algorithm("custom-2048:"), "custom-4096:");
940    }
941
942    #[test]
943    fn test_verify_hash_custom_n() {
944        register_custom_provider(256);
945        let provider = Shake256Provider::new(256);
946        let content = b"hello";
947        let raw = provider.hash(content);
948        let prefixed = format!("custom-256:{}", raw);
949        assert!(verify_hash(&prefixed, content).is_ok());
950        assert!(verify_hash(&prefixed, b"world").is_err());
951    }
952
953    #[test]
954    fn test_md5_provider() {
955        let provider = Md5Provider;
956        let h = provider.hash(b"hello");
957        assert_eq!(h.len(), 32); // 128 bits = 16 bytes = 32 hex chars
958        assert_eq!(h, "5d41402abc4b2a76b9719d911017c592");
959        assert_eq!(provider.prefix(), "md5:");
960    }
961
962    #[test]
963    fn test_sha1_provider() {
964        let provider = Sha1Provider;
965        let h = provider.hash(b"hello");
966        assert_eq!(h.len(), 40); // 160 bits = 20 bytes = 40 hex chars
967        assert_eq!(h, "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d");
968        assert_eq!(provider.prefix(), "sha1:");
969    }
970
971    #[test]
972    fn test_sha512_provider() {
973        let provider = Sha512Provider;
974        let h = provider.hash(b"hello");
975        assert_eq!(h.len(), 128); // 512 bits = 64 bytes = 128 hex chars
976        assert_eq!(
977            h,
978            "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"
979        );
980        assert_eq!(provider.prefix(), "sha512:");
981    }
982
983    #[test]
984    fn test_blake3_provider() {
985        let provider = Blake3Provider;
986        let h = provider.hash(b"hello");
987        // 256 bits = 32 bytes = 64 hex chars
988        assert_eq!(h.len(), 64);
989        assert_eq!(
990            h,
991            "ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f"
992        );
993        assert_eq!(provider.prefix(), "blake3:");
994    }
995
996    #[test]
997    fn test_all_providers_registered() {
998        let algorithms = list_algorithms();
999        assert!(algorithms.contains(&"blake3:"));
1000        assert!(algorithms.contains(&"sha256:"));
1001        assert!(algorithms.contains(&"md5:"));
1002        assert!(algorithms.contains(&"sha1:"));
1003        assert!(algorithms.contains(&"sha512:"));
1004    }
1005
1006    #[test]
1007    fn test_verify_hash_blake3() {
1008        let provider = Blake3Provider;
1009        let content = b"hello";
1010        let prefixed = format!("blake3:{}", provider.hash(content));
1011        assert!(verify_hash(&prefixed, content).is_ok());
1012        assert!(verify_hash(&prefixed, b"world").is_err());
1013    }
1014
1015    #[test]
1016    fn test_verify_hash_md5() {
1017        let provider = Md5Provider;
1018        let content = b"hello";
1019        let prefixed = format!("md5:{}", provider.hash(content));
1020        assert!(verify_hash(&prefixed, content).is_ok());
1021        assert!(verify_hash(&prefixed, b"world").is_err());
1022    }
1023
1024    #[test]
1025    fn test_verify_hash_sha512() {
1026        let provider = Sha512Provider;
1027        let content = b"hello";
1028        let prefixed = format!("sha512:{}", provider.hash(content));
1029        assert!(verify_hash(&prefixed, content).is_ok());
1030        assert!(verify_hash(&prefixed, b"world").is_err());
1031    }
1032
1033    #[test]
1034    #[cfg(feature = "native")]
1035    fn test_migrate_through_hierarchy() {
1036        use rusqlite::Connection;
1037        register_custom_provider(1024);
1038        let mut conn = Connection::open_in_memory().unwrap();
1039        conn.execute_batch(
1040            "CREATE TABLE card (hash TEXT PRIMARY KEY, content BLOB NOT NULL, g_time TEXT NOT NULL);
1041             CREATE TABLE handle_registry (handle TEXT PRIMARY KEY, current_hash TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
1042             CREATE TABLE handle_history (handle TEXT NOT NULL, previous_hash TEXT NOT NULL, changed_at TEXT NOT NULL);",
1043        ).unwrap();
1044        let content = b"hierarchy_test_payload";
1045        let h = prefixed_hash_bytes(content);
1046        conn.execute("INSERT INTO card (hash, content, g_time) VALUES (?, ?, '2025-01-01')", rusqlite::params![h, content]).unwrap();
1047        conn.execute("INSERT INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, '2025-01-01', '2025-01-01')", rusqlite::params!["test:hier_handle", h]).unwrap();
1048        // Migrate sha256 -> sha512
1049        let h512 = migrate_handle_hash(&mut conn, "test:hier_handle", "sha512:").unwrap();
1050        assert!(h512.starts_with("sha512:"));
1051        assert!(content_equivalent(&conn, &h, &h512).unwrap());
1052        // Migrate sha512 -> custom-1024
1053        let h_custom = migrate_handle_hash(&mut conn, "test:hier_handle", "custom-1024:").unwrap();
1054        assert!(h_custom.starts_with("custom-1024:"));
1055        assert!(content_equivalent(&conn, &h, &h_custom).unwrap());
1056        // Verify 3 cards coexist
1057        let count: i64 = conn.query_row("SELECT count(*) FROM card WHERE hash IN (?, ?, ?)", rusqlite::params![h, h512, h_custom], |r| r.get(0)).unwrap();
1058        assert_eq!(count, 3);
1059        // Verify 2 history entries
1060        let hist: i64 = conn.query_row("SELECT count(*) FROM handle_history WHERE handle = 'test:hier_handle'", [], |r| r.get(0)).unwrap();
1061        assert_eq!(hist, 2);
1062    }
1063
1064    #[test]
1065    #[cfg(feature = "native")]
1066    fn test_content_equivalent() {
1067        use rusqlite::Connection;
1068        let conn = Connection::open_in_memory().unwrap();
1069        conn.execute(
1070            "CREATE TABLE card (hash TEXT PRIMARY KEY, content BLOB NOT NULL, g_time TEXT NOT NULL)",
1071            [],
1072        )
1073        .unwrap();
1074        let content = b"hello world";
1075        let hash_a = "sha256:aaa";
1076        let hash_b = "sha512:bbb";
1077        let hash_c = "sha256:ccc";
1078        conn.execute(
1079            "INSERT INTO card (hash, content, g_time) VALUES (?, ?, '2025-01-01')",
1080            rusqlite::params![hash_a, content],
1081        )
1082        .unwrap();
1083        conn.execute(
1084            "INSERT INTO card (hash, content, g_time) VALUES (?, ?, '2025-01-01')",
1085            rusqlite::params![hash_b, content],
1086        )
1087        .unwrap();
1088        conn.execute(
1089            "INSERT INTO card (hash, content, g_time) VALUES (?, ?, '2025-01-01')",
1090            rusqlite::params![hash_c, b"different"],
1091        )
1092        .unwrap();
1093
1094        // Same content, different hashes → equivalent
1095        assert_eq!(content_equivalent(&conn, hash_a, hash_b).unwrap(), true);
1096        // Same hash → equivalent
1097        assert_eq!(content_equivalent(&conn, hash_a, hash_a).unwrap(), true);
1098        // Different content → not equivalent
1099        assert_eq!(content_equivalent(&conn, hash_a, hash_c).unwrap(), false);
1100        // Missing hash → not equivalent
1101        assert_eq!(content_equivalent(&conn, hash_a, "missing").unwrap(), false);
1102    }
1103
1104    #[test]
1105    #[cfg(feature = "native")]
1106    fn test_migrate_handle_hash() {
1107        use rusqlite::Connection;
1108        register_custom_provider(256);
1109        let mut conn = Connection::open_in_memory().unwrap();
1110        conn.execute_batch(
1111            "CREATE TABLE card (hash TEXT PRIMARY KEY, content BLOB NOT NULL, g_time TEXT NOT NULL);
1112             CREATE TABLE handle_registry (handle TEXT PRIMARY KEY, current_hash TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
1113             CREATE TABLE handle_history (handle TEXT NOT NULL, previous_hash TEXT NOT NULL, changed_at TEXT NOT NULL);",
1114        ).unwrap();
1115        let content = b"migration_test_payload";
1116        let h = prefixed_hash_bytes(content);
1117        conn.execute("INSERT INTO card (hash, content, g_time) VALUES (?, ?, '2025-01-01')", rusqlite::params![h, content]).unwrap();
1118        conn.execute("INSERT INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, '2025-01-01', '2025-01-01')", rusqlite::params!["test:handle", h]).unwrap();
1119        let new_h = migrate_handle_hash(&mut conn, "test:handle", "custom-256:").unwrap();
1120        assert!(new_h.starts_with("custom-256:"));
1121        let updated: String = conn.query_row("SELECT current_hash FROM handle_registry WHERE handle = 'test:handle'", [], |r| r.get(0)).unwrap();
1122        assert_eq!(updated, new_h);
1123        let hist: i64 = conn.query_row("SELECT count(*) FROM handle_history WHERE handle = 'test:handle'", [], |r| r.get(0)).unwrap();
1124        assert_eq!(hist, 1);
1125        assert!(content_equivalent(&conn, &h, &new_h).unwrap());
1126    }
1127}