Initial Commit

openspec/archive/2026-04-19-crypto-primitive-replaceability/specs/crypto-utils/spec.md

@@ -0,0 +1,67 @@
+## ADDED 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** decoders throw a `SuaveplanError` subclass with stable code `CRYPTO.UTILS.INVALID_ENCODING` on malformed input
+
+#### 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