@carecard/auth-util 3.1.13 → 3.1.15

package/readme.md

@@ -24,21 +24,39 @@ npm install @carecard/auth-util
 ### JWT Utilities (`jwtUtilAuth`)
 
 ```javascript
-const { jwtUtilAuth } = 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' };
 const privateKey = '...'; // Your private PEM key
 
 // Create a signed JWT
-const token = jwtUtilAuth.createSignedJwtFromObject(header, payload, privateKey);
+const token = jwtCreateSignedToken(header, payload, privateKey);
 
 // Verify a JWT signature
 const publicKey = '...'; // Your public PEM key
-const isValid = jwtUtilAuth.verifyJwtSignature(token, publicKey);
+const isValid = jwtVerifySignedToken(token, publicKey);
 
 // Get header and payload from a JWT
-const { header: decodedHeader, payload: decodedPayload } = jwtUtilAuth.getHeaderPayloadFromJwt(token);
+const { header: decodedHeader, payload: decodedPayload } = jwtGetHeaderPayload(token);
+```
+
+### Service-To-Service JWT Creation
+
+```javascript
+const { jwtCreateServiceAuthorizationHeader, jwtCreateServiceToken } = require('@carecard/auth-util');
+
+const token = jwtCreateServiceToken({
+  issuer: 'ms-institutions',
+  audience: 'ms-auth',
+  privateKey: institutionsPrivateKey,
+});
+
+const authorization = jwtCreateServiceAuthorizationHeader({
+  issuer: 'ms-institutions',
+  audience: 'ms-auth',
+  privateKey: institutionsPrivateKey,
+});
 ```
 
 ### Password Utilities (`pwdUtilAuth`)
