@carecard/auth-util 3.23.0 → 3.25.0

package/.agents/skills/pkg-auth-util-auth-crypto-library/SKILL.md

@@ -107,10 +107,10 @@ depend on those folders being present.
 - `lib/cryptoUtilAuth.js` wraps Node.js `crypto` primitives for signing,
   verifying, generating HMACs, and salts.
 - `lib/keyGen.js` owns Ed25519 and RSA key generation.
-- `lib/stringUtilAuth.js` owns legacy base64, base64-url-safe, JWT, and
-  password-hash string parsing helpers.
-- Keep direct exports preferred and deprecated nested exports backward
-  compatible unless a breaking change is explicitly requested.
+- `lib/stringUtilAuth.js` owns legacy base64, base64-url-safe, and JWT string
+  helpers. Password-hash parsing stays private to `lib/pwdUtilAuth.js`.
+- Keep direct exports as the public package API. Do not add password aliases,
+  nested password objects, or compatibility parsers.
 - Preserve CommonJS exports unless the repository intentionally migrates module
   systems.
 
@@ -133,27 +133,38 @@ depend on those folders being present.
 
 ## Password And Crypto Layer
 
-- Preserve the HMAC-based password hashing behavior.
-- Preserve the saved password hash string format:
+- Create password credentials with Node.js `crypto.argon2` using Argon2id,
+  version 19, 19,456 KiB memory, two passes, one degree of parallelism, a
+  unique 16-byte random salt, a 32-byte tag, and a pepper of at least 32 UTF-8
+  bytes.
+- Persist only the strict unpadded PHC string:
 
   ```text
-  $1$base64(algorithm)$base64(hash)$base64(salt)$
+  $argon2id$v=19$m=19456,t=2,p=1$base64(salt)$base64(tag)
   ```
 
-- Always handle salt automatically when creating new password hashes.
-- Do not silently change cryptographic defaults, password hash string format,
-  salt behavior, or key output format.
-- Prefer Node.js `crypto` primitives already used by the package over new
-  dependencies.
+- `createPasswordHash(password, pepper)` and
+  `verifyPassword(password, savedHash, pepper)` are the only public password
+  credential APIs; both are asynchronous.
+- Generate salts internally for every credential. Never accept caller-selected
+  salts and never persist or log the pepper.
+- Normalize well-formed Unicode passwords to NFC before deriving the tag, but
+  do not trim or impose password policy here. `@carecard/validate` owns policy,
+  while login intentionally permits existing passwords of any length.
+- Return `false` for malformed, non-canonical, differently parameterized, or
+  legacy saved hashes. Throw for programmer/configuration errors such as an
+  invalid pepper.
+- Do not add legacy HMAC verification. Seeded accounts must be rehashed before
+  the Argon2id-only service starts.
+- Prefer Node.js `crypto` primitives over new dependencies.
 
 ## String Utilities
 
 - Use `stringUtilAuth` for base64 and URL-safe string transformations to keep
   parsing and serialization consistent.
-- Keep legacy formatted string parsing behavior backward-compatible.
-- Cover edge cases for malformed JWT strings, malformed password hashes, bad
-  base64 input, missing segments, and unsupported algorithms when these paths
-  change.
+- Do not expose password-hash parsing through `stringUtilAuth`.
+- Cover edge cases for malformed JWT strings, bad base64 input, missing
+  segments, and unsupported algorithms when these paths change.
 
 ## Security And Error Handling
 

package/.nvmrc

@@ -0,0 +1 @@
+24.20.0

package/index.d.ts

@@ -112,21 +112,6 @@ export interface AuthenticatedRequest extends Request {
   visitor?: VisitorRequestObject | null;
 }
 
-/**
- * Represents the decomposed parts of a stored password hash.
- * @deprecated Use native Buffer methods or other modern alternatives.
- */
-export interface PasswordParts {
-  /** Version indicator of the hashing format. */
-  version: string;
-  /** Base64 encoded algorithm name. */
-  alg: string;
-  /** Base64 encoded password hash. */
-  hash: string;
-  /** Base64 encoded random salt. */
-  salt: string;
-}
-
 /**
  * Contains a pair of public and private cryptographic keys.
  */
@@ -171,38 +156,6 @@ export const jwtUtilAuth: {
   getHeaderPayloadFromJwt: (jwt: string) => JwtParts | null;
 };
 
-/**
- * Utility functions for password hashing and verification.
- * @deprecated use direct imports of the new functions.
- */
-export const pwdUtilAuth: {
-  /**
-   * Generates a password hash using a random salt and specified algorithm.
-   * @param password - The plain-text password to hash.
-   * @param secret - A pepper/secret key to combine with the password.
-   * @param algorithm - The hashing algorithm to use (e.g., 'sha256').
-   * @returns A string containing the formatted hash with metadata ($1$alg$hash$salt$) or null if an error occurs.
-   */
-  createPasswordHashWithRandomSalt: (
-    password: string,
-    secret: string,
-    algorithm: string,
-  ) => string | null;
-  /**
-   * Generates a password hash using the same algorithm and salt from a previously saved hash.
-   * Useful for verifying a password against a stored hash.
-   * @param password - The plain-text password to verify.
-   * @param savedPasswordHash - The full stored hash string (including salt and metadata).
-   * @param secret - The pepper/secret key used for hashing.
-   * @returns A hash string that should match the saved hash if the password is correct, or null if an error occurs.
-   */
-  createPasswordHashBasedOnSavedAlgorithmSalt: (
-    password: string,
-    savedPasswordHash: string,
-    secret: string,
-  ) => string | null;
-};
-
 /**
  * Utility functions for string manipulation, base64 encoding, and parsing auth-related strings.
  * @deprecated Use native Buffer methods or other modern alternatives.
@@ -236,13 +189,6 @@ export const stringUtilAuth: {
    * @returns Decoded plain-text string.
    */
   base64ToAscii: (codedString: string) => string;
-  /**
-   * Parses a stored password hash string into its constituent parts.
-   * @deprecated Use native Buffer methods or other modern alternatives.
-   * @param passwordHash - The formatted hash string ($1$alg$hash$salt$).
-   * @returns A PasswordParts object or null if the format is invalid.
-   */
-  dollarSignConnectedStringToAlgorithmHashSalt: (passwordHash: string) => PasswordParts | null;
   /**
    * Splits a JWT into its three base64-encoded string parts (header, payload, signature).
    * @deprecated Use native Buffer methods or other modern alternatives.
@@ -322,28 +268,22 @@ export function jwtVerifySignedToken(jwt: string, publicKey: string): boolean;
 export function jwtGetHeaderPayload(jwt: string): JwtParts | null;
 
 /**
- * Generates a password hash using a random salt and specified algorithm.
+ * Creates an Argon2id PHC password hash with a unique random salt.
  * @param password - The plain-text password to hash.
- * @param secret - A pepper/secret key to combine with the password.
- * @param algorithm - The hashing algorithm to use (e.g., 'sha256').
- * @returns A string containing the formatted hash with metadata ($1$alg$hash$salt$) or null if an error occurs.
+ * @param pepper - A secret pepper containing at least 32 UTF-8 bytes.
+ * @returns The strict Argon2id PHC string.
  */
-export function passwordCreateHashWithRandomSalt(
-  password: string,
-  secret: string,
-  algorithm: string,
-): string | null;
+export function createPasswordHash(password: string, pepper: string): Promise<string>;
 
 /**
- * Generates a password hash using the same algorithm and salt from a previously saved hash.
- * Useful for verifying a password against a stored hash.
+ * Verifies a password against a strict CareCard Argon2id PHC hash.
  * @param password - The plain-text password to verify.
- * @param savedPasswordHash - The full stored hash string (including salt and metadata).
- * @param secret - The pepper/secret key used for hashing.
- * @returns A hash string that should match the saved hash if the password is correct, or null if an error occurs.
+ * @param savedHash - The stored Argon2id PHC hash.
+ * @param pepper - The same secret pepper used when creating the hash.
+ * @returns False for a mismatch or malformed/unsupported saved hash.
  */
