@carecard/jwt-read 3.25.0 → 3.27.0

package/.agents/skills/pkg-jwt-read-jwt-middleware-library/SKILL.md

@@ -113,7 +113,7 @@ depend on those folders being present.
 
 `lib/jwtLib.js` owns:
 
-- Signature verification using public keys.
+- Signature verification using parsed public Ed25519 JWKS values.
 - Middleware-like functions for Express, such as `verifyJwtAndRole`.
 - Service-to-service JWT verification and extraction helpers:
   `jwtValidateAndExtractService` and `jwtVerifyService`.
@@ -141,6 +141,13 @@ depend on those folders being present.
 Use `@carecard/auth-util` for JWT creation, decomposition, and signature
 verification. Do not duplicate cryptographic logic in this package.
 
+Every verification argument and nested `userAuthorization.verificationJwks`
+option must be a value returned by
+`parseJwtVerificationJwks(serializedJwks)`. Do not accept PEM text, RSA keys,
+raw JWK objects, missing-`kid` tokens, or single-key compatibility fallbacks.
+Verification selects the exact public key named by the token's RFC 7638
+thumbprint `kid`; unknown and retired kids fail closed.
+
 JWT creation functions do not belong in this package. Service-to-service token
 creation belongs in `@carecard/auth-util` via `jwtCreateServiceToken` and
 `jwtCreateServiceAuthorizationHeader`.
@@ -153,7 +160,7 @@ JWT context.
 Service JWTs must follow standard JWT claim semantics. They use `iss` for the
 sending service, `sub` for the sending service identity, `aud` for the
 receiving service, and NumericDate `iat`, `exp`, and optional `nbf` claims.
-Receivers must verify the signature with the sending service public key and
+Receivers must verify the signature with the sending service public JWKS and
 must check expected issuer, audience, subject, and lifetime. Do not add
 CareCard-specific replacement claims when a registered JWT claim covers the
 same meaning.

package/index.d.ts

@@ -3,6 +3,7 @@
  */
 
 import type { NextFunction, Request, Response } from 'express';
+import type { JwtVerificationJwks } from '@carecard/auth-util';
 
 export const DEFAULT_USER_AUTHORIZATION_HEADER_NAME: 'X-Authorization-Context';
 export const DEFAULT_USER_AUTHORIZATION_MAX_TOKEN_LENGTH: 2048;
