@onlineapps/service-common 2.0.0 → 3.0.0

package/src/jwt/verifyAccessToken.js

@@ -6,17 +6,34 @@ const ISSUER = 'oa-auth';
 const MIN_SECRET_LENGTH = 16;
 
 /**
- * Resolve JWT_SECRET from environment. Fail-fast on missing/insecure value.
- * @returns {string}
+ * Validate the signing secret the caller passed in.
+ *
+ * The secret is an INPUT of this library and never something it resolves for
+ * itself: a library that reads `process.env.JWT_SECRET` knows where the platform
+ * keeps its configuration, which is exactly what principle 1 (dependencies by
+ * constructor) and principle 8 (explicit over implicit) forbid. The RULE about
+ * the value — a string of at least MIN_SECRET_LENGTH characters, the minimum
+ * `JWT_AUTH.md` § Configuration states — stays here, because it is a property of
+ * the secret rather than of where it came from.
+ *
+ * Both public entry points validate against this one function: `createJwtValidator`
+ * at construction and `verifyAccessToken` at method entry (principle 4,
+ * fail-fast), so an instance can never be built with a secret a request would
+ * then be refused for.
+ *
+ * @param {string} secret - HMAC-SHA256 signing secret, resolved by the caller
+ * @throws {Error} If the secret is absent, not a string, or shorter than the minimum
+ * @see api/docs/standards/JWT_AUTH.md § Configuration
  */
