suaveplan/openspec/specs/crypto-utils/spec.md

crypto-utils

Purpose

@suaveplan/crypto-utils is the cross-package crypto-helper layer for the Suaveplan monorepo. It owns the pure-composition utilities every primitive package builds on: hex / base64 / base64url / base58 encoding (delegated to @suaveplan/bytes where overlap exists), byte helpers (concatBytes, i2osp, os2ip, xor), constant-time equality, cryptographically-secure randomBytes, eager zeroize, the PrimitiveId registry + PrimitiveNotImplemented error, and the KAT / differential-fuzz test harness consumed by every @suaveplan/crypto-* engine selector. The package is deliberately field-arithmetic-free and side-channel-clean (no secret-data branches beyond constant-time compare) so it can ship as the universal-tier dependency for crypto-cipher, crypto-curve, crypto-hash, and the higher-level crypto package.

Requirements

Requirement: Pure-composition utility surface

@suaveplan/crypto-utils SHALL expose encoding, byte, constant-time, and test-harness utilities that are safe to author from scratch (no field arithmetic, no secret-data side channels beyond constant-time equality).

Scenario: Encoding utilities available

• WHEN a consumer imports from @suaveplan/crypto-utils
• THEN hex, base64, base64url, base58 encoders/decoders are exported, each with encode(bytes): string and decode(text): Uint8Array
• AND toHex / fromHex and toBase64 / fromBase64 delegate to @suaveplan/bytes; decoders throw BytesError (a SuaveplanError subclass) on malformed input
• AND toBase64Url / fromBase64Url are implemented in-package by post-processing the standard base64 result

Requirement: Encoding delegation to @suaveplan/bytes

@suaveplan/crypto-utils SHALL delegate toHex / fromHex and toBase64 / fromBase64 to @suaveplan/bytes, and concatBytes to concatUint8Arrays from @suaveplan/bytes. The exported function names are preserved so downstream callers need no import changes.

Scenario: Hex delegates to bytes

• WHEN toHex or fromHex is called
• THEN the call is forwarded to bytesToHex / hexToBytes from @suaveplan/bytes
• AND errors thrown are BytesError instances with code BYTES.ENCODE.INVALID_HEX

Scenario: Standard base64 delegates to bytes

• WHEN toBase64 or fromBase64 is called
• THEN the call is forwarded to bytesToBase64 / base64ToBytes from @suaveplan/bytes
• AND errors thrown are BytesError instances with code BYTES.ENCODE.INVALID_BASE64

Scenario: concatBytes delegates to bytes

• WHEN concatBytes is called
• THEN the call is forwarded to concatUint8Arrays from @suaveplan/bytes

Scenario: Byte utilities available

• WHEN a consumer imports from @suaveplan/crypto-utils
• THEN concatBytes(...arrays: Uint8Array[]): Uint8Array, xor(a: Uint8Array, b: Uint8Array): Uint8Array, i2osp(n: bigint, len: number): Uint8Array, os2ip(bytes: Uint8Array): bigint are exported

Scenario: Constant-time, random, and zeroize utilities available

• WHEN a consumer imports from @suaveplan/crypto-utils
• THEN constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean is exported and implemented without early return
• AND randomBytes(n: number): Uint8Array is exported, sourcing from globalThis.crypto.getRandomValues
• AND zeroize(bytes: Uint8Array): void is exported

Requirement: Test-vector and fuzz harness

@suaveplan/crypto-utils SHALL expose harness functions that crypto-hash, crypto-curve, and crypto-cipher use to run KATs and differential fuzz against their primitive impls.

Scenario: KAT harness

• WHEN a primitive test imports runVectors from @suaveplan/crypto-utils/testing
• THEN it can pass a vector list and a set of impls, and receive a per-impl pass/fail/pending report
• AND pending impls (throwing PrimitiveNotImplemented) are distinguished from failing impls

Scenario: Differential fuzz harness

• WHEN a primitive test imports diffFuzz from @suaveplan/crypto-utils/testing
• THEN it can pass two impls, an input generator, and an iteration count, and receive a mismatch report
• AND any byte-level divergence in outputs is reported with the reproducing input

Requirement: Primitive id registry

@suaveplan/crypto-utils SHALL export the PrimitiveId union type enumerating every hash, curve, and AEAD primitive across the crypto family, and a PRIMITIVE_IDS const array for runtime iteration.

Scenario: Registry available

• WHEN a consumer imports PrimitiveId and PRIMITIVE_IDS from @suaveplan/crypto-utils/primitive-id
• THEN PRIMITIVE_IDS contains every id supported by crypto-hash, crypto-curve, and crypto-cipher
• AND PrimitiveId narrows to the same union at compile time

Requirement: No vendored code

@suaveplan/crypto-utils SHALL contain only original code authored in this monorepo. No src/vendored/ directory.

Scenario: No vendored directory

• WHEN the package tree is inspected
• THEN no path matches packages/universal/crypto-utils/src/vendored/**

Requirement: Merkle helpers

@suaveplan/crypto-utils SHALL expose Merkle tree construction and inclusion-proof helpers generic over any hash primitive from @suaveplan/crypto-hash.

Scenario: Merkle helpers available

• WHEN a consumer imports merkleRoot and merkleProof from @suaveplan/crypto-utils/merkle
• THEN they accept a hash function parameter and a list of leaves, returning a root and an inclusion proof respectively