Skip to main content

hyprstream_rpc/
cid.rs

1//! CIDv1 + multihash encoder for content-addressed model references (#395).
2//!
3//! Produces deterministic CIDv1 strings for git OIDs and XET chunk/shard hashes,
4//! giving every model artifact a single canonical identifier that survives moves
5//! between the local registry, the atproto federated record store, and XET-backed
6//! CAS shards. The wire representation stays `modelRef :Text` in the capnp schema
7//! (#395 is a Rust-only grammar change); the CID is the canonical text payload
8//! federated peers resolve.
9//!
10//! ## Layout
11//!
12//! ```text
13//! CIDv1   ::= multibase("b") || base32( <0x01> || multicodec || multihash )
14//! multihash ::= uvarint(algo) || uvarint(len) || digest
15//! ```
16//!
17//! - **Multibase `b`** is lowercase RFC4648 base32 without padding — the
18//!   IPFS/atproto *canonical* CIDv1 encoding. (The `z` base58btc prefix used by
19//!   DID-doc Multikeys is rejected here: CIDs are base32.) See
20//!   <https://github.com/multiformats/multibase>.
21//! - **CID version** is always `0x01` (CIDv1). CIDv0 (sha1+git implicit) is not
22//!   emitted; git OIDs get an explicit CIDv1 instead.
23//! - **Multicodec** identifies the *content type*: `git-raw` (0x78) for a raw git
24//!   object addressed by OID, the local XET codes below for XET hashes, and the
25//!   local `at9p-capsule` code for capsule commitments.
26//! - **Multihash** carries the hash algorithm + digest, so a CID is self-describing
27//!   and can address sha1 git blobs, sha2-256 git-tree hashes, and blake3 XET
28//!   chunks uniformly.
29//!
30//! ## Hash codes (multiformats/multicodec registry)
31//!
32//! | algo      | code   | used for                          |
33//! |-----------|--------|-----------------------------------|
34//! | sha1      | 0x11   | legacy git blob/tree/commit OIDs  |
35//! | sha2-256  | 0x12   | git OIDs (sha256 repos), XET tags |
36//! | blake3    | 0x1e   | XET hashes; at9p BLAKE3-512 CIDs  |
37//!
38//! ## Multicodec codes
39//!
40//! | codec         | code  | status                                  |
41//! |---------------|-------|-----------------------------------------|
42//! | git-raw       | 0x78  | registered (multicodec table)           |
43//! | xet-xorb      | 0x71  | LOCAL convention, unregistered (#395)   |
44//! | xet-shard     | 0x72  | LOCAL convention, unregistered (#395)   |
45//! | at9p-capsule  | 0x73  | LOCAL convention, unregistered (#881)   |
46//!
47//! The XET and at9p-capsule codes live in the multicodec reserved (`0x70`–`0x7f`)
48//! private-use range and MUST be replaced with official codes once registered
49//! with multiformats. They are tagged `LOCAL_CONVENTION` so a `grep` finds them
50//! when the migration lands.
51//!
52//! ## Determinism
53//!
54//! Encoding is a pure function of `(codec, algo, digest)`: the same input always
55//! yields the same CID string (no randomness, no timestamps, no canonicalization
56//! ambiguity). Round-tripping `decode(encode(x)) == x` holds for all valid CIDs.
57
58use anyhow::{bail, ensure, Context, Result};
59use data_encoding::BASE32_NOPAD;
60
61// ---------------------------------------------------------------------------
62// CIDv1 + multihash structural constants
63// ---------------------------------------------------------------------------
64
65/// Multibase prefix for lowercase RFC4648 base32 without padding — the canonical
66/// CIDv1 encoding. (Contrast DID-doc Multikeys, which use `z` = base58btc.)
67const MULTIBASE_BASE32: char = 'b';
68
69/// CID version byte for CIDv1 (the only version this module emits).
70const CIDV1: u8 = 0x01;
71
72/// Hash-algorithm codes from the multihash table
73/// (<https://github.com/multiformats/multicodec/blob/master/table.md>).
74///
75/// Only the algorithms we actually address (git sha1/sha2-256, XET blake3) are
76/// modeled; the table is intentionally not exhaustive.
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
78#[repr(u64)]
79pub enum HashAlgo {
80    /// sha1 (code 0x11). Legacy git blob/tree/commit OIDs.
81    Sha1 = 0x11,
82    /// sha2-256 (code 0x12). git OIDs in sha256 repos; XET tag hashes.
83    Sha2_256 = 0x12,
84    /// blake3 (code 0x1e). XET chunk/shard hashes and at9p capsule commitments.
85    Blake3 = 0x1e,
86}
87
88impl HashAlgo {
89    /// Validate the digest length carried by a multihash for this algorithm.
90    ///
91    /// BLAKE3 is an XOF: `0x1e` may carry either the existing 32-byte XET/CAS
92    /// digest or the 64-byte at9p capsule commitment. The length remains part of
93    /// the encoded multihash and therefore part of the CID identity.
94    pub fn validate_digest_len(self, len: usize) -> Result<()> {
95        let valid = match self {
96            HashAlgo::Sha1 => len == 20,
97            HashAlgo::Sha2_256 => len == 32,
98            HashAlgo::Blake3 => matches!(len, 32 | 64),
99        };
100        ensure!(
101            valid,
102            "digest length mismatch for {self:?}: expected {}, got {len}",
103            self.expected_digest_lengths()
104        );
105        Ok(())
106    }
107
108    fn expected_digest_lengths(self) -> &'static str {
109        match self {
110            HashAlgo::Sha1 => "20 bytes",
111            HashAlgo::Sha2_256 => "32 bytes",
112            HashAlgo::Blake3 => "32 or 64 bytes",
113        }
114    }
115
116    /// Decode a multihash algorithm code into the typed enum.
117    pub fn from_code(code: u64) -> Result<Self> {
118        match code {
119            0x11 => Ok(HashAlgo::Sha1),
120            0x12 => Ok(HashAlgo::Sha2_256),
121            0x1e => Ok(HashAlgo::Blake3),
122            other => bail!("unsupported multihash algorithm code: 0x{other:x}"),
123        }
124    }
125}
126
127/// Content-type codec identifying *what* a CID addresses.
128///
129/// `GitRaw` is the registered multicodec for a raw git object (0x78). The XET
130/// variants are **LOCAL_CONVENTION** codes in the reserved private-use range
131/// (0x70–0x7f); replace them with official codes once XET is registered.
132#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
133#[repr(u64)]
134pub enum Codec {
135    /// git-raw (multicodec 0x78): a raw git object addressed by OID.
136    GitRaw = 0x78,
137    /// xet-xorb (LOCAL_CONVENTION, 0x71): a XET chunk/cas-serve content hash.
138    XetXorb = 0x71,
139    /// xet-shard (LOCAL_CONVENTION, 0x72): a XET shard (merkle) hash.
140    XetShard = 0x72,
141    /// at9p-capsule (LOCAL_CONVENTION, 0x73): an at9p capsule commitment.
142    At9pCapsule = 0x73,
143    /// xet-manifest (LOCAL_CONVENTION, 0x74): a labeled CAS blob manifest.
144    XetManifest = 0x74,
145}
146
147impl Codec {
148    /// Decode a multicodec content-type code into the typed enum.
149    pub fn from_code(code: u64) -> Result<Self> {
150        match code {
151            0x78 => Ok(Codec::GitRaw),
152            0x71 => Ok(Codec::XetXorb),
153            0x72 => Ok(Codec::XetShard),
154            0x73 => Ok(Codec::At9pCapsule),
155            0x74 => Ok(Codec::XetManifest),
156            other => bail!("unsupported CID multicodec: 0x{other:x}"),
157        }
158    }
159}
160
161// ---------------------------------------------------------------------------
162// unsigned-varint (LEB128) — the multiformats varint used by multihash/CIDv1
163// ---------------------------------------------------------------------------
164
165/// Encode a `u64` as an unsigned varint (LEB128, little-endian groups of 7 bits,
166/// continuation bit = high bit). The multiformats varint spec caps values at
167/// 2^63 − 1 and limits the encoded length to 9 bytes; we enforce the 9-byte cap.
168fn write_uvarint(out: &mut Vec<u8>, mut value: u64) {
169    // Special-case zero so we always emit at least one byte.
170    if value == 0 {
171        out.push(0);
172        return;
173    }
174    while value >= 0x80 {
175        out.push((value as u8) | 0x80);
176        value >>= 7;
177    }
178    out.push(value as u8);
179}
180
181/// Decode an unsigned varint from `bytes` starting at `pos`, returning the value
182/// and the number of bytes consumed.
183fn read_uvarint(bytes: &[u8], pos: usize) -> Result<(u64, usize)> {
184    let mut value: u64 = 0;
185    let mut shift = 0u32;
186    for (i, byte) in bytes[pos..].iter().take(9).enumerate() {
187        value |= u64::from(byte & 0x7f) << shift;
188        if byte & 0x80 == 0 {
189            return Ok((value, i + 1));
190        }
191        shift += 7;
192    }
193    bail!("unsigned varint is truncated or longer than 9 bytes");
194}
195
196// ---------------------------------------------------------------------------
197// multihash: uvarint(algo) || uvarint(len) || digest
198// ---------------------------------------------------------------------------
199
200/// Encode a digest as a multihash: `uvarint(algo) || uvarint(len) || digest`.
201///
202/// The digest length is checked against the lengths supported by the algorithm:
203/// sha1=20, sha2-256=32, and blake3=32 or 64.
204pub fn encode_multihash(algo: HashAlgo, digest: &[u8]) -> Result<Vec<u8>> {
205    algo.validate_digest_len(digest.len())?;
206    let mut out = Vec::with_capacity(2 + digest.len());
207    write_uvarint(&mut out, algo as u64);
208    write_uvarint(&mut out, digest.len() as u64);
209    out.extend_from_slice(digest);
210    Ok(out)
211}
212
213/// A decoded multihash: the algorithm tag and the raw digest bytes.
214#[derive(Debug, Clone, PartialEq, Eq)]
215pub struct Multihash {
216    pub algo: HashAlgo,
217    pub digest: Vec<u8>,
218}
219
220/// Decode a multihash produced by [`encode_multihash`].
221pub fn decode_multihash(bytes: &[u8]) -> Result<Multihash> {
222    let (algo_code, n1) =
223        read_uvarint(bytes, 0).context("multihash: failed to read algorithm code")?;
224    let (len, n2) = read_uvarint(bytes, n1).context("multihash: failed to read length")?;
225    let len = usize::try_from(len).context("multihash: length overflow")?;
226    ensure!(
227        n1 + n2 + len == bytes.len(),
228        "multihash: trailing bytes after digest (declared len {len})"
229    );
230    let digest = bytes
231        .get(n1 + n2..)
232        .context("multihash: digest truncated")?;
233    ensure!(digest.len() == len, "multihash: digest length mismatch");
234    let algo = HashAlgo::from_code(algo_code)?;
235    // Validate the digest length belongs to the algorithm's accepted domain, so
236    // a truncated/corrupted multihash is rejected rather than silently accepted.
237    algo.validate_digest_len(digest.len())?;
238    Ok(Multihash {
239        algo,
240        digest: digest.to_vec(),
241    })
242}
243
244// ---------------------------------------------------------------------------
245// CIDv1: 0x01 || multicodec || multihash, then base32-multibase encoded
246// ---------------------------------------------------------------------------
247
248/// Encode raw `(codec, algo, digest)` as a canonical CIDv1 base32 string.
249///
250/// The output always begins with the multibase base32 prefix `b`. Encoding is
251/// deterministic: identical inputs produce identical strings.
252///
253/// ```
254/// # use hyprstream_rpc::cid::{encode_cid, Codec, HashAlgo};
255/// let cid = encode_cid(Codec::GitRaw, HashAlgo::Sha1, &[0u8; 20]).unwrap();
256/// assert!(cid.starts_with('b'));
257/// ```
258pub fn encode_cid(codec: Codec, algo: HashAlgo, digest: &[u8]) -> Result<String> {
259    let multihash = encode_multihash(algo, digest)?;
260    // CIDv1 body: version || codec || multihash
261    let mut body = Vec::with_capacity(1 + 2 + multihash.len());
262    body.push(CIDV1);
263    write_uvarint(&mut body, codec as u64);
264    body.extend_from_slice(&multihash);
265
266    // Canonical CIDv1 multibase = base32 lowercase, RFC4648, no padding ('b').
267    // `data_encoding::BASE32_NOPAD` is the uppercase RFC4648 alphabet; CIDs are
268    // canonically lowercase, so we downcase the encoded output. (base32 is
269    // case-insensitive, so decoding upper-cases first.)
270    let encoded = BASE32_NOPAD.encode(&body).to_ascii_lowercase();
271    Ok(format!("{MULTIBASE_BASE32}{encoded}"))
272}
273
274/// A decoded CIDv1: the content-type codec and the multihash.
275#[derive(Debug, Clone, PartialEq, Eq)]
276pub struct Cid {
277    pub codec: Codec,
278    pub multihash: Multihash,
279}
280
281/// Decode a canonical CIDv1 base32 string produced by [`encode_cid`].
282///
283/// Both the base32 multibase prefix (`b`) and the CIDv1 version byte (`0x01`)
284/// are validated. CIDv0 (implicit sha1+base58btc, no version byte) is rejected
285/// — this module only emits CIDv1.
286pub fn decode_cid(s: &str) -> Result<Cid> {
287    let body_b32 = s
288        .strip_prefix(MULTIBASE_BASE32)
289        .context("CID must use base32 multibase ('b') prefix — base58btc 'z' is for Multikeys")?;
290    // base32 is case-insensitive; the predefined table is uppercase, so up-case
291    // before decoding. (We canonicalize CIDs to lowercase on encode.)
292    let body = BASE32_NOPAD
293        .decode(body_b32.to_ascii_uppercase().as_bytes())
294        .context("CID body is not valid base32")?;
295
296    let (version, n_ver) = read_uvarint(&body, 0).context("CID: failed to read version")?;
297    ensure!(
298        version == CIDV1 as u64,
299        "only CIDv1 is supported (got version {version})"
300    );
301    let (codec_code, n_codec) = read_uvarint(&body, n_ver).context("CID: failed to read codec")?;
302    let multihash =
303        decode_multihash(&body[n_ver + n_codec..]).context("CID: malformed multihash")?;
304    Ok(Cid {
305        codec: Codec::from_code(codec_code)?,
306        multihash,
307    })
308}
309
310// ---------------------------------------------------------------------------
311// git-oid convenience: hex SHA-1/SHA-256 → CID
312// ---------------------------------------------------------------------------
313
314/// Encode a git OID (hex string) as a `git-raw` CIDv1. The algorithm is inferred
315/// from the hex length: 40 chars → sha1, 64 chars → sha2-256.
316pub fn encode_git_oid(hex_oid: &str) -> Result<String> {
317    let raw =
318        hex::decode(hex_oid).with_context(|| format!("git OID is not valid hex: {hex_oid}"))?;
319    let algo = match raw.len() {
320        20 => HashAlgo::Sha1,
321        32 => HashAlgo::Sha2_256,
322        other => bail!("git OID has unexpected length {other} (expected 20 or 32 bytes)"),
323    };
324    encode_cid(Codec::GitRaw, algo, &raw)
325}
326
327#[cfg(test)]
328#[allow(clippy::unwrap_used, clippy::expect_used)]
329mod tests {
330    use super::*;
331
332    // ---- uvarint round-trip ------------------------------------------------
333
334    #[test]
335    fn uvarint_round_trip_single_and_multi_byte() {
336        for &v in &[
337            0u64,
338            1,
339            0x7f,
340            0x80,
341            0xff,
342            0x100,
343            0x4000,
344            0x7fff_ffff_ffff_ffff,
345        ] {
346            let mut buf = Vec::new();
347            write_uvarint(&mut buf, v);
348            assert!(buf.len() <= 9, "uvarint for {v} too long");
349            let (decoded, n) = read_uvarint(&buf, 0).expect("decode");
350            assert_eq!(decoded, v, "round-trip {v}");
351            assert_eq!(n, buf.len(), "consumed len {v}");
352        }
353    }
354
355    #[test]
356    fn uvarint_known_encodings() {
357        // From the multiformats unsigned-varint examples.
358        let mut buf = Vec::new();
359        write_uvarint(&mut buf, 1);
360        assert_eq!(buf, [0x01]);
361        buf.clear();
362        write_uvarint(&mut buf, 0x78); // git-raw codec
363        assert_eq!(buf, [0x78]);
364        buf.clear();
365        write_uvarint(&mut buf, 0x12); // sha2-256
366        assert_eq!(buf, [0x12]);
367        buf.clear();
368        write_uvarint(&mut buf, 127);
369        assert_eq!(buf, [0x7f]);
370        buf.clear();
371        write_uvarint(&mut buf, 128);
372        assert_eq!(buf, [0x80, 0x01]);
373    }
374
375    #[test]
376    fn uvarint_rejects_truncated() {
377        // Continuation byte with no following byte → truncated.
378        assert!(read_uvarint(&[0x80], 0).is_err());
379        // All continuation, 9 bytes, no terminator → truncated.
380        assert!(read_uvarint(&[0x80; 9], 0).is_err());
381    }
382
383    // ---- multihash round-trip ---------------------------------------------
384
385    #[test]
386    fn multihash_sha1_round_trip() {
387        let digest = [0xabu8; 20];
388        let mh = encode_multihash(HashAlgo::Sha1, &digest).unwrap();
389        // uvarint(0x11) || uvarint(20) || 20 bytes
390        assert_eq!(mh[0], 0x11);
391        assert_eq!(mh[1], 20);
392        assert_eq!(&mh[2..], &digest);
393        let decoded = decode_multihash(&mh).unwrap();
394        assert_eq!(decoded.algo, HashAlgo::Sha1);
395        assert_eq!(decoded.digest, digest.to_vec());
396    }
397
398    #[test]
399    fn multihash_sha2_256_round_trip() {
400        let digest = [0xcdu8; 32];
401        let mh = encode_multihash(HashAlgo::Sha2_256, &digest).unwrap();
402        assert_eq!(mh[0], 0x12);
403        assert_eq!(mh[1], 32);
404        let decoded = decode_multihash(&mh).unwrap();
405        assert_eq!(decoded.algo, HashAlgo::Sha2_256);
406        assert_eq!(decoded.digest, digest.to_vec());
407    }
408
409    #[test]
410    fn multihash_blake3_round_trip() {
411        let digest = [0xefu8; 32];
412        let mh = encode_multihash(HashAlgo::Blake3, &digest).unwrap();
413        assert_eq!(mh[0], 0x1e);
414        assert_eq!(mh[1], 32);
415        let decoded = decode_multihash(&mh).unwrap();
416        assert_eq!(decoded.algo, HashAlgo::Blake3);
417        assert_eq!(decoded.digest, digest.to_vec());
418    }
419
420    #[test]
421    fn multihash_blake3_512_round_trip() {
422        let digest = [0x51u8; 64];
423        let mh = encode_multihash(HashAlgo::Blake3, &digest).unwrap();
424        assert_eq!(mh[0], 0x1e);
425        assert_eq!(mh[1], 64);
426        let decoded = decode_multihash(&mh).unwrap();
427        assert_eq!(decoded.algo, HashAlgo::Blake3);
428        assert_eq!(decoded.digest, digest.to_vec());
429    }
430
431    #[test]
432    fn multihash_rejects_wrong_length() {
433        // sha1 expects 20 bytes; 19 must be rejected.
434        assert!(encode_multihash(HashAlgo::Sha1, &[0u8; 19]).is_err());
435        // sha2-256 expects 32; 33 must be rejected.
436        assert!(encode_multihash(HashAlgo::Sha2_256, &[0u8; 33]).is_err());
437        // blake3 accepts 32 or 64; other lengths must be rejected.
438        assert!(encode_multihash(HashAlgo::Blake3, &[0u8; 16]).is_err());
439        assert!(encode_multihash(HashAlgo::Blake3, &[0u8; 63]).is_err());
440    }
441
442    #[test]
443    fn multihash_rejects_trailing_bytes() {
444        let mut mh = encode_multihash(HashAlgo::Sha1, &[0u8; 20]).unwrap();
445        mh.push(0xff); // trailing garbage
446        assert!(decode_multihash(&mh).is_err());
447    }
448
449    #[test]
450    fn multihash_rejects_unknown_algo() {
451        // algo code 0x99 is not in our table.
452        let mh = [0x99, 0x01, 0x00];
453        assert!(decode_multihash(&mh).is_err());
454    }
455
456    // ---- CID round-trip ----------------------------------------------------
457
458    #[test]
459    fn cid_git_raw_sha1_round_trip() {
460        let digest = [0x11u8; 20];
461        let cid = encode_cid(Codec::GitRaw, HashAlgo::Sha1, &digest).unwrap();
462        assert!(
463            cid.starts_with('b'),
464            "canonical CIDv1 must use base32 'b' multibase"
465        );
466        assert!(
467            !cid.starts_with('z'),
468            "base58btc 'z' is for DID Multikeys, not CIDs"
469        );
470        // Lowercase, no padding.
471        assert_eq!(cid, cid.to_lowercase());
472        assert!(!cid.contains('='), "base32 must be unpadded");
473
474        let decoded = decode_cid(&cid).unwrap();
475        assert_eq!(decoded.codec, Codec::GitRaw);
476        assert_eq!(decoded.multihash.algo, HashAlgo::Sha1);
477        assert_eq!(decoded.multihash.digest, digest.to_vec());
478    }
479
480    #[test]
481    fn cid_xet_xorb_blake3_round_trip() {
482        let digest = [0x22u8; 32];
483        let cid = encode_cid(Codec::XetXorb, HashAlgo::Blake3, &digest).unwrap();
484        let decoded = decode_cid(&cid).unwrap();
485        assert_eq!(decoded.codec, Codec::XetXorb);
486        assert_eq!(decoded.multihash.algo, HashAlgo::Blake3);
487        assert_eq!(decoded.multihash.digest, digest.to_vec());
488    }
489
490    #[test]
491    fn cid_xet_shard_sha2_256_round_trip() {
492        let digest = [0x33u8; 32];
493        let cid = encode_cid(Codec::XetShard, HashAlgo::Sha2_256, &digest).unwrap();
494        let decoded = decode_cid(&cid).unwrap();
495        assert_eq!(decoded.codec, Codec::XetShard);
496        assert_eq!(decoded.multihash.algo, HashAlgo::Sha2_256);
497        assert_eq!(decoded.multihash.digest, digest.to_vec());
498    }
499
500    #[test]
501    fn cid_at9p_capsule_blake3_512_round_trip() {
502        let digest = [0x44u8; 64];
503        let cid = encode_cid(Codec::At9pCapsule, HashAlgo::Blake3, &digest).unwrap();
504        let decoded = decode_cid(&cid).unwrap();
505        assert_eq!(decoded.codec, Codec::At9pCapsule);
506        assert_eq!(decoded.multihash.algo, HashAlgo::Blake3);
507        assert_eq!(decoded.multihash.digest, digest.to_vec());
508    }
509
510    #[test]
511    fn cid_is_deterministic() {
512        // Same input → identical string. Run a handful of times; if any byte
513        // drifts, encoding is not a pure function and federation breaks.
514        let digest = [0x42u8; 20];
515        let c1 = encode_cid(Codec::GitRaw, HashAlgo::Sha1, &digest).unwrap();
516        for _ in 0..5 {
517            let c2 = encode_cid(Codec::GitRaw, HashAlgo::Sha1, &digest).unwrap();
518            assert_eq!(c1, c2, "CID encoding must be deterministic");
519        }
520    }
521
522    #[test]
523    fn cid_different_digests_yield_different_cids() {
524        let a = encode_cid(Codec::GitRaw, HashAlgo::Sha1, &[0u8; 20]).unwrap();
525        let b = encode_cid(Codec::GitRaw, HashAlgo::Sha1, &[1u8; 20]).unwrap();
526        assert_ne!(a, b);
527    }
528
529    #[test]
530    fn cid_blake3_32_and_64_byte_digests_do_not_alias() {
531        let input = b"canonical genesis capsule";
532        let digest32 = *blake3::hash(input).as_bytes();
533        let mut digest64 = [0u8; 64];
534        let mut hasher = blake3::Hasher::new();
535        hasher.update(input);
536        hasher.finalize_xof().fill(&mut digest64);
537
538        assert_eq!(&digest64[..32], &digest32);
539
540        let cid32 = encode_cid(Codec::At9pCapsule, HashAlgo::Blake3, &digest32).unwrap();
541        let cid64 = encode_cid(Codec::At9pCapsule, HashAlgo::Blake3, &digest64).unwrap();
542        assert_ne!(cid32, cid64);
543
544        let decoded32 = decode_cid(&cid32).unwrap();
545        let decoded64 = decode_cid(&cid64).unwrap();
546        assert_eq!(decoded32.multihash.algo, decoded64.multihash.algo);
547        assert_eq!(decoded32.multihash.digest.len(), 32);
548        assert_eq!(decoded64.multihash.digest.len(), 64);
549        assert_ne!(decoded32.multihash, decoded64.multihash);
550    }
551
552    #[test]
553    fn cid_different_codecs_yield_different_cids() {
554        let digest = [0u8; 32];
555        let git_raw = encode_cid(Codec::GitRaw, HashAlgo::Sha2_256, &digest).unwrap();
556        let xet = encode_cid(Codec::XetXorb, HashAlgo::Sha2_256, &digest).unwrap();
557        let shard = encode_cid(Codec::XetShard, HashAlgo::Sha2_256, &digest).unwrap();
558        assert_ne!(git_raw, xet);
559        assert_ne!(git_raw, shard);
560        assert_ne!(xet, shard);
561    }
562
563    #[test]
564    fn cid_rejects_base58btc_multibase() {
565        // A 'z'-prefixed string (base58btc) is for DID Multikeys, not CIDs.
566        assert!(decode_cid("z1234").is_err());
567    }
568
569    #[test]
570    fn cid_rejects_invalid_base32() {
571        // 'b' prefix but non-base32 body. '1' is not in the base32 alphabet.
572        assert!(decode_cid("b1@@@").is_err());
573    }
574
575    // ---- git-oid convenience ----------------------------------------------
576
577    #[test]
578    fn encode_git_oid_sha1_hex() {
579        let hex = "1234567890abcdef1234567890abcdef12345678";
580        let cid = encode_git_oid(hex).unwrap();
581        let decoded = decode_cid(&cid).unwrap();
582        assert_eq!(decoded.codec, Codec::GitRaw);
583        assert_eq!(decoded.multihash.algo, HashAlgo::Sha1);
584        assert_eq!(decoded.multihash.digest.len(), 20);
585    }
586
587    #[test]
588    fn encode_git_oid_sha2_256_hex() {
589        let hex = "a".repeat(64);
590        let cid = encode_git_oid(&hex).unwrap();
591        let decoded = decode_cid(&cid).unwrap();
592        assert_eq!(decoded.codec, Codec::GitRaw);
593        assert_eq!(decoded.multihash.algo, HashAlgo::Sha2_256);
594        assert_eq!(decoded.multihash.digest.len(), 32);
595    }
596
597    #[test]
598    fn encode_git_oid_rejects_bad_length() {
599        // 10 bytes (20 hex chars) is neither sha1 nor sha2-256.
600        assert!(encode_git_oid("12345678901234567890").is_err());
601        // Non-hex.
602        assert!(encode_git_oid("zz").is_err());
603    }
604
605    // ---- cross-check against a known CID vector ---------------------------
606    //
607    // The empty-byte sha2-256 CIDv1 is a well-known fixture: its multihash is
608    // the sha2-256 of the empty string (e3b0c442...). This anchors our encoder
609    // against the IPFS canonical output (base32, 'b' prefix, no padding).
610
611    #[test]
612    fn cid_matches_ipfs_empty_sha256_vector() {
613        let empty_sha256: [u8; 32] = [
614            0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f,
615            0xb9, 0x24, 0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b,
616            0x78, 0x52, 0xb8, 0x55,
617        ];
618        // raw codec = 0x55 in the multicodec table (not one we expose by name,
619        // but the multihash/base32 layer is codec-agnostic). Use git-raw (0x78)
620        // since that's our domain codec; this test pins the multihash + base32
621        // encoding, which is what must match IPFS byte-for-byte.
622        let cid = encode_cid(Codec::GitRaw, HashAlgo::Sha2_256, &empty_sha256).unwrap();
623        // Round-trips and the multihash body is the canonical sha2-256 of empty.
624        let decoded = decode_cid(&cid).unwrap();
625        assert_eq!(decoded.multihash.digest, empty_sha256);
626        // The base32 body (sans 'b' prefix) must decode back to
627        //   01 78 12 20 e3b0c4...55
628        let body_b32 = &cid[1..];
629        let body = BASE32_NOPAD
630            .decode(body_b32.to_ascii_uppercase().as_bytes())
631            .unwrap();
632        assert_eq!(body[0], 0x01, "CIDv1 version byte");
633        assert_eq!(body[1], 0x78, "git-raw codec");
634        assert_eq!(body[2], 0x12, "sha2-256 algo");
635        assert_eq!(body[3], 0x20, "digest length 32");
636        assert_eq!(&body[4..], &empty_sha256[..]);
637    }
638}