Skip to main content

datumesh_http/
bundle.rs

1//! `bundle 1` (CONTRACT-1.8b H2, `docs/bundle-1.md`): a namespace's function descriptors, name
2//! bindings and signed receipts as one JSON object, with a manifest signed by the namespace's host
3//! (Ed25519, RFC 8032, over the JCS bytes of the names, the namespace and the receipt hashes).
4//! Operator format, not spec: the body of the plan-3.1 write endpoint and of `import-signed`.
5
6use std::collections::{BTreeMap, BTreeSet};
7
8use datumesh_core::json::{self, Value};
9use datumesh_core::{
10    keys_from_response, lexical::to_hex, verify, verify_ed25519, FunctionDescriptor, Keys, Receipt, SigningKey,
11};
12use datumesh_engine::Clock;
13use datumesh_store::Store;
14
15/// After every binding.
16const END: &str = "9999-12-31T23:59:59.999999Z";
17
18/// The members of a bundle, in JCS order. `catalog` is optional (CONTRACT-build2-part2-read R5).
19const MEMBERS: [&str; 6] = ["bundle", "descriptors", "manifest", "names", "namespace", "receipts"];
20
21/// Why a bundle is refused. The first failing check is reported; nothing is written unless all pass.
22#[non_exhaustive]
23#[derive(Clone, Debug, PartialEq, Eq)]
24pub enum BundleError {
25    /// Not JSON, a missing or extra member, `bundle` not 1, a malformed hex, or an order not kept.
26    Format(String),
27    /// The namespace's host is neither the mesh's nor an owned one, or a name is not under the namespace.
28    NotOwned(String),
29    /// The manifest: no key of the namespace's host, the key's window does not hold now, or the
30    /// signature does not verify over the bundle's names and receipt hashes.
31    Manifest(String),
32    /// A descriptor that is not canonical, or a name whose descriptor is neither in the bundle nor stored.
33    Descriptor(String),
34    /// A receipt: computed (with inputs), not verifying against the namespace's key document, or
35    /// not for one of the bundle's names.
36    Receipt(String),
37    /// A receipt whose `tx` is later than the mesh clock.
38    TxInFuture {
39        /// The receipt's hash.
40        receipt: String,
41        /// Its `tx`.
42        tx: String,
43        /// The mesh clock.
44        now: String,
45    },
46    /// A name whose latest binding is at or after the clock.
47    Bind(String),
48    /// The store refused a read or a write (a cell with a later version, say).
49    Store(String),
50    /// A test hook (`import_signed_with`'s `stop_after`): stopped after this many writes.
51    Stopped(usize),
52    /// The public rule (Build 2 Part 3, D8): a computed function of the bundle is not covered by its
53    /// tests (`E_TESTS_MISSING`), or one of its tests fails (`E_TESTS_FAILING`). The text starts with
54    /// the code and lists them.
55    Tests(String),
56}
57
58impl std::fmt::Display for BundleError {
59    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
60        match self {
61            BundleError::Format(s) => write!(f, "bundle format: {s}"),
62            BundleError::NotOwned(s) => write!(f, "not owned: {s}"),
63            BundleError::Manifest(s) => write!(f, "manifest: {s}"),
64            BundleError::Descriptor(s) => write!(f, "descriptor: {s}"),
65            BundleError::Receipt(s) => write!(f, "receipt: {s}"),
66            BundleError::TxInFuture { receipt, tx, now } => {
67                write!(f, "receipt {receipt}: tx {tx} is later than the mesh clock {now}")
68            }
69            BundleError::Bind(s) => write!(f, "binding: {s}"),
70            BundleError::Store(s) => write!(f, "store: {s}"),
71            BundleError::Stopped(n) => write!(f, "stopped after write {n}"),
72            BundleError::Tests(s) => write!(f, "tests: {s}"),
73        }
74    }
75}
76
77impl std::error::Error for BundleError {}
78
79/// What an import did.
80#[non_exhaustive]
81#[derive(Clone, Debug, PartialEq, Eq)]
82pub struct Imported {
83    /// The bundle's namespace.
84    pub namespace: String,
85    /// Names newly bound (a name already bound to its hash is not counted).
86    pub functions_bound: usize,
87    /// Receipts in the bundle (each is stored; putting one again is idempotent).
88    pub receipts: usize,
89    /// Versions newly added.
90    pub versions: usize,
91    /// The instant the names were bound at: the mesh clock.
92    pub bound_at: String,
93}
94
95impl Imported {
96    /// The result as one JCS object (the CLI prints this).
97    pub fn to_jcs(&self) -> Vec<u8> {
98        Value::Object(vec![
99            ("bound_at".into(), s(&self.bound_at)),
100            ("functions_bound".into(), number(self.functions_bound)),
101            ("namespace".into(), s(&self.namespace)),
102            ("receipts".into(), number(self.receipts)),
103            ("versions".into(), number(self.versions)),
104        ])
105        .to_jcs()
106    }
107}
108
109fn s(v: &str) -> Value {
110    Value::String(v.to_string())
111}
112
113fn number(n: usize) -> Value {
114    json::parse(n.to_string().as_bytes()).unwrap_or(Value::Null)
115}
116
117fn is_hex(text: &str, len: usize) -> bool {
118    text.len() == len && text.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
119}
120
121fn unhex(text: &str) -> Vec<u8> {
122    (0..text.len()).step_by(2).filter_map(|i| u8::from_str_radix(text.get(i..i + 2)?, 16).ok()).collect()
123}
124
125/// The host of a namespace: its first segment.
126fn host_of(namespace: &str) -> &str {
127    namespace.split('/').next().unwrap_or("")
128}
129
130/// The JSON of a name and its function hash, as the bundle and the manifest write it.
131fn name_value(name: &str, fn_hash: &str) -> Value {
132    Value::Object(vec![("fn_hash".into(), s(fn_hash)), ("name".into(), s(name))])
133}
134
135/// The bytes the manifest signs (CONTRACT-1.8b H2): the JCS object of the names (`(name, fn_hash)`,
136/// ascending by name), the namespace and the receipt hashes (ascending).
137pub fn manifest_bytes(namespace: &str, names: &[(String, String)], receipts: &[String]) -> Vec<u8> {
138    manifest_bytes_with(namespace, names, receipts, None, None)
139}
140
141/// As [`manifest_bytes`], and the catalogue member when the bundle has one (R5): the manifest signs
142/// the catalogue too, so a changed entry fails the signature.
143fn manifest_bytes_with(
144    namespace: &str,
145    names: &[(String, String)],
146    receipts: &[String],
147    catalog: Option<&Value>,
148    tests: Option<&Value>,
149) -> Vec<u8> {
150    let mut members = vec![
151        ("names".into(), Value::Array(names.iter().map(|(n, h)| name_value(n, h)).collect())),
152        ("namespace".into(), s(namespace)),
153        ("receipts".into(), Value::Array(receipts.iter().map(|h| s(h)).collect())),
154    ];
155    if let Some(c) = catalog {
156        members.push(("catalog".into(), c.clone()));
157    }
158    if let Some(t) = tests {
159        members.push(("tests".into(), t.clone()));
160    }
161    Value::Object(members).to_jcs()
162}
163
164/// Ed25519 (RFC 8032) over `message` with the key of `seed`, by `ed25519-dalek`: the signature
165/// `R || S`. The public key and key id are those of `SigningKey::from_seed(seed)`; the import
166/// verifies with core's `verify_ed25519`, the strict rules of receipt verification.
167fn sign(seed: &[u8; 32], message: &[u8]) -> [u8; 64] {
168    use ed25519_dalek::Signer;
169    ed25519_dalek::SigningKey::from_bytes(seed).sign(message).to_bytes()
170}
171
172/// Builds a bundle 1 (see the module documentation): `descriptors` (each a canonical function
173/// descriptor), `names` (`(name, fn_hash)`), `receipts` (each a receipt's JSON), signed with the
174/// key of `seed` as the manifest of `namespace`. The names and the receipts are put in ascending
175/// order. Errors: `Format` for a receipt or descriptor that does not parse.
176pub fn build(
177    namespace: &str,
178    descriptors: Vec<Vec<u8>>,
179    names: Vec<(String, String)>,
180    receipts: Vec<Vec<u8>>,
181    seed: &[u8; 32],
182) -> Result<Vec<u8>, BundleError> {
183    build_with_catalog(namespace, descriptors, names, receipts, Vec::new(), seed)
184}
185
186/// As [`build_with_catalog`], with the bundle's tests (Build 2 Part 3, E5): `tests` are the test
187/// objects of `test` lines (each `{"test", "call", "asof"?, "inputs"?, "expect"}`), sorted by function
188/// name then by case id into the bundle's `tests` member, which the manifest signs. No tests make a
189/// bundle without the member. Errors: `Format` for a test that is not a test.
190pub fn build_with_tests(
191    namespace: &str,
192    descriptors: Vec<Vec<u8>>,
193    names: Vec<(String, String)>,
194    receipts: Vec<Vec<u8>>,
195    catalog: Vec<Vec<u8>>,
196    tests: Vec<Vec<u8>>,
197    seed: &[u8; 32],
198) -> Result<Vec<u8>, BundleError> {
199    let mut entries: Vec<(String, String, Value)> = Vec::new();
200    for t in tests {
201        let v = json::parse(&t).map_err(|e| BundleError::Format(format!("test: {e}")))?;
202        let spec = crate::testrun::parse_test(&v).map_err(|e| BundleError::Format(format!("test: {e}")))?;
203        entries.push((spec.function.clone(), spec.case.clone(), v));
204    }
205    entries.sort_by(|a, b| (a.0.as_str(), a.1.as_str()).cmp(&(b.0.as_str(), b.1.as_str())));
206    let tests_value = (!entries.is_empty()).then(|| Value::Array(entries.into_iter().map(|(_, _, v)| v).collect()));
207    build_inner(namespace, descriptors, names, receipts, catalog, tests_value, seed)
208}
209
210/// As [`build`], with the publisher's catalogue (CONTRACT-build2-part2-read R5): `catalog` is a list
211/// of entries `{"name", "kind", "label", "description", "args", "examples", "dictionary"}` (each a
212/// JSON object), checked as a publish's catalogue lines are, and sorted by name into the bundle's
213/// `catalog` member, which the manifest signs. An empty list makes a bundle without the member.
214/// Errors: `Format` for an entry that breaks its bounds.
215pub fn build_with_catalog(
216    namespace: &str,
217    descriptors: Vec<Vec<u8>>,
218    names: Vec<(String, String)>,
219    receipts: Vec<Vec<u8>>,
220    catalog: Vec<Vec<u8>>,
221    seed: &[u8; 32],
222) -> Result<Vec<u8>, BundleError> {
223    build_inner(namespace, descriptors, names, receipts, catalog, None, seed)
224}
225
226fn build_inner(
227    namespace: &str,
228    descriptors: Vec<Vec<u8>>,
229    names: Vec<(String, String)>,
230    receipts: Vec<Vec<u8>>,
231    catalog: Vec<Vec<u8>>,
232    tests: Option<Value>,
233    seed: &[u8; 32],
234) -> Result<Vec<u8>, BundleError> {
235    let mut catalog_entries: Vec<(String, Value)> = Vec::new();
236    for c in catalog {
237        let v = json::parse(&c).map_err(|e| BundleError::Format(format!("catalog: {e}")))?;
238        let d = crate::catalog::parse(&v, "name").map_err(|e| BundleError::Format(format!("catalog: {e}")))?;
239        catalog_entries.push((d.name.clone(), v));
240    }
241    catalog_entries.sort_by(|a, b| a.0.cmp(&b.0));
242    let catalog_value =
243        (!catalog_entries.is_empty()).then(|| Value::Array(catalog_entries.into_iter().map(|(_, v)| v).collect()));
244    let mut names = names;
245    names.sort();
246    let mut signed: Vec<(String, Value)> = Vec::new();
247    for r in receipts {
248        let hash = Receipt::from_json(&r).map_err(|e| BundleError::Format(format!("receipt: {e}")))?.hash().to_string();
249        let v = json::parse(&r).map_err(|e| BundleError::Format(format!("receipt: {e}")))?;
250        signed.push((hash, v));
251    }
252    signed.sort_by(|a, b| a.0.cmp(&b.0));
253    let hashes: Vec<String> = signed.iter().map(|(h, _)| h.clone()).collect();
254    let sig = sign(seed, &manifest_bytes_with(namespace, &names, &hashes, catalog_value.as_ref(), tests.as_ref()));
255    let key = SigningKey::from_seed(seed);
256    let descriptors = descriptors
257        .iter()
258        .map(|d| json::parse(d).map_err(|e| BundleError::Format(format!("descriptor: {e}"))))
259        .collect::<Result<Vec<Value>, _>>()?;
260    let mut members = vec![("bundle".into(), number(1))];
261    if let Some(c) = catalog_value {
262        members.push(("catalog".into(), c));
263    }
264    if let Some(t) = tests {
265        members.push(("tests".into(), t));
266    }
267    members.extend([
268        ("descriptors".into(), Value::Array(descriptors)),
269        (
270            "manifest".into(),
271            Value::Object(vec![("key_id".into(), s(key.key_id())), ("signature".into(), s(&to_hex(&sig)))]),
272        ),
273        ("names".into(), Value::Array(names.iter().map(|(n, h)| name_value(n, h)).collect())),
274        ("namespace".into(), s(namespace)),
275        ("receipts".into(), Value::Array(signed.into_iter().map(|(_, v)| v).collect())),
276    ]);
277    Ok(Value::Object(members).to_jcs())
278}
279
280/// The keys of an object's members, sorted.
281fn member_names(v: &Value) -> Option<Vec<&str>> {
282    let mut keys: Vec<&str> = v.as_object()?.iter().map(|(k, _)| k.as_str()).collect();
283    keys.sort_unstable();
284    Some(keys)
285}
286
287/// A string member of `v`, or a format error.
288fn text<'a>(v: &'a Value, key: &str) -> Result<&'a str, BundleError> {
289    v.get(key).and_then(Value::as_str).ok_or_else(|| BundleError::Format(format!("{key} is not a string")))
290}
291
292/// Imports the bundle `bytes` for the mesh `host`, whose own namespaces are `owned`, at the clock's
293/// now (CONTRACT-1.8b H2). Checks run in the order of the contract, and nothing is written unless
294/// they all pass. The writes are, in order: the descriptors; the receipts (each `put_receipt`), then
295/// the versions (each `put_version`); the name bindings last, so that a crash part-way leaves no
296/// name answering. A re-run completes a partial import: a version or a binding already there is
297/// skipped.
298pub fn import_signed<S: Store + ?Sized>(
299    store: &S,
300    host: &str,
301    owned: &[String],
302    clock: &dyn Clock,
303    bytes: &[u8],
304) -> Result<Imported, BundleError> {
305    import_signed_with(store, host, owned, clock, bytes, None)
306}
307
308/// As [`import_signed`], with a test hook (`#[doc(hidden)]`): with `stop_after` `Some(n)` the import
309/// stops with [`BundleError::Stopped`]`(n)` after its `n`-th write (each `put_descriptor`,
310/// `put_receipt`, `put_version` and `bind_name` counts as one), to test that a re-run completes it.
311#[doc(hidden)]
312pub fn import_signed_with<S: Store + ?Sized>(
313    store: &S,
314    host: &str,
315    owned: &[String],
316    clock: &dyn Clock,
317    bytes: &[u8],
318    stop_after: Option<usize>,
319) -> Result<Imported, BundleError> {
320    import_with(store, host, owned, clock, bytes, None, stop_after, Stage::All)
321}
322
323/// How far an import goes: the domain proof only (`POST /bundles`'s first two checks), or all of it.
324#[derive(Clone, Copy, Debug, PartialEq, Eq)]
325pub(crate) enum Stage {
326    Proof,
327    All,
328}
329
330/// The domain proof of a bundle (Build 2 Part 4, P1, checks 1 and 2): the bundle parses, every name
331/// and catalogue entry is under its namespace, and its manifest is signed by a key of `keydoc` (the
332/// publisher's key document, as fetched) that holds now. Writes nothing.
333pub(crate) fn prove<S: Store + ?Sized>(
334    store: &S,
335    host: &str,
336    clock: &dyn Clock,
337    bytes: &[u8],
338    keydoc: &[u8],
339) -> Result<(), BundleError> {
340    import_with(store, host, &[], clock, bytes, Some(keydoc), None, Stage::Proof).map(|_| ())
341}
342
343/// The import of a bundle whose publisher's key document is `keydoc` (fetched for the request) or,
344/// when `None`, the store's record of its namespace's host. `owned` are the hosts that may publish
345/// here besides `host`.
346pub(crate) fn import_published<S: Store + ?Sized>(
347    store: &S,
348    host: &str,
349    owned: &[String],
350    clock: &dyn Clock,
351    bytes: &[u8],
352    keydoc: Option<&[u8]>,
353) -> Result<Imported, BundleError> {
354    import_with(store, host, owned, clock, bytes, keydoc, None, Stage::All)
355}
356
357#[allow(clippy::too_many_arguments)]
358fn import_with<S: Store + ?Sized>(
359    store: &S,
360    host: &str,
361    owned: &[String],
362    clock: &dyn Clock,
363    bytes: &[u8],
364    keydoc: Option<&[u8]>,
365    stop_after: Option<usize>,
366    stage: Stage,
367) -> Result<Imported, BundleError> {
368    let now = clock.now();
369    let doc = json::parse(bytes).map_err(|e| BundleError::Format(format!("not JSON: {e}")))?;
370
371    // 1. Format.
372    let mut keys = member_names(&doc).ok_or_else(|| BundleError::Format("not an object".into()))?;
373    keys.sort_unstable();
374    let has_catalog = keys.contains(&"catalog");
375    let has_tests = keys.contains(&"tests");
376    keys.retain(|k| *k != "catalog" && *k != "tests");
377    let mut want = MEMBERS;
378    want.sort_unstable();
379    if keys != want {
380        return Err(BundleError::Format("the members are not exactly those of a bundle".into()));
381    }
382    if doc.get("bundle").and_then(Value::as_number_text) != Some("1") {
383        return Err(BundleError::Format("bundle is not 1".into()));
384    }
385    let namespace = text(&doc, "namespace")?.to_string();
386    if namespace.split('/').count() < 2 {
387        return Err(BundleError::Format("namespace has no host and name".into()));
388    }
389    let manifest = doc.get("manifest").ok_or_else(|| BundleError::Format("no manifest".into()))?;
390    if member_names(manifest) != Some(vec!["key_id", "signature"]) {
391        return Err(BundleError::Format("the manifest's members are not key_id and signature".into()));
392    }
393    let key_id = text(manifest, "key_id")?.to_string();
394    let signature = text(manifest, "signature")?.to_string();
395    if !is_hex(&key_id, 16) || !is_hex(&signature, 128) {
396        return Err(BundleError::Format("the manifest's key_id or signature is not hex".into()));
397    }
398    let mut names: Vec<(String, String)> = Vec::new();
399    let Some(Value::Array(name_vs)) = doc.get("names") else {
400        return Err(BundleError::Format("names is not an array".into()));
401    };
402    for n in name_vs {
403        if member_names(n) != Some(vec!["fn_hash", "name"]) {
404            return Err(BundleError::Format("a name's members are not fn_hash and name".into()));
405        }
406        let fh = text(n, "fn_hash")?;
407        if !is_hex(fh, 64) {
408            return Err(BundleError::Format(format!("fn_hash {fh} is not 64 hex digits")));
409        }
410        names.push((text(n, "name")?.to_string(), fh.to_string()));
411    }
412    if names.windows(2).any(|w| w[0].0 >= w[1].0) {
413        return Err(BundleError::Format("names are not in ascending order".into()));
414    }
415    let Some(Value::Array(desc_vs)) = doc.get("descriptors") else {
416        return Err(BundleError::Format("descriptors is not an array".into()));
417    };
418    let Some(Value::Array(receipt_vs)) = doc.get("receipts") else {
419        return Err(BundleError::Format("receipts is not an array".into()));
420    };
421    // (the JCS bytes of the receipt, the receipt)
422    let mut receipts: Vec<(Vec<u8>, Receipt)> = Vec::new();
423    for r in receipt_vs {
424        let rb = r.to_jcs();
425        let parsed = Receipt::from_json(&rb).map_err(|e| BundleError::Receipt(format!("unreadable: {e}")))?;
426        receipts.push((rb, parsed));
427    }
428    if receipts.windows(2).any(|w| w[0].1.hash() >= w[1].1.hash()) {
429        return Err(BundleError::Format("receipts are not in ascending order of their hashes".into()));
430    }
431    let hashes: Vec<String> = receipts.iter().map(|(_, r)| r.hash().to_string()).collect();
432    // The catalogue (R5): each entry checked as a publish's line is; a function's hash is its name's.
433    let mut catalog_entries: Vec<(crate::catalog::Described, Option<String>)> = Vec::new();
434    let catalog_doc = if has_catalog { doc.get("catalog").cloned() } else { None };
435    if let Some(Value::Array(items)) = &catalog_doc {
436        for item in items {
437            let d = crate::catalog::parse(item, "name").map_err(|e| BundleError::Format(format!("catalog: {e}")))?;
438            let hash =
439                match d.kind {
440                    datumesh_store::CatalogKind::Class => None,
441                    _ => {
442                        Some(names.iter().find(|(n, _)| *n == d.name).map(|(_, h)| h.clone()).ok_or_else(|| {
443                            BundleError::Format(format!("catalog: {} is not among the names", d.name))
444                        })?)
445                    }
446                };
447            catalog_entries.push((d, hash));
448        }
449    } else if has_catalog {
450        return Err(BundleError::Format("catalog is not an array".into()));
451    }
452
453    // 2. NotOwned.
454    let ns_host = host_of(&namespace);
455    if stage == Stage::All && ns_host != host && !owned.iter().any(|o| o == ns_host) {
456        return Err(BundleError::NotOwned(format!("{ns_host} is neither this mesh's host nor owned")));
457    }
458    if let Some((n, _)) = names.iter().find(|(n, _)| !n.starts_with(&format!("{namespace}/"))) {
459        return Err(BundleError::NotOwned(format!("{n} is not under {namespace}/")));
460    }
461    if let Some((d, _)) = catalog_entries.iter().find(|(d, _)| !d.name.starts_with(&format!("{namespace}/"))) {
462        return Err(BundleError::NotOwned(format!("catalog: {} is not under {namespace}/", d.name)));
463    }
464
465    // 3. Manifest: the key of the namespace's host, valid now, signing the bundle's names and receipts.
466    let keydoc_fetched = keydoc;
467    let keydoc = match keydoc {
468        Some(d) => d.to_vec(),
469        None => {
470            store
471                .namespace(ns_host)
472                .map_err(|e| BundleError::Store(e.to_string()))?
473                .ok_or_else(|| BundleError::Manifest(format!("the store holds no key document of {ns_host}")))?
474                .keydoc
475        }
476    };
477    let kd = keys_from_response(ns_host, 200, Some(&keydoc)).map_err(|e| BundleError::Manifest(e.to_string()))?;
478    let key = kd
479        .key(&key_id)
480        .ok_or_else(|| BundleError::Manifest(format!("key {key_id} is not in the key document of {ns_host}")))?;
481    if !key.usable_at(&now) {
482        return Err(BundleError::Manifest(format!("key {key_id} does not hold at {now}")));
483    }
484    let mut keys_set = Keys::new();
485    keys_set.insert(kd.clone());
486    let sig: [u8; 64] = unhex(&signature).try_into().map_err(|_| BundleError::Format("signature length".into()))?;
487    let tests_doc = if has_tests { doc.get("tests").cloned() } else { None };
488    if tests_doc.as_ref().is_some_and(|t| !matches!(t, Value::Array(_))) {
489        return Err(BundleError::Format("tests is not an array".into()));
490    }
491    if !verify_ed25519(
492        &key.public,
493        &manifest_bytes_with(&namespace, &names, &hashes, catalog_doc.as_ref(), tests_doc.as_ref()),
494        &sig,
495    ) {
496        return Err(BundleError::Manifest("the signature does not verify".into()));
497    }
498    if stage == Stage::Proof {
499        return Ok(Imported { namespace, functions_bound: 0, receipts: 0, versions: 0, bound_at: now });
500    }
501
502    // 4. Descriptor.
503    let mut descriptors: BTreeMap<String, Vec<u8>> = BTreeMap::new();
504    for d in desc_vs {
505        let db = d.to_jcs();
506        let fd = FunctionDescriptor::from_json(&db).map_err(|e| BundleError::Descriptor(e.to_string()))?;
507        if fd.canonical() != db {
508            return Err(BundleError::Descriptor("a descriptor is not canonical".into()));
509        }
510        descriptors.insert(fd.hash(), db);
511    }
512    for (name, fh) in &names {
513        if !descriptors.contains_key(fh) && store.descriptor(fh).is_none() {
514            return Err(BundleError::Descriptor(format!(
515                "{name}: descriptor {fh} is neither in the bundle nor stored"
516            )));
517        }
518    }
519
520    // 5. Receipt.
521    for (rb, r) in &receipts {
522        if !r.inputs().is_empty() {
523            return Err(BundleError::Receipt(format!("{}: a computed receipt is not imported", r.hash())));
524        }
525        let fname = r.cell().function_name();
526        let Some((_, fh)) = names.iter().find(|(n, _)| *n == fname) else {
527            return Err(BundleError::Receipt(format!("{}: {fname} is not among the names", r.hash())));
528        };
529        if r.cell().fn_hash != *fh {
530            return Err(BundleError::Receipt(format!("{}: the function hash differs from {fname}'s", r.hash())));
531        }
532        let out = verify(rb, &keys_set, None, None);
533        if !out.ok {
534            let why = out.error().map(|e| e.to_string()).unwrap_or_else(|| "does not verify".into());
535            return Err(BundleError::Receipt(format!("{}: {why}", r.hash())));
536        }
537    }
538
539    // 6. TxInFuture.
540    for (_, r) in &receipts {
541        if r.tx() > now.as_str() {
542            return Err(BundleError::TxInFuture {
543                receipt: r.hash().to_string(),
544                tx: r.tx().to_string(),
545                now: now.clone(),
546            });
547        }
548    }
549
550    // The public rule (D8): every computed function of the bundle is covered by its tests, and they pass.
551    let mut overlay = crate::testrun::Overlay::default();
552    for (name, fh) in &names {
553        overlay.functions.entry(name.clone()).or_default().push((now.clone(), fh.clone()));
554    }
555    for (fh, db) in &descriptors {
556        overlay.descriptors.insert(fh.clone(), db.clone());
557    }
558    for (rb, _) in &receipts {
559        overlay.cell(rb).map_err(BundleError::Receipt)?;
560    }
561    let mut formulas = Vec::new();
562    for (name, fh) in &names {
563        let bytes = match descriptors.get(fh) {
564            Some(b) => Some(b.clone()),
565            None => store.descriptor(fh).map(|b| b.into_owned()),
566        };
567        let Some(bytes) = bytes else { continue };
568        let fd = FunctionDescriptor::from_json(&bytes).map_err(|e| BundleError::Descriptor(e.to_string()))?;
569        if fd.lang != "stored" {
570            formulas.push((0usize, name.clone(), fh.clone()));
571        }
572    }
573    let mut test_specs = Vec::new();
574    for (i, t) in tests_doc
575        .iter()
576        .flat_map(|v| match v {
577            Value::Array(a) => a.iter().collect::<Vec<_>>(),
578            _ => Vec::new(),
579        })
580        .enumerate()
581    {
582        let spec = crate::testrun::parse_test(t).map_err(|e| BundleError::Format(format!("test: {e}")))?;
583        test_specs.push((i + 1, spec));
584    }
585    let test_rows =
586        crate::publish::check_tests(store, &overlay, &test_specs, &formulas, host, &now, true).map_err(|e| {
587            let code = match e.kind {
588                crate::publish::PublishErrorKind::TestsFailing(_) => "E_TESTS_FAILING",
589                crate::publish::PublishErrorKind::TestsMissing(_) => "E_TESTS_MISSING",
590                _ => "E_BUNDLE_TESTS",
591            };
592            BundleError::Tests(format!("{code}: {}", e.detail))
593        })?;
594    // Plan: the binds, and the versions not already there; a conflict is refused before any write.
595    let mut binds: Vec<&(String, String)> = Vec::new();
596    for pair in &names {
597        let (name, fh) = pair;
598        match store.resolve_binding(name, END).map_err(|e| BundleError::Store(e.to_string()))? {
599            Some(b) if b.fn_hash == *fh => {}
600            Some(b) if b.tx.as_str() >= now.as_str() => {
601                return Err(BundleError::Bind(format!("{name} is bound from {} (at or after the clock)", b.tx)));
602            }
603            _ => binds.push(pair),
604        }
605    }
606    let mut new_versions: Vec<(String, String, String)> = Vec::new(); // (cell id, tx, receipt hash)
607    for (_, r) in &receipts {
608        let id = r.cell().id();
609        let tx = r.tx();
610        match store.version_asof(&id, tx).map_err(|e| BundleError::Store(e.to_string()))? {
611            Some(v) if v.tx == tx => {
612                if v.receipt_hash != r.hash() {
613                    return Err(BundleError::Store(format!("{id} has another version at {tx}")));
614                }
615                continue;
616            }
617            _ => {}
618        }
619        if let Some(l) = store.latest(&id).map_err(|e| BundleError::Store(e.to_string()))? {
620            if l.tx.as_str() >= tx {
621                return Err(BundleError::Store(format!("{id} has a version at or after {tx}")));
622            }
623        }
624        new_versions.push((id, tx.to_string(), r.hash().to_string()));
625    }
626
627    // The publisher's key document, as fetched for this request, is the namespace's record before its
628    // receipts are written (the store checks each receipt's signer against it): written after every
629    // check has passed, as the bundle's first write.
630    if let Some(doc) = keydoc_fetched {
631        let stored = store.namespace(ns_host).map_err(|e| BundleError::Store(e.to_string()))?.map(|n| n.keydoc);
632        if stored.as_deref() != Some(doc) {
633            store.put_namespace(ns_host, doc, &now).map_err(|e| BundleError::Store(e.to_string()))?;
634        }
635    }
636    // Writes: descriptors, receipts, versions, then the bindings (a version without its binding is
637    // not answered, so a crash before the bindings leaves nothing answerable).
638    let mut writes = 0usize;
639    let mut step = || -> Result<(), BundleError> {
640        writes += 1;
641        if stop_after == Some(writes) {
642            return Err(BundleError::Stopped(writes));
643        }
644        Ok(())
645    };
646    for db in descriptors.values() {
647        store.put_descriptor(db).map_err(|e| BundleError::Store(e.to_string()))?;
648        step()?;
649    }
650    for (rb, _) in &receipts {
651        store.put_receipt(rb).map_err(|e| BundleError::Store(e.to_string()))?;
652        step()?;
653    }
654    for (id, tx, h) in &new_versions {
655        store.put_version(id, tx, h).map_err(|e| BundleError::Store(e.to_string()))?;
656        step()?;
657    }
658    for (name, fh) in &binds {
659        store.bind_name(name, fh, &now).map_err(|e| BundleError::Bind(format!("{name}: {e}")))?;
660        step()?;
661    }
662    crate::testrun::apply_rows(store, &test_rows, &now).map_err(BundleError::Store)?;
663    let rebound: Vec<String> = binds.iter().map(|(n, _)| (*n).clone()).collect();
664    crate::testrun::rerun_readers(store, &rebound, &now).map_err(BundleError::Store)?;
665    // The publisher's catalogue (R5), signed by this bundle's key; then the values of the cells (R3).
666    for (d, hash) in &catalog_entries {
667        let entry = d.entry(hash.clone(), datumesh_store::CatalogSource::Publisher, Some(key_id.clone()));
668        crate::catalog::store_publisher(store, &entry, &d.dictionary).map_err(BundleError::Store)?;
669    }
670    let mut cell_values = BTreeSet::new();
671    for (_, r) in &receipts {
672        crate::publish::cell_string_values(r, &mut cell_values);
673    }
674    crate::publish::store_cell_values(store, cell_values).map_err(BundleError::Store)?;
675    Ok(Imported {
676        namespace,
677        functions_bound: binds.len(),
678        receipts: receipts.len(),
679        versions: new_versions.len(),
680        bound_at: now,
681    })
682}
683
684#[cfg(test)]
685mod tests {
686    use super::*;
687
688    /// RFC 8032 section 7.1, test 1: the empty message.
689    #[test]
690    fn rfc8032_test_1() {
691        let seed: [u8; 32] =
692            unhex("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60").try_into().unwrap();
693        let sig = sign(&seed, b"");
694        assert_eq!(
695            to_hex(&sig),
696            "e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b"
697        );
698    }
699
700    /// A signature over some bytes verifies with core's strict verification, under the key of the seed.
701    #[test]
702    fn a_signature_verifies_under_the_seed_key() {
703        let seed = [7u8; 32];
704        let message = b"the manifest bytes";
705        let sig = sign(&seed, message);
706        let public = SigningKey::from_seed(&seed).public_key();
707        assert!(verify_ed25519(&public, message, &sig));
708        assert!(!verify_ed25519(&public, b"other bytes", &sig));
709    }
710}