Skip to main content

qualia_core_db/semantic_instruments/
package.rs

1//! Logical collectable: HMC archive of HCF + definition N3 + `.10d` visual.
2//!
3//! Large Q42 volumes are dependencies, not this package. Native builds may also
4//! embed a small `.q42` compiled from the definition graph.
5
6use crate::bundle::{BundleReader, BundleWriter};
7
8use super::canonical::{canonical_manifest_bytes, sha256_prefixed};
9use super::errors::InstrumentError;
10use super::manifest::InstrumentManifest;
11use super::visual::{demo_badge_10d, VISUAL_MEDIA_TYPE};
12
13pub const KEY_MANIFEST: &str = "manifest.json";
14pub const KEY_HCF: &str = "instrument.hcf";
15pub const KEY_GRAPH: &str = "graphs/instrument-definition.n3";
16pub const KEY_VISUAL: &str = "assets/badge.10d";
17pub const KEY_Q42: &str = "graphs/instrument.q42";
18
19pub const MAX_COLLECTABLE_BYTES: usize = 8 * 1024 * 1024;
20pub const MAX_MEMBER_BYTES: usize = 2 * 1024 * 1024;
21pub const MAX_MEMBERS: usize = 16;
22
23/// Parts of one collectable before digest is sealed.
24pub struct CollectableParts {
25    pub manifest: InstrumentManifest,
26    pub definition_n3: Vec<u8>,
27    pub hcf: Vec<u8>,
28    pub visual_10d: Vec<u8>,
29    pub small_q42: Option<Vec<u8>>,
30}
31
32/// Opened HMC collectable.
33#[derive(Debug, Clone)]
34pub struct OpenedCollectable {
35    pub manifest: InstrumentManifest,
36    pub definition_n3: Vec<u8>,
37    pub hcf: Vec<u8>,
38    pub visual_10d: Vec<u8>,
39    pub small_q42: Option<Vec<u8>>,
40    pub bundle_digest: String,
41}
42
43fn reject_unsafe_key(key: &str) -> Result<(), InstrumentError> {
44    if key.is_empty()
45        || key.starts_with('/')
46        || key.starts_with('\\')
47        || key.contains("..")
48        || key.contains('\\')
49        || key.contains('\0')
50    {
51        return Err(InstrumentError::PathTraversal);
52    }
53    Ok(())
54}
55
56fn push_member(
57    writer: &mut BundleWriter,
58    key: &'static str,
59    kind: &str,
60    bytes: Vec<u8>,
61) -> Result<(), InstrumentError> {
62    reject_unsafe_key(key)?;
63    if bytes.is_empty() {
64        return Err(InstrumentError::EmptyMember(key));
65    }
66    if bytes.len() > MAX_MEMBER_BYTES {
67        return Err(InstrumentError::EntryTooLarge {
68            key: key.into(),
69            bytes: bytes.len(),
70        });
71    }
72    writer.add_file(key, kind, bytes, None)?;
73    Ok(())
74}
75
76/// yaml-ld-q42 style HCF document for a collectable (authoring layer).
77pub fn hcf_from_manifest(manifest: &InstrumentManifest) -> Vec<u8> {
78    let yaml = format!(
79        "# Hypermedia Content Format (HCF) — semantic instrument collectable\n\
80         # Category: {cat}\n\
81         \"@context\":\n\
82         \"  si\": \"https://ns.webizen.org/semantic-instrument/\"\n\
83         \"@id\": \"{release}\"\n\
84         \"@type\": \"si:InstrumentRelease\"\n\
85         si:instrument: \"{instrument}\"\n\
86         si:version: \"{version}\"\n\
87         si:name: \"{name}\"\n\
88         si:purpose: \"{purpose}\"\n\
89         si:contentCategory: \"{cat_iri}\"\n\
90         si:honestyNotice: \"{notice}\"\n\
91         si:accessibleText: \"{a11y}\"\n\
92         si:visualMediaType: \"{media}\"\n",
93        cat = format!("{:?}", manifest.content_category).to_lowercase(),
94        release = manifest.release_id,
95        instrument = manifest.instrument_id,
96        version = manifest.version,
97        name = manifest.name,
98        purpose = manifest.purpose,
99        cat_iri = manifest.content_category.as_iri(),
100        notice = manifest.honesty_notice,
101        a11y = manifest.accessible_text,
102        media = manifest.visual_media_type,
103    );
104    yaml.into_bytes()
105}
106
107/// Build an HMC collectable. The sealed `content_digest` is the SHA-256 of the
108/// bundle bytes after members (including a digest-less manifest) are packed,
109/// then the manifest is rewritten... To keep a single pass: digest is of all
110/// members except the manifest; the manifest records that digest; the bundle
111/// digest is SHA-256 of the finished HMC.
112pub fn build_collectable(mut parts: CollectableParts) -> Result<Vec<u8>, InstrumentError> {
113    parts.manifest.validate()?;
114    if parts.manifest.visual_media_type.is_empty() {
115        parts.manifest.visual_media_type = VISUAL_MEDIA_TYPE.into();
116    }
117    if parts.visual_10d.is_empty() {
118        parts.visual_10d = demo_badge_10d().to_vec();
119    }
120    if parts.hcf.is_empty() {
121        parts.hcf = hcf_from_manifest(&parts.manifest);
122    }
123
124    use sha2::{Digest, Sha256};
125    let mut payload_hasher = Sha256::new();
126    payload_hasher.update(&parts.hcf);
127    payload_hasher.update(&parts.definition_n3);
128    payload_hasher.update(&parts.visual_10d);
129    if let Some(q) = &parts.small_q42 {
130        payload_hasher.update(q);
131    }
132    let payload_digest = payload_hasher.finalize();
133    let mut hex = String::from("sha256:");
134    for b in payload_digest {
135        hex.push_str(&format!("{b:02x}"));
136    }
137    parts.manifest.content_digest = hex;
138    parts.manifest.validate()?;
139
140    let mut writer = BundleWriter::new();
141    push_member(
142        &mut writer,
143        KEY_MANIFEST,
144        "manifest",
145        canonical_manifest_bytes(&parts.manifest)?,
146    )?;
147    push_member(&mut writer, KEY_HCF, "hcf", parts.hcf)?;
148    push_member(&mut writer, KEY_GRAPH, "n3", parts.definition_n3)?;
149    push_member(&mut writer, KEY_VISUAL, "10d", parts.visual_10d)?;
150    if let Some(q42) = parts.small_q42 {
151        push_member(&mut writer, KEY_Q42, "q42", q42)?;
152    }
153    if writer.len() > MAX_MEMBERS {
154        return Err(InstrumentError::TooManyEntries {
155            count: writer.len(),
156        });
157    }
158    let bytes = writer.build()?;
159    if bytes.len() > MAX_COLLECTABLE_BYTES {
160        return Err(InstrumentError::BundleTooLarge { bytes: bytes.len() });
161    }
162    Ok(bytes)
163}
164
165/// Opens `collectable`.
166pub fn open_collectable(bytes: &[u8]) -> Result<OpenedCollectable, InstrumentError> {
167    if bytes.len() > MAX_COLLECTABLE_BYTES {
168        return Err(InstrumentError::BundleTooLarge { bytes: bytes.len() });
169    }
170    let reader = BundleReader::parse(bytes)?;
171    let manifest_bytes = reader
172        .get(KEY_MANIFEST)
173        .ok_or(InstrumentError::MissingField("manifest.json"))?;
174    let manifest: InstrumentManifest = serde_json::from_slice(manifest_bytes)
175        .map_err(|e| InstrumentError::Canonical(e.to_string()))?;
176    manifest.validate()?;
177    let definition_n3 = reader
178        .get(KEY_GRAPH)
179        .ok_or(InstrumentError::MissingField(KEY_GRAPH))?
180        .to_vec();
181    let hcf = reader
182        .get(KEY_HCF)
183        .ok_or(InstrumentError::MissingField(KEY_HCF))?
184        .to_vec();
185    let visual_10d = reader
186        .get(KEY_VISUAL)
187        .ok_or(InstrumentError::MissingField(KEY_VISUAL))?
188        .to_vec();
189    crate::container_10d::Container10dHeader::parse(&visual_10d)
190        .map_err(|e| InstrumentError::Canonical(format!("badge.10d: {e}")))?;
191    if visual_10d.is_empty() || !reader.verify_entry(KEY_VISUAL) {
192        return Err(InstrumentError::DigestMismatch);
193    }
194    let small_q42 = reader.get(KEY_Q42).map(|s| s.to_vec());
195    Ok(OpenedCollectable {
196        manifest,
197        definition_n3,
198        hcf,
199        visual_10d,
200        small_q42,
201        bundle_digest: sha256_prefixed(bytes),
202    })
203}
204
205/// `Ok(())` when the key is not a traversal key.
206pub fn reject_traversal_key(key: &str) -> Result<(), InstrumentError> {
207    reject_unsafe_key(key)
208}
209
210#[cfg(test)]
211mod tests {
212    use super::*;
213    use crate::semantic_instruments::category::ContentCategory;
214    use crate::semantic_instruments::manifest::{InstrumentManifest, COLLECTABLE_FORMAT_VERSION};
215
216    fn demo_parts() -> CollectableParts {
217        let manifest = InstrumentManifest {
218            format_version: COLLECTABLE_FORMAT_VERSION.into(),
219            instrument_id: "https://ns.webizen.org/demo/unit-convert".into(),
220            release_id: "https://ns.webizen.org/demo/unit-convert/releases/1.0.0".into(),
221            version: "1.0.0".into(),
222            name: "Unit conversion (demo)".into(),
223            purpose: "demonstration-and-development".into(),
224            content_category: ContentCategory::Demo,
225            prohibited_interpretation: "operational-use".into(),
226            domain: "https://ns.webizen.org/demo/concepts/units".into(),
227            ontology_reference: "https://ns.webizen.org/semantic-instrument/".into(),
228            entry_point: "assess".into(),
229            citation: "https://ns.webizen.org/demo/citations/si-units".into(),
230            honesty_notice: "Demo instrument for demonstration and development.".into(),
231            incomplete_input: "held".into(),
232            result_kind: "demo-claim".into(),
233            licence: "https://spdx.org/licenses/CC-BY-4.0.html".into(),
234            authored_by: "did:webizen:agent:demo-seed".into(),
235            accessible_text: "Unit conversion demo instrument".into(),
236            visual_media_type: VISUAL_MEDIA_TYPE.into(),
237            content_digest: String::new(),
238            extra: Default::default(),
239        };
240        CollectableParts {
241            hcf: hcf_from_manifest(&manifest),
242            definition_n3: b"ex:unit a si:SemanticInstrument .\n".to_vec(),
243            visual_10d: demo_badge_10d().to_vec(),
244            small_q42: None,
245            manifest,
246        }
247    }
248
249    #[test]
250    fn round_trip_hmc_collectable() {
251        let bytes = build_collectable(demo_parts()).unwrap();
252        let opened = open_collectable(&bytes).unwrap();
253        assert_eq!(opened.manifest.content_category, ContentCategory::Demo);
254        assert!(opened.manifest.content_digest.starts_with("sha256:"));
255        assert!(!opened.visual_10d.is_empty());
256        assert!(opened.hcf.starts_with(b"# Hypermedia"));
257    }
258
259    #[test]
260    fn demo_without_notice_fails() {
261        let mut parts = demo_parts();
262        parts.manifest.honesty_notice = "fine".into();
263        assert_eq!(
264            build_collectable(parts).unwrap_err(),
265            InstrumentError::DemoUnlabelled
266        );
267    }
268
269    #[test]
270    fn path_traversal_keys_rejected() {
271        assert!(reject_traversal_key("../secret").is_err());
272        assert!(reject_traversal_key("graphs/instrument-definition.n3").is_ok());
273    }
274
275    #[test]
276    fn extra_field_survives_round_trip() {
277        let mut parts = demo_parts();
278        parts
279            .manifest
280            .extra
281            .insert("seed".into(), serde_json::json!("demo-catalog"));
282        let opened = open_collectable(&build_collectable(parts).unwrap()).unwrap();
283        assert_eq!(
284            opened.manifest.extra.get("seed").and_then(|v| v.as_str()),
285            Some("demo-catalog")
286        );
287    }
288}