dig_urn_protocol/
lib.rs

1//! # dig-urn-protocol
2//!
3//! The **canonical DIG content-addressing + server-untrusted verification contract** — the one
4//! definition of how a DIG URN names content and how a blind client turns opaque gateway bytes into
5//! verified plaintext, fail-closed.
6//!
7//! This crate OWNS (and is the single source of truth for):
8//!
9//! * **The `urn:dig:` scheme + byte-level grammar** — [`DigUrn`] parsing, [`DigUrn::canonical`]
10//!   rendering, and `retrieval_key = SHA-256(canonical())` (plus the root-independent
11//!   `content_key = SHA-256(canonical_rootless())`) derivation. The [`grammar`]
12//!   module carries the normative ABNF, pinned by the frozen conformance vectors.
13//! * **The resolution INTERFACE** — the [`UrnResolver`] trait plus [`ResolveOutcome`] /
14//!   [`ResolveError`] / [`ResolveOptions`]. The contract, not the transport.
15//! * **The browser content-VERIFICATION contract** — [`verify`]: rootless rejection, leaf-binding,
16//!   path-fold, root-anchoring, gate-then-decrypt, and the u64-bounded chunk split — over crypto
17//!   primitives INJECTED via [`verify::ContentCrypto`].
18//!
19//! ## A leaf crate that reimplements no crypto
20//!
21//! `dig-urn-protocol` has NO `dig-*` dependencies and NO transport (reqwest/tokio). The merkle-fold
22//! and AES primitives are supplied by the caller (`digstore_core`), so this crate can never skew from
23//! the canonical read-crypto. It performs only SHA-256 (the retrieval key + the content leaf), which
24//! is byte-identical to `digstore_core`'s.
25//!
26//! ## Relationship to `dig-rpc-protocol`
27//!
28//! This crate owns addressing + resolution + verification only. It CONSUMES the `dig-rpc-protocol`
29//! `PublicRead` contract conceptually for the actual fetch, but does not depend on it or duplicate
30//! any RPC method — a concrete [`UrnResolver`] wires the two together.
31
32#![forbid(unsafe_code)]
33
34pub mod bytes;
35pub mod grammar;
36pub mod resolve;
37pub mod urn;
38pub mod verify;
39
40pub use bytes::{Bytes32, InvalidBytes32};
41pub use grammar::{CANONICAL_CHAIN, DEFAULT_RESOURCE_KEY, SALT_QUERY_MARKER, URN_ABNF, URN_PREFIX};
42pub use resolve::{
43    ResolveError, ResolveOptions, ResolveOutcome, ResolvedData, Result, UrnResolver,
44};
45pub use urn::{DigUrn, SecretSalt, UrnParseError};
46pub use verify::{
47    chunk_ranges, decrypt, require_blind_root, resource_leaf, verify_and_decrypt, verify_inclusion,
48    ContentCrypto, FoldedProof,
49};
50
51/// The crate version (matches `Cargo.toml`), for compatibility checks.
52pub fn version() -> &'static str {
53    env!("CARGO_PKG_VERSION")
54}
55
56#[cfg(test)]
57mod tests {
58    #[test]
59    fn version_is_reported() {
60        assert!(!super::version().is_empty());
61    }
62}
dig_urn_protocol/lib.rs

dig_urn_protocol/
lib.rs
