@carecard/auth-util 3.1.15 → 3.2.0

package/.agents/skills/npm-package-flow/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: npm-package-flow
+description: 'Use in pkg-* repositories when publishable package code changes require a version bump, GitHub development/main squash-merge flow, npm publication, and uncommitted consumer package updates in ms-* and app-dashboard.'
+---
+
+# npm Package Flow
+
+## Purpose
+
+Use this skill in a `pkg-*` repository when package code changes need to be
+published to npm and propagated to CareCard consumers.
+
+The package name is the `name` field in the repository `package.json`.
+
+## Publishable vs Non-Publishable Changes
+
+Publishable package changes include runtime source changes, public exports,
+TypeScript declarations, package metadata that affects consumers, security
+behavior, or dependency behavior that changes the package contract.
+
+The following are not publishable package changes by themselves:
+
+- Skills or `.agents` guidance.
+- Documentation and README updates.
+- Tests, fixtures, mocks, snapshots, or validation-only changes.
+- Formatting-only changes and comments.
+
+For non-publishable changes, do not bump the package version, publish to npm,
+or update `ms-*` and `app-dashboard` package versions.
+
+## Required Flow For Publishable Changes
+
+Run this workflow only when the user explicitly asks for package publication,
+remote GitHub merge work, or the full package-flow completion. Remote Git and
+GitHub operations must not be inferred.
+
+1. Finish package code, tests, documentation, and skill updates inside the
+   current `pkg-*` repository.
+2. Bump the package version in `package.json` and `package-lock.json` according
+   to the user request or the package change scope.
+3. Run the package's required tests, lint, type checks, and every direct Husky
+   script. Fix failures before continuing.
+4. Commit the package changes to the current branch.
+5. Push the current branch, create or reuse the PR into `development`,
+   squash-merge it with administrator privileges, and delete the merged branch.
+6. Create a new merge branch from the updated `development` branch and use that
+   branch to open a PR into `main`.
+7. Squash-merge the merge branch into `main` with administrator privileges and
+   delete the merge branch. This `main` merge publishes the package.
+8. Confirm publication with `npm view <package-name>@<version> version`.
+9. Check out a fresh local branch with the same name as the deleted working
+   branch from the updated `development` branch.
+10. Update the new `@carecard/...` package version in `app-dashboard` and in
+    only the `ms-*` repositories that already declare the package, plus any
+    explicitly intended new consumers.
+11. Run `npm install` and relevant validation in each updated consumer.
+12. Do not commit the `ms-*` or `app-dashboard` consumer updates unless the user
+    explicitly asks.
+
+## Consumer Update Rules
+
+- Discover existing consumers by checking each target repository `package.json`
+  for the published package name.
+- Install exact package versions, for example
+  `npm install <package-name>@<version> --save-exact`.
+- Keep consumer updates local and uncommitted unless the user gives a separate
+  commit or PR instruction.
+- If a consumer should become a new dependency, require explicit user intent for
+  that repository.
+
+## Reporting
+
+Report the package name, published version, development PR, main PR, npm
+publication check, consumer repositories updated, validation commands run, and
+any consumer updates intentionally left uncommitted.

package/.agents/skills/npm-package-flow/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: 'npm Package Flow'
+  short_description: 'Use in pkg-* repositories when publishable @carecard package code changes need npm publication and consumer updates.'
+  brand_color: '#0F766E'
+  default_prompt: 'Use $npm-package-flow when this task matches the skill scope.'

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

@@ -1,6 +1,6 @@
 ---
 name: pkg-auth-util-auth-crypto-library
-description: Use when changing pkg-auth-util auth, password, JWT, crypto, key, exported API, types, or package validation behavior.
+description: 'Use when changing pkg-auth-util auth, password, JWT, crypto, key, exported API, types, or package validation behavior.'
 ---
 
 # Package Auth Util
@@ -43,8 +43,8 @@ CareCard auth utility package for JWT creation/verification primitives, password
 
 ## Safety Constraints
 
-- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task explicitly requires it.
-- Do not revert or overwrite user changes; stage only files related to the requested skill or instruction update.
+- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task requires it.
+- Do not revert or overwrite user changes; stage only requested skill or instruction files.
 - Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
 - Do not log or expose secrets, JWTs, passwords, credentials, private keys, sensitive personal data, SQL internals, or stack traces.
 
@@ -107,6 +107,9 @@ depend on those folders being present.
   `jwtCreateServiceAuthorizationHeader`.
 - Do not silently change token timing behavior, token formats, JWT string
   assembly, signature verification semantics, or decomposition return shapes.
+- Preserve application JWT payload claims, including the `roles` array.
+  `ms-auth` RLS treats `roles: ["ad"]` as the auth-service super-admin signal,
+  so JWT helpers must not hide, rename, or drop that role data.
 - Expected parse and verify failures should return `null` or `false` where the
   current public API does so.
 
@@ -146,7 +149,7 @@ depend on those folders being present.
 - Use `try/catch` inside utility functions where existing functions fail
   gracefully instead of throwing uncaught exceptions.
 - Do not broaden catch blocks in a way that hides unexpected implementation
