@carecard/auth-util 3.24.0 → 3.25.0

package/lib/pwdUtilAuth.js

@@ -15,6 +15,7 @@ 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: 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.');
@@ -26,6 +27,7 @@ function createPepperBuffer(pepper) {
   return pepperBuffer;
 }
 
+// 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.');
@@ -33,10 +35,12 @@ function createPasswordBuffer(password) {
   return Buffer.from(password.normalize('NFC'), 'utf8');
 }
 
+// Pattern: Serializer Helper - emits canonical unpadded PHC Base64 text.
 function encodePhcBase64(value) {
   return value.toString('base64').replace(/=+$/, '');
 }
 
+// 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) {
@@ -45,6 +49,7 @@ function decodePhcBase64(value, expectedLength) {
   return decodedValue;
 }
 
+// Pattern: Strict Parser - accepts only the exact CareCard Argon2id storage contract.
 function parsePasswordHash(savedHash) {
   if (typeof savedHash !== 'string') {
     return null;
@@ -58,6 +63,7 @@ function parsePasswordHash(savedHash) {
   return salt && tag ? { salt, tag } : null;
 }
 
+// Pattern: Parameter Object - centralizes the fixed Argon2id security profile.
 function createArgon2Parameters(passwordBuffer, salt, pepperBuffer) {
   return {
     message: passwordBuffer,
@@ -70,16 +76,19 @@ function createArgon2Parameters(passwordBuffer, salt, 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);
@@ -87,6 +96,7 @@ async function createPasswordHash(password, pepper) {
   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()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
@@ -50,8 +50,8 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.24.0",
-    "@carecard/validate": "3.24.0",
+    "@carecard/common-util": "3.25.0",
+    "@carecard/validate": "3.25.0",
     "@types/express": "5.0.6"
   },
   "overrides": {