[haskou]

Summary

• Add a versioned asymmetric payload format using ephemeral X25519 + HKDF-SHA256 + AES-256-GCM.
• Authenticate current payload headers as AES-GCM AAD: asymmetric v2.x25519-hkdf-sha256-aes-256-gcm, symmetric v1.aes-256-gcm, and encrypted private key v3.scrypt.N16384.r8.p5.
• Keep backward-compatible decryption for the previous 4-part asymmetric payload format, pre-AAD symmetric payloads, v2 encrypted private keys, and the legacy PBKDF2 private-key format.
• Add Password and use it through crypto password-based APIs while preserving string | StringValueObject compatibility.
• Add SymmetricKey.fromPasswordUsingOwasp() with the OWASP-listed scrypt profile and preserve fromPassword() legacy defaults.
• Add encrypted private key v3 with scrypt.N16384.r8.p5 + AES-256-GCM, strict Base64 16-byte salt validation on decrypt, and updated README/technical documentation.
• Replace encrypted-private-key generic errors with InvalidEncryptedPrivateKeyFormatError and centralize strict Base64 validation for crypto payloads.
• Use assert(...) for guard-style error paths instead of ad-hoc if (...) throw ... blocks.
• Preserve null-object behavior in Password before running password complexity validation.

Security properties covered

• New ephemeral X25519 key material per asymmetric encryption.
• Random 12-byte AES-GCM IV and 16-byte authentication tag.
• HKDF salt/info domain separation for asymmetric payload encryption.
• Tampering tests fail when changing asymmetric key, IV, ciphertext, or tag.
• Tampering tests fail when changing symmetric IV, ciphertext, tag, custom AAD, or v3 private-key header.
• V3 encrypted private key salts reject malformed Base64 and any decoded length other than 16 bytes before key derivation.

OWASP alignment

• AES-256-GCM keeps the preferred authenticated symmetric encryption mode and ideal AES key size.
• X25519/Curve25519 remains the preferred ECC family for asymmetric encryption.
• Password-derived new private-key encryption uses the OWASP-listed scrypt profile N=2^14, r=8, p=5.

Validation

• yarn lint
• yarn test:coverage (100% statements, branches, functions, and lines)
• yarn build

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[haskou]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 267dc9b847

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".