security(pqc): standards-alignment metadata registry + conformance/NatSpec wording fixes - #135
Merged
Merged
Conversation
…tSpec wording fixes
Implements findings H1, H2, M2, L6, L7 from docs/security/pqc-standards-alignment-audit.md.
- Add a canonical PQ algorithm registry (src/standards/pq-algorithm-registry.ts)
modeling ML-DSA-65 as implemented/not-validated/prototype, and ML-KEM/SLH-DSA
as explicitly not-implemented, plus a derived standards-alignment status
helper. Purely descriptive metadata; does not touch verifier selection or
dispatch (src/verifier/schema.ts, evidence.ts's algorithm/fips typing and
isValidReason remain untouched — out of scope per M3/PR-G).
- Extend the evidence envelope (src/verifier/evidence.ts) and its JSON Schema
with an optional `standards` snapshot (fipsValidated-equivalent
certificationStatus, structured implementation{provider,package,version},
conformanceStatus, productionStatus). buildEvidence() auto-populates it;
validateEvidence() rejects malformed values while treating absence as
backward-compatible legacy evidence, never a positive claim (M2, L7).
- Same `standards` block added to the ML-DSA evidence manifest
(evidence/ml-dsa/manifest.json + its schema + scripts/lib/ml-dsa-evidence-manifest.ts),
required there since the manifest is a single generated file.
- Clarify the `fips` const field's JSON Schema description as an algorithm
identifier, not a validation flag (L6).
- Soften ZKMLDSAVerifier.sol's NatSpec from present-tense "Trustless
verification... Replaces the trusted-attestation model" to intent language
plus an explicit PROTOTYPE/not-deployed/unaudited/unproven-vkey-binding
disclaimer (H1).
- Correct the "15/15 ACVP test cases" overclaim in README.md and the NIST
CAVP fixture README to the actual committed/exercised surface (6 of 15
group-3 vectors); rename the conformance test's describe() block from
"full ACVP test group 3" to "committed group-3 subset" (H2).
- Add PQAlgorithmRegistry.test.ts and extend PQEvidence/MLDSAEvidenceManifest
tests: registry invariants (nothing validated today, ML-KEM/SLH-DSA carry
no implementation details), standards field accept/reject/backward-compat,
malformed-metadata rejection, schema-sync checks.
Regenerated docs/schemas/examples/*.json and evidence/ml-dsa/manifest.json via
their existing generator scripts (npm run evidence:fixtures / evidence:manifest)
so committed artifacts match the code with no drift.
Does not implement M3/PR-G (off-chain crypto-agility redesign) or M1 (embedded
research copy reconciliation, private-repo side) — out of scope for this PR.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
sirmrdrgod
marked this pull request as ready for review
July 17, 2026 00:27
sirmrdrgod
marked this pull request as draft
July 17, 2026 00:28
sirmrdrgod
marked this pull request as ready for review
July 17, 2026 00:29
…idateStandardsMetadata Addresses SonarCloud findings on the twin implementation in the private app (src/lib/pqVerifierEvidence.js): the enum-membership checks in validateStandardsMetadata are now data-driven via STANDARDS_ENUM_CHECKS instead of six sequential if-statements, and the implementation-shape check is extracted into validateStandardsImplementation(). Object.keys(...).sort() now takes an explicit localeCompare comparator. Pure refactor — same error messages, same validation behavior. 834 vault tests passing, tsc --noEmit clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
sirmrdrgod
marked this pull request as draft
July 17, 2026 00:42
sirmrdrgod
marked this pull request as ready for review
July 17, 2026 00:42
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements findings H1, H2, M2, L6, L7 from
docs/security/pqc-standards-alignment-audit.md(private-repo audit, not yet merged upstream). Does not implement M3/PR-G (the off-chain crypto-agility redesign) — explicitly out of scope for this change.src/standards/pq-algorithm-registry.ts— canonical, purely descriptive PQ algorithm registry. Models ML-DSA-65 asimplemented/not-validated/prototypewith its real implementation package+version (@noble/post-quantum@0.6.1), and ML-KEM (FIPS 203) / SLH-DSA (FIPS 205) as explicitlynot-implemented— no cryptographic code added for either. Also exposes a derived standards-alignment status helper (no percentage/score, by design).src/verifier/evidence.ts+docs/schemas/pq-verifier-evidence.v1.schema.jsongain an optionalstandardssnapshot (certificationStatus, structuredimplementation,conformanceStatus,productionStatus).buildEvidence()auto-populates it from the registry;validateEvidence()rejects malformed values but treats absence as valid (backward-compatible with pre-existing evidence). The same block is added toevidence/ml-dsa/manifest.json+ its schema, required there since the manifest is a single generated file, not a widely-forked artifact type.fipsconst's schema description now explicitly states it's an algorithm identifier, not a validation flag —standards.certificationStatusis the authoritative validation-status field.ZKMLDSAVerifier.solNatSpec softened from present-tense "Trustless verification... Replaces the trusted-attestation model" to intent language, plus an explicitPROTOTYPE — not deployed, unauditeddisclaimer noting the unproven SP1-vkey↔ML-DSA binding.README.mdand the NIST CAVP fixture README corrected to the actual committed/exercised surface (6 of 15 group-3 vectors);MLDSAConformance.test.ts'sdescribe()renamed from "full ACVP test group 3" to "committed group-3 subset".None of this touches the verifier's algorithm-selection/dispatch logic (
PQ_VERIFIER_ALGORITHM/PQ_VERIFIER_FIPSstring-literal typing,isValidReason), scoring, Dune, provider-spend, or verifier governance/timelocks.Test plan
npm run compile— 18 Solidity files compile cleannpm run typecheck(tsc --noEmit) — cleannpm test(hardhat/mocha) — 834 passing, 11 pending (gated SP1/RUN_SP1_E2E, pre-existing), 0 failingnpm run format:check(prettier) — cleannpm run lint(solhint) — 0 errors (79 pre-existing warnings in files this PR doesn't touch)npm run security:audit(npm audit --omit=dev) — 0 vulnerabilitiesgit diff --check— cleandocs/schemas/examples/*.jsonandevidence/ml-dsa/manifest.jsonvia their existing generator scripts (npm run evidence:fixtures,npm run evidence:manifest) — no drift between generator and committed artifactsNIST certified|FIPS certified|FIPS compliant|FIPS validated|CMVP validated— no matchestest/PQAlgorithmRegistry.test.ts(registry invariants, ML-KEM/SLH-DSA non-implementation) + extensions toPQEvidence.test.ts/MLDSAEvidenceManifest.test.ts(standards field accept/reject/backward-compat/malformed-rejection, schema-sync checks)Draft — not to be merged without review.
🤖 Generated with Claude Code