qualia_core_db/semantic_instruments/
package.rs1use 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
23pub 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#[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
76pub 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
107pub 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
165pub 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
205pub 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}