MoonSecureCodec (安全编码与供应链内容指纹工具箱)

MoonSecureCodec is a production-grade, multi-base encoding, high-speed content fingerprinting, and RFC 6962-compliant Merkle Tree verification toolkit built specifically for Software Supply Chain Security (SBOM / Manifest auditing) in MoonBit.

🌟 Core Highlights & Architectural Focus

In modern software ecosystems, avoiding single-point cryptographic dependencies while maintaining lightning-fast build/test verification and tamper-evident supply chain tracking is critical. MoonSecureCodec bridges the intersection of Encoding, Content Digesting, and Cryptographic Merkle Proofs:

                  +-------------------------------------------------+
                  |               MoonSecureCodec                   |
                  |     Supply Chain Security & Fingerprinting      |
                  +-------------------------------------------------+
                    /                     |                      \
                   /                      |                       \
      +----------------------+  +---------------------+  +------------------------+
      |      lib/codec       |  |     lib/digest      |  |       lib/merkle       |
      |  Multi-Base Codecs   |  | Fingerprints & Hash |  |  Domain-Separated Tree |
      +----------------------+  +---------------------+  +------------------------+
        - Hex (Base16)            - XXHash64 (64-bit)      - RFC 6962 Prefix 0x00
        - Base32 (RFC 4648)       - Murmur3_32 (32-bit)    - RFC 6962 Prefix 0x01
        - Base64 & Base64URL      - SHA-256 (FIPS 180-4)   - Merkle Inclusion Proofs
        - Base58 (Bitcoin)        - HMAC-SHA256 Auth       - Tamper Proof Checks
                                         \                         /
                                          \                       /
                                     +---------------------------------+
                                     |          lib/manifest           |
                                     |     SBOM / Manifest Auditing    |
                                     +---------------------------------+
                                       - Canonical File Snapshots
                                       - Embedded Merkle Root Hash
                                       - O(N) Manifest Diff Auditing

📦 Package Architecture & Subsystems

Package Path	Description	Key Features & APIs
`lib/codec`	Multi-Base Encoders / Decoders	`to_hex` / `from_hex`, `to_base32` / `from_base32`, `to_base64` / `from_base64` (`url_safe~`), `to_base58` / `from_base58`. Returns `Result[Bytes, String]` for safe parsing.
`lib/digest`	High-Speed & Cryptographic Digests	`xxhash64` / `xxhash64_hex` (ultra-fast 64-bit SBOM equality checks), `murmur3_32`, exact FIPS 180-4 `sha256` / `sha256_hex`, and `hmac_sha256`.
`lib/merkle`	Tamper-Evident Merkle Trees	`MerkleTree::new`, `root_hex()`, `get_proof(index)`, and `verify_proof()`. Strictly implements RFC 6962 domain separation (`0x00` leaf / `0x01` inner node) to prevent second-preimage attacks.
`lib/manifest`	Supply Chain Manifests (SBOM)	Canonical `FileSnapshot` representation, automated Merkle tree construction (`refresh_merkle_root()`), JSON serialization, and `Manifest::diff(old, new)` for audit reports.
`cmd/cli`	Interactive Tooling & Demo	Executable entry point running comprehensive workflows via `moon run cmd/cli`.

🚀 Quick Start & Installation

1. Requirements & Prerequisites

Ensure you have the latest MoonBit SDK (moon) installed:

moon version

2. Run All Unit & Integration Tests

Run the entire suite of 18 verification tests across all packages with zero warnings:

moon test

Expected Output:

Total tests: 18, passed: 18, failed: 0.

3. Run the Supply Chain CLI Demo

Run the interactive CLI demonstration to see multi-base encoding, SHA-256/XXHash64 hashing, Merkle proof verification, and manifest diffing in action:

moon run cmd/cli

📖 Usage Examples

1. Multi-Base Codecs (`lib/codec`)

let original = b"Supply Chain Security in MoonBit"

// Encode to Base64 (or Base64URL)
let b64 = @codec.to_base64(original, url_safe=false)
println(b64) // U3VwcGx5IENoYWluIFNlY3VyaXR5IGluIE1vb25CaXQ=

// Decode securely with Result handling
match @codec.from_base64(b64) {
  Ok(bytes) => println("Decoded correctly!")
  Err(err)  => println("Decoding failed: " + err)
}

2. Fast SBOM Fingerprinting vs Cryptographic Hashing (`lib/digest`)

let data = b"moonbit-community/moon_secure_codec binary artifact"

// Fast 64-bit content fingerprinting (for checking thousands of build artifacts instantly)
let fp64 : UInt64 = @digest.xxhash64(data)

// Cryptographic SHA-256 hash (for immutable verification)
let sha_hex : String = @digest.sha256_hex(data)

3. Merkle Inclusion Proofs & Verification (`lib/merkle`)

let leaves = [
  b"dependency: moonbitlang/core v0.1.0",
  b"dependency: moonbit-community/moon_secure_codec v0.1.0",
  b"license: Apache-2.0",
]

let tree = @merkle.MerkleTree::new(leaves)
let root_hash = tree.root_hex()
println("Merkle Root: " + root_hash)

// Generate an inclusion proof for leaf #1
let proof = tree.get_proof(1).unwrap()

// Verify proof against the public root
let is_valid = @merkle.verify_proof(proof, tree.root())
assert_true(is_valid)

4. SBOM Manifest & Diff Auditing (`lib/manifest`)

let f1 = @manifest.FileSnapshot::from_bytes("src/lib.mbt", b"pub fn hash() -> Int { 1 }")
let f2 = @manifest.FileSnapshot::from_bytes("moon.mod", b"name = \"my_package\"")

let manifest_v1 = @manifest.Manifest::new("my_package", "v1.0.0", "2026-07-08", [f1, f2])

// Automatically verifies all file snapshots against the embedded Merkle root
assert_true(manifest_v1.verify_integrity())

// Audit diffing against a newer version
let f1_v2 = @manifest.FileSnapshot::from_bytes("src/lib.mbt", b"pub fn hash() -> Int { 2 }")
let manifest_v2 = @manifest.Manifest::new("my_package", "v1.1.0", "2026-07-09", [f1_v2, f2])

let diff = manifest_v1.diff(manifest_v2)
println("Modified files count: " + diff.modified.length().to_string()) // 1

🔒 Security Design & RFC 6962 Compliance

When constructing Merkle trees from raw file or transaction leaves, naive concatenation H(left || right) allows an adversary to construct a second-preimage attack by submitting a single leaf whose payload happens to equal the concatenation of two internal node hashes.

To completely prevent this, lib/merkle implements the RFC 6962 (Certificate Transparency) domain separation standard:

Leaf Hashes: Prepends 0x00 before hashing (SHA256(0x00 || LeafData)).
Internal Node Hashes: Prepends 0x01 before hashing (SHA256(0x01 || LeftChild || RightChild)).

🏆 OSC 2026 Competition Compliance

This repository is submitted as part of the 2026 MoonBit Open Source Competition (OSC 2026).

Pure MoonBit: Written entirely in idiomatic MoonBit with zero external C/OCaml/JS dependencies.
Cross-Platform & Wasm-GC Ready: Fully optimized for wasm-gc, js, and native backends (options("preferred-target": "wasm-gc")).
Comprehensive Testing: 100% test coverage across individual subsystems and root integration.
Open OSI License: Licensed under Apache License 2.0.

📄 License

Licensed under the Apache License, Version 2.0. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.