@carecard/jwt-read 3.10.0 → 3.12.0

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

@@ -3,12 +3,29 @@ name: carecard-workspace-standards
 description: 'Follow the shared SO_CareCardCa/CareCard workspace coding, testing, repository, dependency, shared package, frontend, database, API response, and security standards. Use before modifying, testing, reviewing, or debugging any ms-*, pkg-*, app-*, website, dashboard, or other CareCard repository in this workspace, especially when choosing validation commands, package boundaries, TypeScript types, dependencies, API contracts, database logic, service patterns, or frontend architecture.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # CareCard Workspace Standards
 
 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.
 
+This requirement is non-negotiable and may be overridden only with the user's
+explicit, direct approval.
+
+A pre-existing test—defined as any test present before work on the current task
+begins—must not be deleted, disabled, skipped, weakened, excluded from execution,
+or otherwise removed. A pre-existing test must not be modified without the
+user's explicit approval for the exact proposed change. If changing a
+pre-existing test is believed necessary, stop before making the change and
+request approval. The request must identify every affected test, describe the
+precise proposed modification, provide detailed technical justification, and
+explain all known or reasonably foreseeable regression risks. Until approval is
+granted, leave every pre-existing test unchanged.
+
 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
@@ -85,7 +102,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
@@ -215,7 +232,7 @@ 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-messages`
-and `ms-template-ts` use Jest or TypeScript tooling and should keep their
+use Jest or TypeScript tooling and should keep their
 existing TypeScript style.
 
 - Keep environment-specific files explicit: `.env.development`, `.env.test`,
@@ -380,7 +397,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 or server-auth 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.

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

@@ -3,12 +3,16 @@ name: github-pr-create-update
 description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating or updating a PR, or marking a PR ready from the current repository branch into development or main.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Pull Request Create
 
 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
@@ -77,14 +81,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

@@ -3,12 +3,16 @@ name: github-pr-merge-cleanup
 description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating a missing PR, reviewing mergeability, validating, merging, deleting, or cleaning up a pull request branch.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Pull Request Merge Close
 
 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
@@ -74,14 +78,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"
@@ -171,7 +181,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
@@ -183,8 +205,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-jwt-read-jwt-middleware-library/SKILL.md

@@ -3,12 +3,16 @@ name: pkg-jwt-read-jwt-middleware-library
 description: 'Use when changing pkg-jwt-read JWT parsing, middleware, visitor tokens, role checks, auth context, package exports, or tests.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Package JWT Read
 
 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

@@ -3,12 +3,16 @@ name: pkg-publish
 description: 'Use when any pkg-* repository has non-Markdown package changes, including source code, public types, tests, scripts, package metadata, lockfiles, dependency behavior, or validation config, and the CareCard packages must be versioned, published in order with just-in-time package pushes, and propagated to pkg-*, ms-*, and app-dashboard consumers. Do not use for Markdown-only changes.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # pkg Publish
 
 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

@@ -3,12 +3,16 @@ 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.'
 ---
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 # Software Design Patterns And Clean Code
 
 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/lib/jwtLib.js

@@ -34,7 +34,15 @@ function doesJwtUserHasRole(req, userRole) {
 }
 
 function throwError(customErrorFunction) {
-  typeof customErrorFunction === 'function' ? customErrorFunction() : throwLoginRequiredError();
+  if (typeof customErrorFunction !== 'function') {
+    return throwLoginRequiredError();
+  }
+
+  const customError = customErrorFunction();
+
+  if (customError instanceof Error) throw customError;
+
+  throw new Error('Custom authentication error function returned without throwing');
 }
 
 function isJwtExpired(req, jwtValiditySeconds) {
@@ -123,15 +131,11 @@ function validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expe
   if (jwtString && isJwtSignatureValid) {
     _extractJwtObject(req, jwtString, customErrorFunction);
   } else {
-    /* istanbul ignore else */
-    if (req) {
-      req.jwt = null;
-    }
+    req.jwt = null;
   }
 
   if (!req?.jwt || !_isServiceJwtFor(req.jwt.payload, expectedIssuer, expectedAudience)) {
-    /* istanbul ignore else */
-    if (req) req.jwt = null;
+    req.jwt = null;
     throwError(customErrorFunction);
   }
 
@@ -337,16 +341,14 @@ function validateAndExtractOptionalUserAuthorizationObject(req, options, customE
 
   const header = readUserAuthorizationHeader(req, config);
   if (!header.present) {
-    /* istanbul ignore else */
-    if (req) req.userAuthorization = null;
+    req.userAuthorization = null;
     return req;
   }
 
   if (isUserAuthorizationTokenAllowed(header.token, config)) {
     _extractUserAuthorizationObjectNoThrow(req, header.token);
   } else {
-    /* istanbul ignore else */
-    if (req) req.userAuthorization = null;
+    req.userAuthorization = null;
     throwError(customErrorFunction);
   }
 
@@ -362,10 +364,7 @@ function validateAndExtractOptionalUserAuthorizationObjectNoThrow(req, options)
   if (header.present && isUserAuthorizationTokenAllowed(header.token, config)) {
     _extractUserAuthorizationObjectNoThrow(req, header.token);
   } else {
-    /* istanbul ignore else */
-    if (req) {
-      req.userAuthorization = null;
-    }
+    req.userAuthorization = null;
   }
 
   return req;
@@ -390,8 +389,7 @@ function tryValidateAndExtractJwtObject(req, publicKey) {
 
   const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
   if (!isJwtSignatureValid) {
-    /* istanbul ignore else */
-    if (req) req.jwt = null;
+    req.jwt = null;
     return false;
   }
 
@@ -569,7 +567,7 @@ function getRequestHeader(req, headerName) {
 function isUserAuthorizationTokenAllowed(token, config) {
   if (!token || !config.publicKey || !jwtVerifySignedToken(token, config.publicKey)) return false;
 
-  const payload = readJwtPayloadNoThrow(token);
+  const payload = readVerifiedJwtPayload(token);
   if (!payload) return false;
   if (isJwtPayloadIssuedInFuture(payload)) return false;
   if (isJwtPayloadExpired(payload)) return false;
@@ -582,12 +580,8 @@ function isUserAuthorizationTokenAllowed(token, config) {
 }
 
 // Pattern: Pure Function - decodes payload defensively after signature and shape checks.
-function readJwtPayloadNoThrow(token) {
-  try {
-    return jwtGetHeaderPayload(token)?.payload || null;
-  } catch {
-    return null;
-  }
+function readVerifiedJwtPayload(token) {
+  return jwtGetHeaderPayload(token)?.payload || null;
 }
 
 // Pattern: Pure Function - supports either one expected audience or a small allowed set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/jwt-read",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/CareCard-ca/pkg-jwt-read.git"
@@ -41,9 +41,9 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/auth-util": "3.10.0",
-    "@carecard/common-util": "3.10.0",
-    "@carecard/validate": "3.10.0"
+    "@carecard/auth-util": "3.12.0",
+    "@carecard/common-util": "3.12.0",
+    "@carecard/validate": "3.12.0"
   },
   "overrides": {
     "diff": "8.0.4",

package/readme.md

@@ -1,5 +1,7 @@
 # @carecard/jwt-read
 
+Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.
+
 ![Tests Passing](https://github.com/CareCard-ca/pkg-jwt-read/actions/workflows/ci.yml/badge.svg)
 ![Coverage](https://img.shields.io/badge/Coverage-80%25-orange)
 
@@ -14,6 +16,8 @@ Non-negotiable TDD rule: Always write the failing test first, run it to confirm
 
 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