go.step.sm/crypto v0.89.0: fingerprint

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 go.step.sm/crypto/fingerprint in pkg:golang/go.step.sm/crypto@v0.89.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.step.sm/crypto@v0.89.0
Demonstrate these symbols/APIs:
  - go.step.sm/crypto/fingerprint

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.

{"case":{"caseId":"case:sha256:6cf7e54627bf99685e4a8067e0361a923c8a3d3a705e98bb5c8e32a18a117ef4","contract":["fingerprint.New hashes input data and formats fingerprints into standard encodings (hex, base64, base64url, base64raw, base64rawurl, emoji)","fingerprint.Fingerprint formats precomputed digests into specified encodings without hashing","fingerprint.New supports multiple cryptographic hash algorithms including SHA-256 and SHA-512","fingerprint.New returns an error when an unavailable hash algorithm or invalid encoding is supplied"],"goal":"verify go.step.sm/crypto/fingerprint in pkg:golang/go.step.sm/crypto@v0.89.0","kind":"HOW","packages":["pkg:golang/go.step.sm/crypto@v0.89.0"],"schemaVersion":1,"symbols":["go.step.sm/crypto/fingerprint"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.step.sm/crypto@v0.89.0"],"schemaVersion":1,"subject":"pkg:golang/go.step.sm/crypto@v0.89.0","symbols":["go.step.sm/crypto/fingerprint"],"verifierAdapter":"golang@1"}

package fingerprintsample

import (
	"crypto"
	"fmt"

	"go.step.sm/crypto/fingerprint"
)

// HashAndFingerprint hashes data with the specified algorithm and formats it using the given encoding.
func HashAndFingerprint(data []byte, h crypto.Hash, enc fingerprint.Encoding) (string, error) {
	return fingerprint.New(data, h, enc)
}

// FormatRawDigest formats a precomputed hash digest using the given fingerprint encoding.
func FormatRawDigest(digest []byte, enc fingerprint.Encoding) (string, error) {
	result := fingerprint.Fingerprint(digest, enc)
	if result == "" && len(digest) > 0 {
		return "", fmt.Errorf("unsupported or invalid fingerprint encoding: %d", enc)
	}
	return result, nil
}

// AvailableEncodings returns the list of all standard fingerprint encodings supported by the package.
func AvailableEncodings() []fingerprint.Encoding {
	return []fingerprint.Encoding{
		fingerprint.HexFingerprint,
		fingerprint.Base64Fingerprint,
		fingerprint.Base64URLFingerprint,
		fingerprint.Base64RawFingerprint,
		fingerprint.Base64RawURLFingerprint,
		fingerprint.EmojiFingerprint,
	}
}

module example.com/fingerprint-sample

go 1.26.6

require go.step.sm/crypto v0.89.0

go.step.sm/crypto v0.89.0 h1:NPxryE+cZ4XDwXOQY2U6Gu+mOzOihuRLPIsX7WtPzZM=
go.step.sm/crypto v0.89.0/go.mod h1:IEgE6DndnYojbDyHU7eYXpwWzpu4ftkouw7nyI6jsxg=

{
  "schemaVersion": 1,
  "goal": "verify go.step.sm/crypto/fingerprint in pkg:golang/go.step.sm/crypto@v0.89.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.step.sm/crypto@v0.89.0"
  ],
  "symbols": [
    "go.step.sm/crypto/fingerprint"
  ]
}

package main

import (
	"crypto"
	"crypto/sha256"
	_ "crypto/sha256"
	_ "crypto/sha512"
	"encoding/base64"
	"encoding/hex"
	"fmt"
	"os"
	"strings"

	sample "example.com/fingerprint-sample"
	"go.step.sm/crypto/fingerprint"
)

func main() {
	inputData := []byte("clean-room fingerprint contract payload")

	// Assertion 1: fingerprint.New computes correct fingerprints for all standard encodings
	expectedSum := sha256.Sum256(inputData)
	expectedHex := hex.EncodeToString(expectedSum[:])
	expectedB64 := base64.StdEncoding.EncodeToString(expectedSum[:])
	expectedB64URL := base64.URLEncoding.EncodeToString(expectedSum[:])
	expectedRawB64 := base64.RawStdEncoding.EncodeToString(expectedSum[:])
	expectedRawB64URL := base64.RawURLEncoding.EncodeToString(expectedSum[:])

	// Hex
	hexFP, err := fingerprint.New(inputData, crypto.SHA256, fingerprint.HexFingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: fingerprint.New with HexFingerprint failed: %v\n", err)
		os.Exit(1)
	}
	if hexFP != strings.ToLower(expectedHex) {
		fmt.Fprintf(os.Stderr, "FAIL: Hex mismatch: got %q, want %q\n", hexFP, expectedHex)
		os.Exit(1)
	}

	// Base64
	b64FP, err := fingerprint.New(inputData, crypto.SHA256, fingerprint.Base64Fingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: fingerprint.New with Base64Fingerprint failed: %v\n", err)
		os.Exit(1)
	}
	if b64FP != expectedB64 {
		fmt.Fprintf(os.Stderr, "FAIL: Base64 mismatch: got %q, want %q\n", b64FP, expectedB64)
		os.Exit(1)
	}

	// Base64URL
	b64urlFP, err := fingerprint.New(inputData, crypto.SHA256, fingerprint.Base64URLFingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: fingerprint.New with Base64URLFingerprint failed: %v\n", err)
		os.Exit(1)
	}
	if b64urlFP != expectedB64URL {
		fmt.Fprintf(os.Stderr, "FAIL: Base64URL mismatch: got %q, want %q\n", b64urlFP, expectedB64URL)
		os.Exit(1)
	}

	// Base64Raw
	rawB64FP, err := fingerprint.New(inputData, crypto.SHA256, fingerprint.Base64RawFingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: fingerprint.New with Base64RawFingerprint failed: %v\n", err)
		os.Exit(1)
	}
	if rawB64FP != expectedRawB64 {
		fmt.Fprintf(os.Stderr, "FAIL: Base64Raw mismatch: got %q, want %q\n", rawB64FP, expectedRawB64)
		os.Exit(1)
	}

	// Base64RawURL
	rawB64urlFP, err := fingerprint.New(inputData, crypto.SHA256, fingerprint.Base64RawURLFingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: fingerprint.New with Base64RawURLFingerprint failed: %v\n", err)
		os.Exit(1)
	}
	if rawB64urlFP != expectedRawB64URL {
		fmt.Fprintf(os.Stderr, "FAIL: Base64RawURL mismatch: got %q, want %q\n", rawB64urlFP, expectedRawB64URL)
		os.Exit(1)
	}

	// Emoji
	emojiFP, err := fingerprint.New(inputData, crypto.SHA256, fingerprint.EmojiFingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: fingerprint.New with EmojiFingerprint failed: %v\n", err)
		os.Exit(1)
	}
	if len(emojiFP) == 0 {
		fmt.Fprintf(os.Stderr, "FAIL: Emoji fingerprint should not be empty\n")
		os.Exit(1)
	}

	// Assertion 2: fingerprint.Fingerprint formats precomputed raw digests directly
	rawDigest := []byte{0xde, 0xad, 0xbe, 0xef, 0x01, 0x02, 0x03, 0x04}
	directHex := fingerprint.Fingerprint(rawDigest, fingerprint.HexFingerprint)
	if directHex != "deadbeef01020304" {
		fmt.Fprintf(os.Stderr, "FAIL: direct Fingerprint Hex mismatch: got %q, want %q\n", directHex, "deadbeef01020304")
		os.Exit(1)
	}
	directB64 := fingerprint.Fingerprint(rawDigest, fingerprint.Base64Fingerprint)
	expectedDirectB64 := base64.StdEncoding.EncodeToString(rawDigest)
	if directB64 != expectedDirectB64 {
		fmt.Fprintf(os.Stderr, "FAIL: direct Fingerprint Base64 mismatch: got %q, want %q\n", directB64, expectedDirectB64)
		os.Exit(1)
	}

	formatted, err := sample.FormatRawDigest(rawDigest, fingerprint.HexFingerprint)
	if err != nil || formatted != "deadbeef01020304" {
		fmt.Fprintf(os.Stderr, "FAIL: sample.FormatRawDigest failed: %v\n", err)
		os.Exit(1)
	}

	// Assertion 3: fingerprint.New supports different hash functions like SHA-512
	sha512FP, err := sample.HashAndFingerprint(inputData, crypto.SHA512, fingerprint.HexFingerprint)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: sample.HashAndFingerprint with SHA-512 failed: %v\n", err)
		os.Exit(1)
	}
	if len(sha512FP) != 128 {
		fmt.Fprintf(os.Stderr, "FAIL: expected 128 hex chars for SHA-512, got %d\n", len(sha512FP))
		os.Exit(1)
	}

	// Assertion 4: fingerprint.New rejects unavailable hash functions with an error
	unavailableHash := crypto.Hash(9999)
	if _, err := fingerprint.New(inputData, unavailableHash, fingerprint.HexFingerprint); err == nil {
		fmt.Fprintf(os.Stderr, "FAIL: expected error when using unavailable hash function, got nil\n")
		os.Exit(1)
	}

	// Assertion 5: fingerprint.New and Fingerprint reject invalid encoding values
	invalidEnc := fingerprint.Encoding(999)
	if _, err := fingerprint.New(inputData, crypto.SHA256, invalidEnc); err == nil {
		fmt.Fprintf(os.Stderr, "FAIL: expected error when using invalid encoding in New, got nil\n")
		os.Exit(1)
	}
	if got := fingerprint.Fingerprint(rawDigest, invalidEnc); got != "" {
		fmt.Fprintf(os.Stderr, "FAIL: expected empty string when using invalid encoding in Fingerprint, got %q\n", got)
		os.Exit(1)
	}

	fmt.Println("PASS: go.step.sm/crypto/fingerprint contract passed")
}