@carecard/auth-util 3.9.0 → 3.11.0

package/.agents/skills/carecard-workspace-standards/SKILL.md

@@ -7,6 +7,10 @@ description: 'Follow the shared SO_CareCardCa/CareCard workspace coding, testing
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose
@@ -83,7 +87,7 @@ config.
 - Never suppress errors, TypeScript errors, linter warnings, authorization
   failures, RLS failures, build failures, hydration issues, or failing tests.
   Do not add `eslint-disable`, `@ts-ignore`, broad catches, empty catches, or
-  similar suppression unless explicitly requested.
+  similar suppression. Fix the root cause.
 - Do not add dependencies unless clearly necessary. If one might be needed, ask
   first with the reason, tradeoff, and why existing code cannot solve it.
 - Before finalizing repository work, run the affected repository's relevant
@@ -212,8 +216,8 @@ build artifacts, logs, or `.DS_Store`.
 
 Most JavaScript `ms-*` services use CommonJS, Mocha, Supertest, Docker Compose
 database tests, `@carecard/*` packages, and `sub-apps`
-controller/router/model patterns. TypeScript services such as `ms-contact-us`
-and `ms-template-ts` use Jest or TypeScript tooling and should keep their
+controller/router/model patterns. TypeScript services such as `ms-messages`
+use Jest or TypeScript tooling and should keep their
 existing TypeScript style.
 
 - Keep environment-specific files explicit: `.env.development`, `.env.test`,
@@ -311,7 +315,7 @@ existing TypeScript style.
 
 `app-dashboard` is a Next.js App Router TypeScript app using MUI, React Query,
 `next-intl`, and shared CareCard utilities. It consumes `ms-auth`,
-`ms-institutions`, `ms-contact-us`, and `ms-user-profiles` through service
+`ms-institutions`, `ms-messages`, and `ms-user-profiles` through service
 modules.
 
 - Keep backend URL definitions centralized in `src/services/api.routes.ts`.
@@ -378,7 +382,7 @@ the authenticated dashboard.
 
 ## Auth Service RLS Contract
 
-- `ms-auth` follows the shared PostgreSQL/RLS pattern from `ms-template-js`: auth tables live in the `carecard` schema, RLS is enabled and forced on every auth table, and application runtime queries use the unprivileged database role.
+- `ms-auth` follows the shared PostgreSQL/RLS pattern: auth tables live in the `carecard` schema, RLS is enabled and forced on every auth table, and application runtime queries use the unprivileged database role.
 - Auth table policies allow normal JWT users to access only self-owned rows. Do not add redundant `user_id = <jwt sub>` SQL predicates to duplicate self-row checks when RLS owns the authorization decision.
 - A JWT payload containing `roles: ["ad"]` is the auth-service super-admin signal and can perform any action on auth tables. Dashboard code may map that role to `super_admin`, but backend auth RLS must not require a separate database role row for that bypass.
 - Public auth flows such as registration, login, confirmation, recovery, visitor creation, and service user lookup must use narrow system contexts (`system_create`, `system_login`, `system_confirm`, `system_recovery`, `system_visitor`, `system_service`) instead of privileged runtime queries.

package/.agents/skills/github-pr-create-update/SKILL.md

@@ -7,6 +7,10 @@ description: 'Use only when the user explicitly asks for remote Git or GitHub PR
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose
@@ -75,14 +79,20 @@ Do not continue automatically when:
    when `origin/development` is absent:
 
    ```sh
-   if git ls-remote --exit-code --heads origin development >/dev/null 2>&1; then
-     base="development"
-   elif git ls-remote --exit-code --heads origin main >/dev/null 2>&1; then
-     base="main"
-   else
-     echo "No origin/development or origin/main branch exists."
-     exit 1
+   remote_base_refs="$(git ls-remote --heads origin development main)"
+   remote_query_status=$?
+   if [ "$remote_query_status" -ne 0 ]; then
+     printf 'Unable to inspect origin base branches (exit %s).\n' "$remote_query_status" >&2
+     exit "$remote_query_status"
    fi
+   case "$remote_base_refs" in
+     *"refs/heads/development") base="development" ;;
+     *"refs/heads/main") base="main" ;;
+     *)
+       printf '%s\n' "No origin/development or origin/main branch exists." >&2
+       exit 1
+       ;;
+   esac
    git fetch origin "$base" --prune
    ```
 

