@carecard/jwt-read 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 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

@@ -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-jwt-read-jwt-middleware-library/SKILL.md

@@ -7,6 +7,10 @@ description: 'Use when changing pkg-jwt-read JWT parsing, middleware, visitor to
 
 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
@@ -118,6 +122,9 @@ depend on those folders being present.
 - Server-auth request attachment behavior that normalizes introspected claims
   into `req.jwt.payload` with `authMode: "server-auth"` and
   `auth_mode: "server-auth"`.
+- Server-auth email confirmation claims are copied only when present. The
+  `emailVerified`, `email_verified`, `emailConfirmed`, and `email_confirmed`
+  aliases retain their exact names and values, and omission remains omission.
 - Integration with `@carecard/common-util` for standardized login and
   authorization errors.
 

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/lib/jwtLib.js

@@ -5,6 +5,7 @@ const { throwLoginRequiredError, throwNotAuthorizedError } = require('@carecard/
 
 const DEFAULT_USER_AUTHORIZATION_HEADER_NAME = 'X-Authorization-Context';
 const DEFAULT_USER_AUTHORIZATION_MAX_TOKEN_LENGTH = 2048;
+const EMAIL_CONFIRMATION_CLAIM_NAMES = ['emailVerified', 'email_verified', 'emailConfirmed', 'email_confirmed'];
 
 function jwtClientId(req) {
   const jwtObj = req?.jwt || this;
@@ -33,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) {
@@ -122,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);
   }
 
@@ -336,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);
   }
 
@@ -361,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;
@@ -389,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;
   }
 
@@ -437,11 +436,22 @@ function attachServerAuthClaims(req, claims, customErrorFunction) {
   _attachJwtMethods(req.jwt);
 }
 
+// Pattern: Projection - copies only authoritative confirmation aliases and preserves their exact values.
+function pickEmailConfirmationClaims(claims) {
+  return Object.fromEntries(
+    EMAIL_CONFIRMATION_CLAIM_NAMES.filter(claimName => Object.prototype.hasOwnProperty.call(claims, claimName)).map(claimName => [
+      claimName,
+      claims[claimName],
+    ]),
+  );
+}
+
+// Pattern: Mapper - attaches server-auth metadata while preserving authoritative confirmation claims.
 function createServerAuthPayload(claims) {
   return {
     sub: claims.sub || claims.userId || claims.user_id,
     email: claims.email || '',
-    email_verified: claims.emailVerified || claims.email_verified || claims.emailConfirmed || claims.email_confirmed || false,
+    ...pickEmailConfirmationClaims(claims),
     roles: Array.isArray(claims.roles) ? claims.roles : [],
     authMode: 'server-auth',
     auth_mode: 'server-auth',
@@ -557,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;
@@ -570,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.9.0",
+  "version": "3.11.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.9.0",
-    "@carecard/common-util": "3.9.0",
-    "@carecard/validate": "3.9.0"
+    "@carecard/auth-util": "3.11.0",
+    "@carecard/common-util": "3.11.0",
+    "@carecard/validate": "3.11.0"
   },
   "overrides": {
     "diff": "8.0.4",

package/readme.md

@@ -12,6 +12,10 @@ introspected by `ms-auth`.
 
 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
@@ -142,6 +146,10 @@ those claims onto `req.jwt.payload` with `authMode: "server-auth"` and
 `auth_mode: "server-auth"` so services can keep their existing JWT-backed
 database context and role checks.
 
+Server-auth email confirmation claims are copied only when present. The
+`emailVerified`, `email_verified`, `emailConfirmed`, and `email_confirmed`
+aliases retain their exact names and values, and omission remains omission.
+
 ### Scoped User Authorization Context
 
 Use `jwtVerifyUserAuthorization` when a route needs to verify only the compact