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//! ```
15//! use datumesh_core::{verify, Keys, Level};
16//!
17//! 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"}"#;
18//! 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"}"#;
19//!
20//! let mut keys = Keys::new();
21//! keys.insert_response("rates.example.org", 200, Some(key_doc));
22//! let result = verify(receipt, &keys, None, None);
23//! assert!(result.ok);
24//! assert_eq!(result.level, Some(Level::Signed));
25//! assert_eq!(result.hash.as_deref(), Some("19a5fe3a744c5792f747fb4c286ce396ab44b95922de4f07937502fe595b6f81"));
26//! ```
27
28#![forbid(unsafe_code)]
29#![deny(missing_docs)]
30
31mod crypto;
32mod descriptor;
33mod envelope;
34mod error;
35#[cfg(feature = "fetch")]
36mod fetch;
37pub mod json;
38mod keys;
39pub mod lexical;
40mod model;
41mod receipt;
42mod schema;
43#[rustfmt::skip]
44mod tables;
45mod uri;
46mod verify;
47
48pub use crypto::{key_id, sha256, sha256_hex, verify_ed25519};
49pub use descriptor::{
50    resolve_with, resolved_unit, resolved_unit_value, ArgDecl, Descriptor, RateSide, Returns, Signature, Unit,
51};
52pub use envelope::{check_envelope, Envelope, InvalidRequest, Outcome, Quote, Request, Trust};
53pub use error::{Error, ErrorCode, Result};
54#[cfg(feature = "fetch")]
55pub use fetch::fetch_keys;
56pub use keys::{keys_from_response, Key, KeyDoc, Keys};
57pub use model::{Arg, Args, Cell, CellRef, Scalar, Type};
58pub use receipt::{receipt_hash, receipt_payload, Receipt};
59pub use uri::{cell_uri_from_https, format_uri, https_url, parse_uri};
60pub use verify::{verify, Level, Recompute, VerifyResult};
61
62/// Canonical bytes of a typed scalar given as JSON text (4.1, 6.2).
63pub fn canonicalize_scalar(json: &[u8]) -> Result<Vec<u8>> {
64    Ok(Scalar::from_json(json)?.canonical())
65}
66
67/// Canonical bytes of a cell given as JSON text (4.4, 6.2). Slices are allowed.
68pub fn canonicalize_cell(json: &[u8]) -> Result<Vec<u8>> {
69    Ok(Cell::from_json(json)?.canonical())
70}
71
72/// Canonical bytes of a cell reference given as JSON text (4.3, 6.2).
73pub fn canonicalize_ref(json: &[u8]) -> Result<Vec<u8>> {
74    Ok(CellRef::from_json(json)?.canonical())
75}
76
77/// Canonical bytes of a function descriptor given as JSON text (7, 6.2).
78pub fn canonicalize_descriptor(json: &[u8]) -> Result<Vec<u8>> {
79    Ok(Descriptor::from_json(json)?.canonical())
80}
81
82/// The signed payload of a receipt given as JSON text: canonical bytes without `sig` (8.3).
83/// Runs verification steps 1-4 first.
84pub fn canonicalize_receipt(json: &[u8]) -> Result<Vec<u8>> {
85    receipt_payload(json)
86}
87
88/// The cell id of a cell given as JSON text: SHA-256 of its canonical bytes (4.4, 6.3).
89pub fn cell_hash(json: &[u8]) -> Result<String> {
90    Ok(Cell::from_json(json)?.id())
91}
92
93/// The function hash of a descriptor given as JSON text (7, 6.3).
94pub fn function_hash(json: &[u8]) -> Result<String> {
95    Ok(Descriptor::from_json(json)?.hash())
96}
datumesh_core/lib.rs

datumesh_core/
lib.rs