@@ -118,7 +119,7 @@ export interface JwtRequestContext {
 }
 
 export interface UserAuthorizationTokenOptions {
-  publicKey?: string;
+  verificationJwks?: JwtVerificationJwks;
   headerName?: string;
   maxTokenLength?: number;
   expectedType?: string;
@@ -166,7 +167,7 @@ export type ServerAuthIntrospector = (
  * and extracts it into req.jwt. Throws an error if invalid.
  */
 export function jwtVerify(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
@@ -176,7 +177,7 @@ export function jwtVerify(
  * Throws an error if invalid.
  */
 export function jwtVerifyWebToken(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   headerName: string,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
@@ -187,7 +188,7 @@ export function jwtVerifyWebToken(
  * and extracts it into req.jwt. Returns false instead of throwing if invalid.
  */
 export function jwtVerifyNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
@@ -196,7 +197,7 @@ export function jwtVerifyNoThrow(
  * Returns false instead of throwing if invalid.
  */
 export function jwtVerifyWebTokenNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   headerName: string,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
@@ -205,7 +206,7 @@ export function jwtVerifyWebTokenNoThrow(
  * Returns middleware that verifies X-Authorization-Context and extracts it into req.userAuthorization.
  */
 export function jwtVerifyUserAuthorization(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationTokenOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
@@ -214,7 +215,7 @@ export function jwtVerifyUserAuthorization(
  * Returns middleware that verifies X-Authorization-Context into req.userAuthorization without throwing for invalid tokens.
  */
 export function jwtVerifyUserAuthorizationNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationTokenOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
@@ -223,7 +224,7 @@ export function jwtVerifyUserAuthorizationNoThrow(
  * and extracts it into req.visitor. Returns false instead of throwing if invalid.
  */
 export function jwtVerifyVisitorNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
@@ -254,7 +255,7 @@ export function jwtGetAgeInSeconds(req?: JwtRequestContext): number;
  */
 export function jwtVerifyAndHasRole(
   userRole: string,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
@@ -264,7 +265,7 @@ export function jwtVerifyAndHasRole(
  * Server-auth tokens are validated by the supplied introspector on every request.
  */
 export function jwtVerifyOrServerAuth(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   serverAuthIntrospector: ServerAuthIntrospector,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
@@ -276,7 +277,7 @@ export function jwtVerifyOrServerAuth(
  */
 export function jwtVerifyOrServerAuthAndHasRole(
   userRole: string,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   serverAuthIntrospector: ServerAuthIntrospector,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
@@ -318,7 +319,7 @@ export function jwtGetContext(req: JwtRequestContext): JwtContext;
  */
 export function jwtValidateAndExtract(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
 ): void;
@@ -328,7 +329,7 @@ export function jwtValidateAndExtract(
  */
 export function jwtValidateAndExtractUserAuthorization(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationTokenOptions,
 ): void;
@@ -338,7 +339,7 @@ export function jwtValidateAndExtractUserAuthorization(
  */
 export function jwtValidateAndExtractUserAuthorizationNoThrow(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationTokenOptions,
 ): void;
 
@@ -347,7 +348,7 @@ export function jwtValidateAndExtractUserAuthorizationNoThrow(
  */
 export function jwtValidateAndExtractService(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   expectedIssuer: string,
   expectedAudience: string,
   customErrorFunction?: () => void,
@@ -360,7 +361,7 @@ export function jwtValidateAndExtractService(
  */
 export function jwtValidateAndExtractOrServerAuth(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   serverAuthIntrospector: ServerAuthIntrospector,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
@@ -371,7 +372,7 @@ export function jwtValidateAndExtractOrServerAuth(
  */
 export function jwtValidateAndExtractWebToken(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   headerName: string,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
@@ -382,7 +383,7 @@ export function jwtValidateAndExtractWebToken(
  */
 export function jwtValidateAndExtractNoThrow(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationReadOptions,
 ): void;
 
@@ -391,7 +392,7 @@ export function jwtValidateAndExtractNoThrow(
  */
 export function jwtValidateAndExtractWebTokenNoThrow(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   headerName: string,
   options?: UserAuthorizationReadOptions,
 ): void;
@@ -401,7 +402,7 @@ export function jwtValidateAndExtractWebTokenNoThrow(
  */
 export function jwtValidateAndExtractVisitorNoThrow(
   req: AuthenticatedRequest,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationReadOptions,
 ): void;
 
@@ -409,7 +410,7 @@ export function jwtValidateAndExtractVisitorNoThrow(
  * Returns middleware that verifies a service-to-service JWT from one expected sender.
  */
 export function jwtVerifyService(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   expectedIssuer: string,
   expectedAudience: string,
   customErrorFunction?: () => void,
@@ -422,7 +423,7 @@ export function jwtVerifyService(
  * @deprecated use jwtVerify
  */
 export function verifyJwt(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
@@ -433,7 +434,7 @@ export function verifyJwt(
  * @deprecated use jwtVerifyWebToken
  */
 export function verifyWebToken(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   headerName: string,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
@@ -445,7 +446,7 @@ export function verifyWebToken(
  * @deprecated use jwtVerifyNoThrow
  */
 export function verifyJwtNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
@@ -455,7 +456,7 @@ export function verifyJwtNoThrow(
  * @deprecated use jwtVerifyWebTokenNoThrow
  */
 export function verifyWebTokenNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   headerName: string,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
@@ -466,7 +467,7 @@ export function verifyWebTokenNoThrow(
  * @deprecated use jwtVerifyVisitorNoThrow
  */
 export function verifyVisitorNoThrow(
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
@@ -504,7 +505,7 @@ export function jwtAgeInSeconds(req?: JwtRequestContext): number;
  */
 export function verifyJwtAndRole(
   userRole: string,
-  publicKey: string,
+  verificationJwks: JwtVerificationJwks,
   customErrorFunction?: () => void,
   options?: UserAuthorizationReadOptions,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;

package/lib/jwtLib.js

@@ -90,10 +90,10 @@ function jwtAgeInSeconds(req) {
 }
 
 // Pattern: Decorator - preserves JWT extraction while optionally adding a scoped authorization context.
-function validateAndExtractJwtObject(req, publicKey, customErrorFunction, options) {
+function validateAndExtractJwtObject(req, verificationJwks, customErrorFunction, options) {
   const jwtString = _validateJwt(req, customErrorFunction);
 
-  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, verificationJwks);
 
   if (jwtString && isJwtSignatureValid) {
     _extractJwtObject(req, jwtString, customErrorFunction);
@@ -108,10 +108,16 @@ function validateAndExtractJwtObject(req, publicKey, customErrorFunction, option
 }
 
 // Pattern: Decorator - keeps custom-header JWT behavior and optionally reads user authorization context.
-function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunction, options) {
+function validateAndExtractWebToken(
+  req,
+  verificationJwks,
+  headerName,
+  customErrorFunction,
+  options,
+) {
   const webTokenString = _validateWebToken(req, headerName, customErrorFunction);
 
-  const isJwtSignatureValid = jwtVerifySignedToken(webTokenString, publicKey);
+  const isJwtSignatureValid = jwtVerifySignedToken(webTokenString, verificationJwks);
 
   if (webTokenString && isJwtSignatureValid) {
     _extractJwtObject(req, webTokenString, customErrorFunction);
@@ -126,10 +132,10 @@ function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunct
 }
 
 // Pattern: Decorator - extends no-throw JWT extraction without changing req.jwt failure semantics.
-function validateAndExtractJwtObjectNoThrow(req, publicKey, options) {
+function validateAndExtractJwtObjectNoThrow(req, verificationJwks, options) {
   _validateAndExtractGenericNoThrow(
     req,
-    publicKey,
+    verificationJwks,
     _validateJwtNoThrow,
     _extractJwtObjectNoThrow,
     'jwt',
@@ -141,14 +147,14 @@ function validateAndExtractJwtObjectNoThrow(req, publicKey, options) {
 // Pattern: Decorator - keeps service-JWT checks distinct from optional user authorization context.
 function validateAndExtractServiceJwtObject(
   req,
-  publicKey,
+  verificationJwks,
   expectedIssuer,
   expectedAudience,
   customErrorFunction,
   options,
 ) {
   const jwtString = _validateJwt(req, customErrorFunction);
-  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, verificationJwks);
 
   if (jwtString && isJwtSignatureValid) {
     _extractJwtObject(req, jwtString, customErrorFunction);
@@ -168,12 +174,12 @@ function validateAndExtractServiceJwtObject(
 // Pattern: Decorator - normalizes primary auth first, then applies optional scoped authorization.
 async function validateAndExtractJwtOrServerAuthObject(
   req,
-  publicKey,
+  verificationJwks,
   serverAuthIntrospector,
   customErrorFunction,
   options,
 ) {
-  if (!tryValidateAndExtractJwtObject(req, publicKey)) {
+  if (!tryValidateAndExtractJwtObject(req, verificationJwks)) {
     const serverAuthToken = _validateServerAuthToken(req, customErrorFunction);
     const claims = await introspectServerAuthToken(
       serverAuthIntrospector,
@@ -189,10 +195,10 @@ async function validateAndExtractJwtOrServerAuthObject(
 }
 
 // Pattern: Decorator - extends custom-header no-throw extraction with optional user authorization context.
-function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName, options) {
+function validateAndExtractWebTokenObjectNoThrow(req, verificationJwks, headerName, options) {
   _validateAndExtractGenericNoThrow(
     req,
-    publicKey,
+    verificationJwks,
     r => _validateWebTokenNoThrow(r, headerName),
     _extractJwtObjectNoThrow,
     'jwt',
@@ -202,10 +208,10 @@ function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName, opt
 }
 
 // Pattern: Decorator - keeps visitor token extraction independent from optional user authorization context.
-function validateAndExtractVisitorObjectNoThrow(req, publicKey, options) {
+function validateAndExtractVisitorObjectNoThrow(req, verificationJwks, options) {
   _validateAndExtractGenericNoThrow(
     req,
-    publicKey,
+    verificationJwks,
     _validateVisitorNoThrow,
     _extractVisitorObjectNoThrow,
     'visitor',
@@ -215,10 +221,10 @@ function validateAndExtractVisitorObjectNoThrow(req, publicKey, options) {
 }
 
 // Pattern: Middleware - composes JWT verification, optional user authorization, and role checks.
-function verifyJwtAndRole(role, publicKey, customErrorFunction, options) {
+function verifyJwtAndRole(role, verificationJwks, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractJwtObject(req, publicKey, customErrorFunction, options);
+      validateAndExtractJwtObject(req, verificationJwks, customErrorFunction, options);
       const isRoleExist = doesJwtUserHasRole(req, role);
       _isLoginRequired(isRoleExist, customErrorFunction);
       next();
@@ -229,10 +235,10 @@ function verifyJwtAndRole(role, publicKey, customErrorFunction, options) {
 }
 
 // Pattern: Middleware - verifies the primary JWT and optionally attaches user authorization context.
-function verifyJwt(publicKey, customErrorFunction, options) {
+function verifyJwt(verificationJwks, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractJwtObject(req, publicKey, customErrorFunction, options);
+      validateAndExtractJwtObject(req, verificationJwks, customErrorFunction, options);
       next();
     } catch (err) {
       next(err);
@@ -242,7 +248,7 @@ function verifyJwt(publicKey, customErrorFunction, options) {
 
 // Pattern: Middleware - verifies service identity and optionally carries user authorization context.
 function verifyServiceJwt(
-  publicKey,
+  verificationJwks,
   expectedIssuer,
   expectedAudience,
   customErrorFunction,
@@ -252,7 +258,7 @@ function verifyServiceJwt(
     try {
       validateAndExtractServiceJwtObject(
         req,
-        publicKey,
+        verificationJwks,
         expectedIssuer,
         expectedAudience,
         customErrorFunction,
@@ -266,12 +272,17 @@ function verifyServiceJwt(
 }
 
 // Pattern: Middleware - accepts JWT or server-auth and then optionally verifies scoped authorization.
-function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFunction, options) {
+function verifyJwtOrServerAuth(
+  verificationJwks,
+  serverAuthIntrospector,
+  customErrorFunction,
+  options,
+) {
   return async function (req, res, next) {
     try {
       await validateAndExtractJwtOrServerAuthObject(
         req,
-        publicKey,
+        verificationJwks,
         serverAuthIntrospector,
         customErrorFunction,
         options,
@@ -286,7 +297,7 @@ function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFun
 // Pattern: Middleware - composes flexible auth, optional user authorization, and role checks.
 function verifyJwtOrServerAuthAndHasRole(
   role,
-  publicKey,
+  verificationJwks,
   serverAuthIntrospector,
   customErrorFunction,
   options,
@@ -295,7 +306,7 @@ function verifyJwtOrServerAuthAndHasRole(
     try {
       await validateAndExtractJwtOrServerAuthObject(
         req,
-        publicKey,
+        verificationJwks,
         serverAuthIntrospector,
         customErrorFunction,
         options,
@@ -310,10 +321,10 @@ function verifyJwtOrServerAuthAndHasRole(
 }
 
 // Pattern: Middleware - verifies a custom-header JWT and optionally scoped user authorization.
-function verifyWebToken(publicKey, headerName, customErrorFunction, options) {
+function verifyWebToken(verificationJwks, headerName, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractWebToken(req, publicKey, headerName, customErrorFunction, options);
+      validateAndExtractWebToken(req, verificationJwks, headerName, customErrorFunction, options);
       next();
     } catch (err) {
       next(err);
@@ -322,10 +333,10 @@ function verifyWebToken(publicKey, headerName, customErrorFunction, options) {
 }
 
 // Pattern: Middleware - preserves no-throw JWT behavior while clearing invalid optional context.
-function verifyJwtNoThrow(publicKey, options) {
+function verifyJwtNoThrow(verificationJwks, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractJwtObjectNoThrow(req, publicKey, options);
+      validateAndExtractJwtObjectNoThrow(req, verificationJwks, options);
       next();
     } catch (err) {
       next(err);
@@ -334,10 +345,10 @@ function verifyJwtNoThrow(publicKey, options) {
 }
 
 // Pattern: Middleware - preserves custom-header no-throw behavior with optional context extraction.
-function verifyWebTokenNoThrow(publicKey, headerName, options) {
+function verifyWebTokenNoThrow(verificationJwks, headerName, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName, options);
+      validateAndExtractWebTokenObjectNoThrow(req, verificationJwks, headerName, options);
       next();
     } catch (err) {
       next(err);
@@ -346,10 +357,10 @@ function verifyWebTokenNoThrow(publicKey, headerName, options) {
 }
 
 // Pattern: Middleware - keeps visitor extraction no-throw and independently reads optional context.
-function verifyVisitorNoThrow(publicKey, options) {
+function verifyVisitorNoThrow(verificationJwks, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractVisitorObjectNoThrow(req, publicKey, options);
+      validateAndExtractVisitorObjectNoThrow(req, verificationJwks, options);
       next();
     } catch (err) {
       next(err);
@@ -358,10 +369,15 @@ function verifyVisitorNoThrow(publicKey, options) {
 }
 
 // Pattern: Middleware - verifies only the scoped user authorization token.
-function verifyUserAuthorization(publicKey, customErrorFunction, options) {
+function verifyUserAuthorization(verificationJwks, customErrorFunction, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractUserAuthorizationObject(req, publicKey, customErrorFunction, options);
+      validateAndExtractUserAuthorizationObject(
+        req,
+        verificationJwks,
+        customErrorFunction,
+        options,
+      );
       next();
     } catch (err) {
       next(err);
@@ -370,10 +386,10 @@ function verifyUserAuthorization(publicKey, customErrorFunction, options) {
 }
 
 // Pattern: Middleware - reads scoped user authorization without throwing for invalid tokens.
-function verifyUserAuthorizationNoThrow(publicKey, options) {
+function verifyUserAuthorizationNoThrow(verificationJwks, options) {
   return function (req, res, next) {
     try {
-      validateAndExtractUserAuthorizationObjectNoThrow(req, publicKey, options);
+      validateAndExtractUserAuthorizationObjectNoThrow(req, verificationJwks, options);
       next();
     } catch (err) {
       next(err);
@@ -382,8 +398,13 @@ function verifyUserAuthorizationNoThrow(publicKey, options) {
 }
 
 // Pattern: Single Responsibility - validates and attaches only the scoped user authorization token.
-function validateAndExtractUserAuthorizationObject(req, publicKey, customErrorFunction, options) {
-  const config = createUserAuthorizationConfig(publicKey, options);
+function validateAndExtractUserAuthorizationObject(
+  req,
+  verificationJwks,
+  customErrorFunction,
+  options,
+) {
+  const config = createUserAuthorizationConfig(verificationJwks, options);
   const header = readUserAuthorizationHeader(req, config);
 
   if (header.present && isUserAuthorizationTokenAllowed(header.token, config)) {
@@ -399,8 +420,8 @@ function validateAndExtractUserAuthorizationObject(req, publicKey, customErrorFu
 }
 
 // Pattern: Single Responsibility - clears invalid scoped authorization without changing primary auth state.
-function validateAndExtractUserAuthorizationObjectNoThrow(req, publicKey, options) {
-  const config = createUserAuthorizationConfig(publicKey, options);
+function validateAndExtractUserAuthorizationObjectNoThrow(req, verificationJwks, options) {
+  const config = createUserAuthorizationConfig(verificationJwks, options);
   const header = readUserAuthorizationHeader(req, config);
 
   if (header.present && isUserAuthorizationTokenAllowed(header.token, config)) {
@@ -466,13 +487,13 @@ function _isLoginRequired(hasRequiredRole, customErrorFunction) {
 }
 
 // Pattern: Fail-Closed Probe - accepts a bearer JWT only when signature and lifetime are valid.
-function tryValidateAndExtractJwtObject(req, publicKey) {
+function tryValidateAndExtractJwtObject(req, verificationJwks) {
   const jwtString = _validateJwtNoThrow(req);
   if (!jwtString || !isJwtString(jwtString)) {
     return false;
   }
 
-  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, verificationJwks);
   if (!isJwtSignatureValid) {
     req.jwt = null;
     return false;
@@ -650,10 +671,10 @@ function requireActiveExtractedToken(req, propertyName, customErrorFunction) {
 }
 
 // Pattern: Factory - normalizes direct user authorization options into one config shape.
-function createUserAuthorizationConfig(publicKey, options) {
+function createUserAuthorizationConfig(verificationJwks, options) {
   return normalizeUserAuthorizationConfig({
     ...(options || {}),
-    publicKey,
+    verificationJwks,
   });
 }
 
@@ -668,7 +689,7 @@ function createOptionalUserAuthorizationConfig(options) {
 // Pattern: Pure Function - centralizes defaults for scoped authorization header verification.
 function normalizeUserAuthorizationConfig(options) {
   return {
-    publicKey: options?.publicKey,
+    verificationJwks: options?.verificationJwks,
     headerName: options?.headerName || DEFAULT_USER_AUTHORIZATION_HEADER_NAME,
     maxTokenLength: normalizePositiveInteger(
       options?.maxTokenLength,
@@ -717,7 +738,7 @@ function getRequestHeader(req, headerName) {
 
 // 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)) {
+  if (!token || !config.verificationJwks || !jwtVerifySignedToken(token, config.verificationJwks)) {
     return false;
   }
 
@@ -777,10 +798,16 @@ function _validateGeneric(req, headerName, extractor, customErrorFunction) {
 }
 
 // Pattern: Fail-Closed Extraction - optional tokens survive only valid signatures and lifetimes.
-function _validateAndExtractGenericNoThrow(req, publicKey, validator, extractor, propertyName) {
+function _validateAndExtractGenericNoThrow(
+  req,
+  verificationJwks,
+  validator,
+  extractor,
+  propertyName,
+) {
   try {
     const jwtString = validator(req);
-    const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+    const isJwtSignatureValid = jwtVerifySignedToken(jwtString, verificationJwks);
 
     if (jwtString && isJwtSignatureValid) {
       extractor(req, jwtString);
@@ -850,8 +877,8 @@ function _attachVisitorMethods(visitorObj) {
   }
 }
 
-async function _isJwtSignatureValid(jwt, publicKey, customErrorFunction) {
-  const isValid = await _isJwtSignatureValidNoThrow(jwt, publicKey);
+async function _isJwtSignatureValid(jwt, verificationJwks, customErrorFunction) {
+  const isValid = await _isJwtSignatureValidNoThrow(jwt, verificationJwks);
 
   if (isValid) {
     return isValid;
@@ -860,9 +887,9 @@ async function _isJwtSignatureValid(jwt, publicKey, customErrorFunction) {
   }
 }
 
-async function _isJwtSignatureValidNoThrow(jwt, publicKey) {
+async function _isJwtSignatureValidNoThrow(jwt, verificationJwks) {
   if (jwt && typeof jwt === 'string') {
-    return jwtVerifySignedToken(jwt, publicKey);
+    return jwtVerifySignedToken(jwt, verificationJwks);
   } else {
     return false;
   }

package/package.json

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

package/readme.md

@@ -52,9 +52,10 @@ npm install @carecard/jwt-read
 
 ```javascript
 const { verifyJwtAndRole, throwUsedTokenError } = require('@carecard/jwt-read');
+const { parseJwtVerificationJwks } = require('@carecard/auth-util');
 
-// Create a verification function for 'admin' role
-const verifyAdmin = verifyJwtAndRole('admin', publicKey, throwUsedTokenError);
+const verificationJwks = parseJwtVerificationJwks(process.env.MS_AUTH_JWT_VERIFICATION_JWKS);
+const verifyAdmin = verifyJwtAndRole('admin', verificationJwks, throwUsedTokenError);
 
 // In an Express controller/middleware
 try {
@@ -66,15 +67,12 @@ try {
 }
 ```
 
-### Direct JWT Reading
+### Bearer JWT Verification
 
 ```javascript
-const { verifyJwt, isJwtExpired } = require('@carecard/jwt-read');
+const { jwtVerify } = require('@carecard/jwt-read');
 
-const result = verifyJwt(rawJwt, publicKey);
-if (result && !isJwtExpired(result)) {
-  console.log('JWT is valid and not expired:', result.payload);
-}
+app.use(jwtVerify(verificationJwks));
 ```
 
 ### Role Utilities
@@ -103,8 +101,8 @@ Access level is conveyed by route middleware and endpoint placement, not by
 
 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.
+this package to verify the token by `kid` through the sending service's public
+JWKS and check the expected issuer and audience.
 
 ```javascript
 const { jwtCreateServiceAuthorizationHeader } = require('@carecard/auth-util');
@@ -113,10 +111,17 @@ const { jwtVerifyService } = require('@carecard/jwt-read');
 const authorization = jwtCreateServiceAuthorizationHeader({
   issuer: 'ms-institutions',
   audience: 'ms-auth',
-  privateKey: institutionsPrivateKey,
+  signingJwk: institutionsSigningJwk,
 });
 
-app.use(jwtVerifyService(institutionsPublicKey, 'ms-institutions', 'ms-auth', throwNotAuthorizedError));
+app.use(
+  jwtVerifyService(
+    institutionsVerificationJwks,
+    'ms-institutions',
+    'ms-auth',
+    throwNotAuthorizedError,
+  ),
+);
 ```
 
 Service JWT payloads follow standard JWT semantics:
@@ -131,19 +136,27 @@ Service JWT payloads follow standard JWT semantics:
 
 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,
+`ms-auth` public JWKS. 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 {
+  jwtGetRoleCode,
+  jwtVerifyOrServerAuth,
+  jwtVerifyOrServerAuthAndHasRole,
+} = require('@carecard/jwt-read');
+
+const verifyUser = jwtVerifyOrServerAuth(
+  msAuthVerificationJwks,
+  token => introspectServerAuthTokenWithMsAuth(token),
+  throwNotAuthorizedError,
+);
 
 const verifyAdmin = jwtVerifyOrServerAuthAndHasRole(
   jwtGetRoleCode('admin'),
-  msAuthPublicKey,
+  msAuthVerificationJwks,
   token => introspectServerAuthTokenWithMsAuth(token),
   throwNotAuthorizedError,
 );
@@ -171,7 +184,7 @@ local limit.
 const { jwtVerifyUserAuthorization } = require('@carecard/jwt-read');
 
 app.use(
-  jwtVerifyUserAuthorization(institutionsPublicKey, throwNotAuthorizedError, {
+  jwtVerifyUserAuthorization(institutionsVerificationJwks, throwNotAuthorizedError, {
     expectedType: 'carecard.authorization-context.scoped.v1',
     expectedIssuer: 'ms-institutions',
     expectedAudience: 'ms-documents',
@@ -184,16 +197,27 @@ 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',
+const verifyUser = jwtVerifyOrServerAuth(
+  msAuthVerificationJwks,
+  token => introspectServerAuthTokenWithMsAuth(token),
+  throwNotAuthorizedError,
+  {
+    userAuthorization: {
+      verificationJwks: institutionsVerificationJwks,
+      expectedType: 'carecard.authorization-context.scoped.v1',
+      expectedIssuer: 'ms-institutions',
+      expectedAudience: 'ms-documents',
+    },
   },
-});
+);
 ```
 
+Every verification value must come from
+`parseJwtVerificationJwks(serializedJwks)`. A JWKS may contain active and
+retiring public Ed25519 keys, so rotation adds the replacement verifier before
+switching signers and removes the retiring key only after the maximum JWT
+lifetime plus clock skew. Unknown or removed `kid` values fail closed.
+
 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