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

ADDED Requirements

Requirement: Universal curve primitive surface

@suaveplan/crypto-curve SHALL expose a stable public API for the curves listed below, independent of the underlying implementation source.

Scenario: Curves available

• WHEN a consumer imports from @suaveplan/crypto-curve
• THEN secp256k1, ed25519, x25519, p256 are exported
• AND each curve exposes the operations it supports: getPublicKey, sign, verify, getSharedSecret (ECDH), utils.randomPrivateKey, as appropriate
• AND each curve is also exported from the subpath @suaveplan/crypto-curve/<id> for tree-shaking

Requirement: Per-primitive replaceability

Every curve in @suaveplan/crypto-curve 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 curve has both impl files

• WHEN the package is inspected
• THEN every curve 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 curve SHALL come from a vendor-fork of @noble/curves stored inside this package, not from the @noble/curves npm package.

Scenario: No external runtime dependency on @noble/curves (post-0.5)

• WHEN packages/universal/crypto-curve/package.json is inspected after Phase 0.5 completes
• THEN @noble/curves 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. A curve'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 a curve 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
• AND the merge is blocked without a valid audit attachment

Requirement: Constant-time curve math

Native curve implementations SHALL NOT contain data-dependent branches on private-key material, scalar values, or intermediate field elements derived from secrets. Array indexing on secret values is prohibited.

Scenario: Constant-time lint enforces this

• WHEN any impl/*.native.ts in this package is modified
• THEN scripts/ct-lint.ts scans for the prohibited patterns
• AND any match fails CI with a line-level diagnostic