1use anyhow::{bail, ensure, Context, Result};
59use data_encoding::BASE32_NOPAD;
60
61const MULTIBASE_BASE32: char = 'b';
68
69const CIDV1: u8 = 0x01;
71
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
78#[repr(u64)]
79pub enum HashAlgo {
80 Sha1 = 0x11,
82 Sha2_256 = 0x12,
84 Blake3 = 0x1e,
86}
87
88impl HashAlgo {
89 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 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#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
133#[repr(u64)]
134pub enum Codec {
135 GitRaw = 0x78,
137 XetXorb = 0x71,
139 XetShard = 0x72,
141 At9pCapsule = 0x73,
143 XetManifest = 0x74,
145}
146
147impl Codec {
148 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
161fn write_uvarint(out: &mut Vec<u8>, mut value: u64) {
169 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
181fn 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
196pub 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#[derive(Debug, Clone, PartialEq, Eq)]
215pub struct Multihash {
216 pub algo: HashAlgo,
217 pub digest: Vec<u8>,
218}
219
220pub 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 algo.validate_digest_len(digest.len())?;
238 Ok(Multihash {
239 algo,
240 digest: digest.to_vec(),
241 })
242}
243
244pub fn encode_cid(codec: Codec, algo: HashAlgo, digest: &[u8]) -> Result<String> {
259 let multihash = encode_multihash(algo, digest)?;
260 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 let encoded = BASE32_NOPAD.encode(&body).to_ascii_lowercase();
271 Ok(format!("{MULTIBASE_BASE32}{encoded}"))
272}
273
274#[derive(Debug, Clone, PartialEq, Eq)]
276pub struct Cid {
277 pub codec: Codec,
278 pub multihash: Multihash,
279}
280
281pub 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 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
310pub 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 #[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 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); assert_eq!(buf, [0x78]);
364 buf.clear();
365 write_uvarint(&mut buf, 0x12); 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 assert!(read_uvarint(&[0x80], 0).is_err());
379 assert!(read_uvarint(&[0x80; 9], 0).is_err());
381 }
382
383 #[test]
386 fn multihash_sha1_round_trip() {
387 let digest = [0xabu8; 20];
388 let mh = encode_multihash(HashAlgo::Sha1, &digest).unwrap();
389 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 assert!(encode_multihash(HashAlgo::Sha1, &[0u8; 19]).is_err());
435 assert!(encode_multihash(HashAlgo::Sha2_256, &[0u8; 33]).is_err());
437 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); assert!(decode_multihash(&mh).is_err());
447 }
448
449 #[test]
450 fn multihash_rejects_unknown_algo() {
451 let mh = [0x99, 0x01, 0x00];
453 assert!(decode_multihash(&mh).is_err());
454 }
455
456 #[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 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 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 assert!(decode_cid("z1234").is_err());
567 }
568
569 #[test]
570 fn cid_rejects_invalid_base32() {
571 assert!(decode_cid("b1@@@").is_err());
573 }
574
575 #[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 assert!(encode_git_oid("12345678901234567890").is_err());
601 assert!(encode_git_oid("zz").is_err());
603 }
604
605 #[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 let cid = encode_cid(Codec::GitRaw, HashAlgo::Sha2_256, &empty_sha256).unwrap();
623 let decoded = decode_cid(&cid).unwrap();
625 assert_eq!(decoded.multihash.digest, empty_sha256);
626 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}