@carecard/auth-util 3.25.0 → 3.27.0

package/.agents/skills/pkg-auth-util-auth-crypto-library/SKILL.md

@@ -103,10 +103,11 @@ depend on those folders being present.
 - `index.d.ts` must stay aligned with every public export in `index.js`.
 - `lib/jwtUtilAuth.js` owns JWT creation, service-to-service JWT creation,
   verification, and decomposition.
-- `lib/pwdUtilAuth.js` owns password hashing and saved-hash verification.
+- `lib/jwkUtilAuth.js` owns strict signing-JWK and verification-JWKS parsing.
+- `lib/pwdUtilAuth.js` owns password keyring parsing and versioned credential
+  hashing and verification.
 - `lib/cryptoUtilAuth.js` wraps Node.js `crypto` primitives for signing,
   verifying, generating HMACs, and salts.
-- `lib/keyGen.js` owns Ed25519 and RSA key generation.
 - `lib/stringUtilAuth.js` owns legacy base64, base64-url-safe, and JWT string
   helpers. Password-hash parsing stays private to `lib/pwdUtilAuth.js`.
 - Keep direct exports as the public package API. Do not add password aliases,
@@ -116,10 +117,15 @@ depend on those folders being present.
 
 ## JWT Layer
 
-- Use EdDSA/Ed25519 as the default JWT algorithm unless a task explicitly
-  changes crypto behavior.
-- Preserve standardized headers and payload behavior, including automatic `iat`
-  and `exp` population where the existing API does that.
+- Accept only parsed Ed25519 signing JWKs and verification JWKS values. Do not
+  add PEM, RSA, algorithm-selection, missing-`kid`, or single-key fallbacks.
+- Derive every `kid` as the RFC 7638 SHA-256 base64url thumbprint of canonical
+  `{ "crv": "Ed25519", "kty": "OKP", "x": ... }` members.
+- Require exact JWK metadata: `alg: "EdDSA"`, `use: "sig"`, and one `key_ops`
+  value (`sign` for private keys, `verify` for public keys). Ensure private and
+  public key material agree before accepting signing configuration.
+- Create JWTs with the fixed `{ alg: "EdDSA", typ: "JWT", kid }` header and
+  verify by selecting the exact public key named by `kid`.
 - Keep service-to-service JWT creation here, not in `@carecard/jwt-read`.
   Public service-token creation exports are `jwtCreateServiceToken` and
   `jwtCreateServiceAuthorizationHeader`.
