@carecard/jwt-read 3.0.10 → 3.1.12

package/index.d.ts

@@ -1,25 +1,56 @@
 /**
- * Utility functions for reading and verifying JWTs.
+ * Utility functions for authentication and authorization in the CareCard ecosystem.
  */
 
 import { Request, Response, NextFunction } from 'express';
 
 /**
- * Basic structure of a JWT payload as used in this package.
+ * Represents the standard JWT header structure.
+ */
+export interface JwtHeader {
+  /** The cryptographic algorithm used to secure the JWT. */
+  alg?: string;
+  /** The media type of the JWT. Defaults to 'JWT'. */
+  typ?: string;
+  /** Any other custom header fields. */
+  [key: string]: any;
+}
+
+/**
+ * Represents the standard JWT payload (claims) structure.
  */
 export interface JwtPayload {
-    client_id?: string;
-    exp?: number;
-    iat?: number;
-    roles?: string[];
-    [key: string]: any;
+  /** Issued at time, in seconds since the epoch. */
+  iat?: number;
+  /** Expiration time, in seconds since the epoch. */
+  exp?: number;
+  /** Not before time, in seconds since the epoch. */
+  nbf?: number;
+  /** Authentication time, in seconds since the epoch. */
+  auth_time?: number;
+  /** Subject (usually the client ID). */
+  sub?: string;
+  /** Roles assigned to the user. */
+  roles?: string[];
+  /** Any other custom payload fields. */
+  [key: string]: any;
+}
+
+/**
+ * Container for the decoded header and payload of a JWT.
+ */
+export interface JwtParts {
+  /** Decoded JWT header. */
+  header: JwtHeader;
+  /** Decoded JWT payload. */
+  payload: JwtPayload;
 }
 
 /**
  * Structure of the JWT object attached to the request.
  */
 export interface JwtRequestObject {
-    header: any;
+    header: JwtHeader;
     payload: JwtPayload;
     age?: number;
     jwtClientId: (req?: any) => string | undefined;
@@ -32,7 +63,7 @@ export interface JwtRequestObject {
  * Structure of the visitor object attached to the request.
  */
 export interface VisitorRequestObject {
-    header: any;
+    header: JwtHeader;
     payload: JwtPayload;
     visitorClientId: (req?: any) => string | undefined;
 }
@@ -45,78 +76,194 @@ export interface AuthenticatedRequest extends Request {
     visitor?: VisitorRequestObject | null;
 }
 
+
 /**
  * Returns a middleware that verifies a JWT from the 'Authorization: Bearer <token>' header
  * and extracts it into req.jwt. Throws an error if invalid.
  */
+export function jwtVerify(publicKey: string, customErrorFunction?: () => void): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Returns a middleware that verifies a JWT from a custom header and extracts it into req.jwt.
+ * Throws an error if invalid.
+ */
+export function jwtVerifyWebToken(publicKey: string, headerName: string, customErrorFunction?: () => void): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Returns a middleware that verifies a JWT from the 'Authorization: Bearer <token>' header
+ * and extracts it into req.jwt. Returns false instead of throwing if invalid.
+ */
+export function jwtVerifyNoThrow(publicKey: string): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Returns a middleware that verifies a JWT from a custom header and extracts it into req.jwt.
+ * Returns false instead of throwing if invalid.
+ */
+export function jwtVerifyWebTokenNoThrow(publicKey: string, headerName: string): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Returns a middleware that verifies a visitor token from the 'Visitor' header
+ * and extracts it into req.visitor. Returns false instead of throwing if invalid.
+ */
+export function jwtVerifyVisitorNoThrow(publicKey: string): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Returns the sub from the extracted JWT in req.jwt.
+ */
+export function jwtGetClientId(req?: any): string | undefined;
+
+/**
+ * Returns the sub from the extracted visitor token in req.visitor.
+ */
+export function jwtGetVisitorClientId(req?: any): string | undefined;
+
+/**
+ * Checks if the extracted JWT in req.jwt has expired.
+ */
+export function jwtIsExpired(req: any, jwtValiditySeconds?: number): boolean;
+export function jwtIsExpired(jwtValiditySeconds: number): boolean;
+export function jwtIsExpired(): boolean;
+
+/**
+ * Returns the age of the extracted JWT in seconds.
+ */
+export function jwtGetAgeInSeconds(req?: any): number;
+
+/**
+ * Returns a middleware that verifies the JWT and checks if the user has the required role.
+ */
+export function jwtVerifyAndHasRole(userRole: string, publicKey: string, customErrorFunction?: () => void): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Gets the full name of a role from its code (e.g., 'ad' -> 'admin').
+ */
+export function jwtGetRoleName(roleCode: string): string;
+
+/**
+ * Gets the code of a role from its name (e.g., 'admin' -> 'ad').
+ */
+export function jwtGetRoleCode(roleName: string): string;
+
+/**
+ * Validates the JWT from the Authorization header and extracts it into req.jwt.
+ */
+export function jwtValidateAndExtract(req: AuthenticatedRequest, publicKey: string, customErrorFunction?: () => void): void;
+
+/**
+ * Validates the JWT from a custom header and extracts it into req.jwt.
+ */
+export function jwtValidateAndExtractWebToken(req: AuthenticatedRequest, publicKey: string, headerName: string, customErrorFunction?: () => void): void;
+
+/**
+ * Validates the JWT from the Authorization header and extracts it into req.jwt (no-throw).
+ */
+export function jwtValidateAndExtractNoThrow(req: AuthenticatedRequest, publicKey: string): void;
+
+/**
+ * Validates the JWT from a custom header and extracts it into req.jwt (no-throw).
+ */
+export function jwtValidateAndExtractWebTokenNoThrow(req: AuthenticatedRequest, publicKey: string, headerName: string): void;
+
+/**
+ * Validates the visitor token from the 'Visitor' header and extracts it into req.visitor (no-throw).
+ */
+export function jwtValidateAndExtractVisitorNoThrow(req: AuthenticatedRequest, publicKey: string): void;
+
+
+/**
+ * Returns a middleware that verifies a JWT from the 'Authorization: Bearer <token>' header
+ * and extracts it into req.jwt. Throws an error if invalid.
+ * @deprecated use jwtVerify
+ */
 export function verifyJwt(publicKey: string, customErrorFunction?: () => void): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
 /**
  * Returns a middleware that verifies a JWT from a custom header and extracts it into req.jwt.
  * Throws an error if invalid.
+ * @deprecated use jwtVerifyWebToken
  */
 export function verifyWebToken(publicKey: string, headerName: string, customErrorFunction?: () => void): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
 /**
  * Returns a middleware that verifies a JWT from the 'Authorization: Bearer <token>' header
  * and extracts it into req.jwt. Returns false instead of throwing if invalid.
+ * @deprecated use jwtVerifyNoThrow
  */
 export function verifyJwtNoThrow(publicKey: string): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
 /**
  * Returns a middleware that verifies a JWT from a custom header and extracts it into req.jwt.
  * Returns false instead of throwing if invalid.
+ * @deprecated use jwtVerifyWebTokenNoThrow
  */
 export function verifyWebTokenNoThrow(publicKey: string, headerName: string): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
 /**
  * Returns a middleware that verifies a visitor token from the 'Visitor' header
  * and extracts it into req.visitor. Returns false instead of throwing if invalid.
+ * @deprecated use jwtVerifyVisitorNoThrow
  */
 export function verifyVisitorNoThrow(publicKey: string): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
 /**
- * Returns the client_id from the extracted JWT in req.jwt.
+ * Returns the sub from the extracted JWT in req.jwt.
+ * @deprecated use jwtGetClientId
  */
 export function jwtClientId(req?: any): string | undefined;
 
 /**
- * Returns the client_id from the extracted visitor token in req.visitor.
+ * Returns the sub from the extracted visitor token in req.visitor.
+ * @deprecated use jwtGetVisitorClientId
  */
 export function visitorClientId(req?: any): string | undefined;
 
 /**
  * Checks if the extracted JWT in req.jwt has expired.
+ * @deprecated use jwtIsExpired
  */
-export function isJwtExpired(req?: any, jwtValiditySeconds?: number): boolean;
+export function isJwtExpired(req: any, jwtValiditySeconds?: number): boolean;
+/** @deprecated use jwtIsExpired */
+export function isJwtExpired(jwtValiditySeconds: number): boolean;
+/** @deprecated use jwtIsExpired */
+export function isJwtExpired(): boolean;
 
 /**
  * Returns the age of the extracted JWT in seconds.
+ * @deprecated use jwtGetAgeInSeconds
  */
 export function jwtAgeInSeconds(req?: any): number;
 
 /**
  * Returns a middleware that verifies the JWT and checks if the user has the required role.
+ * @deprecated use jwtVerifyAndHasRole
  */
 export function verifyJwtAndRole(userRole: string, publicKey: string, customErrorFunction?: () => void): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
 /**
  * Throws a Used_Token error.
+ * @deprecated use jwtThrowUsedTokenError
  */
 export function throwUsedTokenError(): never;
 
+
 /**
  * Checks if the user in the extracted JWT has the specified role.
+ * @deprecated use jwtDoesJwtUserHasRole
  */
 export function doesJwtUserHasRole(req: any, userRole: string): boolean;
+/** @deprecated use jwtDoesJwtUserHasRole */
 export function doesJwtUserHasRole(userRole: string): boolean;
 
 /**
  * Gets the full name of a role from its code (e.g., 'ad' -> 'admin').
+ * @deprecated use jwtGetRoleName
  */
 export function getNameOfRole(roleCode: string): string;
 
+
 /**
  * Gets the code of a role from its name (e.g., 'admin' -> 'ad').
+ * @deprecated use jwtGetRoleCode
  */
 export function getCodeOfRole(roleName: string): string;
+

package/index.js

@@ -1,21 +1,51 @@
-const jwtLib = require( './lib/jwtLib' );
-const jwtRoles = require( './lib/jwtRoles' );
-
+const jwtLib = require('./lib/jwtLib');
+const jwtRoles = require('./lib/jwtRoles');
 
 module.exports = {
+    jwtVerify: jwtLib.verifyJwt,
+    jwtVerifyWebToken: jwtLib.verifyWebToken,
+    jwtVerifyNoThrow: jwtLib.verifyJwtNoThrow,
+    jwtVerifyWebTokenNoThrow: jwtLib.verifyWebTokenNoThrow,
+    jwtVerifyVisitorNoThrow: jwtLib.verifyVisitorNoThrow,
+    jwtGetClientId: jwtLib.jwtClientId,
+    jwtGetVisitorClientId: jwtLib.visitorClientId,
+    jwtIsExpired: jwtLib.isJwtExpired,
+    jwtGetAgeInSeconds: jwtLib.jwtAgeInSeconds,
+    jwtVerifyAndHasRole: jwtLib.verifyJwtAndRole,
+    jwtGetRoleName: jwtRoles.getNameOfRoleFromCode,
+    jwtGetRoleCode: jwtRoles.getCodeFromNameOfRole,
+    jwtValidateAndExtract: jwtLib.validateAndExtractJwtObject,
+    jwtValidateAndExtractWebToken: jwtLib.validateAndExtractWebToken,
+    jwtValidateAndExtractNoThrow: jwtLib.validateAndExtractJwtObjectNoThrow,
+    jwtValidateAndExtractWebTokenNoThrow: jwtLib.validateAndExtractWebTokenObjectNoThrow,
+    jwtValidateAndExtractVisitorNoThrow: jwtLib.validateAndExtractVisitorObjectNoThrow,
+
+    /** @deprecated use jwtVerify */
     verifyJwt: jwtLib.verifyJwt,
+    /** @deprecated use jwtVerifyWebToken */
     verifyWebToken: jwtLib.verifyWebToken,
+    /** @deprecated use jwtVerifyNoThrow */
     verifyJwtNoThrow: jwtLib.verifyJwtNoThrow,
+    /** @deprecated use jwtVerifyWebTokenNoThrow */
     verifyWebTokenNoThrow: jwtLib.verifyWebTokenNoThrow,
+    /** @deprecated use jwtVerifyVisitorNoThrow */
     verifyVisitorNoThrow: jwtLib.verifyVisitorNoThrow,
+    /** @deprecated use jwtGetClientId */
     jwtClientId: jwtLib.jwtClientId,
+    /** @deprecated use jwtGetVisitorClientId */
     visitorClientId: jwtLib.visitorClientId,
+    /** @deprecated use jwtIsExpired */
     isJwtExpired: jwtLib.isJwtExpired,
+    /** @deprecated use jwtGetAgeInSeconds */
     jwtAgeInSeconds: jwtLib.jwtAgeInSeconds,
+    /** @deprecated use jwtVerifyAndHasRole */
     verifyJwtAndRole: jwtLib.verifyJwtAndRole,
+    /** @deprecated use jwtThrowUsedTokenError */
     throwUsedTokenError: jwtLib.throwUsedTokenError,
+    /** @deprecated use jwtDoesJwtUserHasRole */
     doesJwtUserHasRole: jwtLib.doesJwtUserHasRole,
+    /** @deprecated use jwtGetRoleName */
     getNameOfRole: jwtRoles.getNameOfRoleFromCode,
+    /** @deprecated use jwtGetRoleCode */
     getCodeOfRole: jwtRoles.getCodeFromNameOfRole
 };
-

package/lib/jwtLib.js

@@ -1,5 +1,6 @@
 const {isJwtString} = require('@carecard/validate').validate;
-const {jwtUtilAuth} = require('@carecard/auth-util');
+const {jwtVerifySignedToken, jwtGetHeaderPayload} = require('@carecard/auth-util');
+
 const {
     throwLoginRequiredError,
     throwNotAuthorizedError
@@ -7,12 +8,12 @@ const {
 
 function jwtClientId(req) {
     const jwtObj = req?.jwt || this;
-    return jwtObj?.payload?.client_id;
+    return jwtObj?.payload?.sub;
 }
 
 function visitorClientId(req) {
     const visitorObj = req?.visitor || this;
-    return visitorObj?.payload?.client_id;
+    return visitorObj?.payload?.sub;
 }
 
 function doesJwtUserHasRole(req, userRole) {
@@ -24,11 +25,11 @@ function doesJwtUserHasRole(req, userRole) {
 
     const jwtObj = req?.jwt || this;
 
-    if (userRole && typeof userRole === "string") {
-        return jwtObj?.payload?.roles?.includes(userRole);
-    } else {
+    if (!userRole || typeof userRole !== "string" || !jwtObj?.payload?.roles || !Array.isArray(jwtObj.payload.roles)) {
         throwNotAuthorizedError();
     }
+
+    return jwtObj.payload.roles.includes(userRole);
 }
 
 function throwError(customErrorFunction) {
@@ -83,7 +84,7 @@ function validateAndExtractJwtObject(req, publicKey, customErrorFunction) {
 
     const jwtString = _validateJwt(req, customErrorFunction);
 
-    const isJwtSignatureValid = jwtUtilAuth.verifyJwtSignature(jwtString, publicKey);
+    const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
 
     if (jwtString && isJwtSignatureValid) {
         _extractJwtObject(req, jwtString, customErrorFunction);
@@ -99,7 +100,7 @@ function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunct
 
     const webTokenString = _validateWebToken(req, headerName, customErrorFunction);
 
-    const isJwtSignatureValid = jwtUtilAuth.verifyJwtSignature(webTokenString, publicKey);
+    const isJwtSignatureValid = jwtVerifySignedToken(webTokenString, publicKey);
 
     if (webTokenString && isJwtSignatureValid) {
         _extractJwtObject(req, webTokenString, customErrorFunction);
@@ -112,72 +113,15 @@ function validateAndExtractWebToken(req, publicKey, headerName, customErrorFunct
 }
 
 function validateAndExtractJwtObjectNoThrow(req, publicKey) {
-
-    try {
-
-        const jwtString = _validateJwtNoThrow(req);
-
-        const isJwtSignatureValid = jwtUtilAuth.verifyJwtSignature(jwtString, publicKey);
-
-        if (jwtString && isJwtSignatureValid) {
-            _extractJwtObjectNoThrow(req, jwtString);
-        } else {
-            req["jwt"] = null;
-        }
-
-    } catch (err) {
-
-        req["jwt"] = null;
-
-    }
-
-    return req;
+    return _validateAndExtractGenericNoThrow(req, publicKey, _validateJwtNoThrow, _extractJwtObjectNoThrow, "jwt");
 }
 
 function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName) {
-
-    try {
-
-        const jwtString = _validateWebTokenNoThrow(req, headerName);
-
-        const isJwtSignatureValid = jwtUtilAuth.verifyJwtSignature(jwtString, publicKey);
-
-        if (jwtString && isJwtSignatureValid) {
-            _extractJwtObjectNoThrow(req, jwtString);
-        } else {
-            req["jwt"] = null;
-        }
-
-    } catch (err) {
-
-        req["jwt"] = null;
-
-    }
-
-    return req;
+    return _validateAndExtractGenericNoThrow(req, publicKey, (r) => _validateWebTokenNoThrow(r, headerName), _extractJwtObjectNoThrow, "jwt");
 }
 
 function validateAndExtractVisitorObjectNoThrow(req, publicKey) {
-
-    try {
-
-        const jwtString = _validateVisitorNoThrow(req);
-
-        const isJwtSignatureValid = jwtUtilAuth.verifyJwtSignature(jwtString, publicKey);
-
-        if (jwtString && isJwtSignatureValid) {
-            _extractVisitorObjectNoThrow(req, jwtString);
-        } else {
-            req["visitor"] = null;
-        }
-
-    } catch (err) {
-
-        req["visitor"] = null;
-
-    }
-
-    return req;
+    return _validateAndExtractGenericNoThrow(req, publicKey, _validateVisitorNoThrow, _extractVisitorObjectNoThrow, "visitor");
 }
 
 function verifyJwtAndRole(role, publicKey, customErrorFunction) {
@@ -263,34 +207,62 @@ function _isLoginRequired(hasRequiredRole, customErrorFunction) {
 
 }
 
-function _extractJwtObject(req, jwt, customErrorFunction) {
+function _validateGenericNoThrow(req, headerName, extractor) {
+    let jwtRaw = req.get(headerName);
+    if (!jwtRaw) return null;
+    let jwt = extractor(jwtRaw);
+    return isJwtString(jwt) ? jwt : null;
+}
+
+function _validateGeneric(req, headerName, extractor, customErrorFunction) {
+    let jwtRaw = req.get(headerName);
+    let jwt = extractor(jwtRaw, customErrorFunction);
+    if (isJwtString(jwt)) return jwt;
+    throwError(customErrorFunction);
+    return null;
+}
+
+function _validateAndExtractGenericNoThrow(req, publicKey, validator, extractor, propertyName) {
+    try {
+        const jwtString = validator(req);
+        const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+
+        if (jwtString && isJwtSignatureValid) {
+            extractor(req, jwtString);
+        } else {
+            req[propertyName] = null;
+        }
+    } catch (err) {
+        if (req) req[propertyName] = null;
+        throw err;
+    }
+    return req;
+}
+
+function _extractGenericObjectNoThrow(req, jwt, attacher, propertyName) {
     if (jwt && typeof jwt === "string") {
-        const jwtObj = jwtUtilAuth.getHeaderPayloadFromJwt(jwt);
-        _attachJwtMethods(jwtObj);
-        req["jwt"] = jwtObj;
+        const obj = jwtGetHeaderPayload(jwt);
+        attacher(obj);
+        req[propertyName] = obj;
     } else {
+        if (req) req[propertyName] = null;
+    }
+}
+
+function _extractJwtObject(req, jwt, customErrorFunction) {
+    _extractJwtObjectNoThrow(req, jwt);
+
+    if (!req["jwt"]) {
         throwError(customErrorFunction);
     }
 }
 
 function _extractJwtObjectNoThrow(req, jwt) {
-    if (jwt && typeof jwt === "string") {
-        const jwtObj = jwtUtilAuth.getHeaderPayloadFromJwt(jwt);
-        _attachJwtMethods(jwtObj);
-        req["jwt"] = jwtObj;
-    } else {
-        req["jwt"] = null;
-    }
+    _extractGenericObjectNoThrow(req, jwt, _attachJwtMethods, "jwt");
 }
 
 function _extractVisitorObjectNoThrow(req, jwt) {
-    if (jwt && typeof jwt === "string") {
-        const visitorObj = jwtUtilAuth.getHeaderPayloadFromJwt(jwt);
-        _attachVisitorMethods(visitorObj);
-        req["visitor"] = visitorObj;
-    } else {
-        req["visitor"] = null;
-    }
+    _extractGenericObjectNoThrow(req, jwt, _attachVisitorMethods, "visitor");
 }
 
 function _attachJwtMethods(jwtObj) {
@@ -314,8 +286,10 @@ function _attachVisitorMethods(visitorObj) {
 
 async function _isJwtSignatureValid(jwt, publicKey, customErrorFunction) {
 
-    if (jwt && typeof jwt === "string") {
-        return jwtUtilAuth.verifyJwtSignature(jwt, publicKey)
+    const isValid = await _isJwtSignatureValidNoThrow(jwt, publicKey);
+
+    if (isValid) {
+        return isValid;
     } else {
         throwError(customErrorFunction);
     }
@@ -324,115 +298,37 @@ async function _isJwtSignatureValid(jwt, publicKey, customErrorFunction) {
 async function _isJwtSignatureValidNoThrow(jwt, publicKey) {
 
     if (jwt && typeof jwt === "string") {
-        return jwtUtilAuth.verifyJwtSignature(jwt, publicKey)
+        return jwtVerifySignedToken(jwt, publicKey)
     } else {
         return false;
     }
 }
 
 function _validateJwt(req, customErrorFunction) {
-
-    // Get from http header.
-    let jwtRaw = req.get("Authorization");
-
-    // Extract jwt from bearer schema.
-    let jwt = _extractJwt(jwtRaw, customErrorFunction);
-
-    // Validate characters string of jwt.
-    if (isJwtString(jwt)) {
-        return jwt;
-    } else {
-        throwError(customErrorFunction);
-    }
+    return _validateGeneric(req, "Authorization", _extractJwt, customErrorFunction);
 }
 
 function _validateWebToken(req, headerName, customErrorFunction) {
-
-    // Get from http header.
-    let jwtRaw = req.get(headerName);
-
-    // Extract jwt from bearer schema.
-    let webToken = _extractWebToken(jwtRaw, customErrorFunction);
-
-    // Validate characters string of jwt.
-    if (isJwtString(webToken)) {
-        return webToken;
-    } else {
-        throwError(customErrorFunction);
-    }
+    return _validateGeneric(req, headerName, _extractWebToken, customErrorFunction);
 }
 
 function _validateJwtNoThrow(req) {
-
-    // Get from http header.
-    let jwtRaw = req.get("Authorization");
-
-    if (!jwtRaw) {
-        return null;
-    }
-
-    // Extract jwt from bearer schema.
-    let jwt = _extractJwtNoThrow(jwtRaw);
-
-    // Validate characters string of jwt.
-    if (isJwtString(jwt)) {
-        return jwt;
-    }
-
-    return null;
+    return _validateGenericNoThrow(req, "Authorization", _extractJwtNoThrow);
 }
 
 function _validateWebTokenNoThrow(req, headerName) {
-
-    // Get from http header.
-    let jwtRaw = req.get(headerName);
-
-    if (!jwtRaw) {
-        return null;
-    }
-
-    // Extract jwt from bearer schema.
-    let webToken = _extractWebTokenNoThrow(jwtRaw);
-
-    // Validate characters string of jwt.
-    if (isJwtString(webToken)) {
-        return webToken;
-    }
-
-    return null;
+    return _validateGenericNoThrow(req, headerName, _extractWebTokenNoThrow);
 }
 
 function _validateVisitorNoThrow(req) {
-
-    // Get from http header.
-    let jwtRaw = req.get("Visitor");
-
-    if (!jwtRaw) {
-        return null;
-    }
-
-    // Extract jwt from bearer schema.
-    let jwt = _extractJwtNoThrow(jwtRaw);
-
-    // Validate characters string of jwt.
-    if (isJwtString(jwt)) {
-        return jwt;
-    }
-
-    return null;
+    return _validateGenericNoThrow(req, "Visitor", _extractJwtNoThrow);
 }
 
 function _extractJwt(jwtRaw, customErrorFunction) {
-    let jwtSplit = null;
-
-    if (jwtRaw && typeof jwtRaw === "string") {
-        jwtSplit = jwtRaw.split(" ");
-    } else {
-        throwError(customErrorFunction);
-    }
+    const jwt = _extractJwtNoThrow(jwtRaw);
 
-    if (jwtSplit[0]?.toLowerCase() === "bearer") {
-        return jwtSplit[1];
+    if (jwt !== null) {
+        return jwt;
     } else {
         throwError(customErrorFunction);
     }
@@ -441,9 +337,10 @@ function _extractJwt(jwtRaw, customErrorFunction) {
 }
 
 function _extractWebToken(jwtRaw, customErrorFunction) {
+    const webToken = _extractWebTokenNoThrow(jwtRaw);
 
-    if (jwtRaw && typeof jwtRaw === "string") {
-        return jwtRaw;
+    if (webToken !== null) {
+        return webToken;
     } else {
         throwError(customErrorFunction);
     }
@@ -481,8 +378,8 @@ module.exports = {
     _isJwtSignatureValid,
     _isJwtSignatureValidNoThrow,
     _extractJwtObject,
-    _extractJwtObjectNoThrow,
     validateAndExtractJwtObject,
+    validateAndExtractWebToken,
     jwtAgeInSeconds,
     isJwtExpired,
     doesJwtUserHasRole,
@@ -495,5 +392,20 @@ module.exports = {
     verifyJwtNoThrow,
     throwUsedTokenError,
     throwError,
-    verifyVisitorNoThrow
+    verifyVisitorNoThrow,
+    validateAndExtractVisitorObjectNoThrow,
+    validateAndExtractJwtObjectNoThrow,
+    validateAndExtractWebTokenObjectNoThrow,
+    _extractJwtNoThrow,
+    _extractWebTokenNoThrow,
+    _extractJwt,
+    _validateWebTokenNoThrow,
+    _validateVisitorNoThrow,
+    _extractJwtObjectNoThrow,
+    _extractVisitorObjectNoThrow,
+    _extractWebToken,
+    _isLoginRequired,
+    _attachJwtMethods,
+    _attachVisitorMethods,
+    _validateWebToken
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/jwt-read",
-  "version": "3.0.10",
+  "version": "3.1.12",
   "repository": {
     "type": "git",
     "url": "https://github.com/CareCard-ca/pkg-jwt-read.git"
@@ -10,12 +10,15 @@
   "types": "index.d.ts",
   "scripts": {
     "test": "export NODE_ENV=test && mocha --recursive",
-    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts"
+    "test:types": "tsc --noEmit && mocha -r ts-node/register test/types.test.ts",
+    "test:coverage": "tsc --noEmit && export NODE_ENV=test && nyc mocha --recursive -r ts-node/register 'test/**/*.{js,ts}'",
+    "prepare": "husky"
   },
   "keywords": [
     "auth",
     "utility",
-    "cryptology"
+    "cryptology",
+    "jwt"
   ],
   "author": "CareCard team",
   "license": "ISC",
@@ -23,13 +26,15 @@
     "@types/express": "5.0.6",
     "@types/mocha": "10.0.10",
     "@types/node": "25.5.0",
+    "husky": "^9.1.7",
     "mocha": "11.7.5",
+    "nyc": "^18.0.0",
     "ts-node": "10.9.2",
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "@carecard/auth-util": "3.0.10",
-    "@carecard/common-util": "3.0.10",
+    "@carecard/common-util": "3.1.11",
+    "@carecard/auth-util": "3.1.12",
     "@carecard/validate": "3.0.10"
   }
 }

package/readme.md

@@ -1,32 +1,88 @@
-# Jwt read utility
+# @carecard/jwt-read
 
-## Main Functionality
+![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)
 
-This is a collection of jwt reading functions.
+Utility package for reading, parsing, and verifying JWTs in the CareCard ecosystem.
 
-### Main functions
+## Features
 
-```js
-const jwtReader = require( '@chatpta/jwt-read' );
+- **JWT Verification**: Middleware-like utilities for signature and role verification.
+- **Express Integration**: Designed to work seamlessly with Express `req` objects.
+- **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.
+
+## Installation
+
+```bash
+npm install @carecard/jwt-read
 ```
 
-Read jwt
+## Usage
+
+### Middleware-like Verification (`verifyJwtAndRole`)
+
+```javascript
+const { verifyJwtAndRole, throwUsedTokenError } = require('@carecard/jwt-read');
 
-```js
-const jwtMiddleware = jwtReader.verifyJwtAndRole( "admin", publicKey, jwtReader.throwUsedTokenError );
-await jwtMiddleware( req, res, next );
+// Create a verification function for 'admin' role
+const verifyAdmin = verifyJwtAndRole('admin', publicKey, throwUsedTokenError);
+
+// In an Express controller/middleware
+try {
+    await verifyAdmin(req, res, next);
+    // If successful, req.jwt contains { header, payload }
+    console.log(req.jwt.payload.sub);
+} catch (error) {
+    // Handle verification error
+}
 ```
 
-Following the above ```req.jwt``` contains
-
-```js
-{
-    header: {
-    alg:...
-    }
-,
-    payload: {
-    ...
-    }
+### Direct JWT Reading
+
+```javascript
+const { verifyJwt, isJwtExpired } = require('@carecard/jwt-read');
+
+const result = verifyJwt(rawJwt, publicKey);
+if (result && !isJwtExpired(result)) {
+    console.log('JWT is valid and not expired:', result.payload);
 }
 ```
+
+### Role Utilities
+
+```javascript
+const { getNameOfRole, getCodeOfRole } = require('@carecard/jwt-read');
+
+console.log(getNameOfRole('ad')); // Result: 'admin'
+console.log(getCodeOfRole('super_admin')); // Result: 'su'
+```
+
+## Testing
+
+Run tests using:
+
+```bash
+npm test
+```
+
+To run tests with coverage:
+
+```bash
+npm run test:coverage
+```
+
+To run type tests:
+
+```bash
+npm run test:types
+```
+
+## Architecture
+
+The package is organized into several modules:
+- `jwtLib`: Main logic for JWT verification, extraction, and Express integration.
+- `jwtRoles`: Role mapping between internal codes and names.
+
+All modules are exported through the main `index.js`.