package/.agents/skills/github-pr-merge-cleanup/SKILL.md

@@ -7,6 +7,10 @@ description: 'Use only when the user explicitly asks for remote Git or GitHub PR
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose
@@ -72,14 +76,20 @@ completion.
 
    ```sh
    gh auth status
-   if git ls-remote --exit-code --heads origin development >/dev/null 2>&1; then
-     base="development"
-   elif git ls-remote --exit-code --heads origin main >/dev/null 2>&1; then
-     base="main"
-   else
-     echo "No origin/development or origin/main branch exists."
-     exit 1
+   remote_base_refs="$(git ls-remote --heads origin development main)"
+   remote_query_status=$?
+   if [ "$remote_query_status" -ne 0 ]; then
+     printf 'Unable to inspect origin base branches (exit %s).\n' "$remote_query_status" >&2
+     exit "$remote_query_status"
    fi
+   case "$remote_base_refs" in
+     *"refs/heads/development") base="development" ;;
+     *"refs/heads/main") base="main" ;;
+     *)
+       printf '%s\n' "No origin/development or origin/main branch exists." >&2
+       exit 1
+       ;;
+   esac
    target_branch="$(git branch --show-current)"
    test -n "$target_branch"
    test "$target_branch" != "$base"
@@ -169,7 +179,19 @@ completion.
    not protected:
 
    ```sh
-   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
+   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected')"
+   protection_query_status=$?
+   if [ "$protection_query_status" -ne 0 ]; then
+     printf 'Unable to inspect branch protection (exit %s).\n' "$protection_query_status" >&2
+     exit "$protection_query_status"
+   fi
+   case "$protected" in
+     true|false) ;;
+     *)
+       printf 'Unexpected branch protection value: %s\n' "$protected" >&2
+       exit 1
+       ;;
+   esac
    if [ "$protected" = true ]; then
      gh pr merge "$pr_number" --squash --admin
    else
@@ -181,8 +203,16 @@ completion.
    delete it explicitly:
 
    ```sh
-   if [ "$protected" != true ] && git ls-remote --exit-code --heads origin "$target_branch" >/dev/null 2>&1; then
-     git push origin --delete "$target_branch"
+   if [ "$protected" != true ]; then
+     remote_target_ref="$(git ls-remote --heads origin "$target_branch")"
+     remote_query_status=$?
+     if [ "$remote_query_status" -ne 0 ]; then
+       printf 'Unable to inspect the remote target branch (exit %s).\n' "$remote_query_status" >&2
+       exit "$remote_query_status"
+     fi
+     if [ -n "$remote_target_ref" ]; then
+       git push origin --delete "$target_branch"
+     fi
    fi
    ```
 

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

@@ -7,6 +7,10 @@ description: 'Use when changing pkg-auth-util auth, password, JWT, crypto, key,
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose

package/.agents/skills/pkg-publish/SKILL.md

@@ -7,6 +7,10 @@ description: 'Use when any pkg-* repository has non-Markdown package changes, in
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Trigger

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

@@ -7,6 +7,10 @@ description: 'Use every time before coding, refactoring, debugging, or reviewing
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Purpose

package/index.d.ts