-  errors in callers that currently expect throws.
+  errors in callers that expect throws.
 
 ## Types And Exports
 
@@ -199,7 +202,7 @@ and remaining risk.
 
 ## Remote Git Operations Guardrail
 
-Do not run remote Git or GitHub operations unless the current user request explicitly asks for that remote operation. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would be useful but was not requested.
+Do not run remote Git or GitHub operations unless the current user request explicitly asks for them. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would help but was not requested.
 
 ## Agent Guidance Git Workflow
 

package/.agents/skills/software-design-patterns-and-clean-code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: software-design-patterns-and-clean-code
-description: Use every time before coding, refactoring, debugging, or reviewing in this repository, alongside all other applicable skills, to apply pragmatic software design patterns, SOLID, Clean Code, and testable architecture.
+description: 'Use every time before coding, refactoring, debugging, or reviewing in this repository, alongside all other applicable skills, to apply pragmatic software design patterns, SOLID, Clean Code, and testable architecture.'
 ---
 
 # Software Design Patterns And Clean Code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.1.15",
+  "version": "3.2.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
@@ -25,24 +25,24 @@
   "author": "CareCard team",
   "license": "ISC",
   "devDependencies": {
-    "express": "5.2.1",
     "@istanbuljs/nyc-config-typescript": "1.0.2",
+    "@types/express": "5.0.6",
     "@types/mocha": "10.0.10",
     "@types/node": "25.9.1",
-    "@types/express": "5.0.6",
+    "eslint": "9.39.4",
+    "express": "5.2.1",
     "husky": "9.1.7",
+    "lint-staged": "17.0.5",
     "mocha": "11.7.6",
     "nyc": "18.0.0",
     "prettier": "3.8.3",
-    "eslint": "9.39.4",
-    "lint-staged": "17.0.5",
     "source-map-support": "0.5.21",
     "supertest": "7.2.2",
     "ts-node": "10.9.2",
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.1.15",
-    "@carecard/validate": "3.1.24"
+    "@carecard/common-util": "3.2.0",
+    "@carecard/validate": "3.3.0"
   }
 }

package/readme.md

@@ -100,6 +100,19 @@ const urlSafe = stringUtilAuth.makeStringUrlSafe('a+b/c==');
 // Result: a-b_c
 ```
 
+## CareCard Auth Contract
+
+`ms-auth` issues CareCard user JWTs and now enforces its own auth tables with
+forced PostgreSQL RLS. This package should preserve JWT claim values exactly
+when creating or verifying tokens; a payload containing `roles: ["ad"]` is the
+auth-service super-admin signal. Do not add helpers that hide, rename, or drop
+the `roles` array, and do not add database bypass behavior to this package.
+
+Docs that mention `ms-auth` controller internals should use concise action
+names such as `loginUser`, `registerUser`, `getUserDetail`, and `renewJwt`.
+Access level is conveyed by route middleware and endpoint placement, not by
+`public`/`protected`/`admin`/`Handler` suffixes.
+
 ## Testing
 
 Run tests using:

package/.prettierignore

@@ -1,17 +0,0 @@
-dist/
-coverage/
-node_modules/
-build/
-*.min.js
-.github
-.husky
-dist
-.gitignore
-.npmignore
-.prettierignore
-.prettierrc.js
-eslint.config.mjs
-jest.config.js
-package.json
-readme.md
-rename-cjs.js

package/.prettierrc.cjs

@@ -1,32 +0,0 @@
-/** @type {import('prettier').Config} */
-module.exports = {
-  // Core formatting
-  printWidth: 100,
-  tabWidth: 2,
-  useTabs: false,
-  semi: true,
-  singleQuote: true,
-  trailingComma: 'all',
-  bracketSpacing: true,
-  bracketSameLine: true,
-  arrowParens: 'avoid',
-
-  // Line endings (important for cross-platform + CI)
-  endOfLine: 'auto',
-
-  // Language-specific overrides
-  overrides: [
-    {
-      files: '*.json',
-      options: {
-        printWidth: 80,
-      },
-    },
-    {
-      files: '*.md',
-      options: {
-        proseWrap: 'preserve',
-      },
-    },
-  ],
-};

package/jest.config.js

@@ -1,16 +0,0 @@
-export default {
-    preset: 'ts-jest',
-    testEnvironment: 'node',
-  transform: {
-    '^.+\\.ts$': [
-      'ts-jest',
-      {
-        tsconfig: 'tsconfig.base.json',
-      },
-    ],
-  },
-  testMatch: ['**/tests/**/*.test.ts'],
-    collectCoverage: true,
-    collectCoverageFrom: ['src/**/*.ts'],
-    coverageDirectory: 'coverage'
-};

package/scripts/rename-cjs.js

@@ -1,13 +0,0 @@
-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

@@ -1,111 +0,0 @@
-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

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

package/src/jwtUtilAuth.ts

@@ -1,85 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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);
-};