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

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/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/randutil

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:fc5544d6102777a994ff3995545d68187a495045c5496ceff6f11317db53a1ea","contract":["randutil.Hex returns a lowercase hexadecimal string matching the requested length","randutil.Alphanumeric returns an ASCII alphanumeric string matching the requested length","randutil.Alphabet returns an alphabetic string matching the requested length","randutil.ASCII returns a printable ASCII string matching the requested length","randutil.String returns a string consisting only of runes from the provided character set","randutil.Salt and randutil.Bytes return byte slices of the requested size","randutil.UUIDv4 returns a valid RFC 4122 version 4 UUID formatted as 36 characters with hyphens"],"goal":"verify 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/randutil"]},"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/randutil"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require go.step.sm/crypto v0.89.0

require github.com/pkg/errors v0.9.1 // indirect

github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
go.step.sm/crypto v0.89.0 h1:NPxryE+cZ4XDwXOQY2U6Gu+mOzOihuRLPIsX7WtPzZM=
go.step.sm/crypto v0.89.0/go.mod h1:IEgE6DndnYojbDyHU7eYXpwWzpu4ftkouw7nyI6jsxg=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package main

import (
	"encoding/hex"
	"fmt"
	"log"

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

func main() {
	hexStr, err := randutil.Hex(16)
	if err != nil {
		log.Fatalf("failed to generate hex string: %v", err)
	}
	fmt.Printf("Hex (16): %s\n", hexStr)

	alphanumericStr, err := randutil.Alphanumeric(20)
	if err != nil {
		log.Fatalf("failed to generate alphanumeric string: %v", err)
	}
	fmt.Printf("Alphanumeric (20): %s\n", alphanumericStr)

	alphabetStr, err := randutil.Alphabet(12)
	if err != nil {
		log.Fatalf("failed to generate alphabet string: %v", err)
	}
	fmt.Printf("Alphabet (12): %s\n", alphabetStr)

	customStr, err := randutil.String(8, "0123456789")
	if err != nil {
		log.Fatalf("failed to generate custom string: %v", err)
	}
	fmt.Printf("Custom numeric string (8): %s\n", customStr)

	salt, err := randutil.Salt(16)
	if err != nil {
		log.Fatalf("failed to generate salt: %v", err)
	}
	fmt.Printf("Salt (16 bytes hex): %s\n", hex.EncodeToString(salt))

	uuid, err := randutil.UUIDv4()
	if err != nil {
		log.Fatalf("failed to generate UUIDv4: %v", err)
	}
	fmt.Printf("UUIDv4: %s\n", uuid)
}

{
  "schemaVersion": 1,
  "goal": "verify 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/randutil"
  ]
}

package main

import (
	"fmt"
	"os"
	"regexp"
	"strings"

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

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

func runContract() error {
	// Assertion 1: randutil.Hex returns a lowercase hexadecimal string matching the requested length
	lengthHex := 32
	hexVal, err := randutil.Hex(lengthHex)
	if err != nil {
		return fmt.Errorf("randutil.Hex(%d) failed: %w", lengthHex, err)
	}
	if len(hexVal) != lengthHex {
		return fmt.Errorf("randutil.Hex length mismatch: got %d, want %d", len(hexVal), lengthHex)
	}
	for _, ch := range hexVal {
		if !((ch >= '0' && ch <= '9') || (ch >= 'a' && ch <= 'f')) {
			return fmt.Errorf("randutil.Hex contains invalid character %q", ch)
		}
	}

	// Assertion 2: randutil.Alphanumeric returns an ASCII alphanumeric string matching the requested length
	lengthAlphaNum := 48
	anVal, err := randutil.Alphanumeric(lengthAlphaNum)
	if err != nil {
		return fmt.Errorf("randutil.Alphanumeric(%d) failed: %w", lengthAlphaNum, err)
	}
	if len(anVal) != lengthAlphaNum {
		return fmt.Errorf("randutil.Alphanumeric length mismatch: got %d, want %d", len(anVal), lengthAlphaNum)
	}
	for _, ch := range anVal {
		if !((ch >= '0' && ch <= '9') || (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')) {
			return fmt.Errorf("randutil.Alphanumeric contains non-alphanumeric character %q", ch)
		}
	}

	// Assertion 3: randutil.Alphabet returns an alphabetic string matching the requested length
	lengthAlpha := 20
	aVal, err := randutil.Alphabet(lengthAlpha)
	if err != nil {
		return fmt.Errorf("randutil.Alphabet(%d) failed: %w", lengthAlpha, err)
	}
	if len(aVal) != lengthAlpha {
		return fmt.Errorf("randutil.Alphabet length mismatch: got %d, want %d", len(aVal), lengthAlpha)
	}
	for _, ch := range aVal {
		if !((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')) {
			return fmt.Errorf("randutil.Alphabet contains non-alphabetic character %q", ch)
		}
	}

	// Assertion 4: randutil.ASCII returns a printable ASCII string matching the requested length
	lengthASCII := 40
	asciiVal, err := randutil.ASCII(lengthASCII)
	if err != nil {
		return fmt.Errorf("randutil.ASCII(%d) failed: %w", lengthASCII, err)
	}
	if len(asciiVal) != lengthASCII {
		return fmt.Errorf("randutil.ASCII length mismatch: got %d, want %d", len(asciiVal), lengthASCII)
	}
	for _, ch := range asciiVal {
		if ch < 33 || ch > 126 {
			return fmt.Errorf("randutil.ASCII contains non-printable ASCII character code %d", ch)
		}
	}

	// Assertion 5: randutil.String returns a string consisting only of runes from the provided character set
	customCharset := "ABC123!#"
	strVal, err := randutil.String(25, customCharset)
	if err != nil {
		return fmt.Errorf("randutil.String failed: %w", err)
	}
	if len([]rune(strVal)) != 25 {
		return fmt.Errorf("randutil.String rune length mismatch: got %d, want 25", len([]rune(strVal)))
	}
	for _, r := range strVal {
		if !strings.ContainsRune(customCharset, r) {
			return fmt.Errorf("randutil.String rune %q not in charset %q", r, customCharset)
		}
	}

	// Assertion 6: randutil.Salt and randutil.Bytes return byte slices of the requested size
	saltSize := 24
	salt, err := randutil.Salt(saltSize)
	if err != nil {
		return fmt.Errorf("randutil.Salt(%d) failed: %w", saltSize, err)
	}
	if len(salt) != saltSize {
		return fmt.Errorf("randutil.Salt length mismatch: got %d, want %d", len(salt), saltSize)
	}

	bytesSize := 16
	rawBytes, err := randutil.Bytes(bytesSize)
	if err != nil {
		return fmt.Errorf("randutil.Bytes(%d) failed: %w", bytesSize, err)
	}
	if len(rawBytes) != bytesSize {
		return fmt.Errorf("randutil.Bytes length mismatch: got %d, want %d", len(rawBytes), bytesSize)
	}

	// Assertion 7: randutil.UUIDv4 returns a valid RFC 4122 version 4 UUID formatted as 36 characters with hyphens
	uuidRegex := regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
	for i := 0; i < 10; i++ {
		uuid, err := randutil.UUIDv4()
		if err != nil {
			return fmt.Errorf("randutil.UUIDv4 failed: %w", err)
		}
		if len(uuid) != 36 {
			return fmt.Errorf("randutil.UUIDv4 length mismatch: got %d, want 36", len(uuid))
		}
		if !uuidRegex.MatchString(uuid) {
			return fmt.Errorf("randutil.UUIDv4 format mismatch: got %q", uuid)
		}
	}

	return nil
}