34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
# 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.
|