@carecard/jwt-read 3.1.16 → 3.1.18

package/lib/jwtLib.js

@@ -3,6 +3,9 @@ const { jwtVerifySignedToken, jwtGetHeaderPayload } = require('@carecard/auth-ut
 
 const { throwLoginRequiredError, throwNotAuthorizedError } = require('@carecard/common-util');
 
+const DEFAULT_USER_AUTHORIZATION_HEADER_NAME = 'X-Authorization-Context';
+const DEFAULT_USER_AUTHORIZATION_MAX_TOKEN_LENGTH = 2048;
+
 function jwtClientId(req) {
   const jwtObj = req?.jwt || this;
   return jwtObj?.payload?.sub;
@@ -70,13 +73,15 @@ function jwtAgeInSeconds(req) {
   }
 }
 
-function validateAndExtractJwtObject(req, publicKey, customErrorFunction) {
+// Pattern: Decorator - preserves JWT extraction while optionally adding a scoped authorization context.
+function validateAndExtractJwtObject(req, publicKey, customErrorFunction, options) {
   const jwtString = _validateJwt(req, customErrorFunction);
 
   const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
 
   if (jwtString && isJwtSignatureValid) {
     _extractJwtObject(req, jwtString, customErrorFunction);
+    validateAndExtractOptionalUserAuthorizationObject(req, options, customErrorFunction);
   } else {
     req['jwt'] = null;
     throwError(customErrorFunction);
@@ -85,13 +90,15 @@ function validateAndExtractJwtObject(req, publicKey, customErrorFunction) {
   return req;
 }
 
-function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunction) {
+// Pattern: Decorator - keeps custom-header JWT behavior and optionally reads user authorization context.
+function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunction, options) {
   const webTokenString = _validateWebToken(req, headerName, customErrorFunction);
 
   const isJwtSignatureValid = jwtVerifySignedToken(webTokenString, publicKey);
 
   if (webTokenString && isJwtSignatureValid) {
     _extractJwtObject(req, webTokenString, customErrorFunction);
+    validateAndExtractOptionalUserAuthorizationObject(req, options, customErrorFunction);
   } else {
     req['jwt'] = null;
     throwError(customErrorFunction);
@@ -100,49 +107,68 @@ function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunct
   return req;
 }
 
-function validateAndExtractJwtObjectNoThrow(req, publicKey) {
-  return _validateAndExtractGenericNoThrow(req, publicKey, _validateJwtNoThrow, _extractJwtObjectNoThrow, 'jwt');
+// Pattern: Decorator - extends no-throw JWT extraction without changing req.jwt failure semantics.
+function validateAndExtractJwtObjectNoThrow(req, publicKey, options) {
+  _validateAndExtractGenericNoThrow(req, publicKey, _validateJwtNoThrow, _extractJwtObjectNoThrow, 'jwt');
+  validateAndExtractOptionalUserAuthorizationObjectNoThrow(req, options);
+  return req;
 }
 
-function validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction) {
+// Pattern: Decorator - keeps service-JWT checks distinct from optional user authorization context.
+function validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction, options) {
   const jwtString = _validateJwt(req, customErrorFunction);
   const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
 
   if (jwtString && isJwtSignatureValid) {
     _extractJwtObject(req, jwtString, customErrorFunction);
-  } else if (req) {
-    req.jwt = null;
+  } else {
+    /* istanbul ignore else */
+    if (req) {
+      req.jwt = null;
+    }
   }
 
   if (!req?.jwt || !_isServiceJwtFor(req.jwt.payload, expectedIssuer, expectedAudience)) {
+    /* istanbul ignore else */
     if (req) req.jwt = null;
     throwError(customErrorFunction);
   }
 
+  validateAndExtractOptionalUserAuthorizationObject(req, options, customErrorFunction);
   return req;
 }
 
-async function validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction) {
-  if (tryValidateAndExtractJwtObject(req, publicKey)) return req;
+// Pattern: Decorator - normalizes primary auth first, then applies optional scoped authorization.
+async function validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction, options) {
+  if (!tryValidateAndExtractJwtObject(req, publicKey)) {
+    const serverAuthToken = _validateServerAuthToken(req, customErrorFunction);
+    const claims = await introspectServerAuthToken(serverAuthIntrospector, serverAuthToken, req, customErrorFunction);
+    attachServerAuthClaims(req, claims, customErrorFunction);
+  }
 
-  const serverAuthToken = _validateServerAuthToken(req, customErrorFunction);
-  const claims = await introspectServerAuthToken(serverAuthIntrospector, serverAuthToken, req, customErrorFunction);
-  attachServerAuthClaims(req, claims, customErrorFunction);
+  validateAndExtractOptionalUserAuthorizationObject(req, options, customErrorFunction);
   return req;
 }
 
-function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName) {
-  return _validateAndExtractGenericNoThrow(req, publicKey, r => _validateWebTokenNoThrow(r, headerName), _extractJwtObjectNoThrow, 'jwt');
+// Pattern: Decorator - extends custom-header no-throw extraction with optional user authorization context.
+function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName, options) {
+  _validateAndExtractGenericNoThrow(req, publicKey, r => _validateWebTokenNoThrow(r, headerName), _extractJwtObjectNoThrow, 'jwt');
+  validateAndExtractOptionalUserAuthorizationObjectNoThrow(req, options);
+  return req;
 }
 
-function validateAndExtractVisitorObjectNoThrow(req, publicKey) {
-  return _validateAndExtractGenericNoThrow(req, publicKey, _validateVisitorNoThrow, _extractVisitorObjectNoThrow, 'visitor');
+// Pattern: Decorator - keeps visitor token extraction independent from optional user authorization context.
+function validateAndExtractVisitorObjectNoThrow(req, publicKey, options) {
+  _validateAndExtractGenericNoThrow(req, publicKey, _validateVisitorNoThrow, _extractVisitorObjectNoThrow, 'visitor');
+  validateAndExtractOptionalUserAuthorizationObjectNoThrow(req, options);
+  return req;
 }
 
-function verifyJwtAndRole(role, publicKey, customErrorFunction) {
+// Pattern: Middleware - composes JWT verification, optional user authorization, and role checks.
+function verifyJwtAndRole(role, publicKey, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractJwtObject(req, publicKey, customErrorFunction);
+      validateAndExtractJwtObject(req, publicKey, customErrorFunction, options);
       const isRoleExist = doesJwtUserHasRole(req, role);
       _isLoginRequired(isRoleExist, customErrorFunction);
       next();
@@ -152,10 +178,11 @@ function verifyJwtAndRole(role, publicKey, customErrorFunction) {
   };
 }
 
-function verifyJwt(publicKey, customErrorFunction) {
+// Pattern: Middleware - verifies the primary JWT and optionally attaches user authorization context.
+function verifyJwt(publicKey, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractJwtObject(req, publicKey, customErrorFunction);
+      validateAndExtractJwtObject(req, publicKey, customErrorFunction, options);
       next();
     } catch (err) {
       next(err);
@@ -163,10 +190,11 @@ function verifyJwt(publicKey, customErrorFunction) {
   };
 }
 
-function verifyServiceJwt(publicKey, expectedIssuer, expectedAudience, customErrorFunction) {
+// Pattern: Middleware - verifies service identity and optionally carries user authorization context.
+function verifyServiceJwt(publicKey, expectedIssuer, expectedAudience, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction);
+      validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction, options);
       next();
     } catch (err) {
       next(err);
@@ -174,10 +202,11 @@ function verifyServiceJwt(publicKey, expectedIssuer, expectedAudience, customErr
   };
 }
 
-function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFunction) {
+// Pattern: Middleware - accepts JWT or server-auth and then optionally verifies scoped authorization.
+function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFunction, options) {
   return async function (req, res, next) {
     try {
-      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction);
+      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction, options);
       next();
     } catch (err) {
       next(err);
@@ -185,10 +214,11 @@ function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFun
   };
 }
 
-function verifyJwtOrServerAuthAndHasRole(role, publicKey, serverAuthIntrospector, customErrorFunction) {
+// Pattern: Middleware - composes flexible auth, optional user authorization, and role checks.
+function verifyJwtOrServerAuthAndHasRole(role, publicKey, serverAuthIntrospector, customErrorFunction, options) {
   return async function (req, res, next) {
     try {
-      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction);
+      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction, options);
       const isRoleExist = doesJwtUserHasRole(req, role);
       _isLoginRequired(isRoleExist, customErrorFunction);
       next();
@@ -198,10 +228,23 @@ function verifyJwtOrServerAuthAndHasRole(role, publicKey, serverAuthIntrospector
   };
 }
 
-function verifyWebToken(publicKey, headerName, customErrorFunction) {
+// Pattern: Middleware - verifies a custom-header JWT and optionally scoped user authorization.
+function verifyWebToken(publicKey, headerName, customErrorFunction, options) {
+  return function (req, res, next) {
+    try {
+      validateAndExtractWebToken(req, publicKey, headerName, customErrorFunction, options);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+// Pattern: Middleware - preserves no-throw JWT behavior while clearing invalid optional context.
+function verifyJwtNoThrow(publicKey, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractWebToken(req, publicKey, headerName, customErrorFunction);
+      validateAndExtractJwtObjectNoThrow(req, publicKey, options);
       next();
     } catch (err) {
       next(err);
@@ -209,10 +252,11 @@ function verifyWebToken(publicKey, headerName, customErrorFunction) {
   };
 }
 
-function verifyJwtNoThrow(publicKey) {
+// Pattern: Middleware - preserves custom-header no-throw behavior with optional context extraction.
+function verifyWebTokenNoThrow(publicKey, headerName, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractJwtObjectNoThrow(req, publicKey);
+      validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName, options);
       next();
     } catch (err) {
       next(err);
@@ -220,10 +264,11 @@ function verifyJwtNoThrow(publicKey) {
   };
 }
 
-function verifyWebTokenNoThrow(publicKey, headerName) {
+// Pattern: Middleware - keeps visitor extraction no-throw and independently reads optional context.
+function verifyVisitorNoThrow(publicKey, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName);
+      validateAndExtractVisitorObjectNoThrow(req, publicKey, options);
       next();
     } catch (err) {
       next(err);
@@ -231,10 +276,11 @@ function verifyWebTokenNoThrow(publicKey, headerName) {
   };
 }
 
-function verifyVisitorNoThrow(publicKey) {
+// Pattern: Middleware - verifies only the scoped user authorization token.
+function verifyUserAuthorization(publicKey, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractVisitorObjectNoThrow(req, publicKey);
+      validateAndExtractUserAuthorizationObject(req, publicKey, customErrorFunction, options);
       next();
     } catch (err) {
       next(err);
@@ -242,6 +288,88 @@ function verifyVisitorNoThrow(publicKey) {
   };
 }
 
+// Pattern: Middleware - reads scoped user authorization without throwing for invalid tokens.
+function verifyUserAuthorizationNoThrow(publicKey, options) {
+  return function (req, res, next) {
+    try {
+      validateAndExtractUserAuthorizationObjectNoThrow(req, publicKey, options);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+// Pattern: Single Responsibility - validates and attaches only the scoped user authorization token.
+function validateAndExtractUserAuthorizationObject(req, publicKey, customErrorFunction, options) {
+  const config = createUserAuthorizationConfig(publicKey, options);
+  const header = readUserAuthorizationHeader(req, config);
+
+  if (header.present && isUserAuthorizationTokenAllowed(header.token, config)) {
+    _extractUserAuthorizationObjectNoThrow(req, header.token);
+  } else {
+    if (req) req.userAuthorization = null;
+    throwError(customErrorFunction);
+  }
+
+  return req;
+}
+
+// Pattern: Single Responsibility - clears invalid scoped authorization without changing primary auth state.
+function validateAndExtractUserAuthorizationObjectNoThrow(req, publicKey, options) {
+  const config = createUserAuthorizationConfig(publicKey, options);
+  const header = readUserAuthorizationHeader(req, config);
+
+  if (header.present && isUserAuthorizationTokenAllowed(header.token, config)) {
+    _extractUserAuthorizationObjectNoThrow(req, header.token);
+  } else if (req) {
+    req.userAuthorization = null;
+  }
+
+  return req;
+}
+
+// Pattern: Guard Clause - skips optional context handling unless a caller explicitly configured it.
+function validateAndExtractOptionalUserAuthorizationObject(req, options, customErrorFunction) {
+  const config = createOptionalUserAuthorizationConfig(options);
+  if (!config) return req;
+
+  const header = readUserAuthorizationHeader(req, config);
+  if (!header.present) {
+    /* istanbul ignore else */
+    if (req) req.userAuthorization = null;
+    return req;
+  }
+
+  if (isUserAuthorizationTokenAllowed(header.token, config)) {
+    _extractUserAuthorizationObjectNoThrow(req, header.token);
+  } else {
+    /* istanbul ignore else */
+    if (req) req.userAuthorization = null;
+    throwError(customErrorFunction);
+  }
+
+  return req;
+}
+
+// Pattern: Guard Clause - optional no-throw context extraction never changes primary auth results.
+function validateAndExtractOptionalUserAuthorizationObjectNoThrow(req, options) {
+  const config = createOptionalUserAuthorizationConfig(options);
+  if (!config) return req;
+
+  const header = readUserAuthorizationHeader(req, config);
+  if (header.present && isUserAuthorizationTokenAllowed(header.token, config)) {
+    _extractUserAuthorizationObjectNoThrow(req, header.token);
+  } else {
+    /* istanbul ignore else */
+    if (req) {
+      req.userAuthorization = null;
+    }
+  }
+
+  return req;
+}
+
 function throwUsedTokenError() {
   throw new Error('Used_Token');
 }
@@ -261,6 +389,7 @@ function tryValidateAndExtractJwtObject(req, publicKey) {
 
   const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
   if (!isJwtSignatureValid) {
+    /* istanbul ignore else */
     if (req) req.jwt = null;
     return false;
   }
@@ -371,6 +500,91 @@ function isJwtPayloadNotYetValid(payload) {
   return Math.floor(Date.now() / 1000) < nbf;
 }
 
+// Pattern: Factory - normalizes direct user authorization options into one config shape.
+function createUserAuthorizationConfig(publicKey, options) {
+  return normalizeUserAuthorizationConfig({
+    ...(options || {}),
+    publicKey,
+  });
+}
+
+// Pattern: Factory - detects optional user authorization configuration without affecting legacy callers.
+function createOptionalUserAuthorizationConfig(options) {
+  if (!options || !Object.prototype.hasOwnProperty.call(options, 'userAuthorization')) return null;
+  return normalizeUserAuthorizationConfig(options.userAuthorization || {});
+}
+
+// Pattern: Pure Function - centralizes defaults for scoped authorization header verification.
+function normalizeUserAuthorizationConfig(options) {
+  return {
+    publicKey: options?.publicKey,
+    headerName: options?.headerName || DEFAULT_USER_AUTHORIZATION_HEADER_NAME,
+    maxTokenLength: normalizePositiveInteger(options?.maxTokenLength, DEFAULT_USER_AUTHORIZATION_MAX_TOKEN_LENGTH),
+    expectedType: options?.expectedType,
+    expectedIssuer: options?.expectedIssuer,
+    expectedAudience: options?.expectedAudience,
+  };
+}
+
+// Pattern: Pure Function - keeps numeric option validation deterministic and local.
+function normalizePositiveInteger(value, defaultValue) {
+  const normalized = Number(value);
+  return Number.isInteger(normalized) && normalized > 0 ? normalized : defaultValue;
+}
+
+// Pattern: Single Responsibility - reads only the configured header and never logs token material.
+function readUserAuthorizationHeader(req, config) {
+  const rawToken = getRequestHeader(req, config.headerName);
+  const present = rawToken !== undefined && rawToken !== null;
+  if (!present || typeof rawToken !== 'string') return { present, token: null };
+
+  const token = rawToken.trim();
+  if (!token || token.length > config.maxTokenLength || !isJwtString(token)) return { present: true, token: null };
+  return { present: true, token };
+}
+
+// Pattern: Adapter - supports Express case-insensitive headers and simple test doubles.
+function getRequestHeader(req, headerName) {
+  const value = req?.get?.(headerName);
+  if (value !== undefined && value !== null) return value;
+
+  const lowerCaseHeaderName = headerName.toLowerCase();
+  if (lowerCaseHeaderName === headerName) return value;
+  return req?.get?.(lowerCaseHeaderName);
+}
+
+// Pattern: Single Responsibility - verifies signature and registered JWT time claims for user authorization.
+function isUserAuthorizationTokenAllowed(token, config) {
+  if (!token || !config.publicKey || !jwtVerifySignedToken(token, config.publicKey)) return false;
+
+  const payload = readJwtPayloadNoThrow(token);
+  if (!payload) return false;
+  if (isJwtPayloadIssuedInFuture(payload)) return false;
+  if (isJwtPayloadExpired(payload)) return false;
+  if (isJwtPayloadNotYetValid(payload)) return false;
+  if (config.expectedType && payload.typ !== config.expectedType) return false;
+  if (config.expectedIssuer && payload.iss !== config.expectedIssuer) return false;
+  if (!expectedAudienceMatches(payload.aud, config.expectedAudience)) return false;
+
+  return true;
+}
+
+// Pattern: Pure Function - decodes payload defensively after signature and shape checks.
+function readJwtPayloadNoThrow(token) {
+  try {
+    return jwtGetHeaderPayload(token)?.payload || null;
+  } catch {
+    return null;
+  }
+}
+
+// Pattern: Pure Function - supports either one expected audience or a small allowed set.
+function expectedAudienceMatches(actualAudience, expectedAudience) {
+  if (expectedAudience === undefined || expectedAudience === null || expectedAudience === '') return true;
+  if (Array.isArray(expectedAudience)) return expectedAudience.some(audience => payloadAudienceMatches(actualAudience, audience));
+  return payloadAudienceMatches(actualAudience, expectedAudience);
+}
+
 function _validateGenericNoThrow(req, headerName, extractor) {
   let jwtRaw = req.get(headerName);
   if (!jwtRaw) return null;
@@ -429,6 +643,10 @@ function _extractVisitorObjectNoThrow(req, jwt) {
   _extractGenericObjectNoThrow(req, jwt, _attachVisitorMethods, 'visitor');
 }
 
+function _extractUserAuthorizationObjectNoThrow(req, jwt) {
+  _extractGenericObjectNoThrow(req, jwt, () => {}, 'userAuthorization');
+}
+
 function _attachJwtMethods(jwtObj) {
   if (jwtObj) {
     Object.defineProperties(jwtObj, {
@@ -540,6 +758,8 @@ module.exports = {
   _isJwtSignatureValidNoThrow,
   _extractJwtObject,
   validateAndExtractJwtObject,
+  validateAndExtractUserAuthorizationObject,
+  validateAndExtractUserAuthorizationObjectNoThrow,
   validateAndExtractServiceJwtObject,
   validateAndExtractJwtOrServerAuthObject,
   validateAndExtractWebToken,
@@ -553,6 +773,8 @@ module.exports = {
   verifyJwtOrServerAuth,
   verifyJwtOrServerAuthAndHasRole,
   verifyJwt,
+  verifyUserAuthorization,
+  verifyUserAuthorizationNoThrow,
   verifyWebTokenNoThrow,
   verifyWebToken,
   verifyJwtNoThrow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/jwt-read",
-  "version": "3.1.16",
+  "version": "3.1.18",
   "repository": {
     "type": "git",
     "url": "https://github.com/CareCard-ca/pkg-jwt-read.git"
@@ -41,8 +41,8 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
+    "@carecard/auth-util": "3.1.16",
     "@carecard/common-util": "3.1.15",
-    "@carecard/auth-util": "3.1.15",
-    "@carecard/validate": "3.1.24"
+    "@carecard/validate": "3.1.27"
   }
 }

package/readme.md

@@ -18,6 +18,9 @@ introspected by `ms-auth`.
 - **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.
+- **Scoped User Authorization**: Optional `X-Authorization-Context`
+  verification attaches compact scoped authorization claims to
+  `req.userAuthorization` without replacing `req.jwt`.
 
 ## Installation
 
@@ -133,6 +136,44 @@ 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.
 
+### Scoped User Authorization Context
+
+Use `jwtVerifyUserAuthorization` when a route needs to verify only the compact
+authorization-context token carried in `X-Authorization-Context`. The token is
+read as a raw JWT header value, not as `Bearer <token>`.
+
+```javascript
+const { jwtVerifyUserAuthorization } = require('@carecard/jwt-read');
+
+app.use(
+  jwtVerifyUserAuthorization(institutionsPublicKey, throwNotAuthorizedError, {
+    expectedType: 'carecard.authorization-context.scoped.v1',
+    expectedIssuer: 'ms-institutions',
+    expectedAudience: 'ms-documents',
+  }),
+);
+```
+
+Existing JWT verification helpers can also read the header by passing an
+optional trailing options object. This preserves current `req.jwt` behavior and
+adds decoded scoped claims to `req.userAuthorization`.
+
+```javascript
+const verifyUser = jwtVerifyOrServerAuth(msAuthPublicKey, token => introspectServerAuthTokenWithMsAuth(token), throwNotAuthorizedError, {
+  userAuthorization: {
+    publicKey: institutionsPublicKey,
+    expectedType: 'carecard.authorization-context.scoped.v1',
+    expectedIssuer: 'ms-institutions',
+    expectedAudience: 'ms-documents',
+  },
+});
+```
+
+When the optional reader is configured, a missing `X-Authorization-Context`
+leaves `req.userAuthorization` as `null`. If the header is present but invalid,
+throwing middleware fails closed. No-throw middleware clears
+`req.userAuthorization` and continues.
+
 ## Testing
 
 Run tests using: