@carecard/auth-util 3.0.10 → 3.1.12

package/index.d.ts

@@ -1,174 +1,279 @@
+/**
+ * Utility functions for authentication and authorization in the CareCard ecosystem.
+ */
+
+import {Request} from 'express';
+
 /**
  * Represents the standard JWT header structure.
  */
 export interface JwtHeader {
-  /** The cryptographic algorithm used to secure the JWT. */
-  alg?: string;
-  /** The media type of the JWT. Defaults to 'JWT'. */
-  typ?: string;
-  /** Any other custom header fields. */
-  [key: string]: any;
+    /** The cryptographic algorithm used to secure the JWT. */
+    alg?: string;
+    /** The media type of the JWT. Defaults to 'JWT'. */
+    typ?: string;
+
+    /** Any other custom header fields. */
+    [key: string]: any;
 }
 
 /**
  * Represents the standard JWT payload (claims) structure.
  */
 export interface JwtPayload {
-  /** Issued at time, in seconds since the epoch. */
-  iat?: number;
-  /** Expiration time, in seconds since the epoch. */
-  exp?: number;
-  /** Not before time, in seconds since the epoch. */
-  nbf?: number;
-  /** Authentication time, in seconds since the epoch. */
-  auth_time?: number;
-  /** Any other custom payload fields. */
-  [key: string]: any;
+    /** Issued at time, in seconds since the epoch. */
+    iat?: number;
+    /** Expiration time, in seconds since the epoch. */
+    exp?: number;
+    /** Not before time, in seconds since the epoch. */
+    nbf?: number;
+    /** Authentication time, in seconds since the epoch. */
+    auth_time?: number;
+    /** Subject (usually the client ID). */
+    sub?: string;
+    /** Roles assigned to the user. */
+    roles?: string[];
+
+    /** Any other custom payload fields. */
+    [key: string]: any;
 }
 
 /**
  * Container for the decoded header and payload of a JWT.
  */
 export interface JwtParts {
-  /** Decoded JWT header. */
-  header: JwtHeader;
-  /** Decoded JWT payload. */
-  payload: JwtPayload;
+    /** Decoded JWT header. */
+    header: JwtHeader;
+    /** Decoded JWT payload. */
+    payload: JwtPayload;
+}
+
+/**
+ * Structure of the JWT object attached to the request.
+ */
+export interface JwtRequestObject {
+    header: JwtHeader;
+    payload: JwtPayload;
+    age?: number;
+    jwtClientId: (req?: any) => string | undefined;
+    doesJwtUserHasRole: (role: string) => boolean;
+    isJwtExpired: (jwtValiditySeconds?: number) => boolean;
+    jwtAgeInSeconds: (req?: any) => number;
+}
+
+/**
+ * Structure of the visitor object attached to the request.
+ */
+export interface VisitorRequestObject {
+    header: JwtHeader;
+    payload: JwtPayload;
+    visitorClientId: (req?: any) => string | undefined;
+}
+
+/**
+ * Extended Express Request to include jwt and visitor objects.
+ */
+export interface AuthenticatedRequest extends Request {
+    jwt?: JwtRequestObject | null;
+    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;
+    /** 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.
  */
 export interface KeyPair {
-  /** PEM formatted public key string. */
-  publicKey: string;
-  /** PEM formatted private key string. */
-  privateKey: string;
+    /** PEM formatted public key string. */
+    publicKey: string;
+    /** PEM formatted private key string. */
+    privateKey: string;
 }
 
 /**
  * Utility functions for creating, verifying, and parsing JSON Web Tokens (JWT).
+ * @deprecated use direct import of the new functions.
  */
 export const jwtUtilAuth: {
-  /**
-   * Creates a signed JWT from header and payload objects.
-   * Automatically normalizes header (sets alg/typ) and payload (sets iat/exp/etc. in seconds).
-   * @param headerObject - Header data for the JWT.
-   * @param payloadObject - Payload data for the JWT.
-   * @param privateKey - PEM formatted private key to sign the token.
-   * @returns Signed JWT string or null if an error occurs.
-   */
-  createSignedJwtFromObject: (headerObject: JwtHeader, payloadObject: JwtPayload, privateKey: string) => string | null;
-  /**
-   * Verifies the signature of a JWT using a public key.
-   * @param jwt - The JWT string to verify.
-   * @param publicKey - PEM formatted public key.
-   * @returns True if the signature is valid, false otherwise.
-   */
-  verifyJwtSignature: (jwt: string, publicKey: string) => boolean;
-  /**
-   * Decodes a JWT and returns its header and payload as objects.
-   * Note: This does NOT verify the signature.
-   * @param jwt - The JWT string to parse.
-   * @returns An object containing the header and payload, or null if parsing fails.
-   */
-  getHeaderPayloadFromJwt: (jwt: string) => JwtParts | null;
+    /**
+     * Creates a signed JWT from header and payload objects.
+     * Automatically normalizes header (sets alg/typ) and payload (sets iat/exp/etc. in seconds).
+     * @param headerObject - Header data for the JWT.
+     * @param payloadObject - Payload data for the JWT.
+     * @param privateKey - PEM formatted private key to sign the token.
+     * @returns Signed JWT string or null if an error occurs.
+     */
+    createSignedJwtFromObject: (headerObject: JwtHeader, payloadObject: JwtPayload, privateKey: string) => string | null;
+    /**
+     * Verifies the signature of a JWT using a public key.
+     * @param jwt - The JWT string to verify.
+     * @param publicKey - PEM formatted public key.
+     * @returns True if the signature is valid, false otherwise.
+     */
+    verifyJwtSignature: (jwt: string, publicKey: string) => boolean;
+    /**
+     * Decodes a JWT and returns its header and payload as objects.
+     * Note: This does NOT verify the signature.
+     * @param jwt - The JWT string to parse.
+     * @returns An object containing the header and payload, or null if parsing fails.
+     */
+    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$).
-   */
-  createPasswordHashWithRandomSalt: (password: string, secret: string, algorithm: string) => 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.
-   * @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.
-   */
-  createPasswordHashBasedOnSavedAlgorithmSalt: (password: string, savedPasswordHash: string, secret: string) => string;
+    /**
+     * 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.
+ */
+export const stringUtilAuth: {
+    /**
+     * Converts a base64 string to be URL-safe (replaces + with -, / with _, and removes =).
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     * @param urlUnsafeString - The string to convert.
+     * @returns URL-safe string.
+     */
+    makeStringUrlSafe: (urlUnsafeString?: string) => string;
+    /**
+     * Reverses URL-safe conversion and restores standard base64 characters and padding.
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     * @param urlSafeString - The URL-safe string to restore.
+     * @returns Standard base64 string.
+     */
+    reverseStringUrlSafe: (urlSafeString?: string) => string;
+    /**
+     * Encodes a plain-text string to base64.
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     * @param unCodedString - Plain-text string.
+     * @returns Base64 encoded string.
+     */
+    asciiToBase64: (unCodedString: string) => string;
+    /**
+     * Decodes a base64 string to UTF-8 plain-text.
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     * @param codedString - Base64 encoded string.
+     * @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.
+     * @param jwt - The full JWT string.
+     * @returns An object with the three raw parts, or null if the format is invalid.
+     */
+    dotConnectedStringToHeaderPayloadSignature: (jwt: string) => {
+        header: string,
+        payload: string,
+        signature: string
+    } | null;
+    /**
+     * Serializes an object into a URL-safe base64 string.
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     * @param object - The object to serialize.
+     * @returns URL-safe base64 string.
+     */
+    objectToBase64UrlSafeString: (object: any) => string;
+    /**
+     * Parses a URL-safe base64 string into an object.
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     * @param urlSafeBase64String - URL-safe base64 string.
+     * @returns The parsed object.
+     */
+    urlSafeBase64ToObject: (urlSafeBase64String: string) => any;
+};
+
+
 /**
  * Generates a public/private key pair for JWT signing.
  * @param algorithm - The algorithm to use ('ed25519' or 'rsa'). Defaults to 'ed25519'.
  * @returns A KeyPair object containing PEM formatted keys.
  */
-export const createKeys: (algorithm?: 'ed25519' | 'rsa' | string) => KeyPair;
+export function generateKeyPair(algorithm?: 'ed25519' | 'rsa' | string): KeyPair;
 
 /**
- * Utility functions for string manipulation, base64 encoding, and parsing auth-related strings.
+ * Creates a signed JWT from header and payload objects.
+ * Automatically normalizes header (sets alg/typ) and payload (sets iat/exp/etc. in seconds).
+ * @param headerObject - Header data for the JWT.
+ * @param payloadObject - Payload data for the JWT.
+ * @param privateKey - PEM formatted private key to sign the token.
+ * @returns Signed JWT string or null if an error occurs.
  */
-export const stringUtilAuth: {
-  /**
-   * Converts a base64 string to be URL-safe (replaces + with -, / with _, and removes =).
-   * @param urlUnsafeString - The string to convert.
-   * @returns URL-safe string.
-   */
-  makeStringUrlSafe: (urlUnsafeString?: string) => string;
-  /**
-   * Reverses URL-safe conversion and restores standard base64 characters and padding.
-   * @param urlSafeString - The URL-safe string to restore.
-   * @returns Standard base64 string.
-   */
-  reverseStringUrlSafe: (urlSafeString?: string) => string;
-  /**
-   * Encodes a plain-text string to base64.
-   * @param unCodedString - Plain-text string.
-   * @returns Base64 encoded string.
-   */
-  asciiToBase64: (unCodedString: string) => string;
-  /**
-   * Decodes a base64 string to UTF-8 plain-text.
-   * @param codedString - Base64 encoded string.
-   * @returns Decoded plain-text string.
-   */
-  base64ToAscii: (codedString: string) => string;
-  /**
-   * Parses a stored password hash string into its constituent parts.
-   * @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).
-   * @param jwt - The full JWT string.
-   * @returns An object with the three raw parts, or null if the format is invalid.
-   */
-  dotConnectedStringToHeaderPayloadSignature: (jwt: string) => { header: string, payload: string, signature: string } | null;
-  /**
-   * Serializes an object into a URL-safe base64 string.
-   * @param object - The object to serialize.
-   * @returns URL-safe base64 string.
-   */
-  objectToBase64UrlSafeString: (object: any) => string;
-  /**
-   * Parses a URL-safe base64 string into an object.
-   * @param urlSafeBase64String - URL-safe base64 string.
-   * @returns The parsed object.
-   */
-  urlSafeBase64ToObject: (urlSafeBase64String: string) => any;
-};
+export function jwtCreateSignedToken(headerObject: JwtHeader, payloadObject: JwtPayload, privateKey: string): string | null;
+
+/**
+ * Verifies the signature of a JWT using a public key.
+ * @param jwt - The JWT string to verify.
+ * @param publicKey - PEM formatted public key.
+ * @returns True if the signature is valid, false otherwise.
+ */
+export function jwtVerifySignedToken(jwt: string, publicKey: string): boolean;
+
+/**
+ * Decodes a JWT and returns its header and payload as objects.
+ * Note: This does NOT verify the signature.
+ * @param jwt - The JWT string to parse.
+ * @returns An object containing the header and payload, or null if parsing fails.
+ */
+export function jwtGetHeaderPayload(jwt: string): JwtParts | null;
+
+/**
+ * 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.
+ */
+export function passwordCreateHashWithRandomSalt(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.
+ */
+export function passwordCreateHashFromSavedHash(password: string, savedPasswordHash: string, secret: string): string | null;

package/index.js

@@ -1,21 +1,35 @@
-const pwdUtilAuth = require( './lib/pwdUtilAuth' );
-const jwtUtilAuth = require( './lib/jwtUtilAuth' );
-const keyGen = require( './lib/keyGen' );
+const pwdUtilAuth = require('./lib/pwdUtilAuth');
+const jwtUtilAuth = require('./lib/jwtUtilAuth');
+const keyGen = require('./lib/keyGen');
 
 module.exports = {
+    // New
+    generateKeyPair: keyGen.generateKeyPair,
+    jwtCreateSignedToken: jwtUtilAuth.createSignedJwtFromObject,
+    jwtVerifySignedToken: jwtUtilAuth.verifyJwtSignature,
+    jwtGetHeaderPayload: jwtUtilAuth.getHeaderPayloadFromJwt,
+    passwordCreateHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
+    passwordCreateHashFromSavedHash: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt,
+
+    // Deprecated
+    /**
+     * @deprecated use direct import of the new functions.
+     */
     jwtUtilAuth: {
         createSignedJwtFromObject: jwtUtilAuth.createSignedJwtFromObject,
         verifyJwtSignature: jwtUtilAuth.verifyJwtSignature,
         getHeaderPayloadFromJwt: jwtUtilAuth.getHeaderPayloadFromJwt
     },
-
+    /**
+     * @deprecated use direct import of the new functions.
+     */
     pwdUtilAuth: {
         createPasswordHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
         createPasswordHashBasedOnSavedAlgorithmSalt: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt
     },
-
-    createKeys: keyGen.generateKeyPair,
-
-    stringUtilAuth: require( './lib/stringUtilAuth' ),
+    /**
+     * @deprecated Use native Buffer methods or other modern alternatives.
+     */
+    stringUtilAuth: require('./lib/stringUtilAuth'),
 };
 

package/lib/jwtUtilAuth.js

@@ -1,35 +1,6 @@
-const stringUtilAuth = require( './stringUtilAuth' );
-const cryptoUtilAuth = require( './cryptoUtilAuth' );
+const crypto = require( 'crypto' );
 
-/**
- * User supplied header, payload and signature create jwt.
- * @returns {string|null}
- * @param headerBase64
- * @param payloadBase64
- * @param signatureBase64
- */
-const _assembleJwt = ( headerBase64, payloadBase64, signatureBase64 ) => {
-    return headerBase64 + "." + payloadBase64 + "." + signatureBase64;
-};
-
-/**
- * Normalizes jwt header
- * @param headerObject
- * @returns {{alg: string, typ: string}}
- */
-const normalizeHeader = ( headerObject ) => {
-    const header = { ...headerObject };
-    header.alg = header.alg || 'EdDSA';
-    header.typ = 'JWT';
-    return header;
-};
-
-/**
- * Normalizes jwt payload time-related fields
- * @param payloadObject
- * @returns {*}
- */
-const normalizePayload = ( payloadObject ) => {
+const _normalizePayload = ( payloadObject ) => {
     const payload = { ...payloadObject };
     const now = Math.floor( Date.now() / 1000 );
     const fieldsToNormalize = [ 'iat', 'exp', 'nbf', 'auth_time' ];
@@ -46,22 +17,39 @@ const normalizePayload = ( payloadObject ) => {
     } );
 
     if ( !payload.exp ) {
-        // Default 1 hour expiration if not provided
         payload.exp = payload.iat + 3600;
-    } else if ( payload.exp > msThreshold ) {
-        payload.exp = Math.floor( payload.exp / 1000 );
     }
-
     return payload;
 };
 
-/**
- * User supplied header, payload and signature create jwt.
- * @returns {{payload: *, signature: *, header: *}}
- * @param jwt
- */
-const _splitJwtInToHeaderPayloadSignature = ( jwt ) => {
-    return stringUtilAuth.dotConnectedStringToHeaderPayloadSignature( jwt );
+const _encode = ( obj ) => {
+    return Buffer.from( JSON.stringify( obj ) ).toString( 'base64url' );
+};
+
+const _decode = ( str ) => {
+    return JSON.parse( Buffer.from( str, 'base64url' ).toString( 'utf8' ) );
+};
+
+const _sign = ( token, alg, privateKey ) => {
+    if ( alg === 'EdDSA' || alg === 'Ed25519' ) {
+        return crypto.sign( null, Buffer.from( token ), privateKey ).toString( 'base64url' );
+    }
+
+    const sign = crypto.createSign( alg );
+    sign.write( token );
+    sign.end();
+    return sign.sign( privateKey, 'base64url' );
+};
+
+const _verify = ( token, signature, alg, publicKey ) => {
+    if ( alg === 'EdDSA' || alg === 'Ed25519' ) {
+        return crypto.verify( null, Buffer.from( token ), publicKey, Buffer.from( signature, 'base64url' ) );
+    }
+
+    const verify = crypto.createVerify( alg );
+    verify.update( token );
+    verify.end();
+    return verify.verify( publicKey, signature, 'base64url' );
 };
 
 /**
@@ -75,17 +63,19 @@ const createSignedJwtFromObject = ( headerObject, payloadObject, privateKey ) =>
     try {
         if ( !privateKey ) return null;
 
-        const header = normalizeHeader( headerObject );
-        const payload = normalizePayload( payloadObject );
+        const header = { ...headerObject };
+        header.alg = header.alg || 'EdDSA';
+        header.typ = 'JWT';
 
-        const headerBase64UrlSafe = stringUtilAuth.objectToBase64UrlSafeString( header );
-        const payloadBase64UrlSafe = stringUtilAuth.objectToBase64UrlSafeString( payload );
+        const payload = _normalizePayload( payloadObject );
+
+        const headerBase64UrlSafe = _encode( header );
+        const payloadBase64UrlSafe = _encode( payload );
         const token = headerBase64UrlSafe + "." + payloadBase64UrlSafe;
 
-        const signature = cryptoUtilAuth.createBase64SignatureOfToken( token, privateKey, header.alg );
-        const urlSafeSignature = stringUtilAuth.makeStringUrlSafe( signature );
+        const signature = _sign( token, header.alg, privateKey );
 
-        return _assembleJwt( headerBase64UrlSafe, payloadBase64UrlSafe, urlSafeSignature );
+        return token + "." + signature;
     } catch ( error ) {
         return null;
     }
@@ -100,13 +90,14 @@ const createSignedJwtFromObject = ( headerObject, payloadObject, privateKey ) =>
 const verifyJwtSignature = ( jwt, publicKey ) => {
     try {
         if ( !jwt || !publicKey ) return false;
-        const parts = _splitJwtInToHeaderPayloadSignature( jwt );
-        if ( !parts ) return false;
-        const { header, signature } = parts;
-        const token = header + "." + parts.payload;
-        const headerObject = stringUtilAuth.urlSafeBase64ToObject( header );
-        const signatureBase64 = stringUtilAuth.reverseStringUrlSafe( signature );
-        return cryptoUtilAuth.verifyBase64SignatureOfToken( token, signatureBase64, publicKey, headerObject.alg )
+        const splitJWT = jwt.split( '.' );
+        if ( splitJWT.length !== 3 ) return false;
+
+        const [ header, payload, signature ] = splitJWT;
+        const token = header + "." + payload;
+        const headerObject = _decode( header );
+
+        return _verify( token, signature, headerObject.alg, publicKey );
     } catch ( error ) {
         return false;
     }
@@ -115,28 +106,30 @@ const verifyJwtSignature = ( jwt, publicKey ) => {
 /**
  * Returns header and payload object for jwt.
  * @param jwt
- * @return {{payload: any, header: any}}
+ * @return {{payload: *, header: *}|null}
  */
 const getHeaderPayloadFromJwt = jwt => {
     try {
-        const parts = _splitJwtInToHeaderPayloadSignature( jwt );
-        if ( !parts ) return null;
-        const { header, payload } = parts;
-        let headerObject = stringUtilAuth.urlSafeBase64ToObject( header );
-        let payloadObject = stringUtilAuth.urlSafeBase64ToObject( payload );
+        if ( typeof jwt !== 'string' ) return null;
+        const splitJWT = jwt.split( '.' );
+        if ( splitJWT.length !== 3 ) return null;
+
+        const headerObject = _decode( splitJWT[ 0 ] );
+        const payloadObject = _decode( splitJWT[ 1 ] );
+
         return { header: headerObject, payload: payloadObject }
     } catch ( e ) {
         return null;
     }
 };
 
-
 module.exports = {
-    _assembleJwt,
-    _splitJwtInToHeaderPayloadSignature,
-    normalizeHeader,
-    normalizePayload,
     createSignedJwtFromObject,
     verifyJwtSignature,
-    getHeaderPayloadFromJwt
+    getHeaderPayloadFromJwt,
+    _normalizePayload,
+    _encode,
+    _decode,
+    _sign,
+    _verify
 };

package/lib/pwdUtilAuth.js

@@ -1,40 +1,4 @@
-const cryptoUtilAuth = require( './cryptoUtilAuth' );
-const stringUtilAuth = require( './stringUtilAuth' );
-
-/**
- * Just assemble password together
- * @param algorithmBase64
- * @param hashBase64
- * @param saltBase64
- * @return {string}
- */
-const _assemblePasswordHash = ( algorithmBase64, hashBase64, saltBase64 ) => {
-    return "$1$" + algorithmBase64 + "$" + hashBase64 + "$" + saltBase64 + "$";
-};
-
-/**
- * Break password into its parts does not reverse base64 encoding.
- * @param passwordHashStored
- * @return {{salt: *, version: *, alg: *, hash: *}}
- */
-const _disassemblePasswordHash = passwordHashStored => {
-    return stringUtilAuth.dollarSignConnectedStringToAlgorithmHashSalt( passwordHashStored );
-};
-
-
-/**
- * Creates password hash ready to be saved in database.
- * @param password
- * @param secret
- * @param salt
- * @param algorithm
- * @return {string}
- */
-const _createPasswordHash = ( password, secret, salt, algorithm ) => {
-    const algorithmBase64 = stringUtilAuth.asciiToBase64( algorithm );
-    const hashBase64 = cryptoUtilAuth.createHmacBase64( password, secret, algorithm );
-    return _assemblePasswordHash( algorithmBase64, hashBase64, salt );
-};
+const crypto = require( 'crypto' );
 
 /**
  * Automatically adds random salt.
@@ -44,8 +8,14 @@ const _createPasswordHash = ( password, secret, salt, algorithm ) => {
  * @return {string}
  */
 const createPasswordHashWithRandomSalt = ( password, secret, algorithm ) => {
-    const salt = cryptoUtilAuth.createSaltBase64();
-    return _createPasswordHash( password, secret, salt, algorithm );
+    try {
+        const salt = crypto.randomBytes( 32 ).toString( 'base64' );
+        const algorithmBase64 = Buffer.from( algorithm ).toString( 'base64' );
+        const hashBase64 = crypto.createHmac( algorithm, secret ).update( password ).digest( 'base64' );
+        return "$1$" + algorithmBase64 + "$" + hashBase64 + "$" + salt + "$";
+    } catch ( e ) {
+        return null;
+    }
 };
 
 /**
@@ -56,16 +26,22 @@ const createPasswordHashWithRandomSalt = ( password, secret, algorithm ) => {
  * @return {string}
  */
 const createPasswordHashBasedOnSavedAlgorithmSalt = ( password, savedPasswordHash, secret ) => {
-    const { version, alg, hash, salt } = _disassemblePasswordHash( savedPasswordHash );
-    const algorithm = stringUtilAuth.base64ToAscii( alg );
-    return _createPasswordHash( password, secret, salt, algorithm );
+    try {
+        const splitStringArray = savedPasswordHash.split( '$' );
+        if ( splitStringArray.length !== 6 ) return null;
+
+        const algBase64 = splitStringArray[ 2 ];
+        const salt = splitStringArray[ 4 ];
+        const algorithm = Buffer.from( algBase64, 'base64' ).toString( 'utf8' );
+
+        const hashBase64 = crypto.createHmac( algorithm, secret ).update( password ).digest( 'base64' );
+        return "$1$" + algBase64 + "$" + hashBase64 + "$" + salt + "$";
+    } catch ( e ) {
+        return null;
+    }
 };
 
-
 module.exports = {
-    _assemblePasswordHash,
-    _disassemblePasswordHash,
-    _createPasswordHash,
     createPasswordHashWithRandomSalt,
     createPasswordHashBasedOnSavedAlgorithmSalt
 }

package/lib/stringUtilAuth.js

@@ -6,6 +6,7 @@
 
 /**
  * Adjusts padding of base64String
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @param base64String
  * @return {*}
  */
@@ -15,6 +16,7 @@ const adjustBase64Padding = base64String => {
 
 /**
  * Removes /, + and = from the string
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @returns {string}
  */
 const makeStringUrlSafe = ( urlUnsafeString = '' ) => {
@@ -26,6 +28,7 @@ const makeStringUrlSafe = ( urlUnsafeString = '' ) => {
 
 /**
  * Put back /, + and = into the string
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @returns {string}
  */
 const reverseStringUrlSafe = ( urlSafeString = '' ) => {
@@ -37,6 +40,7 @@ const reverseStringUrlSafe = ( urlSafeString = '' ) => {
 
 /**
  * Encode string to base64 string
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @param unCodedString
  * @returns {string}
  */
@@ -45,6 +49,7 @@ const asciiToBase64 = ( unCodedString ) => {
 }
 
 /** Decode string from base64
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @param codedString
  * @returns {string}
  */
@@ -55,6 +60,7 @@ const base64ToAscii = ( codedString ) => {
 /**
  * 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 ) => {
@@ -72,6 +78,7 @@ const dollarSignConnectedStringToAlgorithmHashSalt = ( passwordHash ) => {
  * Decompose . connected string and return an object with
  * {header: 'string', payload: 'string', signature: 'string'}
  * return null if error
+ * @deprecated Use native Buffer methods or other modern alternatives.
  */
 const dotConnectedStringToHeaderPayloadSignature = ( jwt ) => {
     if ( typeof jwt !== 'string' ) return null;
@@ -87,6 +94,7 @@ const dotConnectedStringToHeaderPayloadSignature = ( jwt ) => {
 
 /**
  * Turns object into url safe string
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @param object
  * @return {string}
  */
@@ -96,6 +104,7 @@ const objectToBase64UrlSafeString = object => {
 
 /**
  * Turns base64 into object
+ * @deprecated Use native Buffer methods or other modern alternatives.
  * @param urlSafeBase64String
  * @return {any}
  */

package/package.json

@@ -1,26 +1,36 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.0.10",
+  "version": "3.1.12",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
     "test": "export NODE_ENV=test && mocha --recursive",
-    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts"
+    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts",
+    "test:coverage": "tsc --noEmit && export NODE_ENV=test && nyc mocha --recursive -r ts-node/register 'test/**/*.{js,ts}'",
+    "prepare": "husky"
   },
   "keywords": [
     "auth",
     "utility",
-    "cryptology"
+    "cryptology",
+    "jwt"
   ],
   "author": "CareCard team",
   "license": "ISC",
   "devDependencies": {
+    "@types/express": "5.0.6",
     "@types/mocha": "10.0.10",
     "@types/node": "25.5.0",
+    "husky": "^9.1.7",
     "mocha": "11.7.5",
+    "nyc": "^18.0.0",
     "ts-node": "10.9.2",
     "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@carecard/common-util": "3.1.11",
+    "@carecard/validate": "3.0.11"
   }
 }

package/readme.md

@@ -1,51 +1,108 @@
-# Auth utilities class
+# @carecard/auth-util
 
-## Main Functionality
+![Tests Passing](https://github.com/CareCard-ca/pkg-auth-util/actions/workflows/ci.yml/badge.svg)
+![Coverage](https://img.shields.io/badge/Coverage-97%25-green)
 
-This is a collection of utility functions for use in authentication
+Utility package for authentication and authorization in the CareCard ecosystem.
 
-### Main functions
+## Features
 
-```js
-const { jwtUtilAuth, pwdUtilAuth } = require( '@chatpta/auth-util' );
+- **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.
+- **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.
+
+## Installation
+
+```bash
+npm install @carecard/auth-util
+```
+
+## Usage
+
+### JWT Utilities (`jwtUtilAuth`)
+
+```javascript
+const { jwtUtilAuth } = require('@carecard/auth-util');
+
+const header = { alg: 'EdDSA', typ: 'JWT' };
+const payload = { sub: '1234567890', name: 'John Doe' };
+const privateKey = '...'; // Your private PEM key
+
+// Create a signed JWT
+const token = jwtUtilAuth.createSignedJwtFromObject(header, payload, privateKey);
+
+// Verify a JWT signature
+const publicKey = '...'; // Your public PEM key
+const isValid = jwtUtilAuth.verifyJwtSignature(token, publicKey);
+
+// Get header and payload from a JWT
+const { header: decodedHeader, payload: decodedPayload } = jwtUtilAuth.getHeaderPayloadFromJwt(token);
 ```
 
-Create jwt
+### Password Utilities (`pwdUtilAuth`)
+
+```javascript
+const { pwdUtilAuth } = require('@carecard/auth-util');
 
-```js
-const headerObject = {
-    alg: "SHA256", // Mendatory acceptable algorithm
-    ...
-};
+const password = 'mySecretPassword';
+const secret = 'application-wide-secret';
+const algorithm = 'sha512';
 
-const payloadObject = {
-    ...
-};
+// 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)$
 
-const jwt = jwtUtilAuth.createSignedJwtFromObject( headerObject, payloadObject, privateKey );
+// Verify a password against a saved hash
+const isCorrect = (pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt(password, hash, secret) === hash);
 ```
 
-Verify jwt signature returns ```true``` or ```false```
+### Key Generation
+
+```javascript
+const { generateKeyPair } = require('@carecard/auth-util');
 
-```js
-const isVerified = jwtUtilAuth.verifyJwtSignature( jwt, publicKey );
+// Generate Ed25519 keys (default)
+const { publicKey, privateKey } = generateKeyPair();
+
+// Generate RSA keys
+const rsaKeys = generateKeyPair('rsa');
 ```
 
-Get header and payload object from jwt.
+### String Utilities (`stringUtilAuth`)
+
+```javascript
+const { stringUtilAuth } = require('@carecard/auth-util');
 
-```js
-const { header, payload } = jwtUtilAuth.getHeaderPayloadFromJwt( jwt );
+const base64 = stringUtilAuth.asciiToBase64('Hello World');
+const original = stringUtilAuth.base64ToAscii(base64);
+
+const urlSafe = stringUtilAuth.makeStringUrlSafe('a+b/c==');
+// Result: a-b_c
 ```
 
-Create password hash to save in database
+## Testing
+
+Run tests using:
 
-```js
-const hash = pwdUtilAuth.createPasswordHashWithRandomSalt( password, secret, algorithm );
+```bash
+npm test
 ```
 
-Create another password hash based on saved hash to compare.
+To run type tests:
 
-```js
-const hashForLogin = pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt( passwordForLogin, savedPasswordHash, secret );
+```bash
+npm run test:types
 ```
 
+## Architecture
+
+The package is organized into several modules:
+- `jwtUtilAuth`: Manages the JWT lifecycle.
+- `pwdUtilAuth`: Handles password hashing and verification.
+- `keyGen`: Utility for generating cryptographic keys.
+- `cryptoUtilAuth`: Core cryptographic operations using Node.js `crypto` module.
+- `stringUtilAuth`: String manipulation and format conversions.
+
+All modules are exported through the main `index.js`.

package/lib/cryptoUtilAuth.js

@@ -1,71 +0,0 @@
-const crypto = require( "crypto" );
-
-
-/**
- * Signs a token returns signature string
- * @param token
- * @param privateKey
- * @param signingAlgorithm
- * @returns {string}
- */
-const createBase64SignatureOfToken = function ( token = '', privateKey, signingAlgorithm = 'EdDSA' ) {
-    if ( signingAlgorithm === 'EdDSA' || signingAlgorithm === 'Ed25519' ) {
-        return crypto.sign( null, Buffer.from( token ), privateKey ).toString( 'base64' );
-    }
-
-    const sign = crypto.createSign( signingAlgorithm );
-    sign.write( token );
-    sign.end();
-    return sign.sign( privateKey, 'base64' );
-};
-
-/**
- * Verifies the signature returns true or false
- * @param token
- * @param signature
- * @param publicKey
- * @param signingAlgorithm
- * @returns {boolean}
- */
-const verifyBase64SignatureOfToken = function ( token = '', signature, publicKey, signingAlgorithm = 'EdDSA' ) {
-    try {
-        if ( signingAlgorithm === 'EdDSA' || signingAlgorithm === 'Ed25519' ) {
-            return crypto.verify( null, Buffer.from( token ), publicKey, Buffer.from( signature, 'base64' ) );
-        }
-
-        const verify = crypto.createVerify( signingAlgorithm );
-        verify.update( token );
-        verify.end();
-        return verify.verify( publicKey, signature, 'base64' );
-    } catch ( e ) {
-        return false;
-    }
-};
-
-/**
- * Creates the hash of given string
- * @param string
- * @param secret
- * @param algorithm
- * @returns {string}
- */
-const createHmacBase64 = function ( string = '', secret, algorithm ) {
-    const hmac = crypto.createHmac( algorithm, secret );
-    hmac.update( string );
-    return hmac.digest( 'base64' );
-};
-
-/**
- * Create random salt
- * @returns {string}
- */
-const createSaltBase64 = ( size = 32 ) => {
-    return crypto.randomBytes( size ).toString( 'base64' );
-};
-
-module.exports = {
-    createBase64SignatureOfToken,
-    verifyBase64SignatureOfToken,
-    createHmacBase64,
-    createSaltBase64
-};