1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
/*!
Objects, canonical serialization, content identifiers and signatures for the
[Publet Protocol]: Section 4 of the specification, and the floor every other
publet crate and tool builds on.
Here is an object built, named by its identifier, and checked against it:
```
use publet_core::{Cid, HashAlg, Object, cbor::Value};
// An author is named by the identifier of their key object.
let author = Cid::of(b"the author's key object", HashAlg::Sha2_256).to_string();
let bytes = Object::builder("claim.prose", &author)
.created("2026-10-05T00:00:00Z")
.field("content", Value::Text("Water boils at 100 °C at sea level.".into()))
.build()?;
let cid = Cid::of(&bytes, HashAlg::Sha2_256);
// Bytes fetched from anywhere are checked against the identifier asked for.
let object = Object::parse(&bytes)?.verify(&cid)?;
assert_eq!(object.object().kind(), "claim.prose");
# Ok::<(), Box<dyn std::error::Error>>(())
```
[Publet Protocol]: https://github.com/Sustenaut/publet/blob/main/spec/index.md
# Overview
The crate holds two invariants that everything built on it assumes:
* **An object has exactly one byte representation.** Objects are CBOR under
a strict profile (Section 4.1): text map keys sorted by their UTF-8 bytes,
integers in shortest form, NFC text, and no floats, tags or
indefinite lengths. [`cbor::decode`] rejects anything else, naming the rule
broken, so equal content always has the same identifier.
* **An object is not usable until it has been checked.** [`Object::parse`]
yields an [`Unverified`] object. Only [`Unverified::verify`], against the
identifier you asked for, gives a [`Verified`] one, and only that is worth
acting on.
The types:
* [`Object`] is a parsed object: its header, its body, and its bytes.
[`Object::builder`] makes one, as canonical bytes.
* [`Cid`] is a content identifier: `pub:<algorithm>:<base32 digest>`,
computed by [`Cid::of`], parsed from text, printed by `Display`.
* [`cbor::Value`] is a value in the profile, with [`cbor::encode`] and
[`cbor::decode`].
* [`sign`], [`verify`] and [`verifying_key`] make and check detached Ed25519
signatures, each bound to a *purpose*.
The rest of this page is:
* [Examples](#examples): a short cookbook.
* [Why this crate?](#why-this-crate): what a general CBOR library or IPFS
identifiers would get wrong here.
* [Related crates](#related-crates): what was considered instead, and why not.
* [Crate features](#crate-features), [Minimum Rust version](#minimum-rust-version)
and [Versioning](#versioning).
Longer documents live in [`_documentation`]: how every item is
[tested](crate::_documentation::testing), how each dependency is
[vouched for](crate::_documentation::supply_chain), the project's
[security](crate::_documentation::security) policy, and the
[changelog](crate::_documentation::changelog).
# Examples
## Example: sign an object for a purpose
A signature covers an object's bytes *and* a purpose. One made for
`authored` says nothing about `retracted`, so an endorsement cannot be
replayed as something else.
```
use publet_core::{SigAlg, sign, verify, verifying_key};
let object = b"an object's canonical bytes";
// A real seed comes from a random source; this crate needs no RNG.
let seed = [7u8; 32];
let public = verifying_key(SigAlg::Ed25519, &seed)?;
let signature = sign(SigAlg::Ed25519, &seed, "authored", object)?;
verify(SigAlg::Ed25519, &public, &signature, "authored", "authored", object)?;
assert!(verify(SigAlg::Ed25519, &public, &signature, "authored", "retracted", object).is_err());
# Ok::<(), publet_core::SigError>(())
```
## Example: non-canonical bytes are refused, by rule
```
use publet_core::cbor::decode;
// 5 written in two bytes; its canonical form is the single byte 0x05.
let error = decode(&[0x18, 0x05]).unwrap_err();
assert_eq!(error.rule(), "shortest-form integers");
// {"b": 1, "a": 2}: keys out of order.
let error = decode(&[0xa2, 0x61, b'b', 0x01, 0x61, b'a', 0x02]).unwrap_err();
assert_eq!(error.rule(), "sorted map keys");
```
## Example: identifiers are text
```
use publet_core::{Cid, CidError, HashAlg};
let cid = Cid::of(b"", HashAlg::Sha2_256);
let text = cid.to_string();
assert_eq!(text, "pub:sha2-256:4oymiquy7qobjgx36tejs35zeqt24qpemsnzgtfeswmrw6csxbkq");
assert_eq!(text.parse::<Cid>(), Ok(cid));
assert_eq!("ipfs:bafy".parse::<Cid>(), Err(CidError::MissingScheme));
```
# Why this crate?
Content addressing works only if equal content has equal bytes. CBOR allows
many encodings of one value: integers padded to longer forms, keys in any
order, lengths left open. General-purpose decoders accept them all; `ciborium`
and `minicbor` both decode a padded integer to the same value as the
canonical one (see [Related crates](#related-crates)), so a program that
checked the decoded value would accept bytes with a different identifier. Section 4.1 requires rejecting non-canonical bytes outright, never
repairing them. The decoder here checks every rule while parsing, so the
first violation is reported with its offset, and no value is built from bad
input.
The identifiers are the protocol's own (Section 4.2): `pub:` and an algorithm
name, then the digest in lowercase base32. The algorithm travels in the
identifier, so a future migration is a new name rather than a flag day.
And the types make the checks hard to skip. Nothing returns an object you can
act on without verifying it against an identifier first, and [`verify`]
takes the purpose you require as an argument, so a signature cannot be
checked without one.
# Related crates
Crates that do similar jobs, and why this one takes another approach. Each
was checked at the version shown. The CBOR libraries were given encodings
Section 4.1 forbids: integers not in shortest form, indefinite lengths,
unsorted and duplicate keys, non-text keys, floats, tags, non-NFC text, and
trailing bytes.
| Crate | What it is | Why not here |
|---|---|---|
| [`ciborium`](https://crates.io/crates/ciborium) 0.2.2 | General CBOR with serde | Accepted every forbidden encoding, decoding several to the same values as the canonical bytes, so a later check cannot tell them apart. Its canonical key order differs from Section 4.1's. |
| [`minicbor`](https://crates.io/crates/minicbor) 2.3.0 | Small `no_std` CBOR codec | Lenient in the same way: it accepted the six forbidden encodings tried, reading a non-shortest integer as the plain value. |
| [`dcbor`](https://crates.io/crates/dcbor) 0.25.2 | Deterministic CBOR | Strict, and rejects most forbidden encodings. But it orders map keys by encoded length (RFC 8949 §4.2.1), while Section 4.1 orders them by UTF-8 bytes, so it rejects this crate's canonical objects. It also admits floats, tags and non-text keys. |
| [`serde_cbor`](https://crates.io/crates/serde_cbor) 0.11.2 | CBOR with serde | Unmaintained since 2021. |
| [`cid`](https://crates.io/crates/cid) 0.11.3 | IPFS content identifiers | A multiformats CID carries a version, a codec and a multibase prefix (`bafy…`). Section 4.2 defines a different text form, `pub:<algorithm>:<base32>`, so its parser and printer don't apply. |
What this crate builds on rather than reimplements: [`sha2`](https://crates.io/crates/sha2)
for SHA-256, [`ed25519-dalek`](https://crates.io/crates/ed25519-dalek) for
signatures, and [`unicode-normalization`](https://crates.io/crates/unicode-normalization)
for the NFC check.
# Crate features
None. Everything in the crate is always available.
# Minimum Rust version
This crate requires Rust 1.85 (its `rust-version`), the first release with
the 2024 edition; CI builds it there. The minimum may rise in a release that
bumps the minor version, and never in a patch release.
# Versioning
Versions follow Cargo's convention: below 1.0, a breaking change bumps the
minor version (`0.1.x` to `0.2.0`) and anything compatible bumps the patch.
Each change to the public API is checked against the last release (its
`publet-core-v` tag) by [`cargo-semver-checks`](https://crates.io/crates/cargo-semver-checks),
so a release cannot break the API without the
[changelog](crate::_documentation::changelog) saying so.
*/
pub use ;
pub use CanonError;
pub use ;
pub use ;
/// Longer documents: testing, the supply chain, security, and the changelog.
///
/// These modules hold no code. Each is a document, kept in the repository as
/// Markdown and rendered here so it is versioned with the crate.
// Prose documents, one of them generated from release records: clippy's
// backtick rule for API docs does not fit them.
/// The README's examples, run as tests without being rendered twice.
;