jmap_cid_types/lib.rs
1//! JMAP Blob Content Identifiers extension types
2//! (draft-atwood-jmap-cid-00).
3//!
4//! Normative reference: draft-atwood-jmap-cid-00 — the
5//! `urn:ietf:params:jmap:cid` JMAP capability. When a server
6//! advertises this capability, it extends the blob upload response
7//! defined in RFC 8620 §6.1 with a `sha256` field carrying the
8//! SHA-256 digest of the uploaded content as a lowercase hex string
9//! of exactly 64 characters. When the JMAP FileNode extension
10//! (draft-ietf-jmap-filenode) is also supported, a `sha256` property
11//! is added to FileNode objects.
12//!
13//! CID is independent of any single consumer extension. It is a
14//! Blob/FileNode-level extension that any JMAP deployment can
15//! advertise, and the `sha256` field defined here is also referenced
16//! by draft-atwood-jmap-chat-00 (which defers to this document as
17//! the normative definition).
18//!
19//! ## Crate posture
20//!
21//! This is a wire-format type crate, per the workspace AGENTS.md
22//! kit-vs-jig posture:
23//!
24//! - No async dependencies.
25//! - No JMAP-server / handler-library dependency.
26//! - Forbids `unsafe`.
27//!
28//! ## Crate family position
29//!
30//! ```text
31//! jmap-types
32//! └── jmap-cid-types ← this crate (capability + sha256 type)
33//! ```
34//!
35//! ## Public surface
36//!
37//! - [`Sha256`] — the 64-character lowercase-hex `sha256-value`
38//! from draft §2, with parse-time ABNF validation on construction
39//! and on deserialize.
40//! - [`Sha256DigestError`] — parse error reported by
41//! [`Sha256::from_hex`] and the [`Sha256`] `Deserialize` impl.
42//! Single-tier enum (no wrapper struct); `#[non_exhaustive]` at
43//! the type level plus per-variant `#[non_exhaustive]` keeps both
44//! variant additions and per-variant field additions
45//! semver-additive.
46//! - [`JMAP_CID_URI`] — the `urn:ietf:params:jmap:cid` capability
47//! URI constant (draft §3).
48//! - [`CidCapability`] — the value object of the
49//! `urn:ietf:params:jmap:cid` capability (draft §3). Currently
50//! empty per the draft; `#[non_exhaustive]` with an `extra`
51//! field per workspace extras-preservation policy.
52//!
53//! ## Wiring into the rest of the kit
54//!
55//! The Blob upload-response binding and `Session::supports_cid()`
56//! advertisement check live in `jmap-base-client` (landed under
57//! closed beads bd:JMAP-v9py.13 and bd:JMAP-v9py.14):
58//!
59//! - `jmap_base_client::blob::BlobUploadResponse.sha256:
60//! Option<jmap_cid_types::Sha256>` — typed digest carried on the
61//! blob upload response when the server advertises CID.
62//! - `jmap_base_client::Session::supports_cid() -> bool` — checks
63//! the session-level capability map for `urn:ietf:params:jmap:cid`.
64//!
65//! The [`CidCapability`] value-object shape (draft §3) lives in
66//! the [`capability`] module alongside [`JMAP_CID_URI`].
67
68#![forbid(unsafe_code)]
69
70pub mod capability;
71pub mod digest;
72
73pub use capability::{CidCapability, JMAP_CID_URI};
74pub use digest::{Sha256, Sha256DigestError};