github.com/zeebo/blake3 v0.2.4

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/zeebo/blake3@v0.2.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/zeebo/blake3@v0.2.4

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package sample

import (
	"encoding/hex"
	"io"

	"github.com/zeebo/blake3"
)

// Hash256Hex computes the BLAKE3 256-bit hash of data and returns it as a hex string.
func Hash256Hex(data []byte) string {
	sum := blake3.Sum256(data)
	return hex.EncodeToString(sum[:])
}

// Hash512Hex computes the BLAKE3 512-bit hash of data and returns it as a hex string.
func Hash512Hex(data []byte) string {
	sum := blake3.Sum512(data)
	return hex.EncodeToString(sum[:])
}

// ComputeMAC computes a keyed BLAKE3 MAC using a 32-byte key.
func ComputeMAC(key []byte, message []byte) ([]byte, error) {
	hasher, err := blake3.NewKeyed(key)
	if err != nil {
		return nil, err
	}
	if _, err := hasher.Write(message); err != nil {
		return nil, err
	}
	return hasher.Sum(nil), nil
}

// DeriveSubkey derives a key of specified length using a context string and key material.
func DeriveSubkey(context string, material []byte, keyLen int) []byte {
	out := make([]byte, keyLen)
	blake3.DeriveKey(context, material, out)
	return out
}

// StreamXOF returns a reader for extendable output of arbitrary length.
func StreamXOF(data []byte) io.Reader {
	hasher := blake3.New()
	hasher.Write(data)
	return hasher.Digest()
}

{"case":{"caseId":"case:sha256:87a42a1aad3a005022fc6088acad1a1c52c47f1fb69d699e12518293bc594d01","contract":["blake3.Sum256 computes standard 32-byte BLAKE3 digest matching known test vector","blake3.Sum512 computes 64-byte BLAKE3 digest whose prefix matches Sum256","blake3.New implements hash.Hash and incremental writes match Sum256","Hasher.Clone creates an independent clone preserving intermediate state","Hasher.Reset clears accumulated state","blake3.NewKeyed enforces 32-byte key and produces distinct keyed MACs","blake3.DeriveKey derives arbitrary-length subkeys bound to context strings","blake3.Digest provides extendable output seeking and arbitrary-length reading"],"goal":"verify pkg:golang/github.com/zeebo/blake3@v0.2.4","kind":"HOW","packages":["pkg:golang/github.com/zeebo/blake3@v0.2.4"],"schemaVersion":1},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/zeebo/blake3@v0.2.4"],"schemaVersion":1,"subject":"pkg:golang/github.com/zeebo/blake3@v0.2.4","verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/zeebo/blake3 v0.2.4

require github.com/klauspost/cpuid/v2 v2.0.12 // indirect

github.com/klauspost/cpuid/v2 v2.0.12 h1:p9dKCg8i4gmOxtv35DvrYoWqYzQrvEVdjQ762Y0OqZE=
github.com/klauspost/cpuid/v2 v2.0.12/go.mod h1:g2LTdtYhdyuGPqyWyv7qRAmj1WBqxuObKfj5c0PQa7c=
github.com/zeebo/assert v1.1.0 h1:hU1L1vLTHsnO8x8c9KAR5GmM5QscxHg5RNU5z5qbUWY=
github.com/zeebo/assert v1.1.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
github.com/zeebo/blake3 v0.2.4 h1:KYQPkhpRtcqh0ssGYcKLG1JYvddkEA8QwCM/yBqhaZI=
github.com/zeebo/blake3 v0.2.4/go.mod h1:7eeQ6d2iXWRGF6npfaxl2CU+xy2Fjo2gxeyZGCRUjcE=
github.com/zeebo/pcg v1.0.1 h1:lyqfGeWiv4ahac6ttHs+I5hwtH/+1mrhlCtVNQM2kHo=
github.com/zeebo/pcg v1.0.1/go.mod h1:09F0S9iiKrwn9rlI5yjLkmrug154/YRW6KnnXVDM/l4=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/zeebo/blake3@v0.2.4",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/zeebo/blake3@v0.2.4"
  ]
}

package main

import (
	"bytes"
	"encoding/hex"
	"fmt"
	"io"
	"os"

	"github.com/zeebo/blake3"
	"sample"
)

func main() {
	if err := runTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All blake3 contract tests passed successfully.")
}

