Skip to main content

clm_rust_core/layer2/
uri.rs

1//! MCard URI parsing and canonicalization utilities (INV-552).
2
3use serde::{Deserialize, Serialize};
4
5#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
6pub enum McardUriType {
7    Hash,
8    Handle,
9}
10
11pub type McardUriKind = McardUriType;
12
13#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
14pub struct ParsedMcardUri {
15    pub uri_type: McardUriType,
16    pub target: String,
17    pub fragment: Option<String>,
18    pub original: String,
19}
20
21pub type McardUri = ParsedMcardUri;
22
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct TransclusionCycleError {
25    pub cycle_path: Vec<String>,
26}
27
28impl std::fmt::Display for TransclusionCycleError {
29    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
30        write!(f, "Transclusion cycle detected: {}", self.cycle_path.join(" -> "))
31    }
32}
33
34impl std::error::Error for TransclusionCycleError {}
35
36pub fn canonicalize_mcard_uri(path: &str, context_prefix: &str) -> String {
37    let clean = path.trim_start_matches('/');
38    let mut prefix = context_prefix.trim_matches('/');
39    if prefix == "mcard" {
40        prefix = "";
41    }
42    if let Some(rest) = clean.strip_prefix("mcard:") {
43        let rest = rest.trim_start_matches('/');
44        if prefix.is_empty() || rest == prefix || rest.starts_with(&format!("{prefix}/")) {
45            return format!("mcard:{rest}");
46        }
47        return format!("mcard:{prefix}/{rest}");
48    }
49    if prefix.is_empty() {
50        format!("mcard:{clean}")
51    } else {
52        format!("mcard:{prefix}/{clean}")
53    }
54}
55
56pub fn is_qualified_hash(value: &str) -> bool {
57    let Some((algo, hex)) = value.split_once(':') else {
58        return false;
59    };
60    matches!(algo, "blake3" | "sha256" | "sha512" | "sha3-256" | "sha1" | "md5")
61        && (32..=128).contains(&hex.len())
62        && hex.chars().all(|c| c.is_ascii_hexdigit())
63}
64
65pub fn format_mcard_uri(parsed: &ParsedMcardUri) -> String {
66    let frag = parsed
67        .fragment
68        .as_ref()
69        .map(|f| format!("#{}", f.trim_start_matches('#')))
70        .unwrap_or_default();
71    let kind = match parsed.uri_type {
72        McardUriType::Hash => "hash",
73        McardUriType::Handle => "handle",
74    };
75    format!("mcard://{kind}/{}{frag}", parsed.target)
76}
77
78pub fn parse_mcard_uri(uri: &str) -> std::result::Result<ParsedMcardUri, String> {
79    if uri.is_empty() {
80        return Err("Invalid MCard URI: expected non-empty string".to_string());
81    }
82    let (base, fragment) = match uri.split_once('#') {
83        Some((base, frag)) => (base, Some(frag.to_string())),
84        None => (uri, None),
85    };
86    if let Some(target) = base.strip_prefix("mcard://hash/") {
87        let target = target.trim_end_matches('/');
88        if !target.contains(':') {
89            return Err(format!("Malformed hash URI: expected '<algorithm>:<hex>', got '{target}'"));
90        }
91        return Ok(ParsedMcardUri {
92            uri_type: McardUriType::Hash,
93            target: target.to_string(),
94            fragment,
95            original: uri.to_string(),
96        });
97    }
98    if let Some(rest) = base.strip_prefix("mcard://handle/") {
99        let raw = rest.split('?').next().unwrap_or(rest).trim_end_matches('/');
100        return Ok(ParsedMcardUri {
101            uri_type: McardUriType::Handle,
102            target: canonicalize_mcard_uri(raw, ""),
103            fragment,
104            original: uri.to_string(),
105        });
106    }
107    if base.starts_with("mcard://receipts/") || base.starts_with("mcard://schemas/") {
108        let raw = base.trim_start_matches("mcard://").trim_end_matches('/');
109        return Ok(ParsedMcardUri {
110            uri_type: McardUriType::Handle,
111            target: canonicalize_mcard_uri(raw, ""),
112            fragment,
113            original: uri.to_string(),
114        });
115    }
116    if let Some(raw) = base.strip_prefix("mcard://") {
117        let raw = raw.trim_end_matches('/');
118        if is_qualified_hash(raw) {
119            return Ok(ParsedMcardUri {
120                uri_type: McardUriType::Hash,
121                target: raw.to_lowercase(),
122                fragment,
123                original: uri.to_string(),
124            });
125        }
126        return Ok(ParsedMcardUri {
127            uri_type: McardUriType::Handle,
128            target: canonicalize_mcard_uri(raw, ""),
129            fragment,
130            original: uri.to_string(),
131        });
132    }
133    Ok(ParsedMcardUri {
134        uri_type: McardUriType::Handle,
135        target: canonicalize_mcard_uri(base, ""),
136        fragment,
137        original: uri.to_string(),
138    })
139}
140
141pub fn validate_transclusion_chain(
142    chain: &[String],
143    next_ref: &str,
144) -> std::result::Result<(), TransclusionCycleError> {
145    let next = next_ref.to_lowercase();
146    if chain.iter().any(|ref_| ref_.to_lowercase() == next) {
147        let mut cycle_path = chain.to_vec();
148        cycle_path.push(next_ref.to_string());
149        return Err(TransclusionCycleError { cycle_path });
150    }
151    Ok(())
152}