-export function passwordCreateHashFromSavedHash(
+export function verifyPassword(
   password: string,
-  savedPasswordHash: string,
-  secret: string,
-): string | null;
+  savedHash: string,
+  pepper: string,
+): Promise<boolean>;

package/index.js

@@ -10,8 +10,8 @@ module.exports = {
   jwtCreateServiceAuthorizationHeader: jwtUtilAuth.createServiceAuthorizationHeader,
   jwtVerifySignedToken: jwtUtilAuth.verifyJwtSignature,
   jwtGetHeaderPayload: jwtUtilAuth.getHeaderPayloadFromJwt,
-  passwordCreateHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
-  passwordCreateHashFromSavedHash: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt,
+  createPasswordHash: pwdUtilAuth.createPasswordHash,
+  verifyPassword: pwdUtilAuth.verifyPassword,
 
   // Deprecated
   /**
@@ -22,14 +22,6 @@ module.exports = {
     verifyJwtSignature: jwtUtilAuth.verifyJwtSignature,
     getHeaderPayloadFromJwt: jwtUtilAuth.getHeaderPayloadFromJwt,
   },
-  /**
-   * @deprecated use direct import of the new functions.
-   */
-  pwdUtilAuth: {
-    createPasswordHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
-    createPasswordHashBasedOnSavedAlgorithmSalt:
-      pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt,
-  },
   /**
    * @deprecated Use native Buffer methods or other modern alternatives.
    */

package/lib/pwdUtilAuth.js

@@ -1,70 +1,113 @@
-const crypto = require('crypto');
+'use strict';
 
-const PASSWORD_HASH_VERSION = '1';
+const { argon2, randomBytes, timingSafeEqual } = require('node:crypto');
+const { promisify } = require('node:util');
 
-// Pattern: Pure Function - creates a digest in which both the pepper and random salt participate.
-function createSaltedPasswordDigest(password, secret, algorithm, salt) {
-  return crypto
-    .createHmac(algorithm, secret)
-    .update(Buffer.from(salt, 'base64'))
-    .update(password)
-    .digest('base64');
-}
+const deriveArgon2Tag = promisify(argon2);
+const ARGON2_ALGORITHM = 'argon2id';
+const ARGON2_VERSION = 19;
+const ARGON2_MEMORY_KIB = 19456;
+const ARGON2_PASSES = 2;
+const ARGON2_PARALLELISM = 1;
+const PASSWORD_SALT_BYTES = 16;
+const PASSWORD_TAG_BYTES = 32;
+const MINIMUM_PEPPER_BYTES = 32;
+const PASSWORD_HASH_PATTERN =
+  /^\$argon2id\$v=19\$m=19456,t=2,p=1\$([A-Za-z0-9+/]{22})\$([A-Za-z0-9+/]{43})$/;
 
-// Pattern: Pure Function - recreates the historical digest for existing stored credentials.
-function createLegacyPasswordDigest(password, secret, algorithm) {
-  return crypto.createHmac(algorithm, secret).update(password).digest('base64');
+// Pattern: Configuration Guard - converts only a sufficiently strong string pepper to bytes.
+function createPepperBuffer(pepper) {
+  if (typeof pepper !== 'string') {
+    throw new TypeError('Password pepper must be a string.');
+  }
+  const pepperBuffer = Buffer.from(pepper, 'utf8');
+  if (pepperBuffer.length < MINIMUM_PEPPER_BYTES) {
+    throw new RangeError('Password pepper must be at least 32 bytes.');
+  }
+  return pepperBuffer;
 }
 
-// Pattern: Serializer - preserves the published password-hash storage contract.
-function serializePasswordHash(algorithmBase64, hashBase64, salt) {
-  return `$${PASSWORD_HASH_VERSION}$${algorithmBase64}$${hashBase64}$${salt}$`;
+// Pattern: Canonicalization - converts well-formed NFC password text to stable UTF-8 bytes.
+function createPasswordBuffer(password) {
+  if (typeof password !== 'string' || !password.isWellFormed()) {
+    throw new TypeError('Password must be a well-formed Unicode string.');
+  }
+  return Buffer.from(password.normalize('NFC'), 'utf8');
 }
 
-// Pattern: Constant-Time Comparison - avoids credential-dependent string comparison timing.
-function passwordHashesMatch(candidateHash, savedPasswordHash) {
-  const candidateBuffer = Buffer.from(candidateHash);
-  const savedBuffer = Buffer.from(savedPasswordHash);
-  return (
-    candidateBuffer.length === savedBuffer.length &&
-    crypto.timingSafeEqual(candidateBuffer, savedBuffer)
-  );
+// Pattern: Serializer Helper - emits canonical unpadded PHC Base64 text.
+function encodePhcBase64(value) {
+  return value.toString('base64').replace(/=+$/, '');
 }
 
-// Pattern: Factory - creates a password hash whose random salt changes the credential digest.
-const createPasswordHashWithRandomSalt = (password, secret, algorithm) => {
-  const salt = crypto.randomBytes(32).toString('base64');
-  const algorithmBase64 = Buffer.from(algorithm).toString('base64');
-  const hashBase64 = createSaltedPasswordDigest(password, secret, algorithm, salt);
-  return serializePasswordHash(algorithmBase64, hashBase64, salt);
-};
-
-// Pattern: Compatibility Verification - verifies salted hashes while retaining existing credentials.
-const createPasswordHashBasedOnSavedAlgorithmSalt = (password, savedPasswordHash, secret) => {
-  if (typeof savedPasswordHash !== 'string') {
+// Pattern: Parser Guard - accepts only canonical PHC Base64 with the required byte length.
+function decodePhcBase64(value, expectedLength) {
+  const decodedValue = Buffer.from(value, 'base64');
+  if (decodedValue.length !== expectedLength || encodePhcBase64(decodedValue) !== value) {
     return null;
   }
+  return decodedValue;
+}
 
-  const splitStringArray = savedPasswordHash.split('$');
-  if (splitStringArray.length !== 6) {
+// Pattern: Strict Parser - accepts only the exact CareCard Argon2id storage contract.
+function parsePasswordHash(savedHash) {
+  if (typeof savedHash !== 'string') {
     return null;
   }
-
-  const version = splitStringArray[1];
-  const algBase64 = splitStringArray[2];
-  const salt = splitStringArray[4];
-  if (version !== PASSWORD_HASH_VERSION || !algBase64 || !salt) {
+  const match = savedHash.match(PASSWORD_HASH_PATTERN);
+  if (!match) {
     return null;
   }
-  const algorithm = Buffer.from(algBase64, 'base64').toString('utf8');
-  const saltedDigest = createSaltedPasswordDigest(password, secret, algorithm, salt);
-  const saltedHash = serializePasswordHash(algBase64, saltedDigest, salt);
-  const legacyDigest = createLegacyPasswordDigest(password, secret, algorithm);
-  const legacyHash = serializePasswordHash(algBase64, legacyDigest, salt);
-  return passwordHashesMatch(legacyHash, savedPasswordHash) ? legacyHash : saltedHash;
-};
+  const salt = decodePhcBase64(match[1], PASSWORD_SALT_BYTES);
+  const tag = decodePhcBase64(match[2], PASSWORD_TAG_BYTES);
+  return salt && tag ? { salt, tag } : null;
+}
+
+// Pattern: Parameter Object - centralizes the fixed Argon2id security profile.
+function createArgon2Parameters(passwordBuffer, salt, pepperBuffer) {
+  return {
+    message: passwordBuffer,
+    nonce: salt,
+    parallelism: ARGON2_PARALLELISM,
+    tagLength: PASSWORD_TAG_BYTES,
+    memory: ARGON2_MEMORY_KIB,
+    passes: ARGON2_PASSES,
+    secret: pepperBuffer,
+  };
+}
+
+// Pattern: Cryptographic Adapter - derives one tag through Node's asynchronous Argon2 boundary.
+async function derivePasswordTag(password, salt, pepperBuffer) {
+  const parameters = createArgon2Parameters(createPasswordBuffer(password), salt, pepperBuffer);
+  return deriveArgon2Tag(ARGON2_ALGORITHM, parameters);
+}
+
+// Pattern: Serializer - records the fixed parameters, salt, and tag in strict PHC form.
+function serializePasswordHash(salt, tag) {
+  const parameters = `m=${ARGON2_MEMORY_KIB},t=${ARGON2_PASSES},p=${ARGON2_PARALLELISM}`;
+  return `$${ARGON2_ALGORITHM}$v=${ARGON2_VERSION}$${parameters}$${encodePhcBase64(salt)}$${encodePhcBase64(tag)}`;
+}
+
+// Pattern: Credential Factory - creates an independently salted Argon2id password hash.
+async function createPasswordHash(password, pepper) {
+  const pepperBuffer = createPepperBuffer(pepper);
+  const salt = randomBytes(PASSWORD_SALT_BYTES);
+  const tag = await derivePasswordTag(password, salt, pepperBuffer);
+  return serializePasswordHash(salt, tag);
+}
+
+// Pattern: Constant-Time Verification - derives and compares a strict Argon2id credential tag.
+async function verifyPassword(password, savedHash, pepper) {
+  const pepperBuffer = createPepperBuffer(pepper);
+  if (typeof password !== 'string' || !password.isWellFormed()) {
+    return false;
+  }
+  const parsedHash = parsePasswordHash(savedHash);
+  if (!parsedHash) {
+    return false;
+  }
+  const candidateTag = await derivePasswordTag(password, parsedHash.salt, pepperBuffer);
+  return timingSafeEqual(candidateTag, parsedHash.tag);
+}
 
-module.exports = {
-  createPasswordHashWithRandomSalt,
-  createPasswordHashBasedOnSavedAlgorithmSalt,
-};
+module.exports = { createPasswordHash, verifyPassword };

package/lib/stringUtilAuth.js

@@ -52,25 +52,6 @@ const base64ToAscii = codedString => {
   return Buffer.from(codedString, 'base64').toString('utf8');
 };
 
-/**
- * Decompose $ connected string and return an object
- * return null if error
- * @deprecated Use native Buffer methods or other modern alternatives.
- * @param passwordHash
- */
-const dollarSignConnectedStringToAlgorithmHashSalt = passwordHash => {
-  const splitStringArray = passwordHash.split('$');
-  if (splitStringArray.length !== 6) {
-    return null;
-  }
-  return {
-    version: splitStringArray[1],
-    alg: splitStringArray[2],
-    hash: splitStringArray[3],
-    salt: splitStringArray[4],
-  };
-};
-
 /**
  * Decompose . connected string and return an object with
  * {header: 'string', payload: 'string', signature: 'string'}
@@ -117,7 +98,6 @@ module.exports = {
   reverseStringUrlSafe,
   asciiToBase64,
   base64ToAscii,
-  dollarSignConnectedStringToAlgorithmHashSalt,
   dotConnectedStringToHeaderPayloadSignature,
   objectToBase64UrlSafeString,
   urlSafeBase64ToObject,

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.23.0",
+  "version": "3.25.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
   "types": "index.d.ts",
+  "engines": {
+    "node": ">=24.20.0 <25"
+  },
   "scripts": {
     "test": "node scripts/runPackageTask.mjs test",
     "test:order": "node --test scripts/testOrder/randomizeTestOrder.test.mjs scripts/testParallel/runIndexedMochaTests.test.mjs scripts/packageTaskRunner.test.mjs scripts/canonicalTestCommand.test.mjs",
@@ -47,8 +50,8 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.23.0",
-    "@carecard/validate": "3.23.0",
+    "@carecard/common-util": "3.25.0",
+    "@carecard/validate": "3.25.0",
     "@types/express": "5.0.6"
   },
   "overrides": {

package/readme.md

@@ -26,7 +26,7 @@ Non-negotiable code organization rule: Functions with the same or equivalent beh
 ## Features
 
 - **JWT Utilities**: Create, verify, and parse JSON Web Tokens with support for EdDSA (Ed25519) and RSA.
-- **Password Utilities**: Secure password hashing using HMAC with random salt and a custom string format for easy storage.
+- **Password Utilities**: Asynchronous Argon2id password hashing through Node.js `crypto`, with a unique random salt and application pepper.
 - **Key Generation**: Generate Ed25519 and RSA key pairs for JWT signing.
 - **Crypto Utilities**: Low-level cryptographic primitives for signing, verification, and hashing.
 - **String Utilities**: Base64 and Base64UrlSafe encoding/decoding, and custom string parsing.
@@ -42,7 +42,11 @@ npm install @carecard/auth-util
 ### JWT Utilities (`jwtUtilAuth`)
 
 ```javascript
-const { jwtCreateSignedToken, jwtGetHeaderPayload, jwtVerifySignedToken } = require('@carecard/auth-util');
+const {
+  jwtCreateSignedToken,
+  jwtGetHeaderPayload,
+  jwtVerifySignedToken,
+} = require('@carecard/auth-util');
 
 const header = { alg: 'EdDSA', typ: 'JWT' };
 const payload = { sub: '1234567890', name: 'John Doe' };
@@ -62,7 +66,10 @@ const { header: decodedHeader, payload: decodedPayload } = jwtGetHeaderPayload(t
 ### Service-To-Service JWT Creation
 
 ```javascript
-const { jwtCreateServiceAuthorizationHeader, jwtCreateServiceToken } = require('@carecard/auth-util');
+const {
+  jwtCreateServiceAuthorizationHeader,
+  jwtCreateServiceToken,
+} = require('@carecard/auth-util');
 
 const token = jwtCreateServiceToken({
   issuer: 'ms-institutions',
@@ -77,23 +84,26 @@ const authorization = jwtCreateServiceAuthorizationHeader({
 });
 ```
 
-### Password Utilities (`pwdUtilAuth`)
+### Password Utilities
 
 ```javascript
-const { pwdUtilAuth } = require('@carecard/auth-util');
+const { createPasswordHash, verifyPassword } = require('@carecard/auth-util');
 
-const password = 'mySecretPassword';
-const secret = 'application-wide-secret';
-const algorithm = 'sha512';
+const password = 'correct horse battery staple';
+const pepper = process.env.MS_AUTH_HASH_KEY; // At least 32 UTF-8 bytes.
 
-// Create a new password hash with a random salt
-const hash = pwdUtilAuth.createPasswordHashWithRandomSalt(password, secret, algorithm);
-// Resulting format: $1$base64(algorithm)$base64(hash)$base64(salt)$
+// Create a strict Argon2id PHC credential with a unique random salt.
+const savedHash = await createPasswordHash(password, pepper);
 
-// Verify a password against a saved hash
-const isCorrect = pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt(password, hash, secret) === hash;
+// Verify through the package boundary. Malformed and legacy credentials return false.
+const isCorrect = await verifyPassword(password, savedHash, pepper);
 ```
 
+Both functions preserve password spaces and normalize well-formed Unicode to
+NFC. Password-policy checks belong to `@carecard/validate`; this package hashes
+and compares the supplied value without enforcing password length or
+composition. Keep the pepper outside persisted credentials and logs.
+
 ### Key Generation
 
 ```javascript
@@ -150,7 +160,7 @@ npm run test:types
 The package is organized into several modules:
 
 - `jwtUtilAuth`: Manages the JWT lifecycle.
-- `pwdUtilAuth`: Handles password hashing and verification.
+- `pwdUtilAuth`: Implements asynchronous Argon2id password hashing and verification behind the direct package exports.
 - `keyGen`: Utility for generating cryptographic keys.
 - `cryptoUtilAuth`: Core cryptographic operations using Node.js `crypto` module.
 - `stringUtilAuth`: String manipulation and format conversions.