SuavePlan/suaveplan

Files

admin fbc70f96e6 Initial Commit

2026-05-27 23:29:53 +01:00

1.9 KiB

Raw Blame History

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.