func runTests() error {
	// 1. blake3.Sum256 computes standard 32-byte BLAKE3 digest matching known test vector
	emptyHash := blake3.Sum256([]byte{})
	const expectedEmptyHex = "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262"
	if hex.EncodeToString(emptyHash[:]) != expectedEmptyHex {
		return fmt.Errorf("Sum256 empty hash mismatch: got %x, want %s", emptyHash, expectedEmptyHex)
	}

	data := []byte("The quick brown fox jumps over the lazy dog")
	dataHex := sample.Hash256Hex(data)
	const expectedFoxHex = "2f1514181aadccd913abd94cfa592701a5686ab23f8df1dff1b74710febc6d4a"
	if dataHex != expectedFoxHex {
		return fmt.Errorf("Sum256 fox hash mismatch: got %s, want %s", dataHex, expectedFoxHex)
	}

	// 2. blake3.Sum512 computes 64-byte BLAKE3 digest whose prefix matches Sum256
	sum512 := blake3.Sum512(data)
	if len(sum512) != 64 {
		return fmt.Errorf("expected 64 bytes from Sum512, got %d", len(sum512))
	}
	sum256 := blake3.Sum256(data)
	if !bytes.Equal(sum512[:32], sum256[:]) {
		return fmt.Errorf("Sum512 prefix mismatch with Sum256")
	}

	// 3. blake3.New implements hash.Hash and incremental writes match Sum256
	h := blake3.New()
	if h.Size() != 32 {
		return fmt.Errorf("expected hasher Size() == 32, got %d", h.Size())
	}
	if h.BlockSize() != 64 {
		return fmt.Errorf("expected hasher BlockSize() == 64, got %d", h.BlockSize())
	}

	chunk1 := []byte("The quick brown fox ")
	chunk2 := []byte("jumps over the lazy dog")
	if _, err := h.Write(chunk1); err != nil {
		return fmt.Errorf("hasher Write failed: %w", err)
	}
	if _, err := h.WriteString(string(chunk2)); err != nil {
		return fmt.Errorf("hasher WriteString failed: %w", err)
	}
	streamingDigest := h.Sum(nil)
	if !bytes.Equal(streamingDigest, sum256[:]) {
		return fmt.Errorf("streaming digest mismatch: got %x, want %x", streamingDigest, sum256)
	}

	// 4. Hasher.Clone creates an independent clone preserving intermediate state
	hClone := h.Clone()
	if _, err := hClone.Write([]byte(" extra")); err != nil {
		return fmt.Errorf("clone Write failed: %w", err)
	}
	if bytes.Equal(h.Sum(nil), hClone.Sum(nil)) {
		return fmt.Errorf("modifying clone affected original hasher")
	}

	// 5. Hasher.Reset clears accumulated state
	h.Reset()
	if !bytes.Equal(h.Sum(nil), emptyHash[:]) {
		return fmt.Errorf("hasher after Reset did not match empty hash")
	}

	// 6. blake3.NewKeyed enforces 32-byte key and produces distinct keyed MACs
	validKey1 := bytes.Repeat([]byte{0x01}, 32)
	validKey2 := bytes.Repeat([]byte{0x02}, 32)
	invalidKey := []byte("short-key-less-than-32-bytes")

	if _, err := blake3.NewKeyed(invalidKey); err == nil {
		return fmt.Errorf("expected NewKeyed with invalid key length to return error")
	}

	mac1, err := sample.ComputeMAC(validKey1, data)
	if err != nil {
		return fmt.Errorf("ComputeMAC key1 failed: %w", err)
	}
	mac2, err := sample.ComputeMAC(validKey2, data)
	if err != nil {
		return fmt.Errorf("ComputeMAC key2 failed: %w", err)
	}
	if bytes.Equal(mac1, mac2) {
		return fmt.Errorf("different keys produced identical MACs")
	}
	if bytes.Equal(mac1, sum256[:]) {
		return fmt.Errorf("keyed MAC should differ from unkeyed hash")
	}

	// 7. blake3.DeriveKey derives arbitrary-length subkeys bound to context strings
	const ctxA = "sample.app.auth.v1"
	const ctxB = "sample.app.storage.v1"
	material := []byte("master-secret-seed-material-12345")

	derivedKeyA := sample.DeriveSubkey(ctxA, material, 48)
	if len(derivedKeyA) != 48 {
		return fmt.Errorf("expected derived subkey length 48, got %d", len(derivedKeyA))
	}
	derivedKeyB := sample.DeriveSubkey(ctxB, material, 48)
	if bytes.Equal(derivedKeyA, derivedKeyB) {
		return fmt.Errorf("different contexts produced identical derived keys")
	}

	// NewDeriveKey streaming produces identical result
	hkdfHasher := blake3.NewDeriveKey(ctxA)
	hkdfHasher.Write(material)
	if !bytes.Equal(hkdfHasher.Sum(nil), derivedKeyA[:32]) {
		return fmt.Errorf("NewDeriveKey streaming output mismatch with DeriveKey")
	}

	// 8. blake3.Digest provides extendable output seeking and arbitrary-length reading
	xofReader := sample.StreamXOF(data)
	xofDigest, ok := xofReader.(*blake3.Digest)
	if !ok {
		return fmt.Errorf("expected StreamXOF to return *blake3.Digest")
	}

	buf128 := make([]byte, 128)
	n, err := io.ReadFull(xofDigest, buf128)
	if err != nil || n != 128 {
		return fmt.Errorf("failed reading 128 bytes from XOF: %w (read %d)", err, n)
	}
	if !bytes.Equal(buf128[:32], sum256[:]) {
		return fmt.Errorf("first 32 bytes of XOF must match Sum256")
	}

	// Seek back to start and verify identical stream
	seekPos, err := xofDigest.Seek(0, io.SeekStart)
	if err != nil || seekPos != 0 {
		return fmt.Errorf("failed seeking to 0: %w (pos %d)", err, seekPos)
	}
	bufReRead := make([]byte, 128)
	if _, err := io.ReadFull(xofDigest, bufReRead); err != nil {
		return fmt.Errorf("failed re-reading XOF stream after seek: %w", err)
	}
	if !bytes.Equal(buf128, bufReRead) {
		return fmt.Errorf("re-read XOF stream differs after seek to 0")
	}

	// Seek to offset 32 and verify against second half
	seekPos, err = xofDigest.Seek(32, io.SeekStart)
	if err != nil || seekPos != 32 {
		return fmt.Errorf("failed seeking to 32: %w (pos %d)", err, seekPos)
	}
	bufOffset := make([]byte, 96)
	if _, err := io.ReadFull(xofDigest, bufOffset); err != nil {
		return fmt.Errorf("failed reading from offset 32: %w", err)
	}
	if !bytes.Equal(buf128[32:], bufOffset) {
		return fmt.Errorf("offset read differs from initial stream")
	}

	return nil
}