Initial Commit

openspec/archive/2026-04-18-enterprise-crypto-family/specs/crypto-primitives/spec.md

@@ -0,0 +1,33 @@
+# Capability: crypto-primitives
+
+## ADDED Requirements
+
+### ByteSource type
+
+- REQ-PRIM-001: `@suaveplan/crypto` exports `ByteSource = (n: number) => Uint8Array` — the byte-producing injection type used for key generation.
+- REQ-PRIM-002: `Rng` is exported as a type alias for `ByteSource` for backwards compatibility during the main→genesis port. New code uses `ByteSource`.
+- REQ-PRIM-003: `ByteSource` is explicitly documented as distinct from `@suaveplan/types`'s `Rng` interface (which produces numbers, not bytes).
+
+### randomBytes
+
+- REQ-PRIM-010: Exports `randomBytes(n: number, opts?: { byteSource?: ByteSource }): Uint8Array`.
+- REQ-PRIM-011: Default `byteSource` calls `crypto.getRandomValues` — this is the **only** callsite for `crypto.getRandomValues` in the package.
+- REQ-PRIM-012: Throws `CryptoError("CRYPTO.RNG.INVALID_LENGTH")` if `n` is not a non-negative integer.
+- REQ-PRIM-013: Exports `defaultByteSource: ByteSource`.
+
+### constantTimeEqual
+
+- REQ-PRIM-020: Exports `constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean`.
+- REQ-PRIM-021: Uses XOR-accumulate pattern — branch-free for content bytes. Length mismatch short-circuits (length is not secret).
+- REQ-PRIM-022: Returns `true` iff `a.length === b.length` and all bytes are identical.
+
+### zeroize
+
+- REQ-PRIM-030: Exports `zeroize(buf: Uint8Array): void` — fills buffer with zeros in-place.
+- REQ-PRIM-031: Best-effort (JS GC may have copied); intent is to minimise sensitive-data lifetime on the heap.
+
+### Error surface
+
+- REQ-PRIM-040: Exports `CryptoError extends SuaveplanError<CryptoCode>`.
+- REQ-PRIM-041: Error codes: `CRYPTO.AEAD.DECRYPT_FAILED`, `CRYPTO.AEAD.INVALID_NONCE`, `CRYPTO.KEY.INVALID_LENGTH`, `CRYPTO.SIGN.VERIFY_FAILED`, `CRYPTO.SIGN.INVALID_KEY`, `CRYPTO.RNG.INVALID_LENGTH`, `CRYPTO.RNG.UNAVAILABLE`.
+- REQ-PRIM-042: No error message or context field contains raw key bytes, plaintext, or authentication tags.