@carecard/auth-util 3.1.13 → 3.1.16

package/index.d.ts

@@ -2,80 +2,114 @@
  * Utility functions for authentication and authorization in the CareCard ecosystem.
  */
 
-import {Request} from 'express';
+import { Request } from 'express';
 
 /**
  * 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;
+  /** 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;
+  /** Any other custom header fields. */
+  [key: string]: any;
 }
 
 /**
  * Represents the standard JWT payload (claims) structure.
  */
 export interface JwtPayload {
-    /** 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[];
+  /** 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;
+  /** Any other custom payload fields. */
+  [key: string]: any;
+}
+
+/**
+ * Claims used by service-to-service JWTs.
+ */
+export interface ServiceJwtPayload extends JwtPayload {
+  /** Issuing microservice name, for example 'ms-institutions'. */
+  iss: string;
+  /** Receiving microservice name or names. */
+  aud: string | string[];
+  /** Subject. Defaults to the issuing microservice name. */
+  sub: string;
+}
+
+/**
+ * Options for creating a service-to-service JWT.
+ */
+export interface ServiceJwtOptions {
+  /** Issuing microservice name, for example 'ms-institutions'. */
+  issuer: string;
+  /** Receiving microservice name or names. */
+  audience: string | string[];
+  /** Private key owned by the issuing microservice. */
+  privateKey: string;
+  /** Subject claim. Defaults to issuer. */
+  subject?: string;
+  /** Issued-at timestamp in seconds or milliseconds. Defaults to now. */
+  issuedAt?: number;
+  /** Token lifetime in seconds. Defaults to 60. */
+  expiresInSeconds?: number;
+  /** JWT signing algorithm. Defaults to EdDSA. */
+  algorithm?: string;
+  /** Additional non-sensitive JWT claims. */
+  claims?: Record<string, unknown>;
 }
 
 /**
  * Container for the decoded header and payload of a JWT.
  */
 export interface JwtParts {
-    /** Decoded JWT header. */
-    header: JwtHeader;
-    /** Decoded JWT payload. */
-    payload: JwtPayload;
+  /** Decoded JWT header. */
+  header: JwtHeader;
+  /** Decoded JWT payload. */
+  payload: JwtPayload;
 }
 
 /**
  * Structure of the JWT object attached to the request.
  */
 export interface JwtRequestObject {
-    header: JwtHeader;
-    payload: JwtPayload;
-    age?: number;
-    jwtClientId: (req?: any) => string | undefined;
-    doesJwtUserHasRole: (role: string) => boolean;
-    isJwtExpired: (jwtValiditySeconds?: number) => boolean;
-    jwtAgeInSeconds: (req?: any) => number;
+  header: JwtHeader;
+  payload: JwtPayload;
+  age?: number;
+  jwtClientId: (req?: any) => string | undefined;
+  doesJwtUserHasRole: (role: string) => boolean;
+  isJwtExpired: (jwtValiditySeconds?: number) => boolean;
+  jwtAgeInSeconds: (req?: any) => number;
 }
 
 /**
  * Structure of the visitor object attached to the request.
  */
 export interface VisitorRequestObject {
-    header: JwtHeader;
-    payload: JwtPayload;
-    visitorClientId: (req?: any) => string | undefined;
+  header: JwtHeader;
+  payload: JwtPayload;
+  visitorClientId: (req?: any) => string | undefined;
 }
 
 /**
  * Extended Express Request to include jwt and visitor objects.
  */
 export interface AuthenticatedRequest extends Request {
-    jwt?: JwtRequestObject | null;
-    visitor?: VisitorRequestObject | null;
+  jwt?: JwtRequestObject | null;
+  visitor?: VisitorRequestObject | null;
 }
 
 /**
@@ -83,24 +117,24 @@ export interface AuthenticatedRequest extends Request {
  * @deprecated Use native Buffer methods or other modern alternatives.
  */
 export interface PasswordParts {
-    /** Version indicator of the hashing format. */
-    version: string;
-    /** Base64 encoded algorithm name. */
-    alg: string;
-    /** Base64 encoded password hash. */
-    hash: string;
-    /** Base64 encoded random salt. */
-    salt: string;
+  /** Version indicator of the hashing format. */
+  version: string;
+  /** Base64 encoded algorithm name. */
+  alg: string;
+  /** Base64 encoded password hash. */
+  hash: string;
+  /** Base64 encoded random salt. */
+  salt: string;
 }
 
 /**
  * Contains a pair of public and private cryptographic keys.
  */
 export interface KeyPair {
-    /** PEM formatted public key string. */
-    publicKey: string;
-    /** PEM formatted private key string. */
-    privateKey: string;
+  /** PEM formatted public key string. */
+  publicKey: string;
+  /** PEM formatted private key string. */
+  privateKey: string;
 }
 
 /**
@@ -108,29 +142,29 @@ export interface KeyPair {
  * @deprecated use direct import of the new functions.
  */
 export const jwtUtilAuth: {
-    /**
-     * Creates a signed JWT from header and payload objects.
-     * Automatically normalizes header (sets alg/typ) and payload (sets iat/exp/etc. in seconds).
-     * @param headerObject - Header data for the JWT.
-     * @param payloadObject - Payload data for the JWT.
-     * @param privateKey - PEM formatted private key to sign the token.
-     * @returns Signed JWT string or null if an error occurs.
-     */
-    createSignedJwtFromObject: (headerObject: JwtHeader, payloadObject: JwtPayload, privateKey: string) => string | null;
-    /**
-     * Verifies the signature of a JWT using a public key.
-     * @param jwt - The JWT string to verify.
-     * @param publicKey - PEM formatted public key.
-     * @returns True if the signature is valid, false otherwise.
-     */
-    verifyJwtSignature: (jwt: string, publicKey: string) => boolean;
-    /**
-     * Decodes a JWT and returns its header and payload as objects.
-     * Note: This does NOT verify the signature.
-     * @param jwt - The JWT string to parse.
-     * @returns An object containing the header and payload, or null if parsing fails.
-     */
-    getHeaderPayloadFromJwt: (jwt: string) => JwtParts | null;
+  /**
+   * Creates a signed JWT from header and payload objects.
+   * Automatically normalizes header (sets alg/typ) and payload (sets iat/exp/etc. in seconds).
+   * @param headerObject - Header data for the JWT.
+   * @param payloadObject - Payload data for the JWT.
+   * @param privateKey - PEM formatted private key to sign the token.
+   * @returns Signed JWT string or null if an error occurs.
+   */
+  createSignedJwtFromObject: (headerObject: JwtHeader, payloadObject: JwtPayload, privateKey: string) => string | null;
+  /**
+   * Verifies the signature of a JWT using a public key.
+   * @param jwt - The JWT string to verify.
+   * @param publicKey - PEM formatted public key.
+   * @returns True if the signature is valid, false otherwise.
+   */
+  verifyJwtSignature: (jwt: string, publicKey: string) => boolean;
+  /**
+   * Decodes a JWT and returns its header and payload as objects.
+   * Note: This does NOT verify the signature.
+   * @param jwt - The JWT string to parse.
+   * @returns An object containing the header and payload, or null if parsing fails.
+   */
+  getHeaderPayloadFromJwt: (jwt: string) => JwtParts | null;
 };
 
 /**
@@ -138,94 +172,92 @@ export const jwtUtilAuth: {
  * @deprecated use direct imports of the new functions.
  */
 export const pwdUtilAuth: {
-    /**
-     * Generates a password hash using a random salt and specified algorithm.
-     * @param password - The plain-text password to hash.
-     * @param secret - A pepper/secret key to combine with the password.
-     * @param algorithm - The hashing algorithm to use (e.g., 'sha256').
-     * @returns A string containing the formatted hash with metadata ($1$alg$hash$salt$) or null if an error occurs.
-     */
-    createPasswordHashWithRandomSalt: (password: string, secret: string, algorithm: string) => string | null;
-    /**
-     * Generates a password hash using the same algorithm and salt from a previously saved hash.
-     * Useful for verifying a password against a stored hash.
-     * @param password - The plain-text password to verify.
-     * @param savedPasswordHash - The full stored hash string (including salt and metadata).
-     * @param secret - The pepper/secret key used for hashing.
-     * @returns A hash string that should match the saved hash if the password is correct, or null if an error occurs.
-     */
-    createPasswordHashBasedOnSavedAlgorithmSalt: (password: string, savedPasswordHash: string, secret: string) => string | null;
+  /**
+   * Generates a password hash using a random salt and specified algorithm.
+   * @param password - The plain-text password to hash.
+   * @param secret - A pepper/secret key to combine with the password.
+   * @param algorithm - The hashing algorithm to use (e.g., 'sha256').
+   * @returns A string containing the formatted hash with metadata ($1$alg$hash$salt$) or null if an error occurs.
+   */
+  createPasswordHashWithRandomSalt: (password: string, secret: string, algorithm: string) => string | null;
+  /**
+   * Generates a password hash using the same algorithm and salt from a previously saved hash.
+   * Useful for verifying a password against a stored hash.
+   * @param password - The plain-text password to verify.
+   * @param savedPasswordHash - The full stored hash string (including salt and metadata).
+   * @param secret - The pepper/secret key used for hashing.
+   * @returns A hash string that should match the saved hash if the password is correct, or null if an error occurs.
+   */
+  createPasswordHashBasedOnSavedAlgorithmSalt: (password: string, savedPasswordHash: string, secret: string) => string | null;
 };
 
