Expand description
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");§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::decoderejects 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::parseyields anUnverifiedobject. OnlyUnverified::verify, against the identifier you asked for, gives aVerifiedone, and only that is worth acting on.
The types:
Objectis a parsed object: its header, its body, and its bytes.Object::buildermakes one, as canonical bytes.Cidis a content identifier:pub:<algorithm>:<base32 digest>, computed byCid::of, parsed from text, printed byDisplay.cbor::Valueis a value in the profile, withcbor::encodeandcbor::decode.sign,verifyandverifying_keymake and check detached Ed25519 signatures, each bound to a purpose.
The rest of this page is:
- Examples: a short cookbook.
- Why this crate?: what a general CBOR library or IPFS identifiers would get wrong here.
- Related crates: what was considered instead, and why not.
- Crate features, Minimum Rust version and Versioning.
Longer documents live in _documentation: how every item is
tested, how each dependency is
vouched for, the project’s
security policy, and the
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());§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), 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 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 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 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 0.11.2 | CBOR with serde | Unmaintained since 2021. |
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
for SHA-256, ed25519-dalek for
signatures, and 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,
so a release cannot break the API without the
changelog saying so.
Modules§
- _documentation
- Longer documents: testing, the supply chain, security, and the changelog.
- cbor
- Deterministic CBOR under the profile in Section 4.1 of the specification.
Structs§
- Builder
- Builds an object and emits its canonical bytes.
- Cid
- A content identifier.
- Object
- A parsed object: its header, its body, and the bytes it came from.
- Unverified
- An object whose identity has not been checked.
- Verified
- An object whose bytes have been confirmed against its identifier.
Enums§
- Canon
Error - A way in which bytes failed the canonical serialization profile.
- CidError
- Reasons a string is not a well-formed CID.
- HashAlg
- A hash algorithm usable for content identifiers.
- Object
Error - Reasons an object is not well formed.
- SigAlg
- A signature algorithm.
- SigError
- Reasons a signature does not verify.
Constants§
- PROTOCOL_
VERSION - The protocol major version this build implements.
Functions§
- sign
- Produce a detached signature over
target_bytesforpurpose. - signing_
message - Construct the message a signature covers.
- verify
- Verify a detached signature over
target_bytesforexpected_purpose. - verifying_
key - Derive the public key matching a secret key.