@@ -55,7 +73,7 @@ const hash = pwdUtilAuth.createPasswordHashWithRandomSalt(password, secret, algo
 // Resulting format: $1$base64(algorithm)$base64(hash)$base64(salt)$
 
 // Verify a password against a saved hash
-const isCorrect = (pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt(password, hash, secret) === hash);
+const isCorrect = pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt(password, hash, secret) === hash;
 ```
 
 ### Key Generation
@@ -99,6 +117,7 @@ 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.

package/scripts/rename-cjs.js

@@ -0,0 +1,13 @@
+import fs from 'fs';
+import path from 'path';
+
+const dir = './dist/cjs';
+
+for (const file of fs.readdirSync(dir)) {
+    if (file.endsWith('.js')) {
+        fs.renameSync(
+            path.join(dir, file),
+            path.join(dir, file.replace('.js', '.cjs'))
+        );
+    }
+}

package/src/cryptoUtilAuth.ts

@@ -0,0 +1,111 @@
+import * as crypto from 'crypto';
+
+/**
+ * Signs a token returns signature string
+ * @param token
+ * @param privateKey
+ * @param signingAlgorithm
+ * @returns {string}
+ */
+export const createBase64SignatureOfToken = function (
+  token: string = '',
+  privateKey: string,
+  signingAlgorithm: string,
+): string {
+  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}
+ */
+export const verifyBase64SignatureOfToken = function (
+  token: string = '',
+  signature: string,
+  publicKey: string,
+  signingAlgorithm: string,
+): boolean {
+  const verify = crypto.createVerify(signingAlgorithm);
+  verify.update(token);
+  verify.end();
+  return verify.verify(publicKey, signature, 'base64');
+};
+
+/**
+ * Creates the hash of given string
+ * @param string
+ * @param secret
+ * @param algorithm
+ * @returns {string}
+ */
+export const createHmacBase64 = function (
+  string: string = '',
+  secret: string,
+  algorithm: string,
+): string {
+  const hmac = crypto.createHmac(algorithm, secret);
+  hmac.update(string);
+  return hmac.digest('base64');
+};
+
+/**
+ * Create random salt
+ * @returns {string}
+ */
+export const createSaltBase64 = (): string => {
+  const date = new Date().valueOf();
+  const hmac = crypto.createHmac('SHA256', date.toString());
+  hmac.update(date.toString());
+  return hmac.digest('base64');
+};
+
+/**
+ * Encrypt given string
+ * @param string
+ * @param salt
+ * @param secret
+ * @param algorithm
+ * @returns {string}
+ */
+export const encryptStringAsciiToBase64 = (
+  string: string,
+  salt: string,
+  secret: string,
+  algorithm: string,
+): string => {
+  const key = crypto.scryptSync(secret, salt, 24);
+  const iv = Buffer.alloc(16, 0);
+  const cipher = crypto.createCipheriv(algorithm, key, iv);
+  let encrypted = cipher.update(string, 'ascii', 'base64');
+  encrypted += cipher.final('base64');
+  return encrypted;
+};
+
+/**
+ * Decrypts given string
+ * @param encryptedString
+ * @param salt
+ * @param secret
+ * @param algorithm
+ * @returns {string}
+ */
+export const decryptStringBase64ToAscii = (
+  encryptedString: string,
+  salt: string,
+  secret: string,
+  algorithm: string,
+): string => {
+  const key = crypto.scryptSync(secret, salt, 24);
+  const iv = Buffer.alloc(16, 0);
+  const decipher = crypto.createDecipheriv(algorithm, key, iv);
+  let decrypted = decipher.update(encryptedString, 'base64', 'ascii');
+  decrypted += decipher.final('ascii');
+  return decrypted;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './cryptoUtilAuth';
+export * from './jwtUtilAuth';
+export * from './keyGen';
+export * from './pwdUtilAuth';
+export * from './strEncryptUtil';
+export * from './stringUtilAuth';

package/src/jwtUtilAuth.ts

@@ -0,0 +1,85 @@
+import * as stringUtilAuth from './stringUtilAuth';
+import * as cryptoUtilAuth from './cryptoUtilAuth';
+
+/**
+ * User supplied header, payload and signature create jwt.
+ * @returns {string|null}
+ * @param headerBase64
+ * @param payloadBase64
+ * @param signatureBase64
+ */
+export const _assembleJwt = (
+  headerBase64: string,
+  payloadBase64: string,
+  signatureBase64: string,
+): string => {
+  return headerBase64 + '.' + payloadBase64 + '.' + signatureBase64;
+};
+
+/**
+ * User supplied header, payload and signature create jwt.
+ * @returns {{payload: *, signature: *, header: *}}
+ * @param jwt
+ */
+export const _splitJwtInToHeaderPayloadSignature = (jwt: string): any => {
+  return stringUtilAuth.dotConnectedStringToHeaderPayloadSignature(jwt);
+};
+
+/**
+ * Creates Url safe jwt
+ * @param headerObject
+ * @param payloadObject
+ * @param privateKey
+ * @return {string|null}
+ */
+export const createSignedJwtFromObject = (
+  headerObject: any,
+  payloadObject: any,
+  privateKey: string,
+): any => {
+  try {
+    const algorithm = headerObject.alg;
+    const headerBase64UrlSafe = stringUtilAuth.objectToBase64UrlSafeString(headerObject);
+    const payloadBase64UrlSafe = stringUtilAuth.objectToBase64UrlSafeString(payloadObject);
+    const token = headerBase64UrlSafe + '.' + payloadBase64UrlSafe;
+    const signature = cryptoUtilAuth.createBase64SignatureOfToken(token, privateKey, algorithm);
+    const urlSafeSignature = stringUtilAuth.makeStringUrlSafe(signature);
+    return _assembleJwt(headerBase64UrlSafe, payloadBase64UrlSafe, urlSafeSignature);
+  } catch (error) {
+    return null;
+  }
+};
+
+/**
+ * Verify signature of jwt
+ * @param jwt
+ * @param publicKey
+ * @return {boolean}
+ */
+export const verifyJwtSignature = (jwt: string, publicKey: string): boolean => {
+  try {
+    const { header, payload, signature } = _splitJwtInToHeaderPayloadSignature(jwt);
+    const token = header + '.' + payload;
+    const headerObject = stringUtilAuth.urlSafeBase64ToObject(header);
+    return cryptoUtilAuth.verifyBase64SignatureOfToken(
+      token,
+      signature,
+      publicKey,
+      headerObject.alg,
+    );
+  } catch (error) {
+    return false;
+  }
+};
+
+/**
+ * Returns header and payload object for jwt.
+ * @param jwt
+ * @return {{payload: any, header: any}}
+ */
+export const getHeaderPayloadFromJwt = (jwt: string): any => {
+  const { header, payload } = _splitJwtInToHeaderPayloadSignature(jwt);
+  let headerAscii = stringUtilAuth.base64ToAscii(header);
+  let payloadAscii = stringUtilAuth.base64ToAscii(payload);
+  return { header: JSON.parse(headerAscii), payload: JSON.parse(payloadAscii) };
+};

package/src/keyGen.ts

@@ -0,0 +1,14 @@
+import { generateKeyPairSync } from 'node:crypto';
+
+export const generateKeyPair = (modulusLength: number = 4096) =>
+  generateKeyPairSync('rsa', {
+    modulusLength: modulusLength,
+    publicKeyEncoding: {
+      type: 'spki',
+      format: 'pem',
+    },
+    privateKeyEncoding: {
+      type: 'pkcs8',
+      format: 'pem',
+    },
+  });

package/src/pwdUtilAuth.ts

@@ -0,0 +1,78 @@
+import * as cryptoUtilAuth from './cryptoUtilAuth';
+import * as stringUtilAuth from './stringUtilAuth';
+
+/**
+ * Just assemble password together
+ * @param algorithmBase64
+ * @param hashBase64
+ * @param saltBase64
+ * @return {string}
+ */
+export const _assemblePasswordHash = (
+  algorithmBase64: string,
+  hashBase64: string,
+  saltBase64: string,
+): string => {
+  return '$1$' + algorithmBase64 + '$' + hashBase64 + '$' + saltBase64 + '$';
+};
+
+/**
+ * Break password into its parts does not reverse base64 encoding.
+ * @param passwordHashStored
+ * @return {{salt: *, version: *, alg: *, hash: *}}
+ */
+export const _disassemblePasswordHash = (passwordHashStored: string): any => {
+  return stringUtilAuth.dollarSignConnectedStringToAlgorithmHashSalt(passwordHashStored);
+};
+
+/**
+ * Creates password hash ready to be saved in database.
+ * @param password
+ * @param secret
+ * @param salt
+ * @param algorithm
+ * @return {string}
+ */
+export const _createPasswordHash = (
+  password: string,
+  secret: string,
+  salt: string,
+  algorithm: string,
+): string => {
+  const algorithmBase64 = stringUtilAuth.asciiToBase64(algorithm);
+  const hashBase64 = cryptoUtilAuth.createHmacBase64(password, secret, algorithm);
+  return _assemblePasswordHash(algorithmBase64, hashBase64, salt);
+};
+
+/**
+ * Automatically adds random salt.
+ * @param password
+ * @param secret
+ * @param algorithm
+ * @return {string}
+ */
+export const createPasswordHashWithRandomSalt = (
+  password: string,
+  secret: string,
+  algorithm: string,
+): string => {
+  const salt = cryptoUtilAuth.createSaltBase64();
+  return _createPasswordHash(password, secret, salt, algorithm);
+};
+
+/**
+ * Creates hash based on saved hash in database.
+ * @param password
+ * @param savedPasswordHash
+ * @param secret
+ * @return {string}
+ */
+export const createPasswordHashBasedOnSavedAlgorithmSalt = (
+  password: string,
+  savedPasswordHash: string,
+  secret: string,
+): string => {
+  const { alg, salt } = _disassemblePasswordHash(savedPasswordHash);
+  const algorithm = stringUtilAuth.base64ToAscii(alg);
+  return _createPasswordHash(password, secret, salt, algorithm);
+};

package/src/strEncryptUtil.ts

@@ -0,0 +1,159 @@
+// src/strEncryptUtil.ts
+import * as crypto from 'crypto';
+
+/**
+ * Derive a key using scrypt.
+ */
+export function createKey(key: crypto.BinaryLike, keyLength = 32): Buffer {
+  // scryptSync returns a Buffer
+  return crypto.scryptSync(key, key, keyLength);
+}
+
+/* --------------------------------------------------
+ * Config Types
+ * -------------------------------------------------- */
+
+export interface EncryptionConfig {
+  privateKey: string | Buffer | crypto.KeyObject;
+  encryptedTextEncoding: BufferEncoding; // e.g., 'base64' | 'hex' | ...
+}
+
+export interface DecryptionConfig {
+  publicKey: string | Buffer | crypto.KeyObject;
+  encryptedTextEncoding: BufferEncoding; // encoding of input cipher text buffer
+  plainTextEncoding: BufferEncoding; // encoding for output text, e.g., 'utf8'
+}
+
+export interface SymmetricCryptoConfig {
+  cipherAlgorithm: string; // e.g., 'aes-256-cbc'
+  encryptionKey: crypto.BinaryLike; // passphrase or raw key-like data
+  keyLength: number; // e.g., 32 for aes-256
+  plainTextEncoding: BufferEncoding; // e.g., 'utf8'
+  encryptedTextEncoding: BufferEncoding; // e.g., 'base64' | 'hex'
+}
+
+/* --------------------------------------------------
+ * Helpers
+ * -------------------------------------------------- */
+
+function getErrorCodeOrFallback(error: unknown): string {
+  // Safely narrow 'unknown' to read 'code' when available
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof (error as { code?: unknown }).code === 'string'
+  ) {
+    return (error as { code: string }).code;
+  }
+  if (error instanceof Error) {
+    // You can return message or name; using name keeps it short
+    return `ERROR:${error.name}`;
+  }
+  return 'UNKNOWN_ERROR';
+}
+
+/* --------------------------------------------------
+ * Asymmetric Encryption (RSA or similar)
+ * -------------------------------------------------- */
+
+/**
+ * Encrypts text using a private key, returning an encoded cipher text string.
+ * On error, returns a code string if present, otherwise a fallback.
+ */
+export const encryptByPrivateKey = (
+  encryptionConfigObj: EncryptionConfig,
+  textToEncrypt: string,
+): string => {
+  try {
+    const encrypted = crypto.privateEncrypt(
+      encryptionConfigObj.privateKey,
+      Buffer.from(textToEncrypt, 'utf8'),
+    );
+    return encrypted.toString(encryptionConfigObj.encryptedTextEncoding);
+  } catch (error: unknown) {
+    return getErrorCodeOrFallback(error);
+  }
+};
+
+/**
+ * Decrypts text using a public key, returning a plain text string.
+ * On error, returns a code string if present, otherwise a fallback.
+ */
+export const decryptByPublicKey = (
+  decryptionConfigObj: DecryptionConfig,
+  textToDecrypt: string,
+): string => {
+  try {
+    const decrypted = crypto.publicDecrypt(
+      decryptionConfigObj.publicKey,
+      Buffer.from(textToDecrypt, decryptionConfigObj.encryptedTextEncoding),
+    );
+    return decrypted.toString(decryptionConfigObj.plainTextEncoding);
+  } catch (error: unknown) {
+    return getErrorCodeOrFallback(error);
+  }
+};
+
+/* --------------------------------------------------
+ * Symmetric Encryption (AES or similar)
+ * -------------------------------------------------- */
+
+/**
+ * Encrypts text using a symmetric algorithm and derived key, returning an encoded cipher string.
+ * On error, returns a code string if present, otherwise a fallback.
+ *
+ * NOTE: This uses a zero IV (Buffer.alloc(16, 0)) which is generally **not recommended** for production.
+ * Prefer a random IV per encryption and prepend/append it to the output for decryption.
+ */
+export const encryptByKey = (
+  encryptConfigObj: SymmetricCryptoConfig,
+  textToEncrypt: string,
+): string => {
+  try {
+    const iv = Buffer.alloc(16, 0); // ⚠️ consider using a random IV for security
+    const key = createKey(encryptConfigObj.encryptionKey, encryptConfigObj.keyLength);
+
+    const cipher = crypto.createCipheriv(encryptConfigObj.cipherAlgorithm, key, iv);
+
+    let encrypted = cipher.update(
+      textToEncrypt,
+      encryptConfigObj.plainTextEncoding,
+      encryptConfigObj.encryptedTextEncoding,
+    );
+    encrypted += cipher.final(encryptConfigObj.encryptedTextEncoding);
+
+    return encrypted;
+  } catch (error: unknown) {
+    return getErrorCodeOrFallback(error);
+  }
+};
+
+/**
+ * Decrypts a cipher string using a symmetric algorithm and derived key,
+ * returning the plain text string. On error, returns a code string or fallback.
+ *
+ * NOTE: Must use the same IV that was used during encryption. Here it assumes a zero IV.
+ */
+export const decryptByKey = (
+  encryptConfigObj: SymmetricCryptoConfig,
+  textToDecrypt: string,
+): string => {
+  try {
+    const iv = Buffer.alloc(16, 0); // ⚠️ must match the IV used in encryptByKey
+    const key = createKey(encryptConfigObj.encryptionKey, encryptConfigObj.keyLength);
+
+    const decipher = crypto.createDecipheriv(encryptConfigObj.cipherAlgorithm, key, iv);
+
+    let decrypted = decipher.update(
+      textToDecrypt,
+      encryptConfigObj.encryptedTextEncoding,
+      encryptConfigObj.plainTextEncoding,
+    );
+    decrypted += decipher.final(encryptConfigObj.plainTextEncoding);
+
+    return decrypted;
+  } catch (error: unknown) {
+    return getErrorCodeOrFallback(error);
+  }
+};

package/src/stringUtilAuth.ts

@@ -0,0 +1,102 @@
+'use strict';
+/**
+ * For incoming jwt token validation, splitting and parsing.
+ * For outgoing jwt token assembling to jwt, make it url safe.
+ */
+
+/**
+ * Adjusts padding of base64String
+ * @param base64String
+ * @return {*}
+ */
+export const adjustBase64Padding = (base64String: string): string => {
+  while (base64String.length % 4) base64String += '=';
+  return base64String;
+};
+
+/**
+ * Removes /, + and = from the string
+ * @returns {string}
+ */
+export const makeStringUrlSafe = (urlUnsafeString: string = ''): string => {
+  return urlUnsafeString.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+};
+
+/**
+ * Put back /, + and = into the string
+ * @returns {string}
+ */
+export const reverseStringUrlSafe = (urlSafeString: string = ''): string => {
+  let myString = urlSafeString.replace(/-/g, '+').replace(/_/g, '/');
+  return adjustBase64Padding(myString);
+};
+
+/**
+ * Encode string to base64 string
+ * @param unCodedString
+ * @returns {string}
+ */
+export const asciiToBase64 = (unCodedString: string): string => {
+  return Buffer.from(unCodedString).toString('base64');
+};
+
+/** Decode string from base64
+ * @param codedString
+ * @returns {string}
+ */
+export const base64ToAscii = (codedString: string): string => {
+  return Buffer.from(codedString, 'base64').toString('ascii');
+};
+
+/**
+ * Decompose $ connected string and return an object
+ * return null if error
+ * @param passwordHash
+ */
+export const dollarSignConnectedStringToAlgorithmHashSalt = (passwordHash: string) => {
+  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'}
+ * return null if error
+ */
+export const dotConnectedStringToHeaderPayloadSignature = (jwt: string) => {
+  const splitJWT = jwt.split('.');
+  if (splitJWT.length !== 3) return null;
+  return {
+    header: splitJWT[0],
+    payload: splitJWT[1],
+    signature: splitJWT[2],
+  };
+};
+
+/**
+ * Turns object into url safe string
+ * @param object
+ * @return {string}
+ */
+export const objectToBase64UrlSafeString = (object: any): string => {
+  let stringAscii = JSON.stringify(object);
+  let base64String = asciiToBase64(stringAscii);
+  return makeStringUrlSafe(base64String);
+};
+
+/**
+ * Turns base64 into object
+ * @param urlSafeBase64String
+ * @return {any}
+ */
+export const urlSafeBase64ToObject = (urlSafeBase64String: string): any => {
+  let base64String = reverseStringUrlSafe(urlSafeBase64String);
+  let stringAscii = base64ToAscii(base64String);
+  return JSON.parse(stringAscii);
+};