gabriel / musehub public
Open #64
filed by aaronrene human · 13 days ago

feat: quantum-resistant provenance trust layer

0 Anchors
— Blast radius
— Churn 30d
0 Proposals

Goal

Implement a production-ready post-quantum-ready trust layer for MuseHub provenance without changing existing SHA-256 commit IDs, snapshot IDs, object IDs, manifest hashes, token hashes, or provenance references.

Current standards baseline

  • NIST FIPS 203, 204, and 205 are final standards: ML-KEM for key establishment, ML-DSA for digital signatures, and SLH-DSA for stateless hash-based signatures.
  • Current high-security guidance favors crypto agility, SHA-384/SHA-512 or SHA3-family strong digests, AES-256 where encryption is involved, and ML-KEM/ML-DSA high-security parameter sets for sensitive long-horizon systems.
  • IETF TLS work is active for hybrid TLS 1.3 key agreement using ECDHE + ML-KEM groups including X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024.
  • Product language must say quantum-resistant, post-quantum-ready, or post-quantum signature verified only when verified. Do not use quantum-proof.

Proposed branch

Create and push feat/quantum-resistant-provenance once staging Muse fetch/push is stable. Local branch creation was not completed because muse clone https://staging.musehub.ai/gabriel/musehub currently disconnects during /fetch/mpack after remote HEAD discovery.

Scope

  1. Add crypto-agility metadata to MuseHub trust and provenance records.

    • Preserve existing SHA-256 identifiers for compatibility.
    • Add digest algorithm, digest value, signature algorithm, key id, signature value, verification status, verification timestamp, and policy version.
    • Support at least SHA-512 or SHA3-512 for new trust anchors.

  2. Add a Quantum-Resistant Provenance policy model.

    • Trust levels: unsigned, sha256-integrity-only, strong-digest-attested, hybrid-signed, post-quantum-signed.
    • Never return post-quantum-signed unless the post-quantum signature verifies cryptographically.

  3. Add a post-quantum signature abstraction.

    • Define signer and verifier interfaces behind a provider boundary.
    • Start with deterministic test provider for reproducible tests.
    • Add ML-DSA and SLH-DSA provider path with explicit policy labeling.
    • Do not use experimental PQ libraries for production-sensitive verification unless the policy state clearly labels the provider as non-production.

  4. Add verification APIs and UI trust badges.

    • Expose verified trust state through REST and MCP surfaces.
    • Render badges: Integrity verified, Strong digest verified, Post-quantum signature verified.
    • Badges must be based on verification results, not claimed metadata.

  5. Add migration and backfill.

    • Existing SHA-256 records remain valid.
    • Compute strong digests beside existing IDs.
    • Backfill must be idempotent, auditable, and restart-safe.

  6. Support Knowtation plugin provenance.

    • Ensure Knowtation commit/provenance metadata can consume the same trust model once the local plugin is ready to push.
    • Keep plugin-facing fields algorithm-explicit and policy-versioned.

Required tests

  • Unit: digest calculation, canonicalization, signature policy mapping.
  • Integration: provenance record creation and verification.
  • End to end: commit/provenance record displays the correct trust badge.
  • Stress: bulk verification/backfill over many records.
  • Data integrity: SHA-256 IDs remain unchanged and strong digest metadata is stable.
  • Performance: digest/signature verification bounds are measured.
  • Security: tampered payloads, replayed signatures, downgraded algorithms, malformed keys, and invalid policy states are rejected.

Security requirements

  • No hardcoded secrets or private keys.
  • No silent downgrade from post-quantum to classical trust.
  • No badge based only on claimed metadata.
  • Verification result must be derived from actual cryptographic verification.
  • All new trust records must include algorithm identifiers and policy version.
  • Avoid misleading marketing language in code, docs, and UI.

Deliverables

  • MuseHub crypto-agility/provenance schema.
  • Verification service.
  • REST and MCP exposure.
  • UI trust badges.
  • Migration/backfill path.
  • Complete tests across unit, integration, end-to-end, stress, data-integrity, performance, and security tiers.
◎ Activity1
●
aaronrene opened this issue 13 days ago
○
gabriel 13 days ago

What's already in place

The codebase has a solid crypto-agility skeleton that directly addresses several items in this ticket. Here's what exists today vs. what the ticket asks for.

musehub/crypto/keys.py

  • KeyAlgorithm enum already defines both ED25519 and ML_DSA_65 = "ml-dsa-65" (FIPS 204 / formerly CRYSTALS-Dilithium-3)
  • PUBLIC_KEY_SIZES and SIGNATURE_SIZES dicts carry the correct raw byte sizes for both (Ed25519: 32/64, ML-DSA-65: 1952/3309)
  • ALGORITHM_DESCRIPTIONS explicitly labels Ed25519 as "not quantum-safe" and ML-DSA-65 as "NIST post-quantum standard, quantum-safe"
  • IMPLEMENTED_ALGORITHMS: frozenset currently contains only ED25519; ML-DSA-65 is defined but commented out — enabling it is a one-line change once the library dep is available
  • verify_signature dispatches on the algorithm enum with a hard AlgorithmNotImplementedError guard — no silent downgrade is possible
  • _verify_ml_dsa_65 stub exists with the exact liboqs-python / PyCA upgrade path documented inline
  • DEFAULT_ALGORITHM is a named constant, so switching to ML-DSA-65 is a single assignment

What this means for the ticket

Scope items 1–3 in the ticket (crypto-agility metadata, post-quantum abstraction, provider boundary) are largely pre-wired at the key-verification layer. The missing pieces are:

  • The trust-level policy model (unsigned → sha256-integrity-only → strong-digest-attested → hybrid-signed → post-quantum-signed)
  • The provenance schema additions (digest algorithm, digest value, key_id, policy_version fields on trust/commit records)
  • REST/MCP exposure and UI trust badges
  • Migration/backfill for existing SHA-256-only records
  • The actual ML-DSA library integration (blocked on cryptography PyCA adding FIPS 204 support or pulling in liboqs-python with its native build dep)

The doc at musehub/docs/reference/msign.md already describes the quantum migration path accurately. No changes needed there.

Recommendation: The ticket scope is correct and complete. The existing skeleton reduces risk significantly — the algorithm dispatch layer is already crypto-agile, there is no hardcoded Ed25519 assumption in verify_signature, and the AlgorithmNotImplementedError guard ensures no silent downgrade. The main work is the policy/provenance schema, the REST/MCP surface, the badges, and the eventual library dep once ML-DSA arrives in a stable Python package.