[2.0] Add ML-KEM (FIPS 203) support while keeping legacy Kyber API with deprecation #3

The main idea is to make this library both more secure and enterprise friendly.

With more usage there will be more contributors.

Summary

For 2.0 I want to add proper ML-KEM (FIPS 203) support while keeping the old Kyber* classes working so nobody's code breaks.

The Rust backend stays ours and under the Unlicense. I'm not changing the behavior of the existing API, just adding a deprecation warning.

Note: Kyber and ML-KEM are not interoperable.

Goals

• Add ML_KEM_512, ML_KEM_768, ML_KEM_1024 (ML-KEM: K-PKE key generation, encryption and decryption #9, ML-KEM: KEM layer, input checks and zeroization #10, Python classes ML_KEM_512, ML_KEM_768, ML_KEM_1024 #13)
• Keep Kyber512/768/1024 working with the old behavior (Freeze legacy Kyber output with golden vectors from v1.0.5 #6 locks this in with golden vectors)
• Show a deprecation warning the first time someone uses a Kyber* class (Deprecation warning for the Kyber classes #14)
• Point the docs and examples at ML-KEM (Docs: point everything at ML-KEM and write a migration guide #15)
• Do a security pass (recent CVEs + side channels) and write it up in SECURITY.md (Timing checks: assembly scan and a dynamic timing test #16, Fuzzing and dependency checks #17, Security pass over the legacy Kyber code #18)

Notes

• Deliberately not breaking the current API.
• Might give up a bit of speed for better side-channel resistance (or keep a faster internal path if it turns out to matter).
• Moving the default branch to main, once dev-v2 is merged into it at the end.

How the work is split

The full plan is in PLAN-2.0.md (#19, along with AGENTS.md, the rules any agent working on this has to follow). Each issue is one PR into dev-v2, rebase-merged. Every commit in a PR has to build and pass the tests on its own, and fixes from review get folded into the commit they belong to and rebased, not stacked on top as "fix" commits. When everything's in, I'll open one PR from dev-v2 to main. Roughly in this order:

Setup

• [2.0] Repo setup: protect dev-v2 and add contributor docs #4 Repo setup: protect dev-v2 and add contributor docs
• Fix the failing Kyber-1024 params test #5 Fix the failing Kyber-1024 params test
• Freeze legacy Kyber output with golden vectors from v1.0.5 #6 Freeze legacy Kyber output with golden vectors from v1.0.5
• CI: run tests and lints on every PR #7 CI: run tests and lints on every PR

ML-KEM

• Figure out which Kyber primitives ML-KEM can reuse #8 Figure out which Kyber primitives ML-KEM can reuse
• ML-KEM: K-PKE key generation, encryption and decryption #9 K-PKE key generation, encryption and decryption
• ML-KEM: KEM layer, input checks and zeroization #10 KEM layer, input checks and zeroization
• Test ML-KEM against the NIST ACVP vectors #11 Test against the NIST ACVP vectors
• Test ML-KEM against C2SP CCTV and Wycheproof, plus a differential test #12 Test against C2SP CCTV and Wycheproof, plus a differential test
• Python classes ML_KEM_512, ML_KEM_768, ML_KEM_1024 #13 Python classes ML_KEM_512, ML_KEM_768, ML_KEM_1024
• Deprecation warning for the Kyber classes #14 Deprecation warning for the Kyber classes
• Docs: point everything at ML-KEM and write a migration guide #15 Docs and migration guide

Security

• Timing checks: assembly scan and a dynamic timing test #16 Timing checks: assembly scan and a dynamic timing test (needed for 2.0.0)
• Fuzzing and dependency checks #17 Fuzzing and dependency checks (needed for 2.0.0)
• Security pass over the legacy Kyber code #18 Security pass over the legacy Kyber code (can carry on into 2.0.x)

Dependencies between them are set on each issue.

Done when

• ML-KEM classes pass the official test vectors (Test ML-KEM against the NIST ACVP vectors #11, Test ML-KEM against C2SP CCTV and Wycheproof, plus a differential test #12)
• Old Kyber* classes still give the same results as before (Freeze legacy Kyber output with golden vectors from v1.0.5 #6)
• Warning only shows once per process (Deprecation warning for the Kyber classes #14)
• Docs recommend ML-KEM (Docs: point everything at ML-KEM and write a migration guide #15)