datumesh_core/lib.rs
1//! Core of the [Datumesh](https://datumesh.com) protocol: strict JSON and RFC 8785 JCS,
2//! canonical forms of scalars, cells, references, descriptors and receipts, cell URIs, key
3//! documents, response envelopes, unit resolution and offline receipt verification.
4//!
5//! The rules are those of the specification, `SPEC.md` and `units.md` at
6//! <https://github.com/datumesh-com/datumesh-spec>. Section numbers in this documentation
7//! refer to `SPEC.md`.
8//!
9//! Every function that can fail returns an [`Error`] carrying one of the codes of SPEC 10.2
10//! ([`ErrorCode`]), the JSON path where the failure was found, and a human detail. Nothing in
11//! this crate panics on any input, touches the network (except `fetch_keys` behind the
12//! `fetch` feature), keeps global state or logs.
13//!
14//! [`verify`] runs SPEC 10.1. Keys are an input ([`Keys`]); recomputation (step 7) asks a
15//! [`Resolver`] for the descriptor, the input receipts, the manifests of slice entries and
16//! the evaluation (with its lineage), lazily ([`MapResolver`] holds them in maps). Since
17//! `spec-0.4.0` a receipt's lineage may cite whole slices of cells ([`Slice`], [`Manifest`]),
18//! and descriptors may carry `signature.order` and argument extents ([`FunctionDescriptor`]).
19//! Since `spec-0.4.1` a mesh may answer `pending` ([`check_envelope_any`], [`Pending`]), and
20//! cross-mesh resolution reads a host's mesh document ([`resolve_mesh`], [`MeshDoc`]); a
21//! verifier needs neither. Feature `sign` adds `SigningKey` and
22//! `ReceiptBuilder`, which make receipts that verify byte for byte like the specification's.
23//! Feature `fetch` (`fetch_keys`) is deprecated since 0.3.1 and removed at 1.0: fetch key
24//! documents with your own HTTP client and pass the response to [`keys_from_response`].
25//!
26//! ```
27//! use datumesh_core::{verify, Keys, Level};
28//!
29//! 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"}"#;
30//! 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"}"#;
31//!
32//! let mut keys = Keys::new();
33//! keys.insert_response("rates.example.org", 200, Some(key_doc));
34//! let result = verify(receipt, &keys, None, None);
35//! assert!(result.ok);
36//! assert_eq!(result.level, Some(Level::Signed));
37//! assert_eq!(result.hash.as_deref(), Some("19a5fe3a744c5792f747fb4c286ce396ab44b95922de4f07937502fe595b6f81"));
38//! ```
39
40#![forbid(unsafe_code)]
41#![deny(missing_docs)]
42
43mod crypto;
44mod descriptor;
45mod envelope;
46mod error;
47#[cfg(feature = "fetch")]
48mod fetch;
49pub mod json;
50mod keys;
51pub mod lexical;
52mod mesh;
53mod model;
54mod receipt;
55mod schema;
56#[cfg(feature = "sign")]
57mod sign;
58mod slice;
59#[rustfmt::skip]
60mod tables;
61#[cfg(feature = "testkit")]
62pub mod testkit;
63mod uri;
64mod verify;
65
66pub use crypto::{key_id, sha256, sha256_hex, verify_ed25519};
67pub use descriptor::{
68 resolve_with, resolved_unit, resolved_unit_value, ArgDecl, Descriptor, Extent, FunctionDescriptor, RateSide,
69 Returns, Signature, Unit,
70};
71pub use envelope::{
72 check_envelope, check_envelope_any, check_envelope_extras, AnyEnvelope, Envelope, EnvelopeExtras, Fault,
73 InvalidRequest, Outcome, Pending, Quote, Request, Trust,
74};
75pub use error::{Error, ErrorCode, Result};
76pub use mesh::{resolve_mesh, MeshDoc, ResolvedMesh, Retrieval};
77// The re-export is not a use: only callers see the deprecation (Rust 1.97 warns here otherwise).
78#[cfg(feature = "fetch")]
79#[allow(deprecated)]
80pub use fetch::fetch_keys;
81pub use keys::{keys_from_response, Key, KeyDoc, Keys};
82pub use model::{Arg, Args, Cell, CellRef, Scalar, Type};
83pub use receipt::{receipt_hash, receipt_payload, Receipt};
84#[cfg(feature = "sign")]
85pub use sign::{ReceiptBuilder, SigningKey};
86pub use slice::{Manifest, Slice};
87pub use uri::{cell_uri_from_https, format_uri, https_url, parse_uri};
88pub use verify::{verify, Evaluation, Level, MapResolver, Resolver, VerifyResult};
89
90/// Canonical bytes of a typed scalar given as JSON text (4.1, 6.2).
91pub fn canonicalize_scalar(json: &[u8]) -> Result<Vec<u8>> {
92 Ok(Scalar::from_json(json)?.canonical())
93}
94
95/// Canonical bytes of a cell given as JSON text (4.4, 6.2). Slices are allowed.
96pub fn canonicalize_cell(json: &[u8]) -> Result<Vec<u8>> {
97 Ok(Cell::from_json(json)?.canonical())
98}
99
100/// Canonical bytes of a cell reference given as JSON text (4.3, 6.2).
101pub fn canonicalize_ref(json: &[u8]) -> Result<Vec<u8>> {
102 Ok(CellRef::from_json(json)?.canonical())
103}
104
105/// Canonical bytes of a function descriptor given as JSON text (7, 6.2), `order` and
106/// `extent` included (`spec-0.4.0`; see [`FunctionDescriptor`]).
107pub fn canonicalize_descriptor(json: &[u8]) -> Result<Vec<u8>> {
108 Ok(FunctionDescriptor::from_json(json)?.canonical())
109}
110
111/// The signed payload of a receipt given as JSON text: canonical bytes without `sig` (8.3).
112/// Runs verification steps 1-4 first.
113pub fn canonicalize_receipt(json: &[u8]) -> Result<Vec<u8>> {
114 receipt_payload(json)
115}
116
117/// The cell id of a cell given as JSON text: SHA-256 of its canonical bytes (4.4, 6.3).
118pub fn cell_hash(json: &[u8]) -> Result<String> {
119 Ok(Cell::from_json(json)?.id())
120}
121
122/// The function hash of a descriptor given as JSON text (7, 6.3), `order` and `extent`
123/// included.
124pub fn function_hash(json: &[u8]) -> Result<String> {
125 Ok(FunctionDescriptor::from_json(json)?.hash())
126}
127
128/// Canonical bytes of a slice object given as JSON text (4.4, 6.2; `spec-0.4.0`).
129pub fn canonicalize_slice(json: &[u8]) -> Result<Vec<u8>> {
130 Ok(Slice::from_json(json)?.canonical())
131}