@@ -148,14 +148,14 @@ export const jwtUtilAuth: {
    * @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.
+   * @returns Signed JWT string, or null when the private key is missing. Unexpected failures throw.
    */
   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.
+   * @returns True if the signature is valid, false for malformed or invalid tokens. Unexpected failures throw.
    */
   verifyJwtSignature: (jwt: string, publicKey: string) => boolean;
   /**

package/lib/jwtUtilAuth.js

@@ -77,25 +77,21 @@ const normalizeSeconds = value => {
  * @return {string|null}
  */
 const createSignedJwtFromObject = (headerObject, payloadObject, privateKey) => {
-  try {
-    if (!privateKey) return null;
+  if (!privateKey) return null;
 
-    const header = { ...headerObject };
-    header.alg = header.alg || 'EdDSA';
-    header.typ = 'JWT';
+  const header = { ...headerObject };
+  header.alg = header.alg || 'EdDSA';
+  header.typ = 'JWT';
 
-    const payload = _normalizePayload(payloadObject);
+  const payload = _normalizePayload(payloadObject);
 
-    const headerBase64UrlSafe = _encode(header);
-    const payloadBase64UrlSafe = _encode(payload);
-    const token = headerBase64UrlSafe + '.' + payloadBase64UrlSafe;
+  const headerBase64UrlSafe = _encode(header);
+  const payloadBase64UrlSafe = _encode(payload);
+  const token = headerBase64UrlSafe + '.' + payloadBase64UrlSafe;
 
-    const signature = _sign(token, header.alg, privateKey);
+  const signature = _sign(token, header.alg, privateKey);
 
-    return token + '.' + signature;
-  } catch (error) {
-    return null;
-  }
+  return token + '.' + signature;
 };
 
 function createServiceJwt({
@@ -161,6 +157,7 @@ const verifyJwtSignature = (jwt, publicKey) => {
 
     return _verify(token, signature, headerObject.alg, publicKey);
   } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
     return false;
   }
 };
@@ -180,7 +177,8 @@ const getHeaderPayloadFromJwt = jwt => {
     const payloadObject = _decode(splitJWT[1]);
 
     return { header: headerObject, payload: payloadObject };
-  } catch (e) {
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
     return null;
   }
 };

package/lib/pwdUtilAuth.js

@@ -8,14 +8,10 @@ const crypto = require('crypto');
  * @return {string}
  */
 const createPasswordHashWithRandomSalt = (password, secret, 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;
-  }
+  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 + '$';
 };
 
 /**
@@ -26,19 +22,17 @@ const createPasswordHashWithRandomSalt = (password, secret, algorithm) => {
  * @return {string}
  */
 const createPasswordHashBasedOnSavedAlgorithmSalt = (password, savedPasswordHash, secret) => {
-  try {
-    const splitStringArray = savedPasswordHash.split('$');
-    if (splitStringArray.length !== 6) return null;
+  if (typeof savedPasswordHash !== 'string') return null;
 
-    const algBase64 = splitStringArray[2];
-    const salt = splitStringArray[4];
-    const algorithm = Buffer.from(algBase64, 'base64').toString('utf8');
+  const splitStringArray = savedPasswordHash.split('$');
+  if (splitStringArray.length !== 6) return null;
 
-    const hashBase64 = crypto.createHmac(algorithm, secret).update(password).digest('base64');
-    return '$1$' + algBase64 + '$' + hashBase64 + '$' + salt + '$';
-  } catch (e) {
-    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 + '$';
 };
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
@@ -26,7 +26,6 @@
   "license": "ISC",
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "1.0.2",
-    "@types/express": "5.0.6",
     "@types/mocha": "10.0.10",
     "@types/node": "25.9.3",
     "eslint": "9.39.4",
@@ -42,11 +41,13 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.9.0",
-    "@carecard/validate": "3.9.0"
+    "@carecard/common-util": "3.11.0",
+    "@carecard/validate": "3.11.0",
+    "@types/express": "5.0.6"
   },
   "overrides": {
     "diff": "8.0.4",
+    "glob": "13.0.6",
     "serialize-javascript": "7.0.5",
     "js-yaml": "4.2.0"
   }

package/readme.md

@@ -9,6 +9,10 @@ Utility package for authentication and authorization in the CareCard ecosystem.
 
 Non-negotiable TDD rule: Always write the failing test first, run it to confirm it fails for the intended reason, then implement the code and rerun the test until it passes. Test Driven Development is required for all coding work and must not be skipped. For documentation- or skill-only edits, add or update the relevant validation check before changing the prose.
 
+Non-negotiable repository isolation rule: Every repository must run its Husky hooks and tests using only files, code, fixtures, dependencies, and services contained within that repository. Tests and Husky scripts must not import, require, read, execute, or otherwise depend on sibling repositories or paths outside the repository root. app-e2e-tests is the only exception because cross-repository end-to-end testing is its explicit responsibility.
+
+Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade, filter, ignore, skip, or bypass errors or warnings from code, tests, tools, compilers, linters, or validation. Fix the root cause, then rerun the affected check and require a clean result. Expected error-path tests may assert errors, but must not conceal unexpected failures.
+
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
 ## Features