Memory-hard KDF for hashing API keys at rest (Argon2id)

[kilodesodiq-arch]

Problem Statement. The current keyHash is described as SHA-256 in spec. SHA-256 of an
API key is fast — exactly what an attacker brute-forcing a leaked hash wants.

Why it matters. Even with a long random key, a stolen keyHash can be reversed by
someone who controls the database.

Technical Context. Existing keyHash column allows arbitrary length. Argon2id
produces a 32-byte hash with a parameter-aware string that can fit.

Expected Outcome. API keys are hashed with argon2id, parameters encoded inside the
hash output so verification doesn't need a config match.

Acceptance Criteria.

• Verification uses argon2-cffi's PasswordHasher verify.
• Existing hashes are invalidated on next request (re-authentication required).
• E2E test demonstrates that an SHA-256 hash purely fails the new verifier.

Implementation Notes. Pick parameters (m=64 MiB, t=3, p=1) carefully; benchmark
against the existing verify latency budget.

Files or modules likely to be affected. src/api-keys/*,
src/common/guards/api-key.guard.ts, requirements.txt /
package.json (argon2, argon2-cffi).

Difficulty. Medium
Estimated effort. S

---

Smart-Contract Safety — Issues 15–28

---

Backlog item #14 from `docs/maintainer-issue-backlog.md.

[AnnieIj]

Hi! I'd love to work on this issue.

I plan to implement Argon2id as a memory-hard KDF for hashing API keys at rest, following the existing security architecture, adding comprehensive tests, and ensuring the implementation is secure and well documented. Could you please assign this issue to me?

[Clement-coder]

Hi,

I’m a full-stack software and blockchain engineer with hands-on experience delivering production-ready solutions across frontend, backend, and blockchain systems.

I’d like to take ownership of this issue. I’ve reviewed the requirements and can implement a scalable, maintainable, and well-tested solution that fully satisfies the acceptance criteria.

Ready to start immediately and keep the team updated throughout the process.

[kimanicode]

Hi, I'd like to take this issue. I'll switch API key hashing to argon2id with m=64 MiB, t=3, p=1, update the guard to verify using PasswordHasher.verify, ensure existing SHA-256 hashes fail verification and force re-auth, and add an e2e test covering that failure case. Please assign it to me, thanks.

[grantfox-oss]

🦊 GrantFox — @kimanicode has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #222)
2. Your PR will be reviewed by the ChainForgee maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@kimanicode's PR #408 was approved and merged by @kilodesodiq-arch.

🏆 @kimanicode: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (449 total points). Track your full progress on GrantFox.

👏 Great work, @kimanicode! Keep contributing to ChainForgee.