Skip to main content

Crate publet_core

Crate publet_core 

Source
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::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:

The rest of this page is:

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.

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.

CrateWhat it isWhy not here
ciborium 0.2.2General CBOR with serdeAccepted 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.0Small no_std CBOR codecLenient in the same way: it accepted the six forbidden encodings tried, reading a non-shortest integer as the plain value.
dcbor 0.25.2Deterministic CBORStrict, 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.2CBOR with serdeUnmaintained since 2021.
cid 0.11.3IPFS content identifiersA 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§

CanonError
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.
ObjectError
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_bytes for purpose.
signing_message
Construct the message a signature covers.
verify
Verify a detached signature over target_bytes for expected_purpose.
verifying_key
Derive the public key matching a secret key.