@carecard/jwt-read 3.1.14 → 3.1.16

package/lib/jwtLib.js

@@ -104,6 +104,33 @@ function validateAndExtractJwtObjectNoThrow(req, publicKey) {
   return _validateAndExtractGenericNoThrow(req, publicKey, _validateJwtNoThrow, _extractJwtObjectNoThrow, 'jwt');
 }
 
+function validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction) {
+  const jwtString = _validateJwt(req, customErrorFunction);
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+
+  if (jwtString && isJwtSignatureValid) {
+    _extractJwtObject(req, jwtString, customErrorFunction);
+  } else if (req) {
+    req.jwt = null;
+  }
+
+  if (!req?.jwt || !_isServiceJwtFor(req.jwt.payload, expectedIssuer, expectedAudience)) {
+    if (req) req.jwt = null;
+    throwError(customErrorFunction);
+  }
+
+  return req;
+}
+
+async function validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction) {
+  if (tryValidateAndExtractJwtObject(req, publicKey)) return req;
+
+  const serverAuthToken = _validateServerAuthToken(req, customErrorFunction);
+  const claims = await introspectServerAuthToken(serverAuthIntrospector, serverAuthToken, req, customErrorFunction);
+  attachServerAuthClaims(req, claims, customErrorFunction);
+  return req;
+}
+
 function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName) {
   return _validateAndExtractGenericNoThrow(req, publicKey, r => _validateWebTokenNoThrow(r, headerName), _extractJwtObjectNoThrow, 'jwt');
 }
@@ -136,6 +163,41 @@ function verifyJwt(publicKey, customErrorFunction) {
   };
 }
 
+function verifyServiceJwt(publicKey, expectedIssuer, expectedAudience, customErrorFunction) {
+  return function (req, res, next) {
+    try {
+      validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFunction) {
+  return async function (req, res, next) {
+    try {
+      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+function verifyJwtOrServerAuthAndHasRole(role, publicKey, serverAuthIntrospector, customErrorFunction) {
+  return async function (req, res, next) {
+    try {
+      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction);
+      const isRoleExist = doesJwtUserHasRole(req, role);
+      _isLoginRequired(isRoleExist, customErrorFunction);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
 function verifyWebToken(publicKey, headerName, customErrorFunction) {
   return function (req, res, next) {
     try {
@@ -193,6 +255,122 @@ function _isLoginRequired(hasRequiredRole, customErrorFunction) {
   }
 }
 
+function tryValidateAndExtractJwtObject(req, publicKey) {
+  const jwtString = _validateJwtNoThrow(req);
+  if (!jwtString || !isJwtString(jwtString)) return false;
+
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+  if (!isJwtSignatureValid) {
+    if (req) req.jwt = null;
+    return false;
+  }
+
+  _extractJwtObjectNoThrow(req, jwtString);
+  return Boolean(req?.jwt);
+}
+
+function _validateServerAuthToken(req, customErrorFunction) {
+  const authorizationHeader = req?.get?.('Authorization') || req?.get?.('authorization');
+  const token = _extractJwtNoThrow(authorizationHeader);
+  if (token) return token;
+
+  throwError(customErrorFunction);
+  return null;
+}
+
+async function introspectServerAuthToken(serverAuthIntrospector, token, req, customErrorFunction) {
+  if (typeof serverAuthIntrospector !== 'function') {
+    throwError(customErrorFunction);
+  }
+
+  const claims = await serverAuthIntrospector(token, req);
+  if (!claims || claims.valid === false) {
+    throwError(customErrorFunction);
+  }
+
+  return claims;
+}
+
+function attachServerAuthClaims(req, claims, customErrorFunction) {
+  const payload = createServerAuthPayload(claims);
+  if (!payload.sub) {
+    if (req) req.jwt = null;
+    throwError(customErrorFunction);
+  }
+
+  req.jwt = {
+    header: {
+      alg: 'opaque',
+      typ: 'ServerAuth',
+    },
+    payload,
+  };
+  _attachJwtMethods(req.jwt);
+}
+
+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,
+    roles: Array.isArray(claims.roles) ? claims.roles : [],
+    authMode: 'server-auth',
+    auth_mode: 'server-auth',
+    sessionId: claims.sessionId || claims.session_id,
+    session_id: claims.session_id || claims.sessionId,
+    exp: readEpochSeconds(claims.exp || claims.expiresAt || claims.expires_at),
+  };
+}
+
+function readEpochSeconds(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'number') return normalizeSeconds(value);
+  const millis = Date.parse(value);
+  return Number.isFinite(millis) ? Math.floor(millis / 1000) : undefined;
+}
+
+function normalizeSeconds(value) {
+  if (!Number.isFinite(value)) return null;
+  return value > 1000000000000 ? Math.floor(value / 1000) : Math.floor(value);
+}
+
+function _isServiceJwtFor(payload, expectedIssuer, expectedAudience) {
+  if (!payload) return false;
+  if (payload.iss !== expectedIssuer) return false;
+  if (payload.sub !== expectedIssuer) return false;
+  if (!payloadAudienceMatches(payload.aud, expectedAudience)) return false;
+  if (isJwtPayloadIssuedInFuture(payload)) return false;
+  if (isJwtPayloadExpired(payload)) return false;
+  if (isJwtPayloadNotYetValid(payload)) return false;
+  return true;
+}
+
+function payloadAudienceMatches(actualAudience, expectedAudience) {
+  if (Array.isArray(actualAudience)) return actualAudience.includes(expectedAudience);
+  return actualAudience === expectedAudience;
+}
+
+function isJwtPayloadExpired(payload) {
+  if (!payload.exp) return true;
+  const exp = normalizeSeconds(payload.exp);
+  if (!Number.isInteger(exp)) return true;
+  return Math.floor(Date.now() / 1000) >= exp;
+}
+
+function isJwtPayloadIssuedInFuture(payload) {
+  if (!payload.iat) return true;
+  const iat = normalizeSeconds(payload.iat);
+  if (!Number.isInteger(iat)) return true;
+  return Math.floor(Date.now() / 1000) < iat;
+}
+
+function isJwtPayloadNotYetValid(payload) {
+  if (!payload.nbf) return false;
+  const nbf = normalizeSeconds(payload.nbf);
+  if (!Number.isInteger(nbf)) return true;
+  return Math.floor(Date.now() / 1000) < nbf;
+}
+
 function _validateGenericNoThrow(req, headerName, extractor) {
   let jwtRaw = req.get(headerName);
   if (!jwtRaw) return null;
@@ -362,6 +540,8 @@ module.exports = {
   _isJwtSignatureValidNoThrow,
   _extractJwtObject,
   validateAndExtractJwtObject,
+  validateAndExtractServiceJwtObject,
+  validateAndExtractJwtOrServerAuthObject,
   validateAndExtractWebToken,
   jwtAgeInSeconds,
   isJwtExpired,
@@ -369,6 +549,9 @@ module.exports = {
   jwtClientId,
   visitorClientId,
   verifyJwtAndRole,
+  verifyServiceJwt,
+  verifyJwtOrServerAuth,
+  verifyJwtOrServerAuthAndHasRole,
   verifyJwt,
   verifyWebTokenNoThrow,
   verifyWebToken,
@@ -388,6 +571,10 @@ module.exports = {
   _extractVisitorObjectNoThrow,
   _extractWebToken,
   _isLoginRequired,
+  tryValidateAndExtractJwtObject,
+  attachServerAuthClaims,
+  createServerAuthPayload,
+  _isServiceJwtFor,
   _attachJwtMethods,
   _attachVisitorMethods,
   _validateWebToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/jwt-read",
-  "version": "3.1.14",
+  "version": "3.1.16",
   "repository": {
     "type": "git",
     "url": "https://github.com/CareCard-ca/pkg-jwt-read.git"
@@ -30,19 +30,19 @@
   "devDependencies": {
     "@types/express": "5.0.6",
     "@types/mocha": "10.0.10",
-    "@types/node": "25.6.2",
+    "@types/node": "25.9.1",
     "eslint": "9.39.4",
     "husky": "9.1.7",
-    "lint-staged": "17.0.3",
-    "mocha": "11.7.5",
+    "lint-staged": "17.0.5",
+    "mocha": "11.7.6",
     "nyc": "18.0.0",
     "prettier": "3.8.3",
     "ts-node": "10.9.2",
-    "typescript": "5.9.3"
+    "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.1.13",
-    "@carecard/auth-util": "3.1.13",
-    "@carecard/validate": "3.1.16"
+    "@carecard/common-util": "3.1.15",
+    "@carecard/auth-util": "3.1.15",
+    "@carecard/validate": "3.1.24"
   }
 }

package/readme.md

@@ -3,7 +3,10 @@
 ![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)
 
-Utility package for reading, parsing, and verifying JWTs in the CareCard ecosystem.
+Utility package for reading, parsing, and verifying JWTs in the CareCard
+ecosystem. It also provides the shared request middleware used by `ms-*`
+services to accept either an `ms-auth` JWT or an opaque server-auth token
+introspected by `ms-auth`.
 
 ## Features
 
@@ -12,6 +15,9 @@ Utility package for reading, parsing, and verifying JWTs in the CareCard ecosyst
 - **Role Mapping**: Simple utility for translating internal role codes to human-readable names.
 - **Claims Extraction**: Easy extraction of `sub` (clientId) and other JWT payload claims.
 - **Expiration Management**: Helpers to check if a JWT is expired and calculate its remaining TTL.
+- **Service JWTs**: Helpers for verifying and extracting microservice-to-microservice JWTs with standard `iss`, `sub`, `aud`, `iat`, and `exp` claims.
+- **JWT or Server Auth**: Middleware helpers that verify normal JWTs locally and
+  call a service-provided introspector for opaque server-auth tokens.
 
 ## Installation
 
@@ -59,6 +65,74 @@ console.log(getNameOfRole('ad')); // Result: 'admin'
 console.log(getCodeOfRole('super_admin')); // Result: 'su'
 ```
 
+### Auth RLS Role Semantics
+
+`ms-auth` treats a JWT or server-auth payload containing `roles: ["ad"]` as the
+auth-service super-admin signal for its RLS policies. Consumers may map `ad` to
+UI/domain names such as `super_admin`, but middleware should preserve the
+original roles array on the request context so services can make
+database-context decisions consistently.
+
+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.
+
+### Service-To-Service JWTs
+
+Use service JWT verification helpers for backend service calls. The sending
+service signs the token with `@carecard/auth-util`. The receiving service uses
+this package to verify the token with the sending service public key and check
+the expected issuer and audience.
+
+```javascript
+const { jwtCreateServiceAuthorizationHeader } = require('@carecard/auth-util');
+const { jwtVerifyService } = require('@carecard/jwt-read');
+
+const authorization = jwtCreateServiceAuthorizationHeader({
+  issuer: 'ms-institutions',
+  audience: 'ms-auth',
+  privateKey: institutionsPrivateKey,
+});
+
+app.use(jwtVerifyService(institutionsPublicKey, 'ms-institutions', 'ms-auth', throwNotAuthorizedError));
+```
+
+Service JWT payloads follow standard JWT semantics:
+
+- `iss`: sending service
+- `sub`: sending service identity
+- `aud`: receiving service
+- `iat`: issued-at NumericDate
+- `exp`: expiration NumericDate
+
+### JWT Or Server-Auth Middleware
+
+Use the `OrServerAuth` helpers on app-facing `ms-*` routes that should accept
+both current authentication modes. The JWT path verifies locally with the
+`ms-auth` public key. The server-auth path calls the provided introspector,
+which should send the opaque token to
+`POST /api/v1/ms-auth/server-auth/introspect` with the receiving service's
+service JWT.
+
+```javascript
+const { jwtGetRoleCode, jwtVerifyOrServerAuth, jwtVerifyOrServerAuthAndHasRole } = require('@carecard/jwt-read');
+
+const verifyUser = jwtVerifyOrServerAuth(msAuthPublicKey, token => introspectServerAuthTokenWithMsAuth(token), throwNotAuthorizedError);
+
+const verifyAdmin = jwtVerifyOrServerAuthAndHasRole(
+  jwtGetRoleCode('admin'),
+  msAuthPublicKey,
+  token => introspectServerAuthTokenWithMsAuth(token),
+  throwNotAuthorizedError,
+);
+```
+
+The introspector must return claims for valid tokens. This package normalizes
+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.
+
 ## Testing
 
 Run tests using: