uor_addr/cbor/
pipeline.rs

1//! `cbor::address*` — the CBOR realization's public entry points, one per
2//! admissible σ-axis ([`crate::hash`]).
3//!
4//! 1. [`canonicalize`] re-encodes the
5//!    input under RFC 8949 §4.2 Deterministic Encoding into an `alloc`
6//!    buffer (shortest ints/floats, definite lengths, sorted map keys).
7//! 2. The selected axis's `AddressModel*::forward` runs the shared ψ-tower:
8//!    the canonical bytes flow in as an ADR-060 `Borrowed` carrier and ψ₉
9//!    folds them through the bound `H` to mint the κ-label.
10//! 3. [`AddressOutcome::from_grounded`] extracts the owned κ-label +
11//!    replayable TC-05 witness.
12//!
13//! [`address`] selects `H = Sha256Hasher` (the default); [`address_blake3`],
14//! [`address_sha3_256`], and [`address_keccak256`] select the other 32-byte
15//! axes. CBOR canonicalization requires heap storage (per-map key-sort
16//! scratch + canonical output), so the entry points are gated behind the
17//! `alloc` feature.
18
19pub use crate::outcome::{AddressOutcome, AddressWitness, VerifyError};
20
21/// Failure modes from the CBOR entry points.
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub enum AddressFailure {
24    /// The input bytes were not exactly one well-formed CBOR data item
25    /// (bad/reserved head, non-UTF-8 text string, duplicate map key,
26    /// trailing bytes, or over-deep nesting).
27    InvalidCbor,
28    /// Defensive: foundation's catamorphism or a resolver returned a
29    /// shape violation. Unreachable for well-formed inputs.
30    PipelineFailure,
31}
32
33#[cfg(feature = "alloc")]
34use crate::cbor::model::{
35    AddressModel, AddressModelBlake3, AddressModelKeccak256, AddressModelSha3_256,
36    AddressModelSha512,
37};
38#[cfg(feature = "alloc")]
39use crate::cbor::value::{canonicalize, CborCarrier};
40#[cfg(feature = "alloc")]
41use prism::pipeline::PrismModel;
42
43/// **uor-addr's CBOR entry point** (σ-axis `Sha256Hasher`) — one ψ-pipeline
44/// content-address inference, yielding a `sha256:<64hex>` κ-label over the
45/// RFC 8949 §4.2 canonical form.
46///
47/// # Errors
48///
49/// - [`AddressFailure::InvalidCbor`] — input is not one well-formed CBOR item.
50/// - [`AddressFailure::PipelineFailure`] — defensive; unreachable.
51#[cfg(feature = "alloc")]
52pub fn address(input_bytes: &[u8]) -> Result<AddressOutcome<71>, AddressFailure> {
53    let canonical = canonicalize(input_bytes).map_err(|_| AddressFailure::InvalidCbor)?;
54    let grounded = AddressModel::forward(CborCarrier::new(&canonical))
55        .map_err(|_| AddressFailure::PipelineFailure)?;
56    AddressOutcome::<71>::from_grounded(&grounded).map_err(|_| AddressFailure::PipelineFailure)
57}
58
59/// The CBOR entry point under σ-axis `Blake3Hasher` — yields a
60/// `blake3:<64hex>` κ-label. See [`address`] for the error contract.
61///
62/// # Errors
63///
64/// As [`address`].
65#[cfg(feature = "alloc")]
66pub fn address_blake3(input_bytes: &[u8]) -> Result<AddressOutcome<71>, AddressFailure> {
67    let canonical = canonicalize(input_bytes).map_err(|_| AddressFailure::InvalidCbor)?;
68    let grounded = AddressModelBlake3::forward(CborCarrier::new(&canonical))
69        .map_err(|_| AddressFailure::PipelineFailure)?;
70    AddressOutcome::<71>::from_grounded(&grounded).map_err(|_| AddressFailure::PipelineFailure)
71}
72
73/// The CBOR entry point under σ-axis `Sha3_256Hasher` — yields a
74/// `sha3-256:<64hex>` κ-label. See [`address`] for the error contract.
75///
76/// # Errors
77///
78/// As [`address`].
79#[cfg(feature = "alloc")]
80pub fn address_sha3_256(input_bytes: &[u8]) -> Result<AddressOutcome<73>, AddressFailure> {
81    let canonical = canonicalize(input_bytes).map_err(|_| AddressFailure::InvalidCbor)?;
82    let grounded = AddressModelSha3_256::forward(CborCarrier::new(&canonical))
83        .map_err(|_| AddressFailure::PipelineFailure)?;
84    AddressOutcome::<73>::from_grounded(&grounded).map_err(|_| AddressFailure::PipelineFailure)
85}
86
87/// The CBOR entry point under σ-axis `Keccak256Hasher` — yields a
88/// `keccak256:<64hex>` κ-label. See [`address`] for the error contract.
89///
90/// # Errors
91///
92/// As [`address`].
93#[cfg(feature = "alloc")]
94pub fn address_keccak256(input_bytes: &[u8]) -> Result<AddressOutcome<74>, AddressFailure> {
95    let canonical = canonicalize(input_bytes).map_err(|_| AddressFailure::InvalidCbor)?;
96    let grounded = AddressModelKeccak256::forward(CborCarrier::new(&canonical))
97        .map_err(|_| AddressFailure::PipelineFailure)?;
98    AddressOutcome::<74>::from_grounded(&grounded).map_err(|_| AddressFailure::PipelineFailure)
99}
100
101/// The cbor entry point under σ-axis `Sha512Hasher` — yields a
102/// `sha512:<128hex>` κ-label (135 bytes, 64-byte fingerprint). See
103/// [`address`] for the error contract.
104///
105/// # Errors
106///
107/// As [`address`].
108#[cfg(feature = "alloc")]
109pub fn address_sha512(input_bytes: &[u8]) -> Result<AddressOutcome<135, 64>, AddressFailure> {
110    let canonical = canonicalize(input_bytes).map_err(|_| AddressFailure::InvalidCbor)?;
111    let grounded = AddressModelSha512::forward(CborCarrier::new(&canonical))
112        .map_err(|_| AddressFailure::PipelineFailure)?;
113    AddressOutcome::<135, 64>::from_grounded(&grounded).map_err(|_| AddressFailure::PipelineFailure)
114}
uor_addr/cbor/pipeline.rs

uor_addr/cbor/
pipeline.rs
