@onlineapps/service-common 2.0.0 → 3.0.0

package/src/infrastructure/waitForHealthCheckQueueReady.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const { connectRedis, buildRedisUrl } = require('../redisClient');
+const { createPrefixedLogger } = require('./prefixedLogger');
+const { redactUrl } = require('../redactUrl');
 const runtimeCfg = require('../config');
 
 /**
@@ -14,11 +16,12 @@ const runtimeCfg = require('../config');
  * 
  * **How it works:**
  * 1. Connects to Redis
- * 2. Checks `infrastructure:health:queue:ready` key every 2 seconds
+ * 2. Polls the `infrastructure:health:queue:ready` key at the resolved check
+ *    interval (see the `@param` notes below for where that value comes from)
  * 3. If key is `"true"` → queue is ready → return success
  * 4. If key is missing → wait and retry
  * 5. If timeout reached → throw error
- * 
+ *
  * **Usage:**
  * - Infrastructure services: Wait before starting health check publisher
  */
@@ -26,62 +29,61 @@ const runtimeCfg = require('../config');
 /**
  * Wait for health check queue to be ready
  * @param {Object} options - Options
- * @param {string} [options.redisUrl] - Redis URL (default: REDIS_URL env or redis://api_node_cache:6379)
- * @param {number} [options.maxWait] - Maximum wait time in ms (default: 60000 = 1 minute)
- * @param {number} [options.checkInterval] - Check interval in ms (default: 2000 = 2 seconds)
- * @param {Object} [options.logger] - Logger instance (default: console)
+ * @param {string} [options.redisUrl] - Redis URL. No default: `redisUrl` is
+ *   `required: true` in ../config.js, so an unset `REDIS_URL` fails fast.
+ * @param {number} [options.maxWait] - Maximum wait time in ms
+ *   (env `INFRASTRUCTURE_HEALTH_QUEUE_WAIT_MAX_TIME`, else `infrastructureHealthQueueWaitMaxTimeMs` in ../defaults.js)
+ * @param {number} [options.checkInterval] - Check interval in ms
+ *   (env `INFRASTRUCTURE_HEALTH_QUEUE_WAIT_CHECK_INTERVAL`, else `infrastructureHealthQueueWaitCheckIntervalMs` in ../defaults.js)
+ * @param {Object} options.logger - Logger implementing the four-method contract
+ *   (`info`, `warn`, `error`, `debug` — `@onlineapps/logger-contract`). Required, validated
+ *   before anything is contacted; no console fallback and no shape sniffing.
  * @returns {Promise<boolean>} - True if queue is ready
  * @throws {Error} - If timeout is reached
+ *
+ * Resolution order is the one @onlineapps/runtime-config applies to every key in
+ * ../config.js: explicit option → environment variable → module-owned default in
+ * ../defaults.js — the `runtimeCfg.get()` calls that open the function are the
+ * whole mechanism.
+ * This note used to promise a `redis://api_node_cache:6379` fallback for an unset
+ * `REDIS_URL`; no such default exists on this path — buildRedisUrl() states "No
+ * topology defaults (FAIL-FAST)" (../redisClient.js) and the key is `required`,
+ * so the documented fallback would have hidden the fail-fast it contradicts.
+ *
+ * The numbers are deliberately not repeated here; ../defaults.js owns them, and a
+ * copy in a comment only rots (doc-code-binding.md §1).
  */
 async function waitForHealthCheckQueueReady(options = {}) {
   const redisUrl = buildRedisUrl({ redisUrl: options.redisUrl });
   const maxWait = runtimeCfg.get('infrastructureHealthQueueWaitMaxTimeMs', options.maxWait);
   const checkInterval = runtimeCfg.get('infrastructureHealthQueueWaitCheckIntervalMs', options.checkInterval);
-  const logger = options.logger;
-  if (!logger) {
-    throw new Error('[service-common][waitForHealthCheckQueueReady] Missing dependency - logger is required (no console fallback).');
-  }
-  
-  const log = (msg) => {
-    if (logger && typeof logger.info === 'function') {
-      logger.info(msg);
-    } else if (logger && typeof logger.log === 'function') {
-      logger.log(msg);
-    } else if (logger && typeof logger === 'function') {
-      logger(msg);
-    } else {
-      throw new Error(
-        '[service-common][waitForHealthCheckQueueReady] Invalid logger - Expected logger.info(), logger.log(), or function logger(message).'
-      );
-    }
-  };
+  const logger = createPrefixedLogger(
+    'waitForHealthCheckQueueReady',
+    '[HealthCheckQueueReady]',
+    options.logger,
+    'the wait for the health-check queue is visible while it blocks'
+  );
 
   let redis = null;
   const startTime = Date.now();
   let attemptCount = 0;
 
-  log(`[HealthCheckQueueReady] Waiting for health check queue to be ready...`);
-  log(`[HealthCheckQueueReady] Redis URL: ${redisUrl}`);
-  log(`[HealthCheckQueueReady] Max wait: ${maxWait}ms, Check interval: ${checkInterval}ms`);
+  logger.info('Waiting for health check queue to be ready...');
+  // The URL carries the Redis credential (one rail, INFRA lead 2026-09-10);
+  // these lines go to Loki, so only the endpoint may appear.
+  logger.info(`Redis URL: ${redactUrl(redisUrl)}`);
+  logger.info(`Max wait: ${maxWait}ms, Check interval: ${checkInterval}ms`);
 
   try {
     // Connect to Redis using shared helper (consistent config + fail-fast behaviour)
+    // The same logger goes on, so what connectRedis writes carries this wait's mark.
     redis = await connectRedis({
       purpose: 'wait-for-health-check-queue-ready',
-      logger: {
-        info: (message, meta = {}) => {
-          const suffix = meta && meta.url ? ` (${meta.url})` : '';
-          log(`[HealthCheckQueueReady] ${message}${suffix}`);
-        },
-        error: (message, meta = {}) => {
-          const detail = meta && meta.error ? ` ${meta.error}` : '';
-          log(`[HealthCheckQueueReady] ${message}${detail}`);
-        }
-      },
+      logger,
       timeoutMs: 10000,
       redisUrl
     });
-    log('[HealthCheckQueueReady] Connected to Redis');
+    logger.info('Connected to Redis');
 
     while (Date.now() - startTime < maxWait) {
       attemptCount++;
@@ -93,14 +95,14 @@ async function waitForHealthCheckQueueReady(options = {}) {
         if (queueReady === 'true') {
           // Queue is ready, we can proceed
           const elapsed = Date.now() - startTime;
-          log(`[HealthCheckQueueReady] ✓ Health check queue is ready (took ${elapsed}ms, ${attemptCount} attempts)`);
+          logger.info(`✓ Health check queue is ready (took ${elapsed}ms, ${attemptCount} attempts)`);
           return true;
         }
 
-        log(`[HealthCheckQueueReady] Attempt ${attemptCount}: Queue not ready yet (current status: ${queueReady || 'unknown'}). Waiting ${checkInterval}ms...`);
+        logger.info(`Attempt ${attemptCount}: Queue not ready yet (current status: ${queueReady || 'unknown'}). Waiting ${checkInterval}ms...`);
 
       } catch (error) {
-        log(`[HealthCheckQueueReady] Attempt ${attemptCount}: Failed to get queue ready status from Redis (${error.message}). Waiting ${checkInterval}ms...`);
+        logger.warn(`Attempt ${attemptCount}: Failed to get queue ready status from Redis (${error.message}). Waiting ${checkInterval}ms...`);
       }
 
       await new Promise(resolve => setTimeout(resolve, checkInterval));
@@ -108,13 +110,14 @@ async function waitForHealthCheckQueueReady(options = {}) {
 
     const elapsed = Date.now() - startTime;
     throw new Error(
-      `Health check queue not ready within ${maxWait}ms (${elapsed}ms elapsed, ${attemptCount} attempts). ` +
-      `Check Redis key 'infrastructure:health:queue:ready' and ensure Registry has started.`
+      `[HealthCheckQueueReady] Health check queue not ready within ${maxWait}ms `
+      + `(${elapsed}ms elapsed, ${attemptCount} attempts) - the readiness flag never appeared. `
+      + "Fix: check the Redis key 'infrastructure:health:queue:ready' and that the Registry has started."
     );
   } finally {
     if (redis && redis.isReady) {
       await redis.quit();
-      log('[HealthCheckQueueReady] Disconnected from Redis.');
+      logger.info('Disconnected from Redis.');
     }
   }
 }

package/src/infrastructure/waitForInfrastructureReady.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const { connectRedis, buildRedisUrl } = require('../redisClient');
+const { createPrefixedLogger } = require('./prefixedLogger');
+const { redactUrl } = require('../redactUrl');
 const runtimeCfg = require('../config');
 
 /**
@@ -14,7 +16,8 @@ const runtimeCfg = require('../config');
  * 
  * **How it works:**
  * 1. Connects to Redis (where Registry stores infrastructure health status)
- * 2. Checks `infrastructure:health:all` key every 5 seconds
+ * 2. Polls the `infrastructure:health:all` key at the resolved check interval
+ *    (see the `@param` notes below for where that value comes from)
  * 3. If key is `"true"` → all infrastructure services are UP → return success
  * 4. If key is `"false"` or missing → wait and retry
  * 5. If timeout reached → throw error
@@ -34,69 +37,62 @@ const runtimeCfg = require('../config');
 /**
  * Wait for all infrastructure services to be ready
  * @param {Object} options - Options
- * @param {string} [options.redisUrl] - Redis URL (default: REDIS_URL env or redis://api_node_cache:6379)
- * @param {number} [options.maxWait] - Maximum wait time in ms (default: INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME env or 60000 = 1 minute)
- * @param {number} [options.checkInterval] - Check interval in ms (default: INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL env or 2000 = 2 seconds)
- * @param {Object} [options.logger] - Logger instance (default: console)
+ * @param {string} [options.redisUrl] - Redis URL. No default: `redisUrl` is
+ *   `required: true` in ../config.js, so an unset `REDIS_URL` fails fast.
+ * @param {number} [options.maxWait] - Maximum wait time in ms
+ *   (env `INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME`, else `infrastructureHealthWaitMaxTimeMs` in ../defaults.js)
+ * @param {number} [options.checkInterval] - Check interval in ms
+ *   (env `INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL`, else `infrastructureHealthWaitCheckIntervalMs` in ../defaults.js)
+ * @param {Object} options.logger - Logger implementing the four-method contract
+ *   (`info`, `warn`, `error`, `debug` — `@onlineapps/logger-contract`). Required, validated
+ *   before anything is contacted; no console fallback and no shape sniffing.
  * @returns {Promise<boolean>} - True if all infrastructure services are ready
  * @throws {Error} - If timeout is reached
- * 
- * Note: Default values can be overridden via ENV variables or options parameter.
- * Registry config (config.infrastructureHealth) is the source of truth for these defaults.
+ *
+ * Resolution order is the one @onlineapps/runtime-config applies to every key in
+ * ../config.js: explicit option → environment variable → module-owned default in
+ * ../defaults.js — the `runtimeCfg.get()` calls that open the function are the
+ * whole mechanism.
+ * This note used to send readers to "Registry config (config.infrastructureHealth)"
+ * as the source of truth for these defaults; no line on this path reads anything
+ * from the Registry, and the ownership runs the other way round — ../defaults.js
+ * owns the values, and services that expose them re-declare what it owns.
+ *
+ * The numbers are deliberately not repeated here; ../defaults.js owns them, and a
+ * copy in a comment only rots (doc-code-binding.md §1).
  */
 async function waitForInfrastructureReady(options = {}) {
   const redisUrl = buildRedisUrl({ redisUrl: options.redisUrl });
   const maxWait = runtimeCfg.get('infrastructureHealthWaitMaxTimeMs', options.maxWait);
   const checkInterval = runtimeCfg.get('infrastructureHealthWaitCheckIntervalMs', options.checkInterval);
-  const logger = options.logger;
-  if (!logger) {
-    throw new Error('[service-common][waitForInfrastructureReady] Missing dependency - logger is required (no console fallback).');
-  }
-
-  // Helper to log messages (compatible with both console and winston)
-  const log = (messageStr) => {
-    if (logger && typeof logger.log === 'function') {
-      // Winston-style logger
-      logger.log({ message: messageStr, level: 'info' });
-    } else if (logger && typeof logger.info === 'function') {
-      // Standard logger
-      logger.info(messageStr);
-    } else if (logger && typeof logger === 'function') {
-      // console.log or similar
-      logger(messageStr);
-    } else {
-      throw new Error(
-        '[service-common][waitForInfrastructureReady] Invalid logger - Expected logger.info(), logger.log(), or function logger(message).'
-      );
-    }
-  };
+  const logger = createPrefixedLogger(
+    'waitForInfrastructureReady',
+    '[InfrastructureReady]',
+    options.logger,
+    'the wait that blocks the boot is visible while it blocks'
+  );
 
   const startTime = Date.now();
   let attemptCount = 0;
   let redis = null;
 
-  log('[InfrastructureReady] Waiting for all infrastructure services to be ready...');
-  log(`[InfrastructureReady] Redis URL: ${redisUrl}`);
-  log(`[InfrastructureReady] Max wait: ${maxWait}ms, Check interval: ${checkInterval}ms`);
+  logger.info('Waiting for all infrastructure services to be ready...');
+  // The URL carries the Redis credential (one rail, INFRA lead 2026-09-10);
+  // these lines go to Loki, so only the endpoint may appear.
+  logger.info(`Redis URL: ${redactUrl(redisUrl)}`);
+  logger.info(`Max wait: ${maxWait}ms, Check interval: ${checkInterval}ms`);
 
   try {
     // Connect to Redis with timeout using shared helper (fail-fast, no infinite reconnect loops)
+    // The same logger goes on, so what connectRedis writes carries this wait's mark
+    // without connectRedis knowing anything about it.
     redis = await connectRedis({
       purpose: 'wait-for-infrastructure-ready',
-      logger: {
-        error: (message, meta = {}) => {
-          const msg = meta && meta.error ? `${message} ${meta.error}` : message;
-          log(`[InfrastructureReady] ${msg}`);
-        },
-        info: (message, meta = {}) => {
-          const suffix = meta && meta.url ? ` (${meta.url})` : '';
-          log(`[InfrastructureReady] ${message}${suffix}`);
-        }
-      },
+      logger,
       timeoutMs: 10000,
       redisUrl
     });
-    log('[InfrastructureReady] Connected to Redis');
+    logger.info('Connected to Redis');
 
     while (Date.now() - startTime < maxWait) {
       attemptCount++;
@@ -105,18 +101,32 @@ async function waitForInfrastructureReady(options = {}) {
         // Check Redis key: infrastructure:health:all with timeout to prevent hanging
         const REDIS_OPERATION_TIMEOUT = 5000; // 5 seconds per operation
         const getPromise = redis.get('infrastructure:health:all');
+        let getTimeoutHandle;
         const getTimeoutPromise = new Promise((_, reject) => {
-          setTimeout(() => {
-            reject(new Error(`Redis get() operation timeout after ${REDIS_OPERATION_TIMEOUT}ms`));
+          getTimeoutHandle = setTimeout(() => {
+            reject(new Error(
+              `[InfrastructureReady] Redis get() operation timeout after ${REDIS_OPERATION_TIMEOUT}ms - `
+              + "the key 'infrastructure:health:all' was never read. "
+              + 'Fix: check that Redis is reachable and responsive.'
+            ));
           }, REDIS_OPERATION_TIMEOUT);
         });
-        
-        const allHealthy = await Promise.race([getPromise, getTimeoutPromise]);
-        
+
+        let allHealthy;
+        try {
+          allHealthy = await Promise.race([getPromise, getTimeoutPromise]);
+        } finally {
+          // Promise.race settles on the first arm; the loser keeps running. Without
+          // this, every poll left a five-second timer holding the event loop after
+          // the wait had already answered — and this wait polls in a loop.
+          // Same defect, same fix as connectRedis (../redisClient.js).
+          clearTimeout(getTimeoutHandle);
+        }
+
         if (allHealthy === 'true') {
           // All services are UP, we can proceed
           const elapsed = Date.now() - startTime;
-          log(`[InfrastructureReady] ✓ All infrastructure services are ready (took ${elapsed}ms, ${attemptCount} attempts)`);
+          logger.info(`✓ All infrastructure services are ready (took ${elapsed}ms, ${attemptCount} attempts)`);
           
           // Optionally log individual service status
           // Note: Service names should match config.infrastructureServices in Registry
@@ -125,34 +135,51 @@ async function waitForInfrastructureReady(options = {}) {
           for (const serviceName of serviceKeys) {
             try {
               const statusPromise = redis.get(`infrastructure:health:${serviceName}`);
+              let statusTimeoutHandle;
               const statusTimeoutPromise = new Promise((_, reject) => {
-                setTimeout(() => reject(new Error('timeout')), REDIS_OPERATION_TIMEOUT);
+                statusTimeoutHandle = setTimeout(() => reject(new Error(
+                  `[InfrastructureReady] Redis get() timeout after ${REDIS_OPERATION_TIMEOUT}ms - `
+                  + `the status key of ${serviceName} was never read. `
+                  + 'Fix: check that Redis is reachable and responsive.'
+                )), REDIS_OPERATION_TIMEOUT);
               });
-              const status = await Promise.race([statusPromise, statusTimeoutPromise]);
+
+              let status;
+              try {
+                status = await Promise.race([statusPromise, statusTimeoutPromise]);
+              } finally {
+                clearTimeout(statusTimeoutHandle);
+              }
+
               if (status) {
                 statuses[serviceName] = JSON.parse(status);
               }
             } catch (statusError) {
               // Ignore individual service status errors
-              log(`[InfrastructureReady] Could not get status for ${serviceName}: ${statusError.message}`);
+              logger.warn(`Could not get status for ${serviceName}: ${statusError.message}`);
             }
           }
           if (Object.keys(statuses).length > 0) {
-            log(`[InfrastructureReady] Individual service status: ${JSON.stringify(statuses, null, 2)}`);
+            logger.info(`Individual service status: ${JSON.stringify(statuses, null, 2)}`);
           }
           
           return true;
         }
 
-        log(`[InfrastructureReady] Attempt ${attemptCount}: Not all services ready (current status: ${allHealthy || 'unknown'}). Waiting ${checkInterval}ms...`);
+        logger.info(`Attempt ${attemptCount}: Not all services ready (current status: ${allHealthy || 'unknown'}). Waiting ${checkInterval}ms...`);
 
       } catch (error) {
         const errorMsg = error.message || String(error);
-        log(`[InfrastructureReady] Attempt ${attemptCount}: Failed to get infrastructure health from Redis (${errorMsg}). Waiting ${checkInterval}ms...`);
+        logger.warn(`Attempt ${attemptCount}: Failed to get infrastructure health from Redis (${errorMsg}). Waiting ${checkInterval}ms...`);
         
         // If Redis connection is lost, throw error immediately instead of retrying
         if (errorMsg.includes('timeout') || errorMsg.includes('ECONNREFUSED') || errorMsg.includes('ENOTFOUND')) {
-          throw new Error(`[InfrastructureReady] Redis connection lost: ${errorMsg}. Cannot continue waiting for infrastructure ready.`);
+          throw new Error(
+            `[InfrastructureReady] Redis connection lost - ${errorMsg} `
+            + '— waiting for infrastructure readiness cannot continue without Redis. '
+            + 'Fix: restore Redis and boot again.',
+            { cause: error }
+          );
         }
       }
 
@@ -161,13 +188,14 @@ async function waitForInfrastructureReady(options = {}) {
 
     const elapsed = Date.now() - startTime;
     throw new Error(
-      `Infrastructure services not ready within ${maxWait}ms (${elapsed}ms elapsed, ${attemptCount} attempts). ` +
-      `Check Redis key 'infrastructure:health:all' and individual service health keys.`
+      `[InfrastructureReady] Infrastructure services not ready within ${maxWait}ms `
+      + `(${elapsed}ms elapsed, ${attemptCount} attempts) - the readiness flag never turned true. `
+      + "Fix: check the Redis key 'infrastructure:health:all' and the individual service health keys."
     );
   } finally {
     if (redis && redis.isReady) {
       await redis.quit();
-      log('[InfrastructureReady] Disconnected from Redis.');
+      logger.info('Disconnected from Redis.');
     }
   }
 }

package/src/jwt/createJwtValidator.js

@@ -1,9 +1,12 @@
 'use strict';
 
-const { verifyAccessToken } = require('./verifyAccessToken');
+const { verifyAccessToken, assertSecret } = require('./verifyAccessToken');
 
 // See: docs/standards/JWT_AUTH.md §9.1 — forced refresh on role change
-const ROLES_VERSION_PREFIX = 'person:roles_version:';
+const ROLES_VERSION_PREFIX = 'state:meta:person:roles_version:';
+
+const ROLES_VERSION_CHECK_UNAVAILABLE = 'ROLES_VERSION_CHECK_UNAVAILABLE';
+const TOKEN_PERSON_ID_MISSING = 'TOKEN_PERSON_ID_MISSING';
 
 /**
  * Create Express middleware that validates JWT Bearer tokens on incoming requests.
@@ -12,15 +15,91 @@ const ROLES_VERSION_PREFIX = 'person:roles_version:';
  * On failure: responds with 401 JSON.
  * Paths listed in excludePaths are skipped (transparent pass-through).
  *
+ * A token whose payload carries no `person_id` is refused with 401
+ * TOKEN_PERSON_ID_MISSING before the roles-version check runs: `api_auth` issues
+ * every access and refresh token with the claim, so no legitimate class of
+ * tokens lacks it, and the claim is what the check is keyed on — accepting a
+ * token without it would mean skipping the check for that request.
+ * @see docs/governance/confirmations/jwt-stale-check-fail-closed.md 002
+ *
+ * ## The roles-version check is an injected reader, not a Redis client
+ *
+ * `readRolesVersion(personId)` returns the marker the owning service wrote for
+ * that person — epoch milliseconds — or `null` when no marker exists. It is
+ * REQUIRED: the check runs for every valid token, so an instance that could not
+ * perform it is refused at construction rather than serving unverified requests
+ * (`jwt-stale-check-fail-closed` 001 § Conditions, architecture-principles.md §4).
+ *
+ * Reading is the caller's job because the shape of the store is the caller's
+ * knowledge: the validator used to test `redisClient.isOpen` and call
+ * `redisClient.get()`, which is the node-redis v4 API — a service whose client is
+ * `ioredis` could not be given the check at all (`infra/api_meta_reader`).
+ * A function has one shape and every client can implement it
+ * (architecture-principles.md §1 dependency injection, §8 explicit over implicit).
+ *
+ * The key the reader must read is the FULL, prefixed key
+ * `state:meta:person:roles_version:<person_id>` — exported here as
+ * `ROLES_VERSION_PREFIX`, so the reader composes it rather than spelling it out:
+ * the marker is a projection of the meta service state, written by biz-meta under
+ * the `state:meta:` prefix its state connector adds, and a reader that asks for
+ * the bare `person:roles_version:<id>` gets `null` for every person — which is
+ * indistinguishable from "no role change" and answers `TOKEN_STALE` never.
+ * Owner decision 2026-09-14.
+ * @see api/docs/governance/confirmations/redis-state-prefix.md 002
+ * @see api/docs/standards/redis-key-contract.md
+ *
+ * ```js
+ * const readRolesVersion = async (personId) => {
+ *   const raw = await redis.get(`${ROLES_VERSION_PREFIX}${personId}`);
+ *   return raw === null ? null : Number(raw);
+ * };
+ * ```
+ *
+ * The check is fail-closed: whenever it cannot be performed — the reader rejects,
+ * or answers with anything but a finite number or `null` — the request is refused
+ * with 503, never let through unverified.
+ * @see docs/governance/confirmations/jwt-stale-check-fail-closed.md 001
+ *
+ * ## Units: the token counts seconds, the marker milliseconds
+ *
+ * `iat` is a whole number of SECONDS (RFC 7519 §4.1.6), rounded down; the marker
+ * is epoch MILLISECONDS (`redis-key-contract.md`). Compared in milliseconds, a
+ * token issued 400 ms after the role change it already reflects looks older than
+ * that change, and its holder is told to refresh a token that is current. The
+ * comparison therefore happens in the coarser unit of the two: the marker is
+ * floored to whole seconds, and a token issued in the same second as the marker
+ * is NOT stale.
+ *
+ * The signing secret is an input of the instance, resolved by the caller at boot
+ * (`requireEnv('JWT_SECRET', …, { file: 'shared.env' })`) and passed in here. The
+ * library never reads the environment: where a secret comes from is the owning
+ * service's knowledge, not a shared library's (architecture-principles.md §1, §8).
+ * An instance built without a usable secret is refused at construction (§4).
+ * @see api/docs/standards/JWT_AUTH.md § Configuration
+ *
  * @param {object} options
- * @param {object} options.logger - Logger with .warn() method (required)
+ * @param {object} options.logger - Logger with .warn() and .error() methods (required)
+ * @param {string} options.secret - HMAC-SHA256 signing secret, min 16 characters (required)
+ * @param {function} options.readRolesVersion - `(personId) => Promise<number|null>`
+ *   reading `state:meta:person:roles_version:<person_id>` (required)
  * @param {string[]} [options.excludePaths] - Paths to skip JWT validation
- * @param {object} [options.redisClient] - Redis client for role version check (optional)
  * @returns {Function} Express middleware (req, res, next)
  */
-function createJwtValidator({ logger, excludePaths, redisClient }) {
-  if (!logger || typeof logger.warn !== 'function') {
-    throw new Error('[JWT] Logger is required - Expected object with warn() method');
+function createJwtValidator({ logger, secret, excludePaths, readRolesVersion }) {
+  if (!logger || typeof logger.warn !== 'function' || typeof logger.error !== 'function') {
+    throw new Error('[JWT] Logger is required - Expected object with warn() and error() methods');
+  }
+
+  assertSecret(secret);
+
+  if (typeof readRolesVersion !== 'function') {
+    throw new Error(
+      '[JWT] Roles-version reader is required - Expected a function '
+      + '(personId) => Promise<number|null> returning the epoch milliseconds stored at '
+      + `${ROLES_VERSION_PREFIX}<person_id>, or null when no marker exists. `
+      + 'Fix: pass readRolesVersion when constructing the validator — the check runs for '
+      + 'every valid token and an instance that cannot perform it must not exist'
+    );
   }
 
   const excluded = new Set(excludePaths || []);
@@ -40,28 +119,79 @@ function createJwtValidator({ logger, excludePaths, redisClient }) {
     const token = authHeader.slice(7);
 
     try {
-      const decoded = verifyAccessToken(token);
-
-      if (redisClient && redisClient.isOpen && decoded.person_id) {
-        try {
-          const rolesVersion = await redisClient.get(`${ROLES_VERSION_PREFIX}${decoded.person_id}`);
-          if (rolesVersion) {
-            const versionTs = parseInt(rolesVersion, 10);
-            const tokenIat = decoded.iat * 1000;
-            if (!isNaN(versionTs) && tokenIat < versionTs) {
-              logger.warn('[JWT] Token stale — role changed after issuance', {
-                person_id: decoded.person_id,
-                token_iat: new Date(tokenIat).toISOString(),
-                roles_changed: new Date(versionTs).toISOString()
-              });
-              return res.status(401).json({
-                error: 'Token stale — your roles have changed, please refresh your access token',
-                code: 'TOKEN_STALE'
-              });
-            }
-          }
-        } catch (redisErr) {
-          logger.warn('[JWT] Redis role version check failed (non-blocking)', { error: redisErr.message });
+      const decoded = verifyAccessToken(token, secret);
+
+      // Fail-fast on the payload shape, ahead of any check keyed on it: an
+      // absent (or null, or empty) person_id used to make the roles-version
+      // check silently skippable, which is an implicit lenient branch
+      // (architecture-principles.md §3 no fallbacks, §8 explicit over implicit).
+      const personId = decoded.person_id;
+      if (personId === undefined || personId === null || personId === '') {
+        logger.warn('[JWT] Token rejected — payload carries no person_id', {
+          person_uuid: decoded.sub
+        });
+        return res.status(401).json({
+          error:
+            '[JWT] Token payload carries no person_id - Expected an access token with the ' +
+            'person_id claim (every token api_auth issues has one); without it the token ' +
+            `cannot be checked against ${ROLES_VERSION_PREFIX}<person_id>. ` +
+            'Fix: sign in again to obtain a current access token',
+          code: TOKEN_PERSON_ID_MISSING
+        });
+      }
+
+      let rolesVersion;
+      try {
+        rolesVersion = await readRolesVersion(personId);
+      } catch (readErr) {
+        logger.error('[JWT] Roles-version check failed — request refused', {
+          person_id: personId,
+          error: readErr && readErr.message ? readErr.message : String(readErr)
+        });
+        return res.status(503).json({
+          error:
+            '[JWT] Roles-version check unavailable - reading ' +
+            `${ROLES_VERSION_PREFIX}<person_id> failed, so a role change cannot be ruled out. ` +
+            'Fix: restore the store that holds the marker and retry the request',
+          code: ROLES_VERSION_CHECK_UNAVAILABLE
+        });
+      }
+
+      if (rolesVersion !== null) {
+        // Anything but a finite number is a reader that cannot answer the
+        // question — the same situation as an error, so the same answer
+        // (fail-closed, confirmation 001). `undefined` included: the contract
+        // says null for "no marker", and a reader returning nothing is broken.
+        if (typeof rolesVersion !== 'number' || !Number.isFinite(rolesVersion)) {
+          logger.error('[JWT] Roles-version check failed — request refused', {
+            person_id: personId,
+            error: `readRolesVersion returned ${typeof rolesVersion}, expected number or null`
+          });
+          return res.status(503).json({
+            error:
+              '[JWT] Roles-version check unavailable - readRolesVersion answered with ' +
+              `${typeof rolesVersion}, expected the epoch milliseconds stored at ` +
+              `${ROLES_VERSION_PREFIX}<person_id> as a finite number, or null when the key ` +
+              'does not exist; a role change cannot be ruled out. ' +
+              'Fix: return Number(<stored value>) from the reader',
+            code: ROLES_VERSION_CHECK_UNAVAILABLE
+          });
+        }
+
+        // `iat` counts whole seconds, the marker counts milliseconds: the
+        // comparison happens in the coarser unit, so a token issued in the same
+        // second as the role change is current, not stale.
+        const rolesChangedAtSec = Math.floor(rolesVersion / 1000);
+        if (decoded.iat < rolesChangedAtSec) {
+          logger.warn('[JWT] Token stale — role changed after issuance', {
+            person_id: personId,
+            token_iat: new Date(decoded.iat * 1000).toISOString(),
+            roles_changed: new Date(rolesVersion).toISOString()
+          });
+          return res.status(401).json({
+            error: 'Token stale — your roles have changed, please refresh your access token',
+            code: 'TOKEN_STALE'
+          });
         }
       }