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;
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.
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}
53
54impl std::fmt::Display for BundleError {
55    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56        match self {
57            BundleError::Format(s) => write!(f, "bundle format: {s}"),
58            BundleError::NotOwned(s) => write!(f, "not owned: {s}"),
59            BundleError::Manifest(s) => write!(f, "manifest: {s}"),
60            BundleError::Descriptor(s) => write!(f, "descriptor: {s}"),
61            BundleError::Receipt(s) => write!(f, "receipt: {s}"),
62            BundleError::TxInFuture { receipt, tx, now } => {
63                write!(f, "receipt {receipt}: tx {tx} is later than the mesh clock {now}")
64            }
65            BundleError::Bind(s) => write!(f, "binding: {s}"),
66            BundleError::Store(s) => write!(f, "store: {s}"),
67            BundleError::Stopped(n) => write!(f, "stopped after write {n}"),
68        }
69    }
70}
71
72impl std::error::Error for BundleError {}
73
74/// What an import did.
75#[non_exhaustive]
76#[derive(Clone, Debug, PartialEq, Eq)]
77pub struct Imported {
78    /// The bundle's namespace.
79    pub namespace: String,
80    /// Names newly bound (a name already bound to its hash is not counted).
81    pub functions_bound: usize,
82    /// Receipts in the bundle (each is stored; putting one again is idempotent).
83    pub receipts: usize,
84    /// Versions newly added.
85    pub versions: usize,
86    /// The instant the names were bound at: the mesh clock.
87    pub bound_at: String,
88}
89
90impl Imported {
91    /// The result as one JCS object (the CLI prints this).
92    pub fn to_jcs(&self) -> Vec<u8> {
93        Value::Object(vec![
94            ("bound_at".into(), s(&self.bound_at)),
95            ("functions_bound".into(), number(self.functions_bound)),
96            ("namespace".into(), s(&self.namespace)),
97            ("receipts".into(), number(self.receipts)),
98            ("versions".into(), number(self.versions)),
99        ])
100        .to_jcs()
101    }
102}
103
104fn s(v: &str) -> Value {
105    Value::String(v.to_string())
106}
107
108fn number(n: usize) -> Value {
109    json::parse(n.to_string().as_bytes()).unwrap_or(Value::Null)
110}
111
112fn is_hex(text: &str, len: usize) -> bool {
113    text.len() == len && text.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
114}
115
116fn unhex(text: &str) -> Vec<u8> {
117    (0..text.len()).step_by(2).filter_map(|i| u8::from_str_radix(text.get(i..i + 2)?, 16).ok()).collect()
118}
119
120/// The host of a namespace: its first segment.
121fn host_of(namespace: &str) -> &str {
122    namespace.split('/').next().unwrap_or("")
123}
124
125/// The JSON of a name and its function hash, as the bundle and the manifest write it.
126fn name_value(name: &str, fn_hash: &str) -> Value {
127    Value::Object(vec![("fn_hash".into(), s(fn_hash)), ("name".into(), s(name))])
128}
129
130/// The bytes the manifest signs (CONTRACT-1.8b H2): the JCS object of the names (`(name, fn_hash)`,
131/// ascending by name), the namespace and the receipt hashes (ascending).
132pub fn manifest_bytes(namespace: &str, names: &[(String, String)], receipts: &[String]) -> Vec<u8> {
133    Value::Object(vec![
134        ("names".into(), Value::Array(names.iter().map(|(n, h)| name_value(n, h)).collect())),
135        ("namespace".into(), s(namespace)),
136        ("receipts".into(), Value::Array(receipts.iter().map(|h| s(h)).collect())),
137    ])
138    .to_jcs()
139}
140
141/// Ed25519 (RFC 8032) over `message` with the key of `seed`, by `ed25519-dalek`: the signature
142/// `R || S`. The public key and key id are those of `SigningKey::from_seed(seed)`; the import
143/// verifies with core's `verify_ed25519`, the strict rules of receipt verification.
144fn sign(seed: &[u8; 32], message: &[u8]) -> [u8; 64] {
145    use ed25519_dalek::Signer;
146    ed25519_dalek::SigningKey::from_bytes(seed).sign(message).to_bytes()
147}
148
149/// Builds a bundle 1 (see the module documentation): `descriptors` (each a canonical function
150/// descriptor), `names` (`(name, fn_hash)`), `receipts` (each a receipt's JSON), signed with the
151/// key of `seed` as the manifest of `namespace`. The names and the receipts are put in ascending
152/// order. Errors: `Format` for a receipt or descriptor that does not parse.
153pub fn build(
154    namespace: &str,
155    descriptors: Vec<Vec<u8>>,
156    names: Vec<(String, String)>,
157    receipts: Vec<Vec<u8>>,
158    seed: &[u8; 32],
159) -> Result<Vec<u8>, BundleError> {
160    let mut names = names;
161    names.sort();
162    let mut signed: Vec<(String, Value)> = Vec::new();
163    for r in receipts {
164        let hash = Receipt::from_json(&r).map_err(|e| BundleError::Format(format!("receipt: {e}")))?.hash().to_string();
165        let v = json::parse(&r).map_err(|e| BundleError::Format(format!("receipt: {e}")))?;
166        signed.push((hash, v));
167    }
168    signed.sort_by(|a, b| a.0.cmp(&b.0));
169    let hashes: Vec<String> = signed.iter().map(|(h, _)| h.clone()).collect();
170    let sig = sign(seed, &manifest_bytes(namespace, &names, &hashes));
171    let key = SigningKey::from_seed(seed);
172    let descriptors = descriptors
173        .iter()
174        .map(|d| json::parse(d).map_err(|e| BundleError::Format(format!("descriptor: {e}"))))
175        .collect::<Result<Vec<Value>, _>>()?;
176    Ok(Value::Object(vec![
177        ("bundle".into(), number(1)),
178        ("descriptors".into(), Value::Array(descriptors)),
179        (
180            "manifest".into(),
181            Value::Object(vec![("key_id".into(), s(key.key_id())), ("signature".into(), s(&to_hex(&sig)))]),
182        ),
183        ("names".into(), Value::Array(names.iter().map(|(n, h)| name_value(n, h)).collect())),
184        ("namespace".into(), s(namespace)),
185        ("receipts".into(), Value::Array(signed.into_iter().map(|(_, v)| v).collect())),
186    ])
187    .to_jcs())
188}
189
190/// The keys of an object's members, sorted.
191fn member_names(v: &Value) -> Option<Vec<&str>> {
192    let mut keys: Vec<&str> = v.as_object()?.iter().map(|(k, _)| k.as_str()).collect();
193    keys.sort_unstable();
194    Some(keys)
195}
196
197/// A string member of `v`, or a format error.
198fn text<'a>(v: &'a Value, key: &str) -> Result<&'a str, BundleError> {
199    v.get(key).and_then(Value::as_str).ok_or_else(|| BundleError::Format(format!("{key} is not a string")))
200}
201
202/// Imports the bundle `bytes` for the mesh `host`, whose own namespaces are `owned`, at the clock's
203/// now (CONTRACT-1.8b H2). Checks run in the order of the contract, and nothing is written unless
204/// they all pass. The writes are, in order: the descriptors; the receipts (each `put_receipt`), then
205/// the versions (each `put_version`); the name bindings last, so that a crash part-way leaves no
206/// name answering. A re-run completes a partial import: a version or a binding already there is
207/// skipped.
208pub fn import_signed<S: Store + ?Sized>(
209    store: &S,
210    host: &str,
211    owned: &[String],
212    clock: &dyn Clock,
213    bytes: &[u8],
214) -> Result<Imported, BundleError> {
215    import_signed_with(store, host, owned, clock, bytes, None)
216}
217
218/// As [`import_signed`], with a test hook (`#[doc(hidden)]`): with `stop_after` `Some(n)` the import
219/// stops with [`BundleError::Stopped`]`(n)` after its `n`-th write (each `put_descriptor`,
220/// `put_receipt`, `put_version` and `bind_name` counts as one), to test that a re-run completes it.
221#[doc(hidden)]
222pub fn import_signed_with<S: Store + ?Sized>(
223    store: &S,
224    host: &str,
225    owned: &[String],
226    clock: &dyn Clock,
227    bytes: &[u8],
228    stop_after: Option<usize>,
229) -> Result<Imported, BundleError> {
230    let now = clock.now();
231    let doc = json::parse(bytes).map_err(|e| BundleError::Format(format!("not JSON: {e}")))?;
232
233    // 1. Format.
234    let mut keys = member_names(&doc).ok_or_else(|| BundleError::Format("not an object".into()))?;
235    keys.sort_unstable();
236    let mut want = MEMBERS;
237    want.sort_unstable();
238    if keys != want {
239        return Err(BundleError::Format("the members are not exactly those of a bundle".into()));
240    }
241    if doc.get("bundle").and_then(Value::as_number_text) != Some("1") {
242        return Err(BundleError::Format("bundle is not 1".into()));
243    }
244    let namespace = text(&doc, "namespace")?.to_string();
245    if namespace.split('/').count() < 2 {
246        return Err(BundleError::Format("namespace has no host and name".into()));
247    }
248    let manifest = doc.get("manifest").ok_or_else(|| BundleError::Format("no manifest".into()))?;
249    if member_names(manifest) != Some(vec!["key_id", "signature"]) {
250        return Err(BundleError::Format("the manifest's members are not key_id and signature".into()));
251    }
252    let key_id = text(manifest, "key_id")?.to_string();
253    let signature = text(manifest, "signature")?.to_string();
254    if !is_hex(&key_id, 16) || !is_hex(&signature, 128) {
255        return Err(BundleError::Format("the manifest's key_id or signature is not hex".into()));
256    }
257    let mut names: Vec<(String, String)> = Vec::new();
258    let Some(Value::Array(name_vs)) = doc.get("names") else {
259        return Err(BundleError::Format("names is not an array".into()));
260    };
261    for n in name_vs {
262        if member_names(n) != Some(vec!["fn_hash", "name"]) {
263            return Err(BundleError::Format("a name's members are not fn_hash and name".into()));
264        }
265        let fh = text(n, "fn_hash")?;
266        if !is_hex(fh, 64) {
267            return Err(BundleError::Format(format!("fn_hash {fh} is not 64 hex digits")));
268        }
269        names.push((text(n, "name")?.to_string(), fh.to_string()));
270    }
271    if names.windows(2).any(|w| w[0].0 >= w[1].0) {
272        return Err(BundleError::Format("names are not in ascending order".into()));
273    }
274    let Some(Value::Array(desc_vs)) = doc.get("descriptors") else {
275        return Err(BundleError::Format("descriptors is not an array".into()));
276    };
277    let Some(Value::Array(receipt_vs)) = doc.get("receipts") else {
278        return Err(BundleError::Format("receipts is not an array".into()));
279    };
280    // (the JCS bytes of the receipt, the receipt)
281    let mut receipts: Vec<(Vec<u8>, Receipt)> = Vec::new();
282    for r in receipt_vs {
283        let rb = r.to_jcs();
284        let parsed = Receipt::from_json(&rb).map_err(|e| BundleError::Receipt(format!("unreadable: {e}")))?;
285        receipts.push((rb, parsed));
286    }
287    if receipts.windows(2).any(|w| w[0].1.hash() >= w[1].1.hash()) {
288        return Err(BundleError::Format("receipts are not in ascending order of their hashes".into()));
289    }
290    let hashes: Vec<String> = receipts.iter().map(|(_, r)| r.hash().to_string()).collect();
291
292    // 2. NotOwned.
293    let ns_host = host_of(&namespace);
294    if ns_host != host && !owned.iter().any(|o| o == ns_host) {
295        return Err(BundleError::NotOwned(format!("{ns_host} is neither this mesh's host nor owned")));
296    }
297    if let Some((n, _)) = names.iter().find(|(n, _)| !n.starts_with(&format!("{namespace}/"))) {
298        return Err(BundleError::NotOwned(format!("{n} is not under {namespace}/")));
299    }
300
301    // 3. Manifest: the key of the namespace's host, valid now, signing the bundle's names and receipts.
302    let keydoc = store
303        .namespace(ns_host)
304        .map_err(|e| BundleError::Store(e.to_string()))?
305        .ok_or_else(|| BundleError::Manifest(format!("the store holds no key document of {ns_host}")))?
306        .keydoc;
307    let kd = keys_from_response(ns_host, 200, Some(&keydoc)).map_err(|e| BundleError::Manifest(e.to_string()))?;
308    let key = kd
309        .key(&key_id)
310        .ok_or_else(|| BundleError::Manifest(format!("key {key_id} is not in the key document of {ns_host}")))?;
311    if !key.usable_at(&now) {
312        return Err(BundleError::Manifest(format!("key {key_id} does not hold at {now}")));
313    }
314    let mut keys_set = Keys::new();
315    keys_set.insert(kd.clone());
316    let sig: [u8; 64] = unhex(&signature).try_into().map_err(|_| BundleError::Format("signature length".into()))?;
317    if !verify_ed25519(&key.public, &manifest_bytes(&namespace, &names, &hashes), &sig) {
318        return Err(BundleError::Manifest("the signature does not verify".into()));
319    }
320
321    // 4. Descriptor.
322    let mut descriptors: BTreeMap<String, Vec<u8>> = BTreeMap::new();
323    for d in desc_vs {
324        let db = d.to_jcs();
325        let fd = FunctionDescriptor::from_json(&db).map_err(|e| BundleError::Descriptor(e.to_string()))?;
326        if fd.canonical() != db {
327            return Err(BundleError::Descriptor("a descriptor is not canonical".into()));
328        }
329        descriptors.insert(fd.hash(), db);
330    }
331    for (name, fh) in &names {
332        if !descriptors.contains_key(fh) && store.descriptor(fh).is_none() {
333            return Err(BundleError::Descriptor(format!(
334                "{name}: descriptor {fh} is neither in the bundle nor stored"
335            )));
336        }
337    }
338
339    // 5. Receipt.
340    for (rb, r) in &receipts {
341        if !r.inputs().is_empty() {
342            return Err(BundleError::Receipt(format!("{}: a computed receipt is not imported", r.hash())));
343        }
344        let fname = r.cell().function_name();
345        let Some((_, fh)) = names.iter().find(|(n, _)| *n == fname) else {
346            return Err(BundleError::Receipt(format!("{}: {fname} is not among the names", r.hash())));
347        };
348        if r.cell().fn_hash != *fh {
349            return Err(BundleError::Receipt(format!("{}: the function hash differs from {fname}'s", r.hash())));
350        }
351        let out = verify(rb, &keys_set, None, None);
352        if !out.ok {
353            let why = out.error().map(|e| e.to_string()).unwrap_or_else(|| "does not verify".into());
354            return Err(BundleError::Receipt(format!("{}: {why}", r.hash())));
355        }
356    }
357
358    // 6. TxInFuture.
359    for (_, r) in &receipts {
360        if r.tx() > now.as_str() {
361            return Err(BundleError::TxInFuture {
362                receipt: r.hash().to_string(),
363                tx: r.tx().to_string(),
364                now: now.clone(),
365            });
366        }
367    }
368
369    // Plan: the binds, and the versions not already there; a conflict is refused before any write.
370    let mut binds: Vec<&(String, String)> = Vec::new();
371    for pair in &names {
372        let (name, fh) = pair;
373        match store.resolve_binding(name, END).map_err(|e| BundleError::Store(e.to_string()))? {
374            Some(b) if b.fn_hash == *fh => {}
375            Some(b) if b.tx.as_str() >= now.as_str() => {
376                return Err(BundleError::Bind(format!("{name} is bound from {} (at or after the clock)", b.tx)));
377            }
378            _ => binds.push(pair),
379        }
380    }
381    let mut new_versions: Vec<(String, String, String)> = Vec::new(); // (cell id, tx, receipt hash)
382    for (_, r) in &receipts {
383        let id = r.cell().id();
384        let tx = r.tx();
385        match store.version_asof(&id, tx).map_err(|e| BundleError::Store(e.to_string()))? {
386            Some(v) if v.tx == tx => {
387                if v.receipt_hash != r.hash() {
388                    return Err(BundleError::Store(format!("{id} has another version at {tx}")));
389                }
390                continue;
391            }
392            _ => {}
393        }
394        if let Some(l) = store.latest(&id).map_err(|e| BundleError::Store(e.to_string()))? {
395            if l.tx.as_str() >= tx {
396                return Err(BundleError::Store(format!("{id} has a version at or after {tx}")));
397            }
398        }
399        new_versions.push((id, tx.to_string(), r.hash().to_string()));
400    }
401
402    // Writes: descriptors, receipts, versions, then the bindings (a version without its binding is
403    // not answered, so a crash before the bindings leaves nothing answerable).
404    let mut writes = 0usize;
405    let mut step = || -> Result<(), BundleError> {
406        writes += 1;
407        if stop_after == Some(writes) {
408            return Err(BundleError::Stopped(writes));
409        }
410        Ok(())
411    };
412    for db in descriptors.values() {
413        store.put_descriptor(db).map_err(|e| BundleError::Store(e.to_string()))?;
414        step()?;
415    }
416    for (rb, _) in &receipts {
417        store.put_receipt(rb).map_err(|e| BundleError::Store(e.to_string()))?;
418        step()?;
419    }
420    for (id, tx, h) in &new_versions {
421        store.put_version(id, tx, h).map_err(|e| BundleError::Store(e.to_string()))?;
422        step()?;
423    }
424    for (name, fh) in &binds {
425        store.bind_name(name, fh, &now).map_err(|e| BundleError::Bind(format!("{name}: {e}")))?;
426        step()?;
427    }
428    Ok(Imported {
429        namespace,
430        functions_bound: binds.len(),
431        receipts: receipts.len(),
432        versions: new_versions.len(),
433        bound_at: now,
434    })
435}
436
437#[cfg(test)]
438mod tests {
439    use super::*;
440
441    /// RFC 8032 section 7.1, test 1: the empty message.
442    #[test]
443    fn rfc8032_test_1() {
444        let seed: [u8; 32] =
445            unhex("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60").try_into().unwrap();
446        let sig = sign(&seed, b"");
447        assert_eq!(
448            to_hex(&sig),
449            "e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b"
450        );
451    }
452
453    /// A signature over some bytes verifies with core's strict verification, under the key of the seed.
454    #[test]
455    fn a_signature_verifies_under_the_seed_key() {
456        let seed = [7u8; 32];
457        let message = b"the manifest bytes";
458        let sig = sign(&seed, message);
459        let public = SigningKey::from_seed(&seed).public_key();
460        assert!(verify_ed25519(&public, message, &sig));
461        assert!(!verify_ed25519(&public, b"other bytes", &sig));
462    }
463}