[argos] Migrate bcrypt hashes to Argon2id without forced password resets

[seonghobae]

Target repository

ContextualWisdomLab/argos

Argos issues are disabled, so this organization-level issue tracks the repository-specific follow-up to Argos PR #270.

Buyer-visible problem

Argos currently uses bcryptjs. PR #270 can safely bound work and reject values beyond bcrypt's 72-byte UTF-8 boundary, but that compatibility control cannot provide the long, fully Unicode password contract recommended by current NIST guidance. OWASP treats bcrypt as a legacy fallback when Argon2id or scrypt is unavailable.

Product outcome

Introduce an algorithm-tagged, transport-neutral password verifier that:

• creates new password hashes with Argon2id;
• verifies existing bcrypt hashes and rehashes them only after successful authentication;
• never pre-hashes or silently truncates caller passwords;
• supports Unicode and at least 64 code points within a separately bounded request-size/resource cap;
• preserves existing users without a forced reset;
• makes registration and password reset write Argon2id immediately;
• validates and caps memory, iteration, parallelism, salt, and output parameters at startup;
• keeps password values out of logs, traces, metrics, analytics, and errors; and
• remains independently usable by Argos and importable by naruon/shared identity adapters.

Required tests

Use red-green-refactor TDD and retain 100% production statement and branch coverage.

1. successful bcrypt login atomically upgrades to Argon2id;
2. wrong password never mutates the stored hash;
3. current Argon2id parameters avoid unnecessary rewrites;
4. stale Argon2id parameters rehash on success;
5. concurrent successful logins converge without lost updates or lockout;
6. persistence failure preserves the prior valid credential;
7. registration and password reset write Argon2id;
8. 1-, 2-, 3-, and 4-byte Unicode passwords verify exactly without normalization or truncation;
9. at least 64 Unicode code points are accepted within the documented resource cap;
10. hostile oversized input fails before expensive hashing;
11. benchmark evidence reports p50/p95 latency, peak RSS, and bounded concurrency; and
12. installed-package, production-build, and database-transaction smoke tests reproduce the migration.

Rollout contract

Rollback must retain Argon2id verification once any account is upgraded. Do not bulk-transform bcrypt hashes. Store self-describing algorithm/version/parameter data and use a provider-neutral PasswordHashProvider-style boundary rather than direct algorithm imports in routes.

Documentation and release

Add doctoring, migration state machine, parameter rationale, benchmark evidence, rollback, operational alerts, CHANGELOG entry, and an explicit versioning decision. Do not claim formal NIST or OWASP conformity from algorithm selection alone.

References

National Institute of Standards and Technology. (2025). Digital identity guidelines: Authentication and authenticator management (NIST Special Publication 800-63B-4). U.S. Department of Commerce. https://doi.org/10.6028/NIST.SP.800-63B-4

OWASP Foundation. (n.d.). Authentication cheat sheet. OWASP Cheat Sheet Series. Retrieved August 5, 2026, from https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html

OWASP Foundation. (n.d.). Password storage cheat sheet. OWASP Cheat Sheet Series. Retrieved August 5, 2026, from https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html

Definition of done

Complete only when exact-head tests prove compatibility and atomic migration, Unicode is not truncated, benchmarked parameters are bounded, rollback cannot strand upgraded users, docs/coverage are complete, all security checks pass, review threads are resolved, and independent approval precedes merge.