134 lines
5.4 KiB
Markdown
134 lines
5.4 KiB
Markdown
# Design: enterprise-crypto
|
|
|
|
## Module layout
|
|
|
|
```text
|
|
packages/universal/crypto/
|
|
├── package.json # deps: @noble/*, @suaveplan/error, @suaveplan/types, tslib, zod
|
|
├── tsconfig.lib.json
|
|
├── vite.config.ts
|
|
├── vitest.config.ts # thresholds 100/100/100/100
|
|
├── README.md
|
|
├── src/
|
|
│ ├── index.ts # barrel
|
|
│ ├── constants/index.ts # standard lengths, default iterations
|
|
│ ├── errors/
|
|
│ │ ├── codes.ts
|
|
│ │ ├── crypto-error.ts
|
|
│ │ ├── crypto-error.test.ts
|
|
│ │ └── index.ts
|
|
│ ├── random/
|
|
│ │ ├── random-bytes.ts # default RNG, the one place that reads crypto.getRandomValues
|
|
│ │ ├── random-bytes.test.ts
|
|
│ │ └── random-bytes.md
|
|
│ ├── compare/
|
|
│ │ ├── constant-time-equal.ts
|
|
│ │ ├── constant-time-equal.test.ts
|
|
│ │ └── constant-time-equal.md
|
|
│ ├── zeroize/
|
|
│ │ ├── zeroize.ts
|
|
│ │ ├── zeroize.test.ts
|
|
│ │ └── zeroize.md
|
|
│ ├── hash/
|
|
│ │ ├── sha2.ts # sha256, sha384, sha512 via @noble/hashes
|
|
│ │ ├── sha2.test.ts
|
|
│ │ └── sha2.md
|
|
│ ├── hmac/
|
|
│ │ ├── hmac.ts
|
|
│ │ ├── hmac.test.ts
|
|
│ │ └── hmac.md
|
|
│ ├── kdf/
|
|
│ │ ├── hkdf.ts + hkdf.test.ts + hkdf.md
|
|
│ │ ├── pbkdf2.ts + pbkdf2.test.ts + pbkdf2.md
|
|
│ │ └── argon2id.ts + argon2id.test.ts + argon2id.md
|
|
│ ├── aead/
|
|
│ │ ├── aead.ts # aeadEncrypt / aeadDecrypt dispatcher
|
|
│ │ ├── aead.test.ts
|
|
│ │ └── aead.md
|
|
│ ├── sign/
|
|
│ │ ├── ed25519.ts + ed25519.test.ts + ed25519.md
|
|
│ │ ├── ecdsa-p256.ts + ecdsa-p256.test.ts + ecdsa-p256.md
|
|
│ ├── agree/
|
|
│ │ └── x25519.ts + x25519.test.ts + x25519.md
|
|
│ └── __benchmarks__/
|
|
│ └── crypto.bench.ts
|
|
├── tests/
|
|
│ ├── setup/polyfills.ts
|
|
│ ├── dep-graph.test.ts
|
|
│ ├── no-disallowed.test.ts
|
|
│ └── tree-shake.test.ts
|
|
└── CHANGELOG.md
|
|
```
|
|
|
|
## Key design decisions
|
|
|
|
### Why @noble/* as the implementation
|
|
|
|
- Pure TypeScript — zero WASM, zero native builds, zero platform-specific branches
|
|
- Audited (Trail of Bits, Cure53)
|
|
- Used in production by MetaMask, Ethereum ecosystem, etc.
|
|
- Identical behaviour across Bun, Node, and browser — no `node:crypto` vs `crypto.subtle` branching
|
|
- Small surface, tree-shakes well
|
|
|
|
The alternative (capability-detecting between `node:crypto` and `crypto.subtle`) adds branching complexity that doesn't buy anything: noble is fast enough for the hot paths, and for the slow paths (Argon2id) every implementation is equally slow.
|
|
|
|
### AEAD dispatcher
|
|
|
|
```ts
|
|
type AeadAlgorithm = "AES-256-GCM" | "ChaCha20-Poly1305";
|
|
|
|
export function aeadEncrypt(
|
|
algo: AeadAlgorithm,
|
|
key: Uint8Array,
|
|
plaintext: Uint8Array,
|
|
options: { nonce: Uint8Array; aad?: Uint8Array }
|
|
): Uint8Array;
|
|
```
|
|
|
|
One function, algorithm selected by string — consumers don't need to import the specific algorithm module. Nonce is caller-provided (callers must not reuse nonces).
|
|
|
|
### Key + nonce validation
|
|
|
|
Every public function validates its inputs at the boundary via Zod-adjacent checks (not Zod itself — these are hot paths, we want branch-and-throw not schema-parse). Wrong key length → `CryptoError("CRYPTO.KEY.INVALID_LENGTH")`. Wrong nonce length → `CRYPTO.AEAD.INVALID_NONCE`. Etc.
|
|
|
|
### Random source injection
|
|
|
|
```ts
|
|
export interface RandomDeps {
|
|
readonly rng?: (n: number) => Uint8Array;
|
|
}
|
|
|
|
export function randomBytes(n: number, deps: RandomDeps = {}): Uint8Array {
|
|
const source = deps.rng ?? defaultRandomBytes;
|
|
return source(n);
|
|
}
|
|
```
|
|
|
|
`defaultRandomBytes` lives in `random/random-bytes.ts` and is the ONLY place that calls `crypto.getRandomValues`. Every other module (`ed25519.generateKeypair`, etc.) accepts `{ rng? }` and forwards.
|
|
|
|
### Error messages
|
|
|
|
Messages are i18n keys — `"error.crypto.aead.decrypt-failed"`, not human strings. No dynamic content in messages that could include secret material. Numerical facts (lengths, algorithm names) are allowed in `context`; raw bytes are never put in `context`.
|
|
|
|
### Zeroing
|
|
|
|
`zeroize(buf)` fills the array with zero via `buf.fill(0)`. It's not possible to guarantee zeroing in JS (GC may have already copied), but calling it communicates intent and minimises the window. Tests verify `zeroize(x); expect(x.every(b => b === 0)).toBe(true)`.
|
|
|
|
## Coverage strategy
|
|
|
|
- Enumeration tests for every branch (valid, boundary, rejected input)
|
|
- Property-based tests via fast-check:
|
|
- AEAD: `decrypt(encrypt(p, k, n, aad), k, n, aad) === p` for arbitrary p, n, aad
|
|
- Sign/verify: `verify(pk, sign(sk, m), m) === true`; wrong message → false
|
|
- Hash: determinism
|
|
- Compare: `constantTimeEqual(a, a)` always true; `a !== b` → false
|
|
- No `istanbul ignore` pragmas
|
|
- `tests/no-disallowed.test.ts` guards against `Date.now` / `Math.random` / `crypto.getRandomValues` outside the approved `random/random-bytes.ts`
|
|
|
|
## Non-goals
|
|
|
|
- Streaming AEAD — waits on `@suaveplan/streams`
|
|
- Hardware key storage, HSM, TPM
|
|
- Post-quantum (Kyber, Dilithium) — revisit once NIST standards stabilise and @noble ships them
|
|
- JOSE / JWT / JWE — belongs in `@suaveplan/jwt-tenant`, not here
|