@@ -143,17 +149,22 @@ depend on those folders being present.
   $argon2id$v=19$m=19456,t=2,p=1$base64(salt)$base64(tag)
   ```
 
-- `createPasswordHash(password, pepper)` and
-  `verifyPassword(password, savedHash, pepper)` are the only public password
-  credential APIs; both are asynchronous.
+- `parsePasswordHashKeyring(activeKeyId, serializedKeyring)`,
+  `createPasswordCredential(password, keyring)`, and
+  `verifyPasswordCredential(password, credential, keyring)` are the only
+  public password credential APIs. Keyring entries are comma-separated
+  `key-id:canonical-base64-32-byte-key` values.
+- Persist the returned `hash` and `hashKeyId` together. Verification returns
+  `{ isValid, needsRehash }`; `needsRehash` is true only after a valid retiring
+  key credential is verified.
 - Generate salts internally for every credential. Never accept caller-selected
   salts and never persist or log the pepper.
 - Normalize well-formed Unicode passwords to NFC before deriving the tag, but
   do not trim or impose password policy here. `@carecard/validate` owns policy,
   while login intentionally permits existing passwords of any length.
-- Return `false` for malformed, non-canonical, differently parameterized, or
-  legacy saved hashes. Throw for programmer/configuration errors such as an
-  invalid pepper.
+- Return an invalid verification result for unknown key IDs, malformed,
+  non-canonical, differently parameterized, or legacy saved hashes. Throw for
+  programmer/configuration errors such as an invalid keyring.
 - Do not add legacy HMAC verification. Seeded accounts must be rehashed before
   the Argon2id-only service starts.
 - Prefer Node.js `crypto` primitives over new dependencies.

package/index.d.ts

@@ -12,6 +12,8 @@ export interface JwtHeader {
   alg?: string;
   /** The media type of the JWT. Defaults to 'JWT'. */
   typ?: string;
+  /** RFC 7638 thumbprint identifying the signing key. */
+  kid?: string;
 
   /** Any other custom header fields. */
   [key: string]: unknown;
@@ -58,16 +60,14 @@ export interface ServiceJwtOptions {
   issuer: string;
   /** Receiving microservice name or names. */
   audience: string | string[];
-  /** Private key owned by the issuing microservice. */
-  privateKey: string;
+  /** Parsed private Ed25519 JWK owned by the issuing microservice. */
+  signingJwk: JwtSigningJwk;
   /** 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>;
 }
@@ -112,49 +112,35 @@ export interface AuthenticatedRequest extends Request {
   visitor?: VisitorRequestObject | null;
 }
 
-/**
- * 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;
+declare const jwtSigningJwkBrand: unique symbol;
+declare const jwtVerificationJwksBrand: unique symbol;
+declare const passwordHashKeyringBrand: unique symbol;
+
+export interface JwtSigningJwk {
+  readonly kid: string;
+  readonly [jwtSigningJwkBrand]: true;
 }
 
-/**
- * Utility functions for creating, verifying, and parsing JSON Web Tokens (JWT).
- * @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 when the private key is missing. Unexpected failures throw.
-   */
-  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 for malformed or invalid tokens. Unexpected failures throw.
-   */
-  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;
-};
+export interface JwtVerificationJwks {
+  readonly kids: readonly string[];
+  readonly [jwtVerificationJwksBrand]: true;
+}
+
+export interface PasswordHashKeyring {
+  readonly activeKeyId: string;
+  readonly keyIds: readonly string[];
+  readonly [passwordHashKeyringBrand]: true;
+}
+
+export interface PasswordCredential {
+  readonly hash: string;
+  readonly hashKeyId: string;
+}
+
+export interface PasswordCredentialVerification {
+  readonly isValid: boolean;
+  readonly needsRehash: boolean;
+}
 
 /**
  * Utility functions for string manipulation, base64 encoding, and parsing auth-related strings.
@@ -217,24 +203,14 @@ export const stringUtilAuth: {
 };
 
 /**
- * Generates a public/private key pair for JWT signing.
- * @param algorithm - The algorithm to use ('ed25519' or 'rsa'). Defaults to 'ed25519'.
- * @returns A KeyPair object containing PEM formatted keys.
- */
-export function generateKeyPair(algorithm?: 'ed25519' | 'rsa' | string): KeyPair;
-
-/**
- * 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.
+ * Creates an EdDSA JWT with a fixed JWT header and the signing JWK's kid.
  * @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.
+ * @param signingJwk - A parsed private Ed25519 signing JWK.
+ * @returns Signed JWT string or null for invalid input.
  */
 export function jwtCreateSignedToken(
-  headerObject: JwtHeader,
   payloadObject: JwtPayload,
-  privateKey: string,
+  signingJwk: JwtSigningJwk,
 ): string | null;
 
 /**
@@ -252,12 +228,18 @@ export function jwtCreateServiceToken(options: ServiceJwtOptions): string | null
 export function jwtCreateServiceAuthorizationHeader(options: ServiceJwtOptions): string | null;
 
 /**
- * Verifies the signature of a JWT using a public key.
+ * Verifies a JWT by selecting its kid from a parsed public JWKS.
  * @param jwt - The JWT string to verify.
- * @param publicKey - PEM formatted public key.
+ * @param verificationJwks - Parsed public Ed25519 verification keys.
  * @returns True if the signature is valid, false otherwise.
  */
-export function jwtVerifySignedToken(jwt: string, publicKey: string): boolean;
+export function jwtVerifySignedToken(jwt: string, verificationJwks: JwtVerificationJwks): boolean;
+
+/** Parses and validates one private Ed25519 signing JWK. */
+export function parseJwtSigningJwk(serializedJwk: string): JwtSigningJwk;
+
+/** Parses and validates an RFC 7517 public Ed25519 JWKS. */
+export function parseJwtVerificationJwks(serializedJwks: string): JwtVerificationJwks;
 
 /**
  * Decodes a JWT and returns its header and payload as objects.
@@ -267,23 +249,21 @@ export function jwtVerifySignedToken(jwt: string, publicKey: string): boolean;
  */
 export function jwtGetHeaderPayload(jwt: string): JwtParts | null;
 
-/**
- * Creates an Argon2id PHC password hash with a unique random salt.
- * @param password - The plain-text password to hash.
- * @param pepper - A secret pepper containing at least 32 UTF-8 bytes.
- * @returns The strict Argon2id PHC string.
- */
-export function createPasswordHash(password: string, pepper: string): Promise<string>;
+/** Parses a validated active/retiring password hash keyring. */
+export function parsePasswordHashKeyring(
+  activeKeyId: string,
+  serializedKeyring: string,
+): PasswordHashKeyring;
 
-/**
- * Verifies a password against a strict CareCard Argon2id PHC hash.
- * @param password - The plain-text password to verify.
- * @param savedHash - The stored Argon2id PHC hash.
- * @param pepper - The same secret pepper used when creating the hash.
- * @returns False for a mismatch or malformed/unsupported saved hash.
- */
-export function verifyPassword(
+/** Creates a freshly salted active-key Argon2id credential. */
+export function createPasswordCredential(
+  password: string,
+  keyring: PasswordHashKeyring,
+): Promise<PasswordCredential>;
+
+/** Verifies a credential and reports whether it should move to the active key. */
+export function verifyPasswordCredential(
   password: string,
-  savedHash: string,
-  pepper: string,
-): Promise<boolean>;
+  credential: PasswordCredential,
+  keyring: PasswordHashKeyring,
+): Promise<PasswordCredentialVerification>;

package/index.js

@@ -1,27 +1,18 @@
 const pwdUtilAuth = require('./lib/pwdUtilAuth');
 const jwtUtilAuth = require('./lib/jwtUtilAuth');
-const keyGen = require('./lib/keyGen');
+const jwkUtilAuth = require('./lib/jwkUtilAuth');
 
 module.exports = {
-  // New
-  generateKeyPair: keyGen.generateKeyPair,
   jwtCreateSignedToken: jwtUtilAuth.createSignedJwtFromObject,
   jwtCreateServiceToken: jwtUtilAuth.createServiceJwt,
   jwtCreateServiceAuthorizationHeader: jwtUtilAuth.createServiceAuthorizationHeader,
   jwtVerifySignedToken: jwtUtilAuth.verifyJwtSignature,
   jwtGetHeaderPayload: jwtUtilAuth.getHeaderPayloadFromJwt,
-  createPasswordHash: pwdUtilAuth.createPasswordHash,
-  verifyPassword: pwdUtilAuth.verifyPassword,
-
-  // Deprecated
-  /**
-   * @deprecated use direct import of the new functions.
-   */
-  jwtUtilAuth: {
-    createSignedJwtFromObject: jwtUtilAuth.createSignedJwtFromObject,
-    verifyJwtSignature: jwtUtilAuth.verifyJwtSignature,
-    getHeaderPayloadFromJwt: jwtUtilAuth.getHeaderPayloadFromJwt,
-  },
+  parseJwtSigningJwk: jwkUtilAuth.parseJwtSigningJwk,
+  parseJwtVerificationJwks: jwkUtilAuth.parseJwtVerificationJwks,
+  createPasswordCredential: pwdUtilAuth.createPasswordCredential,
+  parsePasswordHashKeyring: pwdUtilAuth.parsePasswordHashKeyring,
+  verifyPasswordCredential: pwdUtilAuth.verifyPasswordCredential,
   /**
    * @deprecated Use native Buffer methods or other modern alternatives.
    */

package/lib/jwkUtilAuth.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { createHash, createPrivateKey, createPublicKey } = require('node:crypto');
+
+const ED25519_KEY_BYTES = 32;
+const signingKeys = new WeakMap();
+const verificationKeys = new WeakMap();
+const SIGNING_JWK_MEMBERS = ['alg', 'crv', 'd', 'key_ops', 'kid', 'kty', 'use', 'x'];
+const VERIFICATION_JWK_MEMBERS = ['alg', 'crv', 'key_ops', 'kid', 'kty', 'use', 'x'];
+
+function parseJsonObject(serializedValue, configurationName) {
+  try {
+    const value = JSON.parse(serializedValue);
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      throw new TypeError();
+    }
+    return value;
+  } catch {
+    throw new Error(`Invalid ${configurationName} configuration.`);
+  }
+}
+
+function isCanonicalBase64Url(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    return false;
+  }
+  const decodedValue = Buffer.from(value, 'base64url');
+  return decodedValue.length === ED25519_KEY_BYTES && decodedValue.toString('base64url') === value;
+}
+
+function deriveJwkThumbprint(jwk) {
+  const canonicalJwk = JSON.stringify({ crv: 'Ed25519', kty: 'OKP', x: jwk.x });
+  return createHash('sha256').update(canonicalJwk).digest('base64url');
+}
+
+function hasExactKeyOperation(jwk, operation) {
+  return Array.isArray(jwk.key_ops) && jwk.key_ops.length === 1 && jwk.key_ops[0] === operation;
+}
+
+function hasExactMembers(value, expectedMembers) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const members = Object.keys(value).sort();
+  return (
+    members.length === expectedMembers.length &&
+    members.every((member, index) => member === expectedMembers[index])
+  );
+}
+
+function hasValidSharedMetadata(jwk) {
+  return (
+    jwk.kty === 'OKP' &&
+    jwk.crv === 'Ed25519' &&
+    jwk.alg === 'EdDSA' &&
+    jwk.use === 'sig' &&
+    isCanonicalBase64Url(jwk.x) &&
+    jwk.kid === deriveJwkThumbprint(jwk)
+  );
+}
+
+function createSigningKey(jwk) {
+  try {
+    const privateKey = createPrivateKey({ key: jwk, format: 'jwk' });
+    const derivedPublicJwk = createPublicKey(privateKey).export({ format: 'jwk' });
+    if (derivedPublicJwk.x !== jwk.x) {
+      throw new TypeError();
+    }
+    return privateKey;
+  } catch {
+    throw new Error('Invalid JWT signing JWK configuration.');
+  }
+}
+
+function parseJwtSigningJwk(serializedJwk) {
+  const jwk = parseJsonObject(serializedJwk, 'JWT signing JWK');
+  if (!hasExactMembers(jwk, SIGNING_JWK_MEMBERS) || !hasValidSharedMetadata(jwk)) {
+    throw new Error('Invalid JWT signing JWK configuration.');
+  }
+  if (!hasExactKeyOperation(jwk, 'sign') || !isCanonicalBase64Url(jwk.d)) {
+    throw new Error('Invalid JWT signing JWK configuration.');
+  }
+  const parsedJwk = Object.freeze({ ...jwk, key_ops: Object.freeze(['sign']) });
+  signingKeys.set(parsedJwk, createSigningKey(jwk));
+  return parsedJwk;
+}
+
+function parseVerificationJwk(jwk) {
+  if (!hasExactMembers(jwk, VERIFICATION_JWK_MEMBERS) || !hasValidSharedMetadata(jwk)) {
+    throw new Error('Invalid JWT verification JWKS configuration.');
+  }
+  if (!hasExactKeyOperation(jwk, 'verify')) {
+    throw new Error('Invalid JWT verification JWKS configuration.');
+  }
+  try {
+    return [jwk.kid, createPublicKey({ key: jwk, format: 'jwk' })];
+  } catch {
+    throw new Error('Invalid JWT verification JWKS configuration.');
+  }
+}
+
+function parseJwtVerificationJwks(serializedJwks) {
+  const jwks = parseJsonObject(serializedJwks, 'JWT verification JWKS');
+  if (!hasExactMembers(jwks, ['keys']) || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
+    throw new Error('Invalid JWT verification JWKS configuration.');
+  }
+  const entries = jwks.keys.map(parseVerificationJwk);
+  const keyMap = new Map(entries);
+  if (keyMap.size !== entries.length) {
+    throw new Error('Invalid JWT verification JWKS configuration.');
+  }
+  const parsedJwks = Object.freeze({ kids: Object.freeze([...keyMap.keys()]) });
+  verificationKeys.set(parsedJwks, keyMap);
+  return parsedJwks;
+}
+
+function getJwtSigningKey(signingJwk) {
+  return signingKeys.get(signingJwk) ?? null;
+}
+
+function getJwtVerificationKey(jwks, kid) {
+  return verificationKeys.get(jwks)?.get(kid) ?? null;
+}
+
+module.exports = {
+  getJwtSigningKey,
+  getJwtVerificationKey,
+  parseJwtSigningJwk,
+  parseJwtVerificationJwks,
+};

package/lib/jwtUtilAuth.js

@@ -1,89 +1,43 @@
-const crypto = require('crypto');
+'use strict';
 
-const supportedVerificationHashes = new Set(crypto.getHashes().map(hash => hash.toLowerCase()));
+const { sign, verify } = require('node:crypto');
+const { getJwtSigningKey, getJwtVerificationKey } = require('./jwkUtilAuth');
 
-// Pattern: Normalizer - preserves explicit registered times while supplying omitted defaults.
-const _normalizePayload = payloadObject => {
+const normalizePayload = payloadObject => {
   const payload = { ...payloadObject };
   const now = Math.floor(Date.now() / 1000);
   const fieldsToNormalize = ['iat', 'exp', 'nbf', 'auth_time'];
   const msThreshold = 1000000000000;
-
   if (!Number.isFinite(payload.iat)) {
     payload.iat = now;
   }
-
   fieldsToNormalize.forEach(field => {
     if (Number.isFinite(payload[field]) && payload[field] > msThreshold) {
       payload[field] = Math.floor(payload[field] / 1000);
     }
   });
-
   if (!Number.isFinite(payload.exp)) {
     payload.exp = payload.iat + 3600;
   }
   return payload;
 };
 
-const _encode = obj => {
-  return Buffer.from(JSON.stringify(obj)).toString('base64url');
-};
-
-const _decode = str => {
-  return JSON.parse(Buffer.from(str, 'base64url').toString('utf8'));
-};
-
-const _sign = (token, alg, privateKey) => {
-  if (alg === 'EdDSA' || alg === 'Ed25519') {
-    return crypto.sign(null, Buffer.from(token), privateKey).toString('base64url');
-  }
-
-  const sign = crypto.createSign(alg);
-  sign.write(token);
-  sign.end();
-  return sign.sign(privateKey, 'base64url');
-};
-
-const _verify = (token, signature, alg, publicKey) => {
-  if (alg === 'EdDSA' || alg === 'Ed25519') {
-    return crypto.verify(null, Buffer.from(token), publicKey, Buffer.from(signature, 'base64url'));
-  }
-
-  const verify = crypto.createVerify(alg);
-  verify.update(token);
-  verify.end();
-  return verify.verify(publicKey, signature, 'base64url');
-};
-
-// Pattern: Allow List - rejects algorithms that the runtime cannot safely verify.
-const isSupportedVerificationAlgorithm = algorithm => {
-  if (algorithm === 'EdDSA' || algorithm === 'Ed25519') {
-    return true;
-  }
-  return typeof algorithm === 'string' && supportedVerificationHashes.has(algorithm.toLowerCase());
-};
+const encodeJwtPart = value => Buffer.from(JSON.stringify(value)).toString('base64url');
+const decodeJwtPart = value => JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
 
-// Pattern: Type Guard - decoded JWT parts must honor their documented object contract.
 const isDecodedJwtObject = value => {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
 
-const isNonEmptyString = value => {
-  return typeof value === 'string' && value.trim().length > 0;
-};
+const isNonEmptyString = value => typeof value === 'string' && value.trim().length > 0;
 
-const audienceIsNonEmptyStringArray = audience => {
+const isNonEmptyAudience = audience => {
   return (
-    Array.isArray(audience) &&
-    audience.length > 0 &&
-    audience.every(audienceValue => isNonEmptyString(audienceValue))
+    isNonEmptyString(audience) ||
+    (Array.isArray(audience) && audience.length > 0 && audience.every(isNonEmptyString))
   );
 };
 
-const isNonEmptyAudience = audience => {
-  return isNonEmptyString(audience) || audienceIsNonEmptyStringArray(audience);
-};
-
 const normalizeSeconds = value => {
   if (!Number.isFinite(value)) {
     return null;
@@ -91,72 +45,39 @@ const normalizeSeconds = value => {
   return value > 1000000000000 ? Math.floor(value / 1000) : Math.floor(value);
 };
 
-/**
- * Creates Url safe jwt
- * @param headerObject
- * @param payloadObject
- * @param privateKey
- * @return {string|null}
- */
-const createSignedJwtFromObject = (headerObject, payloadObject, privateKey) => {
-  if (!privateKey) {
+function createSignedJwtFromObject(payloadObject, signingJwk) {
+  const privateKey = getJwtSigningKey(signingJwk);
+  if (!privateKey || !isDecodedJwtObject(payloadObject)) {
     return null;
   }
-
-  const header = { ...headerObject };
-  header.alg = header.alg || 'EdDSA';
-  header.typ = 'JWT';
-
-  const payload = _normalizePayload(payloadObject);
-
-  const headerBase64UrlSafe = _encode(header);
-  const payloadBase64UrlSafe = _encode(payload);
-  const token = headerBase64UrlSafe + '.' + payloadBase64UrlSafe;
-
-  const signature = _sign(token, header.alg, privateKey);
-
-  return token + '.' + signature;
-};
+  const header = { alg: 'EdDSA', typ: 'JWT', kid: signingJwk.kid };
+  const token = `${encodeJwtPart(header)}.${encodeJwtPart(normalizePayload(payloadObject))}`;
+  const signature = sign(null, Buffer.from(token), privateKey).toString('base64url');
+  return `${token}.${signature}`;
+}
 
 function createServiceJwt({
   issuer,
   audience,
-  privateKey,
+  signingJwk,
   subject = issuer,
   issuedAt = Math.floor(Date.now() / 1000),
   expiresInSeconds = 60,
-  algorithm = 'EdDSA',
   claims = {},
 } = {}) {
-  if (
-    !isNonEmptyString(issuer) ||
-    !isNonEmptyAudience(audience) ||
-    !isNonEmptyString(subject) ||
-    !isNonEmptyString(privateKey) ||
-    !Number.isInteger(expiresInSeconds) ||
-    expiresInSeconds <= 0
-  ) {
+  if (!isNonEmptyString(issuer) || !isNonEmptyAudience(audience) || !isNonEmptyString(subject)) {
+    return null;
+  }
+  if (!Number.isInteger(expiresInSeconds) || expiresInSeconds <= 0) {
     return null;
   }
-
   const iat = normalizeSeconds(issuedAt);
-  if (!Number.isInteger(iat)) {
+  if (!Number.isInteger(iat) || !isDecodedJwtObject(claims)) {
     return null;
   }
-
-  // Service-to-service tokens use registered JWT claims so receivers can
-  // validate sender, intended audience, subject, and lifetime consistently.
   return createSignedJwtFromObject(
-    { alg: algorithm, typ: 'JWT' },
-    {
-      ...claims,
-      iss: issuer,
-      aud: audience,
-      sub: subject,
-      iat,
-      exp: iat + expiresInSeconds,
-    },
-    privateKey,
+    { ...claims, iss: issuer, aud: audience, sub: subject, iat, exp: iat + expiresInSeconds },
+    signingJwk,
   );
 }
 
@@ -165,81 +86,73 @@ function createServiceAuthorizationHeader(options = {}) {
   return token ? `Bearer ${token}` : null;
 }
 
-/**
- * Verify signature of jwt
- * @param jwt
- * @param publicKey
- * @return {boolean}
- */
-// Pattern: Fail-Closed Verification - malformed token metadata returns false before crypto use.
-const verifyJwtSignature = (jwt, publicKey) => {
+function hasValidJwtHeader(header) {
+  return (
+    isDecodedJwtObject(header) &&
+    header.alg === 'EdDSA' &&
+    header.typ === 'JWT' &&
+    isNonEmptyString(header.kid)
+  );
+}
+
+function decodeCanonicalSignature(signature) {
+  if (typeof signature !== 'string' || !/^[A-Za-z0-9_-]+$/.test(signature)) {
+    return null;
+  }
+  const decoded = Buffer.from(signature, 'base64url');
+  return decoded.length === 64 && decoded.toString('base64url') === signature ? decoded : null;
+}
+
+function verifyJwtSignature(jwt, verificationJwks) {
   try {
-    if (!jwt || !publicKey) {
-      return false;
-    }
-    const splitJWT = jwt.split('.');
-    if (splitJWT.length !== 3) {
+    if (typeof jwt !== 'string') {
       return false;
     }
-
-    const [header, payload, signature] = splitJWT;
-    const token = header + '.' + payload;
-    const headerObject = _decode(header);
-    if (!isDecodedJwtObject(headerObject) || !isSupportedVerificationAlgorithm(headerObject.alg)) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) {
       return false;
     }
-
-    return _verify(token, signature, headerObject.alg, publicKey);
+    const header = decodeJwtPart(parts[0]);
+    const signature = decodeCanonicalSignature(parts[2]);
+    const publicKey = hasValidJwtHeader(header)
+      ? getJwtVerificationKey(verificationJwks, header.kid)
+      : null;
+    const signedData = Buffer.from(`${parts[0]}.${parts[1]}`);
+    return Boolean(publicKey && signature && verify(null, signedData, publicKey, signature));
   } catch (error) {
     if (!(error instanceof SyntaxError)) {
       throw error;
     }
     return false;
   }
-};
+}
 
-/**
- * Returns header and payload object for jwt.
- * @param jwt
- * @return {{payload: *, header: *}|null}
- */
-// Pattern: Boundary Validation - returns only decoded header and payload objects.
-const getHeaderPayloadFromJwt = jwt => {
+function getHeaderPayloadFromJwt(jwt) {
   try {
-    if (typeof jwt !== 'string') {
-      return null;
-    }
-    const splitJWT = jwt.split('.');
-    if (splitJWT.length !== 3) {
-      return null;
-    }
-
-    const headerObject = _decode(splitJWT[0]);
-    const payloadObject = _decode(splitJWT[1]);
-    if (!isDecodedJwtObject(headerObject) || !isDecodedJwtObject(payloadObject)) {
+    if (typeof jwt !== 'string' || jwt.split('.').length !== 3) {
       return null;
     }
-
-    return { header: headerObject, payload: payloadObject };
+    const [headerPart, payloadPart] = jwt.split('.');
+    const header = decodeJwtPart(headerPart);
+    const payload = decodeJwtPart(payloadPart);
+    return isDecodedJwtObject(header) && isDecodedJwtObject(payload) ? { header, payload } : null;
   } catch (error) {
     if (!(error instanceof SyntaxError)) {
       throw error;
     }
     return null;
   }
-};
+}
 
 module.exports = {
   createSignedJwtFromObject,
   createServiceJwt,
   createServiceAuthorizationHeader,
-  verifyJwtSignature,
   getHeaderPayloadFromJwt,
-  _normalizePayload,
-  _encode,
-  _decode,
-  _sign,
-  _verify,
+  verifyJwtSignature,
+  _normalizePayload: normalizePayload,
+  _encode: encodeJwtPart,
+  _decode: decodeJwtPart,
   _isNonEmptyAudience: isNonEmptyAudience,
   _normalizeSeconds: normalizeSeconds,
 };

package/lib/pwdUtilAuth.js

@@ -11,22 +11,12 @@ const ARGON2_PASSES = 2;
 const ARGON2_PARALLELISM = 1;
 const PASSWORD_SALT_BYTES = 16;
 const PASSWORD_TAG_BYTES = 32;
-const MINIMUM_PEPPER_BYTES = 32;
+const PASSWORD_KEY_BYTES = 32;
+const PASSWORD_KEY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const passwordKeyringSecrets = new WeakMap();
 const PASSWORD_HASH_PATTERN =
   /^\$argon2id\$v=19\$m=19456,t=2,p=1\$([A-Za-z0-9+/]{22})\$([A-Za-z0-9+/]{43})$/;
 
-// Pattern: Configuration Guard - converts only a sufficiently strong string pepper to bytes.
-function createPepperBuffer(pepper) {
-  if (typeof pepper !== 'string') {
-    throw new TypeError('Password pepper must be a string.');
-  }
-  const pepperBuffer = Buffer.from(pepper, 'utf8');
-  if (pepperBuffer.length < MINIMUM_PEPPER_BYTES) {
-    throw new RangeError('Password pepper must be at least 32 bytes.');
-  }
-  return pepperBuffer;
-}
-
 // Pattern: Canonicalization - converts well-formed NFC password text to stable UTF-8 bytes.
 function createPasswordBuffer(password) {
   if (typeof password !== 'string' || !password.isWellFormed()) {
@@ -88,26 +78,72 @@ function serializePasswordHash(salt, tag) {
   return `$${ARGON2_ALGORITHM}$v=${ARGON2_VERSION}$${parameters}$${encodePhcBase64(salt)}$${encodePhcBase64(tag)}`;
 }
 
-// Pattern: Credential Factory - creates an independently salted Argon2id password hash.
-async function createPasswordHash(password, pepper) {
-  const pepperBuffer = createPepperBuffer(pepper);
-  const salt = randomBytes(PASSWORD_SALT_BYTES);
-  const tag = await derivePasswordTag(password, salt, pepperBuffer);
-  return serializePasswordHash(salt, tag);
+// Pattern: Strict Configuration Parser - creates an opaque versioned password keyring.
+function parsePasswordHashKeyring(activeKeyId, serializedKeyring) {
+  if (!PASSWORD_KEY_ID_PATTERN.test(activeKeyId) || typeof serializedKeyring !== 'string') {
+    throw new Error('Invalid password hash keyring configuration.');
+  }
+  if (!serializedKeyring || /\s/.test(serializedKeyring)) {
+    throw new Error('Invalid password hash keyring configuration.');
+  }
+  const entries = serializedKeyring.split(',').map(parsePasswordKeyEntry);
+  const keyMap = new Map(entries);
+  if (keyMap.size !== entries.length || !keyMap.has(activeKeyId)) {
+    throw new Error('Invalid password hash keyring configuration.');
+  }
+  const keyring = Object.freeze({ activeKeyId, keyIds: Object.freeze([...keyMap.keys()]) });
+  passwordKeyringSecrets.set(keyring, keyMap);
+  return keyring;
 }
 
-// Pattern: Constant-Time Verification - derives and compares a strict Argon2id credential tag.
-async function verifyPassword(password, savedHash, pepper) {
-  const pepperBuffer = createPepperBuffer(pepper);
-  if (typeof password !== 'string' || !password.isWellFormed()) {
-    return false;
+function parsePasswordKeyEntry(entry) {
+  const separatorIndex = entry.indexOf(':');
+  if (separatorIndex <= 0 || separatorIndex !== entry.lastIndexOf(':')) {
+    throw new Error('Invalid password hash keyring configuration.');
+  }
+  const keyId = entry.slice(0, separatorIndex);
+  const encodedKey = entry.slice(separatorIndex + 1);
+  const key = Buffer.from(encodedKey, 'base64');
+  if (!PASSWORD_KEY_ID_PATTERN.test(keyId) || !isCanonicalPasswordKey(key, encodedKey)) {
+    throw new Error('Invalid password hash keyring configuration.');
   }
-  const parsedHash = parsePasswordHash(savedHash);
-  if (!parsedHash) {
-    return false;
+  return [keyId, key];
+}
+
+function isCanonicalPasswordKey(key, encodedKey) {
+  return key.length === PASSWORD_KEY_BYTES && key.toString('base64') === encodedKey;
+}
+
+function getPasswordKeyringSecrets(keyring) {
+  const keys = passwordKeyringSecrets.get(keyring);
+  if (!keys) {
+    throw new TypeError('A parsed password hash keyring is required.');
+  }
+  return keys;
+}
+
+async function createPasswordCredential(password, keyring) {
+  const keys = getPasswordKeyringSecrets(keyring);
+  const pepper = keys.get(keyring.activeKeyId);
+  const salt = randomBytes(PASSWORD_SALT_BYTES);
+  const tag = await derivePasswordTag(password, salt, pepper);
+  return Object.freeze({ hash: serializePasswordHash(salt, tag), hashKeyId: keyring.activeKeyId });
+}
+
+async function verifyPasswordCredential(password, credential, keyring) {
+  const keys = getPasswordKeyringSecrets(keyring);
+  const pepper = keys.get(credential?.hashKeyId);
+  const parsedHash = parsePasswordHash(credential?.hash);
+  if (!pepper || !parsedHash || typeof password !== 'string' || !password.isWellFormed()) {
+    return { isValid: false, needsRehash: false };
   }
-  const candidateTag = await derivePasswordTag(password, parsedHash.salt, pepperBuffer);
-  return timingSafeEqual(candidateTag, parsedHash.tag);
+  const candidateTag = await derivePasswordTag(password, parsedHash.salt, pepper);
+  const isValid = timingSafeEqual(candidateTag, parsedHash.tag);
+  return { isValid, needsRehash: isValid && credential.hashKeyId !== keyring.activeKeyId };
 }
 
-module.exports = { createPasswordHash, verifyPassword };
+module.exports = {
+  createPasswordCredential,
+  parsePasswordHashKeyring,
+  verifyPasswordCredential,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/auth-util",
-  "version": "3.25.0",
+  "version": "3.27.0",
   "repository": "https://github.com/CareCard-ca/pkg-auth-util.git",
   "description": "Auth utility functions",
   "main": "index.js",
@@ -50,8 +50,8 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.25.0",
-    "@carecard/validate": "3.25.0",
+    "@carecard/common-util": "3.27.0",
+    "@carecard/validate": "3.27.0",
     "@types/express": "5.0.6"
   },
   "overrides": {

package/readme.md

@@ -25,9 +25,8 @@ Non-negotiable code organization rule: Functions with the same or equivalent beh
 
 ## Features
 
-- **JWT Utilities**: Create, verify, and parse JSON Web Tokens with support for EdDSA (Ed25519) and RSA.
-- **Password Utilities**: Asynchronous Argon2id password hashing through Node.js `crypto`, with a unique random salt and application pepper.
-- **Key Generation**: Generate Ed25519 and RSA key pairs for JWT signing.
+- **JWT Utilities**: Create and verify EdDSA JWTs through strict Ed25519 JWK and JWKS configuration.
+- **Password Utilities**: Rotate versioned Argon2id password peppers while preserving a strict saved-credential format.
 - **Crypto Utilities**: Low-level cryptographic primitives for signing, verification, and hashing.
 - **String Utilities**: Base64 and Base64UrlSafe encoding/decoding, and custom string parsing.
 
@@ -46,18 +45,17 @@ const {
   jwtCreateSignedToken,
   jwtGetHeaderPayload,
   jwtVerifySignedToken,
+  parseJwtSigningJwk,
+  parseJwtVerificationJwks,
 } = require('@carecard/auth-util');
 
-const header = { alg: 'EdDSA', typ: 'JWT' };
 const payload = { sub: '1234567890', name: 'John Doe' };
-const privateKey = '...'; // Your private PEM key
+const signingJwk = parseJwtSigningJwk(process.env.JWT_SIGNING_JWK);
+const verificationJwks = parseJwtVerificationJwks(process.env.JWT_VERIFICATION_JWKS);
 
-// Create a signed JWT
-const token = jwtCreateSignedToken(header, payload, privateKey);
+const token = jwtCreateSignedToken(payload, signingJwk);
 
-// Verify a JWT signature
-const publicKey = '...'; // Your public PEM key
-const isValid = jwtVerifySignedToken(token, publicKey);
+const isValid = jwtVerifySignedToken(token, verificationJwks);
 
 // Get header and payload from a JWT
 const { header: decodedHeader, payload: decodedPayload } = jwtGetHeaderPayload(token);
@@ -74,47 +72,51 @@ const {
 const token = jwtCreateServiceToken({
   issuer: 'ms-institutions',
   audience: 'ms-auth',
-  privateKey: institutionsPrivateKey,
+  signingJwk: institutionsSigningJwk,
 });
 
 const authorization = jwtCreateServiceAuthorizationHeader({
   issuer: 'ms-institutions',
   audience: 'ms-auth',
-  privateKey: institutionsPrivateKey,
+  signingJwk: institutionsSigningJwk,
 });
 ```
 
 ### Password Utilities
 
 ```javascript
-const { createPasswordHash, verifyPassword } = require('@carecard/auth-util');
+const {
+  createPasswordCredential,
+  parsePasswordHashKeyring,
+  verifyPasswordCredential,
+} = require('@carecard/auth-util');
 
 const password = 'correct horse battery staple';
-const pepper = process.env.MS_AUTH_HASH_KEY; // At least 32 UTF-8 bytes.
-
-// Create a strict Argon2id PHC credential with a unique random salt.
-const savedHash = await createPasswordHash(password, pepper);
-
-// Verify through the package boundary. Malformed and legacy credentials return false.
-const isCorrect = await verifyPassword(password, savedHash, pepper);
+const keyring = parsePasswordHashKeyring(
+  process.env.MS_AUTH_PASSWORD_HASH_ACTIVE_KEY_ID,
+  process.env.MS_AUTH_PASSWORD_HASH_KEYRING,
+);
+
+const credential = await createPasswordCredential(password, keyring);
+
+const result = await verifyPasswordCredential(password, credential, keyring);
+if (result.isValid && result.needsRehash) {
+  const replacement = await createPasswordCredential(password, keyring);
+  // Persist replacement.hash and replacement.hashKeyId atomically.
+}
 ```
 
-Both functions preserve password spaces and normalize well-formed Unicode to
-NFC. Password-policy checks belong to `@carecard/validate`; this package hashes
-and compares the supplied value without enforcing password length or
-composition. Keep the pepper outside persisted credentials and logs.
-
-### Key Generation
+Keyring entries use `key-id:canonical-base64-32-byte-key`, separated by commas.
+Credential rows persist both the PHC hash and its `hashKeyId`; pepper keys stay
+outside persisted credentials and logs. Passwords retain spaces and normalize
+well-formed Unicode to NFC. `@carecard/validate` owns password policy.
 
-```javascript
-const { generateKeyPair } = require('@carecard/auth-util');
-
-// Generate Ed25519 keys (default)
-const { publicKey, privateKey } = generateKeyPair();
-
-// Generate RSA keys
-const rsaKeys = generateKeyPair('rsa');
-```
+JWT signing configuration is one strict private Ed25519 JWK. Verification
+configuration is an RFC 7517 JWKS containing one or more public Ed25519 JWKs.
+Every key uses `alg: "EdDSA"`, `use: "sig"`, one exact `key_ops` operation, and
+an RFC 7638 SHA-256 thumbprint `kid`. Add replacement public keys before
+switching signers, and retain retiring public keys for the maximum token
+lifetime plus clock skew.
 
 ### String Utilities (`stringUtilAuth`)
 
@@ -159,9 +161,9 @@ npm run test:types
 
 The package is organized into several modules:
 
-- `jwtUtilAuth`: Manages the JWT lifecycle.
-- `pwdUtilAuth`: Implements asynchronous Argon2id password hashing and verification behind the direct package exports.
-- `keyGen`: Utility for generating cryptographic keys.
+- `jwkUtilAuth`: Strictly parses private signing JWKs and public verification JWKS values.
+- `jwtUtilAuth`: Creates fixed-header Ed25519 JWTs and verifies signatures by `kid`.
+- `pwdUtilAuth`: Creates and verifies versioned Argon2id password credentials.
 - `cryptoUtilAuth`: Core cryptographic operations using Node.js `crypto` module.
 - `stringUtilAuth`: String manipulation and format conversions.
 

package/lib/keyGen.js

@@ -1,24 +0,0 @@
-const { generateKeyPairSync } = require('node:crypto');
-
-const generateKeyPair = (algorithm = 'ed25519') => {
-  const options = {
-    publicKeyEncoding: {
-      type: 'spki',
-      format: 'pem',
-    },
-    privateKeyEncoding: {
-      type: 'pkcs8',
-      format: 'pem',
-    },
-  };
-
-  if (algorithm === 'rsa') {
-    options.modulusLength = 2048;
-  }
-
-  return generateKeyPairSync(algorithm, options);
-};
-
-module.exports = {
-  generateKeyPair,
-};