datumesh-core 0.3.6

Datumesh protocol core: strict JSON and JCS, canonical forms, cell URIs, receipts, keys, envelopes and offline verification.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

//! Core of the [Datumesh](https://datumesh.com) protocol: strict JSON and RFC 8785 JCS,
//! canonical forms of scalars, cells, references, descriptors and receipts, cell URIs, key
//! documents, response envelopes, unit resolution and offline receipt verification.
//!
//! The rules are those of the specification, `SPEC.md` and `units.md` at
//! <https://github.com/datumesh-com/datumesh-spec>. Section numbers in this documentation
//! refer to `SPEC.md`.
//!
//! Every function that can fail returns an [`Error`] carrying one of the codes of SPEC 10.2
//! ([`ErrorCode`]), the JSON path where the failure was found, and a human detail. Nothing in
//! this crate panics on any input, touches the network (except `fetch_keys` behind the
//! `fetch` feature), keeps global state or logs.
//!
//! [`verify`] runs SPEC 10.1. Keys are an input ([`Keys`]); recomputation (step 7) asks a
//! [`Resolver`] for the descriptor, the input receipts, the manifests of slice entries and
//! the evaluation (with its lineage), lazily ([`MapResolver`] holds them in maps). Since
//! `spec-0.4.0` a receipt's lineage may cite whole slices of cells ([`Slice`], [`Manifest`]),
//! and descriptors may carry `signature.order` and argument extents ([`FunctionDescriptor`]).
//! Since `spec-0.4.1` a mesh may answer `pending` ([`check_envelope_any`], [`Pending`]), and
//! cross-mesh resolution reads a host's mesh document ([`resolve_mesh`], [`MeshDoc`]); a
//! verifier needs neither. Since `spec-0.4.2` a reference may be pinned to a function hash
//! ([`Reference`], [`parse_reference`]), and [`Answer`] checks ([`check_answer`],
//! [`check_slice_answer`], [`check_batch`]) and builds every envelope, trust `computed`, slice
//! pages and batches included. Feature `sign` adds `SigningKey` and
//! `ReceiptBuilder`, which make receipts that verify byte for byte like the specification's.
//! Feature `fetch` (`fetch_keys`) is deprecated since 0.3.1 and removed at 1.0: fetch key
//! documents with your own HTTP client and pass the response to [`keys_from_response`].
//!
//! ```
//! use datumesh_core::{verify, Keys, Level};
//!
//! let receipt = br#"{"asof":"2024-03-16T09:00:00.000000Z","cell":{"args":{"base":{"type":"string","value":"EUR"},"date":{"type":"date","value":"2024-03-15"},"quote":{"type":"string","value":"USD"}},"fn":"fx_rate","fn_hash":"7b58ecb8fd23b644c87951d0bd609790ff547cbb23fed27186c669ce2ce0aa80","ns":"rates.example.org"},"computed_by":"rates.example.org#d712b32a2cc5cb7c","inputs":[],"issued":"2024-03-16T09:00:00.000000Z","licence":"CC-BY-4.0","proto":"datumesh/1","publisher":"rates.example.org","sig":"ddf61d49ff6593f7b0d94c76f19fefdd27f47778740b3666fc1c3315ec00c5d216f887c4078deb05c83d4d743453c6fecc568473663b3282ac4eda8c3eadcf01","summary":"1 EUR was worth 1.0892 USD at the 15 March 2024 reference rate.","tx":"2024-03-15T16:00:00.000000Z","type":"number","valid":{"date":{"type":"date","value":"2024-03-15"}},"value":"1.0892"}"#;
//! let key_doc = br#"{"host":"rates.example.org","keys":[{"alg":"ed25519","id":"d712b32a2cc5cb7c","public":"843baeb22bfd0364fb1b7262b367fb3202e7886c69a070fecf8e343fedb1eabf","valid_from":"2020-01-01T00:00:00.000000Z","valid_to":"2024-06-01T00:00:00.000000Z"}],"proto":"datumesh/1"}"#;
//!
//! let mut keys = Keys::new();
//! keys.insert_response("rates.example.org", 200, Some(key_doc));
//! let result = verify(receipt, &keys, None, None);
//! assert!(result.ok);
//! assert_eq!(result.level, Some(Level::Signed));
//! assert_eq!(result.hash.as_deref(), Some("19a5fe3a744c5792f747fb4c286ce396ab44b95922de4f07937502fe595b6f81"));
//! ```

#![forbid(unsafe_code)]
#![deny(missing_docs)]

mod answer;
mod crypto;
mod descriptor;
mod envelope;
mod error;
#[cfg(feature = "fetch")]
mod fetch;
pub mod json;
mod keys;
pub mod lexical;
mod mesh;
mod model;
mod receipt;
mod schema;
#[cfg(feature = "sign")]
mod sign;
mod slice;
#[rustfmt::skip]
mod tables;
#[cfg(feature = "testkit")]
pub mod testkit;
mod uri;
mod verify;

pub use answer::{
    batch_body, check_answer, check_batch, check_slice_answer, Answer, AnswerOutcome, Batch, SlicePage, SliceRequest,
    TrustLabel,
};
pub use crypto::{key_id, sha256, sha256_hex, verify_ed25519};
pub use descriptor::{
    resolve_with, resolved_unit, resolved_unit_value, ArgDecl, Descriptor, Extent, FunctionDescriptor, RateSide,
    Returns, Signature, Unit,
};
pub use envelope::{
    check_envelope, check_envelope_any, check_envelope_extras, AnyEnvelope, Envelope, EnvelopeExtras, Fault,
    InvalidRequest, Outcome, Pending, Quote, Request, Trust,
};
pub use error::{Error, ErrorCode, Result};
pub use mesh::{resolve_mesh, MeshDoc, ResolvedMesh, Retrieval};
// The re-export is not a use: only callers see the deprecation (Rust 1.97 warns here otherwise).
#[cfg(feature = "fetch")]
#[allow(deprecated)]
pub use fetch::fetch_keys;
pub use keys::{keys_from_response, Key, KeyDoc, Keys};
pub use model::{Arg, Args, Cell, CellRef, Reference, Scalar, Type};
pub use receipt::{receipt_hash, receipt_payload, Receipt};
#[cfg(feature = "sign")]
pub use sign::{ReceiptBuilder, SigningKey};
pub use slice::{Manifest, Slice};
pub use uri::{cell_uri_from_https, format_reference, format_uri, https_url, parse_reference, parse_uri};
pub use verify::{verify, Evaluation, Level, MapResolver, Resolver, VerifyResult};

/// Canonical bytes of a typed scalar given as JSON text (4.1, 6.2).
pub fn canonicalize_scalar(json: &[u8]) -> Result<Vec<u8>> {
    Ok(Scalar::from_json(json)?.canonical())
}

/// Canonical bytes of a cell given as JSON text (4.4, 6.2). Slices are allowed.
pub fn canonicalize_cell(json: &[u8]) -> Result<Vec<u8>> {
    Ok(Cell::from_json(json)?.canonical())
}

/// Canonical bytes of a cell reference given as JSON text (4.3, 6.2).
pub fn canonicalize_ref(json: &[u8]) -> Result<Vec<u8>> {
    Ok(CellRef::from_json(json)?.canonical())
}

/// Canonical bytes of a function descriptor given as JSON text (7, 6.2), `order` and
/// `extent` included (`spec-0.4.0`; see [`FunctionDescriptor`]).
pub fn canonicalize_descriptor(json: &[u8]) -> Result<Vec<u8>> {
    Ok(FunctionDescriptor::from_json(json)?.canonical())
}

/// The signed payload of a receipt given as JSON text: canonical bytes without `sig` (8.3).
/// Runs verification steps 1-4 first.
pub fn canonicalize_receipt(json: &[u8]) -> Result<Vec<u8>> {
    receipt_payload(json)
}

/// The cell id of a cell given as JSON text: SHA-256 of its canonical bytes (4.4, 6.3).
pub fn cell_hash(json: &[u8]) -> Result<String> {
    Ok(Cell::from_json(json)?.id())
}

/// The function hash of a descriptor given as JSON text (7, 6.3), `order` and `extent`
/// included.
pub fn function_hash(json: &[u8]) -> Result<String> {
    Ok(FunctionDescriptor::from_json(json)?.hash())
}

/// Canonical bytes of a slice object given as JSON text (4.4, 6.2; `spec-0.4.0`).
pub fn canonicalize_slice(json: &[u8]) -> Result<Vec<u8>> {
    Ok(Slice::from_json(json)?.canonical())
}