-
 /**
  * Utility functions for string manipulation, base64 encoding, and parsing auth-related strings.
  * @deprecated Use native Buffer methods or other modern alternatives.
  */
 export const stringUtilAuth: {
-    /**
-     * Converts a base64 string to be URL-safe (replaces + with -, / with _, and removes =).
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param urlUnsafeString - The string to convert.
-     * @returns URL-safe string.
-     */
-    makeStringUrlSafe: (urlUnsafeString?: string) => string;
-    /**
-     * Reverses URL-safe conversion and restores standard base64 characters and padding.
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param urlSafeString - The URL-safe string to restore.
-     * @returns Standard base64 string.
-     */
-    reverseStringUrlSafe: (urlSafeString?: string) => string;
-    /**
-     * Encodes a plain-text string to base64.
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param unCodedString - Plain-text string.
-     * @returns Base64 encoded string.
-     */
-    asciiToBase64: (unCodedString: string) => string;
-    /**
-     * Decodes a base64 string to UTF-8 plain-text.
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param codedString - Base64 encoded string.
-     * @returns Decoded plain-text string.
-     */
-    base64ToAscii: (codedString: string) => string;
-    /**
-     * Parses a stored password hash string into its constituent parts.
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param passwordHash - The formatted hash string ($1$alg$hash$salt$).
-     * @returns A PasswordParts object or null if the format is invalid.
-     */
-    dollarSignConnectedStringToAlgorithmHashSalt: (passwordHash: string) => PasswordParts | null;
-    /**
-     * Splits a JWT into its three base64-encoded string parts (header, payload, signature).
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param jwt - The full JWT string.
-     * @returns An object with the three raw parts, or null if the format is invalid.
-     */
-    dotConnectedStringToHeaderPayloadSignature: (jwt: string) => {
-        header: string,
-        payload: string,
-        signature: string
-    } | null;
-    /**
-     * Serializes an object into a URL-safe base64 string.
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param object - The object to serialize.
-     * @returns URL-safe base64 string.
-     */
-    objectToBase64UrlSafeString: (object: any) => string;
-    /**
-     * Parses a URL-safe base64 string into an object.
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     * @param urlSafeBase64String - URL-safe base64 string.
-     * @returns The parsed object.
-     */
-    urlSafeBase64ToObject: (urlSafeBase64String: string) => any;
+  /**
+   * Converts a base64 string to be URL-safe (replaces + with -, / with _, and removes =).
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param urlUnsafeString - The string to convert.
+   * @returns URL-safe string.
+   */
+  makeStringUrlSafe: (urlUnsafeString?: string) => string;
+  /**
+   * Reverses URL-safe conversion and restores standard base64 characters and padding.
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param urlSafeString - The URL-safe string to restore.
+   * @returns Standard base64 string.
+   */
+  reverseStringUrlSafe: (urlSafeString?: string) => string;
+  /**
+   * Encodes a plain-text string to base64.
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param unCodedString - Plain-text string.
+   * @returns Base64 encoded string.
+   */
+  asciiToBase64: (unCodedString: string) => string;
+  /**
+   * Decodes a base64 string to UTF-8 plain-text.
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param codedString - Base64 encoded string.
+   * @returns Decoded plain-text string.
+   */
+  base64ToAscii: (codedString: string) => string;
+  /**
+   * Parses a stored password hash string into its constituent parts.
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param passwordHash - The formatted hash string ($1$alg$hash$salt$).
+   * @returns A PasswordParts object or null if the format is invalid.
+   */
+  dollarSignConnectedStringToAlgorithmHashSalt: (passwordHash: string) => PasswordParts | null;
+  /**
+   * Splits a JWT into its three base64-encoded string parts (header, payload, signature).
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param jwt - The full JWT string.
+   * @returns An object with the three raw parts, or null if the format is invalid.
+   */
+  dotConnectedStringToHeaderPayloadSignature: (jwt: string) => {
+    header: string;
+    payload: string;
+    signature: string;
+  } | null;
+  /**
+   * Serializes an object into a URL-safe base64 string.
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param object - The object to serialize.
+   * @returns URL-safe base64 string.
+   */
+  objectToBase64UrlSafeString: (object: any) => string;
+  /**
+   * Parses a URL-safe base64 string into an object.
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   * @param urlSafeBase64String - URL-safe base64 string.
+   * @returns The parsed object.
+   */
+  urlSafeBase64ToObject: (urlSafeBase64String: string) => any;
 };
 
