Plan: Transition River crypto primitives to NIST PQC algorithms

[sanity]

Summary

River signs nearly every state mutation and encrypts room secrets using Ed25519 signatures, X25519-derived Diffie–Hellman, and AES-256-GCM. We should migrate to post-quantum schemes (Dilithium for signatures, Kyber for key encapsulation) while maintaining compatibility with existing data.

Motivation

• Eliminate reliance on elliptic-curve algorithms that fall to quantum attacks.
• Provide a forward-looking cipher suite negotiation story before contracts are republished.
• Align River with Freenet-wide security guidance on PQ readiness.

Current Usage Surface

• Signatures: common/src/util.rs:3, common/src/room_state/*, cli/src/crypto.rs, WASM contracts all rely on Ed25519 for Authorized* wrappers.
• Key exchange: cli/src/crypto.rs:74 and ui/src/util/ecies.rs:26 convert Ed25519 keys to X25519 and wrap room secrets with ECIES.
• Symmetric: RoomCipherSpec::Aes256Gcm (common/src/room_state/privacy.rs:31) governs encrypted metadata, member profiles, and messages.
• Identifiers: MemberId/MessageId use freenet-scaffold/src/util.rs:3’s non-cryptographic hash of public keys/signatures; these should change when new keys arrive.

Proposed Plan

1. Research & Abstractions
   • Validate pqcrypto/PQClean Dilithium and Kyber crates for x86_64, aarch64, and wasm32-unknown-unknown.
   • Introduce trait wrappers in river_core for signing and key encapsulation so legacy and PQ modes can coexist.
   • Extend RoomCipherSpec to encode suites (e.g., LegacyEd25519X25519Aes, PqDilithiumKyberAes).
2. Dual-Stack Key Material
   • Add PQ public keys to Member records and invitations; update CBOR schemas with version tags.
   • Teach contracts and clients to accept both legacy and PQ signatures during migration.
3. Signatures
   • Implement Dilithium signing/verification in river_core::util and swap Authorized* wrappers to carry an enum of signature types.
   • Rebuild MemberId/BanId/MessageId using a collision-resistant hash (e.g., BLAKE3) keyed off canonical public key bytes.
4. Secret Distribution (KEM)
   • Replace X25519 ECIES with Kyber encapsulation: store KEM ciphertext + shared secret metadata in EncryptedSecretForMember.
   • Derive symmetric keys with SHA3/KMAC from the Kyber shared secret and document nonce handling.
   • Update invitation flows and CLI tooling to request PQ KEM keys.
5. Symmetric Layer & Data Migration
   • Keep AES-256-GCM but formalize KDFs and nonce generation under the new suite.
   • Provide CLI/contract helpers to re-encrypt stored secrets, coordinate publication of new RoomCipherSpec versions, and flag completion per room.
6. Testing & Rollout
   • Add property tests ensuring legacy CBOR blobs verify under Dilithium once re-signed.
   • Create end-to-end tests for invitation acceptance, message posting, and contract delta validation in PQ mode.
   • Benchmark payload size growth (Dilithium keys/signatures, Kyber ciphertexts) and document storage/network tradeoffs.

Deployment Considerations

• Rev the room contract WASM after PQ support lands and make sure old clients fail gracefully instead of accepting unreadable states.
• Plan an owner-led rotation that publishes PQ parameters and forces members to supply PQ keys before continuing to sync.
• Coordinate with Freenet node tooling so published artifacts stay under size limits.

Open Questions

• Do we require hybrid signatures (Ed25519 + Dilithium) for a long deprecation window?
• Should we standardize on SHA3/Shake-based hashing everywhere as part of this change?
• How will web/desktop clients store the larger PQ private keys securely (browser IndexedDB, OS keychain, etc.)?