Initial Commit

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

@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: Universal AEAD primitive surface
+
+`@suaveplan/crypto-cipher` SHALL expose a stable public API for the AEAD primitives listed below, independent of the underlying implementation source.
+
+#### Scenario: AEAD primitives available
+
+- **WHEN** a consumer imports from `@suaveplan/crypto-cipher`
+- **THEN** `aes256gcm`, `chacha20poly1305`, `xchacha20poly1305` are exported
+- **AND** each primitive exposes `encrypt(key, nonce, plaintext, aad?)` and `decrypt(key, nonce, ciphertext, aad?)` returning / consuming `Uint8Array`
+- **AND** each primitive is also exported from the subpath `@suaveplan/crypto-cipher/<id>` for tree-shaking
+
+### Requirement: Per-primitive replaceability
+
+Every AEAD in `@suaveplan/crypto-cipher` SHALL have both a vendor-forked `noble` implementation and a `native` implementation slot, selected per-primitive at build time via the root `crypto.config.ts`.
+
+#### Scenario: Every AEAD has both impl files
+
+- **WHEN** the package is inspected
+- **THEN** every primitive id has both `src/primitives/<id>/impl/<id>.noble.ts` and `src/primitives/<id>/impl/<id>.native.ts`
+- **AND** the `native.ts` file is either a working implementation or a stub that throws `PrimitiveNotImplemented('<id>')`
+
+### Requirement: Vendored noble source (Phase 0.5)
+
+From Phase 0.5 onward, the `noble` implementation for every AEAD SHALL come from a vendor-fork of `@noble/ciphers` stored inside this package, not from the `@noble/ciphers` npm package.
+
+#### Scenario: No external runtime dependency on @noble/ciphers (post-0.5)
+
+- **WHEN** `packages/universal/crypto-cipher/package.json` is inspected after Phase 0.5
+- **THEN** `@noble/ciphers` does not appear in `dependencies` or `peerDependencies`
+- **AND** `src/vendored/` contains the forked source with its original LICENSE preserved
+- **AND** `NOBLE_UPSTREAM.md` records the pinned upstream commit SHA and sync date
+
+### Requirement: Dangerous-tier CI gate
+
+Every primitive in this package belongs to the **dangerous tier**. An AEAD's default SHALL NOT be changed from `'noble'` to `'native'` in `crypto.config.ts` unless the flip PR demonstrates all gates required by `crypto-hash`, **plus** a third-party cryptographic audit sign-off covering the specific native implementation being flipped.
+
+#### Scenario: Audit required to flip
+
+- **WHEN** a PR modifies `crypto.config.ts` to change an AEAD entry from `'noble'` to `'native'`
+- **THEN** the flip PR template requires an audit report (PDF + auditor signature) attached to the PR
+- **AND** the audit report references the exact commit SHA of the native impl being flipped
+
+### Requirement: Constant-time block-cipher and MAC implementation
+
+Native AES implementations SHALL be bitsliced or use hardware intrinsics — table-lookup AES is prohibited. Native Poly1305 and GHASH implementations SHALL NOT contain data-dependent branches.
+
+#### Scenario: Constant-time lint enforces this
+
+- **WHEN** any `impl/*.native.ts` in this package is modified
+- **THEN** `scripts/ct-lint.ts` scans for prohibited patterns (secret-indexed array access, data-dependent branches, early returns on tag comparison)
+- **AND** any match fails CI with a line-level diagnostic
+
+### Requirement: Nonce handling is the caller's responsibility
+
+Primitives in this package SHALL NOT generate nonces internally. All nonce inputs are supplied by the caller.
+
+#### Scenario: No internal random nonce
+
+- **WHEN** `encrypt(...)` is invoked
+- **THEN** no call to a CSPRNG is made inside the primitive
+- **AND** the nonce parameter is required and validated for length