-
 /**
  * Generates a public/private key pair for JWT signing.
  * @param algorithm - The algorithm to use ('ed25519' or 'rsa'). Defaults to 'ed25519'.
@@ -243,6 +275,20 @@ export function generateKeyPair(algorithm?: 'ed25519' | 'rsa' | string): KeyPair
  */
 export function jwtCreateSignedToken(headerObject: JwtHeader, payloadObject: JwtPayload, privateKey: string): string | null;
 
+/**
+ * Creates a signed service-to-service JWT using the issuing service's private key.
+ * @param options - Service JWT creation options.
+ * @returns Signed JWT string or null if validation or signing fails.
+ */
+export function jwtCreateServiceToken(options: ServiceJwtOptions): string | null;
+
+/**
+ * Creates a Bearer Authorization header containing a signed service-to-service JWT.
+ * @param options - Service JWT creation options.
+ * @returns Bearer Authorization header or null if validation or signing fails.
+ */
+export function jwtCreateServiceAuthorizationHeader(options: ServiceJwtOptions): string | null;
+
 /**
  * Verifies the signature of a JWT using a public key.
  * @param jwt - The JWT string to verify.

package/index.js

@@ -3,33 +3,34 @@ const jwtUtilAuth = require('./lib/jwtUtilAuth');
 const keyGen = require('./lib/keyGen');
 
 module.exports = {
-    // New
-    generateKeyPair: keyGen.generateKeyPair,
-    jwtCreateSignedToken: jwtUtilAuth.createSignedJwtFromObject,
-    jwtVerifySignedToken: jwtUtilAuth.verifyJwtSignature,
-    jwtGetHeaderPayload: jwtUtilAuth.getHeaderPayloadFromJwt,
-    passwordCreateHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
-    passwordCreateHashFromSavedHash: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt,
+  // New
+  generateKeyPair: keyGen.generateKeyPair,
+  jwtCreateSignedToken: jwtUtilAuth.createSignedJwtFromObject,
+  jwtCreateServiceToken: jwtUtilAuth.createServiceJwt,
+  jwtCreateServiceAuthorizationHeader: jwtUtilAuth.createServiceAuthorizationHeader,
+  jwtVerifySignedToken: jwtUtilAuth.verifyJwtSignature,
+  jwtGetHeaderPayload: jwtUtilAuth.getHeaderPayloadFromJwt,
+  passwordCreateHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
+  passwordCreateHashFromSavedHash: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt,
 
-    // Deprecated
-    /**
-     * @deprecated use direct import of the new functions.
-     */
-    jwtUtilAuth: {
-        createSignedJwtFromObject: jwtUtilAuth.createSignedJwtFromObject,
-        verifyJwtSignature: jwtUtilAuth.verifyJwtSignature,
-        getHeaderPayloadFromJwt: jwtUtilAuth.getHeaderPayloadFromJwt
-    },
-    /**
-     * @deprecated use direct import of the new functions.
-     */
-    pwdUtilAuth: {
-        createPasswordHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
-        createPasswordHashBasedOnSavedAlgorithmSalt: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt
-    },
-    /**
-     * @deprecated Use native Buffer methods or other modern alternatives.
-     */
-    stringUtilAuth: require('./lib/stringUtilAuth'),
+  // Deprecated
+  /**
+   * @deprecated use direct import of the new functions.
+   */
+  jwtUtilAuth: {
+    createSignedJwtFromObject: jwtUtilAuth.createSignedJwtFromObject,
+    verifyJwtSignature: jwtUtilAuth.verifyJwtSignature,
+    getHeaderPayloadFromJwt: jwtUtilAuth.getHeaderPayloadFromJwt,
+  },
+  /**
+   * @deprecated use direct import of the new functions.
+   */
+  pwdUtilAuth: {
+    createPasswordHashWithRandomSalt: pwdUtilAuth.createPasswordHashWithRandomSalt,
+    createPasswordHashBasedOnSavedAlgorithmSalt: pwdUtilAuth.createPasswordHashBasedOnSavedAlgorithmSalt,
+  },
+  /**
+   * @deprecated Use native Buffer methods or other modern alternatives.
+   */
+  stringUtilAuth: require('./lib/stringUtilAuth'),
 };
-