-function getJwtSecret() {
-  const secret = process.env.JWT_SECRET;
-  if (!secret || secret.length < MIN_SECRET_LENGTH) {
+function assertSecret(secret) {
+  if (typeof secret !== 'string' || secret.length < MIN_SECRET_LENGTH) {
     throw new Error(
-      `[JWT] Missing or insecure JWT_SECRET - Expected env var with at least ${MIN_SECRET_LENGTH} characters`
+      `[JWT] Missing or insecure secret - Expected a string of at least ${MIN_SECRET_LENGTH} characters, `
+      + 'passed in by the caller. Fix: resolve the platform key once at boot with '
+      + 'requireEnv("JWT_SECRET", "HMAC-SHA256 signing secret", { file: "shared.env" }) and pass the '
+      + 'value as verifyAccessToken(token, secret) / createJwtValidator({ secret }).'
     );
   }
-  return secret;
 }
 
 /**
@@ -27,15 +44,17 @@ function getJwtSecret() {
  * Throws on any validation failure — callers decide how to handle.
  *
  * @param {string} token - Raw JWT string (without "Bearer " prefix)
+ * @param {string} secret - HMAC-SHA256 signing secret (see {@link assertSecret})
  * @returns {object} Decoded payload: { sub, person_id, email, tenants, type, iss, iat, exp }
- * @throws {Error} TokenExpiredError, JsonWebTokenError, or type mismatch
+ * @throws {Error} TokenExpiredError, JsonWebTokenError, type mismatch, or an invalid secret
  */
-function verifyAccessToken(token) {
+function verifyAccessToken(token, secret) {
   if (!token || typeof token !== 'string') {
     throw new Error('[JWT] Token is required - Expected non-empty string');
   }
 
-  const secret = getJwtSecret();
+  assertSecret(secret);
+
   const decoded = jwt.verify(token, secret, { issuer: ISSUER });
 
   if (decoded.type !== 'access') {
@@ -47,4 +66,4 @@ function verifyAccessToken(token) {
   return decoded;
 }
 
-module.exports = { verifyAccessToken, getJwtSecret, ISSUER, MIN_SECRET_LENGTH };
+module.exports = { verifyAccessToken, assertSecret, ISSUER, MIN_SECRET_LENGTH };

package/src/redactUrl.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Redaction of credentials carried in a connection URL.
+ *
+ * `REDIS_URL` is the single rail for the Redis credential (INFRA lead's decision
+ * 2026-09-10: one rail, no separate `REDIS_PASSWORD` in the shared env set).
+ * That makes every place which logs the URL verbatim a credential leak — and
+ * these logs go to Loki, so the leak is durable and searchable.
+ *
+ * `redactUrl` returns the same URL with the userinfo removed: what stays is the
+ * part a reader of the log actually needs — scheme, host, port, path.
+ *
+ * A value that is not a parseable URL is returned as a fixed placeholder rather
+ * than echoed: an unparseable string is exactly the case where nobody can say
+ * whether it holds a credential, and echoing it would be the leak this helper
+ * exists to prevent.
+ */
+
+const UNPARSEABLE_PLACEHOLDER = '<unparseable-url>';
+
+/**
+ * Strip userinfo (`user:password@`) from a connection URL.
+ *
+ * @param {string} url - connection URL, e.g. `redis://:secret@cache:6379`
+ * @returns {string} the URL without userinfo, e.g. `redis://cache:6379`,
+ *   or `<unparseable-url>` when the input is not a URL.
+ */
+function redactUrl(url) {
+  if (typeof url !== 'string' || url.length === 0) {
+    return UNPARSEABLE_PLACEHOLDER;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (_) {
+    return UNPARSEABLE_PLACEHOLDER;
+  }
+  // `new URL('cache-host:6379')` SUCCEEDS — it reads `cache-host:` as the scheme
+  // and `6379` as an opaque path, so the value comes back with an empty host and
+  // no userinfo to strip. Measured 2026-09-11; without this guard such a value
+  // would be echoed verbatim, which is the leak this helper exists to prevent.
+  if (!parsed.host) {
+    return UNPARSEABLE_PLACEHOLDER;
+  }
+  parsed.username = '';
+  parsed.password = '';
+  // `URL.href` re-appends a trailing slash for an empty path; the URLs this is
+  // used on are host:port endpoints, and `redis://cache:6379/` is not the shape
+  // the rest of the platform writes.
+  const href = parsed.href;
+  return parsed.pathname === '/' && !url.endsWith('/') ? href.replace(/\/$/, '') : href;
+}
+
+module.exports = {
+  redactUrl,
+  UNPARSEABLE_PLACEHOLDER
+};

package/src/redisClient.js

@@ -15,6 +15,48 @@
 const { createClient } = require('redis');
 const runtimeCfg = require('./config');
 const { createRuntimeConfig } = require('@onlineapps/runtime-config');
+const { assertLogger } = require('@onlineapps/logger-contract');
+const { redactUrl } = require('./redactUrl');
+
+/**
+ * Share of the caller's `timeoutMs` that node-redis' OWN connect attempt gets;
+ * the remaining fifth is the reserve the hard race below keeps for itself. The
+ * value is derived from the budget the caller already passes — no second knob,
+ * no env key, and the deadline the caller asked for stays the deadline.
+ *
+ * Why the attempt must end FIRST: `RedisSocket#disconnect()` destroys only a
+ * socket it has already assigned (`@redis/client` `socket.js`
+ * `_RedisSocket_disconnect`), so a connect still in flight survives our
+ * `disconnect()` and keeps its TCPWRAP handle open for node-redis' default
+ * 5 s. What does destroy it is node-redis' own
+ * `socket.setTimeout(connectTimeout, () => socket.destroy(…))`, armed in
+ * `_RedisSocket_createSocket` and cleared again the moment the socket connects,
+ * so an established connection is never touched by it.
+ *
+ * A fifth is reserve enough: measured on @redis/client 1.6.1 (2026-09-14), the
+ * attempt rejects 3 ms after its configured deadline (40 ms → 43.0 ms and
+ * 42.3 ms, 200 ms → 203.3 ms and 201.8 ms, 1000 ms → 1001.0 ms), while the
+ * reserve is 10 ms at the smallest timeout this package calls with (50 ms in
+ * the unit tier) and 3 s at the 15 s default.
+ */
+const CONNECT_ATTEMPT_SHARE = 0.8;
+
+/**
+ * Did node-redis end its own connect attempt on the deadline we gave it?
+ *
+ * It reports that as `ConnectionTimeoutError` ('Connection timeout') — a class
+ * it exports but never names on the instance: measured on @redis/client 1.6.1,
+ * `err.name` is 'Error' and only `err.constructor.name` carries the type. It is
+ * read off the instance rather than imported, so a test double of `redis` does
+ * not have to grow an export for this module to keep telling the truth about
+ * which deadline was hit.
+ *
+ * @param {*} err - The error the connect attempt rejected with
+ * @returns {boolean}
+ */
+function isConnectDeadline(err) {
+  return Boolean(err) && Boolean(err.constructor) && err.constructor.name === 'ConnectionTimeoutError';
+}
 
 /**
  * Build a Redis connection URL from environment.
@@ -53,87 +95,183 @@ function buildRedisUrl(options = {}) {
  * @param {Object} options
  * @param {string} [options.purpose] - Logical purpose (for log context)
  * @param {boolean} [options.forTests=false] - If true, disables automatic reconnect loops
- * @param {Object} [options.logger=console] - Logger with .error/.info methods
+ * @param {Object} options.logger - Logger with info/warn/error/debug (required)
  * @param {Object} [options.env=process.env] - Optional env override (for tests)
  * @param {Object} [options.defaults] - Optional default host/port overrides
- * @returns {{ client: import('redis').RedisClientType, url: string }}
+ * @param {number} [options.connectAttemptTimeoutMs] - Deadline for ONE node-redis
+ *   connect attempt (`socket.connectTimeout`). Left to node-redis' own default
+ *   when absent. Not the same thing as the overall ceiling `connectRedis` keeps:
+ *   a reconnect strategy may spend this budget once per attempt.
+ * @returns {{ client: import('redis').RedisClientType, url: string, loggedUrl: string }}
+ *   `url` is the real connection URL, credential included — it goes to the
+ *   client. `loggedUrl` is the same endpoint with the userinfo stripped, and it
+ *   is the ONLY one of the two that may reach a log line or an error message.
  */
 function createRedisClient(options = {}) {
   const {
     purpose = 'default',
     forTests = false,
-    logger = console,
     env,
-    redisUrl
+    redisUrl,
+    connectAttemptTimeoutMs
   } = options;
 
+  // A redis 'error' event has nowhere else to go: the emitter swallows it, and
+  // an unhandled one takes the process down. That is the whole reason the logger
+  // is a hard requirement here (confirmation 001, 002).
+  const log = assertLogger(
+    'createRedisClient',
+    options.logger,
+    'the Redis error event this client swallows still reaches the structured log'
+  );
+
   const url = buildRedisUrl({ env, redisUrl });
 
-  const socketOptions = forTests
-    ? {
-        // In tests we typically want fail-fast behaviour, not infinite reconnect loops
-        reconnectStrategy: false
-      }
-    : {};
+  const socketOptions = {};
+  if (forTests) {
+    // In tests we typically want fail-fast behaviour, not infinite reconnect loops
+    socketOptions.reconnectStrategy = false;
+  }
+  if (connectAttemptTimeoutMs !== undefined) {
+    // node-redis destroys the socket of an attempt that overruns this, which is
+    // the only thing that releases a connect still in flight. @see CONNECT_ATTEMPT_SHARE
+    socketOptions.connectTimeout = connectAttemptTimeoutMs;
+  }
 
   const client = createClient({
     url,
     socket: socketOptions
   });
 
-  const log = logger && typeof logger.error === 'function' ? logger : console;
+  // The URL carries the credential; the log carries the endpoint only.
+  // @see ./redactUrl.js
+  const loggedUrl = redactUrl(url);
 
   client.on('error', (err) => {
-    try {
-      log.error('[Redis] Error', {
-        purpose,
-        url,
-        message: err && err.message ? err.message : String(err)
-      });
-    } catch {
-      // Last-resort fallback to avoid throwing in error handler
-      // eslint-disable-next-line no-console
-      console.error('[Redis] Error', err);
-    }
+    log.error('[Redis] Error', {
+      purpose,
+      url: loggedUrl,
+      message: err && err.message ? err.message : String(err)
+    });
   });
 
-  return { client, url };
+  return { client, url, loggedUrl };
 }
 
 /**
  * Create and connect a Redis client with a hard timeout (useful for tests/tools).
  *
+ * Every way the connect can fail — node-redis rejecting on its own, the hard
+ * race expiring — leaves through ONE message in the `[Context] Problem - Fix`
+ * shape, with the original error as `cause`.
+ *
  * @param {Object} options - Same as createRedisClient plus:
- * @param {number} [options.timeoutMs=15000] - Max time to wait for connect()
+ * @param {number} [options.timeoutMs=15000] - Max time to wait for connect().
+ *   node-redis' own attempt is given `CONNECT_ATTEMPT_SHARE` of it, so the
+ *   attempt ends — and releases its socket — inside this ceiling.
  * @returns {Promise<import('redis').RedisClientType>}
  */
 async function connectRedis(options = {}) {
-  const { timeoutMs = 15000, logger = console } = options;
-  const { client, url } = createRedisClient(options);
+  const { timeoutMs = 15000 } = options;
+  // Validated here as well as in createRedisClient, so the message names the
+  // entry point the caller actually used.
+  const logger = assertLogger(
+    'connectRedis',
+    options.logger,
+    'the established connection and the Redis error events are recorded'
+  );
+  const hasDeadline = Boolean(timeoutMs) && timeoutMs > 0;
+  // node-redis' own attempt ends a fifth of the budget BEFORE our hard race, so
+  // the socket it opened is destroyed by the library that owns it — our
+  // `disconnect()` below cannot reach a socket that is not assigned yet.
+  // @see CONNECT_ATTEMPT_SHARE
+  const connectAttemptTimeoutMs = hasDeadline
+    ? Math.max(1, Math.floor(timeoutMs * CONNECT_ATTEMPT_SHARE))
+    : undefined;
+  // `url` carries the credential and is never rendered anywhere below;
+  // `loggedUrl` is the endpoint form and is what every message here uses.
+  const { client, loggedUrl } = createRedisClient({ ...options, connectAttemptTimeoutMs });
 
-  if (!timeoutMs || timeoutMs <= 0) {
+  if (!hasDeadline) {
     await client.connect();
-    if (logger && typeof logger.info === 'function') {
-      logger.info('[Redis] Connected', { url });
-    }
+    logger.info('[Redis] Connected', { url: loggedUrl });
     return client;
   }
 
   const connectPromise = client.connect();
-  const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(
-      () => reject(new Error(`Redis connection timeout after ${timeoutMs}ms to ${url}`)),
+  let raceLost = false;
+  let timeoutHandle;
+  // The race arm carries no message of its own — it only says which arm won.
+  // Every failure then leaves this function through the single throw below, so
+  // the contract message has one owner and node-redis' bare 'Connection
+  // timeout' never reaches a caller.
+  const hardDeadline = new Promise((resolve) => {
+    timeoutHandle = setTimeout(
+      () => {
+        raceLost = true;
+        resolve();
+      },
       timeoutMs
     );
   });
 
-  await Promise.race([connectPromise, timeoutPromise]);
+  let cause;
+  try {
+    await Promise.race([connectPromise, hardDeadline]);
+  } catch (err) {
+    cause = err;
+  } finally {
+    // Promise.race settles on the first arm; the loser keeps running. Without
+    // this the process held the timer for the full timeoutMs after a connection
+    // that had already succeeded — long enough to keep the event loop alive.
+    clearTimeout(timeoutHandle);
+  }
+
+  if (!raceLost && cause === undefined) {
+    logger.info('[Redis] Connected', { url: loggedUrl });
+    return client;
+  }
 
-  if (logger && typeof logger.info === 'function') {
-    logger.info('[Redis] Connected', { url });
+  // The connect arm keeps running after it loses the race — with node-redis'
+  // default reconnect strategy it keeps retrying — and the caller never
+  // receives the client on this path, so this function is the only place that
+  // can release the socket it opened. `isOpen` is false when connect() failed
+  // on its own (node-redis closed it already) and disconnecting then throws.
+  if (client.isOpen) {
+    try {
+      await client.disconnect();
+    } catch (disconnectErr) {
+      // Reported, never swallowed — and never in place of the original
+      // failure, which is what the caller asked about.
+      logger.warn('[Redis] Releasing the failed connection failed', {
+        url: loggedUrl,
+        message: disconnectErr && disconnectErr.message
+          ? disconnectErr.message
+          : String(disconnectErr)
+      });
+    }
   }
 
-  return client;
+  // One shape for every way a connect can fail, with the original kept as
+  // `cause` rather than interpolated — interpolating copies the text and throws
+  // the stack away. The verdict is the one fact that differs: a deadline (ours,
+  // or the one we gave node-redis) is not the same event as a refused
+  // connection, and a message calling it one would be untrue.
+  const verdict = raceLost || isConnectDeadline(cause)
+    ? `timeout after ${timeoutMs}ms`
+    : 'failed';
+  // node-redis builds its messages from host:port and never renders the URL it
+  // was handed, so the credential cannot arrive through here.
+  const reason = cause === undefined
+    ? 'the client never reported ready'
+    : (cause.message ? cause.message : String(cause));
+
+  throw new Error(
+    `[service-common][redisClient] Redis connection ${verdict} to ${loggedUrl} - ${reason}. `
+    + 'Fix: check that Redis is running at that URL, or raise timeoutMs if the instance '
+    + 'is merely slow to accept.',
+    { cause }
+  );
 }
 
 module.exports = {

package/src/registryReader.js

@@ -29,7 +29,8 @@
  * @see api/docs/standards/redis-key-contract.md — registry namespace
  */
 
-const { createClient } = require('redis');
+const { assertLogger } = require('@onlineapps/logger-contract');
+const { connectRedis } = require('./redisClient');
 const DEFAULTS = require('./defaults');
 
 const CONTEXT = '[service-common][registryReader]';
@@ -45,18 +46,6 @@ function requireKeyPrefix(keyPrefix) {
   return keyPrefix;
 }
 
-function requireLogger(logger) {
-  const missing = ['info', 'warn', 'error'].filter(
-    (method) => !logger || typeof logger[method] !== 'function'
-  );
-  if (missing.length > 0) {
-    throw new Error(
-      `${CONTEXT} Missing dependency - logger is required and must implement ${missing.join(', ')} `
-      + '(no console fallback). Fix: inject the service logger.'
-    );
-  }
-  return logger;
-}
 
 function requireTtl(value, name, fallbackDefault) {
   if (value === undefined) return fallbackDefault;
@@ -112,7 +101,8 @@ function parseOrThrow(raw, key, what) {
  * @param {string}  options.keyPrefix       Registry key namespace (REQUIRED, no default)
  * @param {string}  [options.redisUrl]      Redis connection URL
  * @param {object}  [options.client]        Connected node-redis v4 client
- * @param {object}  options.logger          Logger implementing info/warn/error (REQUIRED)
+ * @param {object}  options.logger          Logger implementing info/warn/error/debug (REQUIRED,
+ *                                          `@onlineapps/logger-contract`; no console fallback)
  * @param {number}  [options.ttlMs]         TTL of a cached spec (default: defaults.registryReaderTtlMs)
  * @param {number}  [options.negativeTtlMs] TTL of a cached "not registered" (default: defaults.registryReaderNegativeTtlMs)
  * @returns {object} reader
@@ -149,7 +139,16 @@ function createRegistryReader(options) {
     requireClientContract(client);
   }
 
-  const log = requireLogger(logger);
+  // The platform's logger contract has ONE owner (`@onlineapps/logger-contract`,
+  // confirmation `connector-logger-contract` 001/004): four methods, validated
+  // up front. The reader used to re-state a three-method variant of it here —
+  // the last local copy in this package — which `connectRedis` could not honour,
+  // because the client it creates logs through the same object.
+  const log = assertLogger(
+    'createRegistryReader',
+    logger,
+    'the registry reads and the Redis error events of the connection it owns reach the structured log'
+  );
   const positiveTtl = requireTtl(ttlMs, 'ttlMs', DEFAULTS.registryReaderTtlMs);
   const negativeTtl = requireTtl(negativeTtlMs, 'negativeTtlMs', DEFAULTS.registryReaderNegativeTtlMs);
   const connectTimeout = requireTtl(
@@ -180,34 +179,19 @@ function createRegistryReader(options) {
     if (connected) return;
 
     if (ownsClient) {
-      const created = createClient({ url: redisUrl, socket: { connectTimeout } });
-      created.on('error', (err) => {
-        log.error(`${CONTEXT} Redis client error: ${err.message}`);
+      // Opening a Redis connection with a ceiling is ONE mechanism and it lives
+      // in ./redisClient.js: the ceiling the caller asked for, the attempt
+      // deadline derived from it (so node-redis destroys its own socket inside
+      // that ceiling), the unified 'error' logging with the userinfo stripped,
+      // and one contract message carrying the original error as `cause`. The
+      // reader states the budget and nothing else.
+      // @see ./redisClient.js connectRedis
+      redis = await connectRedis({
+        purpose: 'registryReader',
+        redisUrl,
+        logger: log,
+        timeoutMs: connectTimeout
       });
-
-      // node-redis keeps retrying a refused connection forever, so the initial
-      // connect gets its own hard ceiling — startup must fail, not hang.
-      let timeoutHandle = null;
-      const deadline = new Promise((_resolve, reject) => {
-        timeoutHandle = setTimeout(() => reject(new Error(
-          `${CONTEXT} Redis connection timeout - no connection to ${redisUrl} within ${connectTimeout}ms. `
-          + 'Fix: check the Redis address and that the instance is running.'
-        )), connectTimeout);
-      });
-
-      try {
-        await Promise.race([created.connect(), deadline]);
-      } catch (err) {
-        try {
-          await created.disconnect();
-        } catch (_ignored) {
-          // The client never opened; nothing to release.
-        }
-        throw err;
-      } finally {
-        clearTimeout(timeoutHandle);
-      }
-      redis = created;
     }
 
     connected = true;