Post-merge improvements for PasswordHash.java documentation and implementation

[github-actions]

Overview

This issue tracks post-merge recommendations from code reviews of PR #1906 (JavaDoc documentation for PasswordHash.java).

Recommendations

1. Fix PBKDF2_ALGORITHM constant bug (Critical - P0)

Problem: The constant PBKDF2_ALGORITHM at line 135 is set to "PBKDF2WithHmacSHA2" which is not a valid Java algorithm name and will cause NoSuchAlgorithmException at runtime.

Current behavior:

• Implementation actually uses PBKDF2 with HMAC-SHA1 (algorithm id "sha1")
• Hash generation at line 248 uses "sha1:" prefix
• Verification at line 322 only accepts "sha1" algorithm

Valid options:

• PBKDF2WithHmacSHA1 (matches current behavior)
• PBKDF2WithHmacSHA256 (recommended upgrade)
• PBKDF2WithHmacSHA384
• PBKDF2WithHmacSHA512

Recommendation: Fix the constant to match actual implementation or upgrade to SHA-256.

References:

• src/main/java/ca/openosp/openo/utility/PasswordHash.java:135
• Documented in JavaDoc at lines 134-139

2. Verify BCrypt policy in CLAUDE.md (High - P1)

Problem: CodeRabbit review flagged potential policy mismatch:

• CLAUDE.md may require BCrypt for password hashing
• PasswordHash.java uses PBKDF2 with HMAC-SHA1
• Need to clarify if this is an approved legacy exception or if migration is needed

Action required:

1. Review CLAUDE.md and related documentation for password hashing requirements
2. Determine if PasswordHash is approved legacy or needs migration
3. If migration needed, create follow-up issue for BCrypt implementation
4. Update documentation to clarify the policy

References:

• CodeRabbit review comment on PR docs: add comprehensive JavaDoc documentation to PasswordHash.java #1906
• CLAUDE.md security requirements section

3. Add @SInCE tags to public methods (Low - P3)

Problem: Public methods and constructors are missing @SInCE tags per CLAUDE.md documentation standards.

Action required:

• Add @SInCE tags to all public constructors in InvalidHashException
• Add @SInCE tags to all public constructors in CannotPerformOperationException
• Add @SInCE tags to createHash() methods
• Add @SInCE tags to verifyPassword() methods
• Use accurate dates from git history

References:

• CLAUDE.md documentation standards
• CodeRabbit review comment

4. Avoid line number references in JavaDoc (Low - P3)

Problem: JavaDoc currently references "line 248" and "line 322" which will drift as code changes.

Current references:

• Line 137: "at line 248"
• Line 137: "at line 322"
• Line 240: "as seen at line 248"

Recommendation: Replace with symbol references using {@link} tags:

• Reference {@link #createHash(char[])} instead of "line 248"
• Reference {@link #verifyPassword(char[], String)} instead of "line 322"

References:

• src/main/java/ca/openosp/openo/utility/PasswordHash.java:137, 240

Context

• Related PR: docs: add comprehensive JavaDoc documentation to PasswordHash.java #1906
• Related Epic: [Epic] JavaDoc - Undocumented Files (Priority 1) - 171 files #1405
• File: src/main/java/ca/openosp/openo/utility/PasswordHash.java
• Type: Documentation + Code improvements
• Healthcare context: This utility is critical for HIPAA/PIPEDA compliant password storage

Priority

• P0 (Critical): Issue Added DownloadInIterceptor import to the classes #1 - Runtime bug that will cause exceptions
• P1 (High): Issue Fix method calls in DemographicRelationship #2 - Policy compliance verification
• P3 (Low): Issues Added development-drugref.sql #3-4 - Documentation improvements

---

Generated from code review feedback on PR #1906