@onlineapps/service-common 2.0.1 → 3.0.0

package/README.md

@@ -1,3 +1,15 @@
+> Status: current
+> Owns: the utilities infrastructure and business services share — JWT verification and tenant context, the Redis client, env and config readers, redaction, and the scope rules
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/runtime](../connector/conn-orch-validator/manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `runtime`: L-RUNTIME-CLIENT
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/service-common
 
 Common utilities for both infrastructure services and business services in OA Drive.
@@ -18,34 +30,24 @@ npm install @onlineapps/service-common
 
 Wait for all infrastructure services to be ready before creating queues:
 
-**Infrastructure Services:**
-```javascript
-const { waitForInfrastructureReady } = require('@onlineapps/service-common');
+The same call for infrastructure and business services — the timings are not a
+per-caller decision, they come from the environment (see **API** below):
 
-await waitForInfrastructureReady({
-  redisUrl: 'redis://api_node_cache:6379',
-  maxWait: 300000, // 5 minutes
-  checkInterval: 5000, // 5 seconds
-  logger: logger
-});
-
-// Now safe to create infrastructure queues
-```
-
-**Business Services:**
 ```javascript
 const { waitForInfrastructureReady } = require('@onlineapps/service-common');
 
 await waitForInfrastructureReady({
   redisUrl: process.env.REDIS_URL,
-  maxWait: 60000, // 1 minute
-  checkInterval: 5000, // 5 seconds
   logger: logger
 });
 
-// Now safe to create business queues
+// Now safe to create queues
 ```
 
+Pass `maxWait` / `checkInterval` only to override the environment for one call;
+hard-coding them in a service is how the deployed timings and the documented
+ones drift apart.
+
 ## API
 
 ### `waitForInfrastructureReady(options)`
@@ -54,19 +56,133 @@ Waits for all infrastructure services to be reported as healthy by Registry.
 
 **Options:**
 - `redisUrl` (string): Redis URL
-- `maxWait` (number): Maximum wait time in ms (default: 300000 = 5 minutes)
-- `checkInterval` (number): Check interval in ms (default: 5000 = 5 seconds)
-- `logger` (Object|Function): **Required** logger instance (or function). No implicit console fallback.
+- `maxWait` (number): Maximum wait time in ms — optional override of `INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME`
+- `checkInterval` (number): Check interval in ms — optional override of `INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL`
+- `logger` (Object): **Required** logger implementing all four contract methods —
+  `info`, `warn`, `error`, `debug` (`@onlineapps/logger-contract`). Validated up front,
+  no console fallback, no shape sniffing. See **The logger contract** below.
 
 **Returns:** `Promise<boolean>` - True if all infrastructure services are ready
 
 **Throws:** `Error` - If timeout is reached
 
+**Where the timings come from** (`src/config.js`, resolved by
+`@onlineapps/runtime-config`): explicit option → environment variable →
+module-owned default. The default values themselves live in exactly one place,
+`src/defaults.js` (`infrastructureHealthWaitMaxTimeMs`,
+`infrastructureHealthWaitCheckIntervalMs`) — read them there rather than from a
+number copied into this file, which is how this section previously came to
+advertise timings the code had not used for months.
+
 **Environment Variables:**
 - `REDIS_URL` - Redis connection URL
 - `INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME` - Maximum wait time in ms
 - `INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL` - Check interval in ms
 
+### `getInfrastructureHealthConfig()` — what this package owns, and what it does not
+
+The function resolves the eight infrastructure-health timings this package owns:
+`queueName`, `publishInterval`, `waitMaxTime`, `waitCheckInterval`,
+`healthCheckTimeout`, `cleanupInterval`, `queueWaitMaxTime`,
+`queueWaitCheckInterval`.
+
+**`redisKeyTTL` is not among them, on purpose.** The TTL of an
+infrastructure-health key in Redis is the registry's value: the registry is the
+only code that writes that key, and the value only makes sense beside the
+threshold it has to outlive (`gracePeriod`), which this package does not declare.
+Until d.391 the block carried a second declaration — `INFRASTRUCTURE_HEALTH_REDIS_TTL`
+with a default of 30 s — that no code read and that contradicted the 90 s the
+registry actually runs on. One fact, one owner
+(`.claude/rules/change-discipline.md` § One rail per concern); the owner is
+`infra/api_services_registry/src/config/config.js`.
+
+### The logger contract
+
+Every entry point here that logs demands the same thing, stated once in
+`@onlineapps/logger-contract`: an object with `info`, `warn`, `error` and `debug`,
+validated at the entry point (architecture-principles.md §3, §4). There is no
+console fallback, and no sniffing of the logger's shape.
+
+**3.0.0 is where that became true of the two infrastructure waits.** Until then
+they inspected the object they were given — winston's `log({ message, level })`,
+then `info`, then the logger as a bare function — and picked a rail. The cascade
+was a fallback chain, its `function` rail had no caller in the workspace, and the
+order alone decided the outcome: a caller passing `{ info, log }` had every
+message rendered as `[object Object]`, because the winston rail was tried first
+and its `log` was not winston's.
+
+What a caller has to change:
+
+| Caller | Was | Now |
+|---|---|---|
+| `@onlineapps/service-wrapper` `_waitForInfrastructureGate` | `{ info, log }` | four-method delegating logger — done |
+| `api_gateway` `index.js` | `{ log, info }` wrapper | pass the service logger itself (`createInfrastructureLogger` already implements all four) |
+| `api_delivery_dispatcher` `DeliveryDispatcher.js` | `{ log, info }` wrapper | same |
+| `api_monitoring` consumer | `console` | unchanged — `console` implements all four |
+
+The two wrappers exist only to prefix messages, and both waits already prefix
+their own; the prefix now rides on the logger (`src/infrastructure/prefixedLogger.js`),
+so a message written by a neighbour these waits hand the logger to — `connectRedis` —
+carries the same mark without knowing about it.
+
+### JWT validation — `createJwtValidator(options)`
+
+Express middleware. On success it sets `req.auth = { person_uuid, person_id,
+email, tenants }` and calls `next()`; every refusal is a JSON body with a `code`.
+
+| Option | Required | What it is |
+|---|---|---|
+| `logger` | yes | logger with `warn()` and `error()` |
+| `secret` | yes | the HMAC-SHA256 signing secret, resolved by the caller at boot |
+| `readRolesVersion` | yes | `(personId) => Promise<number\|null>` — the roles-version marker in epoch milliseconds, or `null` when none exists |
+| `excludePaths` | no | paths that pass through without a token |
+
+All three required options are validated at CONSTRUCTION: an instance that could
+not verify a token, or could not run the roles-version check, never exists.
+
+#### The roles-version reader
+
+The validator does not know Redis. It used to take a `redisClient` and call
+`client.isOpen` / `client.get()` — the node-redis v4 API, which meant a service
+whose client is `ioredis` could not be given the check at all. The reader is a
+function now, so every client shape can implement it:
+
+```javascript
+const { createJwtValidator, ROLES_VERSION_PREFIX } = require('@onlineapps/service-common');
+
+const readRolesVersion = async (personId) => {
+  const raw = await redis.get(`${ROLES_VERSION_PREFIX}${personId}`);
+  return raw === null ? null : Number(raw);
+};
+
+app.use(createJwtValidator({ logger, secret, readRolesVersion, excludePaths: [] }));
+```
+
+The key is the FULL, prefixed one — `state:meta:person:roles_version:<person_id>`,
+which is what `ROLES_VERSION_PREFIX` carries. The marker is a projection of the
+meta service state, written by biz-meta through a connector that adds the
+`state:meta:` prefix, so a reader asking for the bare `person:roles_version:<id>`
+gets `null` for every person and the validator answers `TOKEN_STALE` never (owner
+decision 2026-09-14, `docs/governance/confirmations/redis-state-prefix.md` 002).
+
+The check is **fail-closed**: if the reader rejects, or answers with anything but
+a finite number or `null`, the request is refused with `503`
+`ROLES_VERSION_CHECK_UNAVAILABLE` — the client did nothing wrong, the platform
+could not verify (`docs/governance/confirmations/jwt-stale-check-fail-closed.md`
+001). A token with no `person_id` claim is refused earlier, with `401`
+`TOKEN_PERSON_ID_MISSING`, before the reader is consulted (002).
+
+#### Units — `iat` counts seconds, the marker milliseconds
+
+`iat` is a whole number of seconds rounded down (RFC 7519 §4.1.6); the marker is
+epoch milliseconds (`docs/standards/redis-key-contract.md`). The comparison
+happens in the coarser unit: the marker is floored to whole seconds, so a token
+issued in the SAME second as the role change is current. Compared in
+milliseconds it was not — `addMembership` writes the marker and the new token is
+signed milliseconds later, inside that same second, so the token that already
+carried the new roles was answered `TOKEN_STALE`, and so was the one the refresh
+produced.
+
 ### Scoped registry — `isVisible` / `sqlVisible` and friends
 
 The single home of the registry visibility rule: *a registry row is visible to a
@@ -123,7 +239,7 @@ const { createRegistryReader } = require('@onlineapps/service-common');
 const reader = createRegistryReader({
   keyPrefix: requireEnv('REDIS_REGISTRY_KEY_PREFIX'), // REQUIRED — never assumed
   redisUrl: requireEnv('REDIS_URL'),                  // or: client: <connected node-redis v4 client>
-  logger                                              // REQUIRED — no console fallback
+  logger                                              // REQUIRED — info/warn/error/debug, no console fallback
 });
 await reader.connect();
 
@@ -132,7 +248,7 @@ const op = await reader.getOperation('biz-invoicing', 'create-invoice');
 
 | Export | Purpose |
 |---|---|
-| `connect()` | opens the owned connection (hard `connectTimeoutMs` ceiling), or validates an injected client |
+| `connect()` | opens the owned connection through `connectRedis` (hard `connectTimeoutMs` ceiling — one rail: `src/redisClient.js`), or validates an injected client |
 | `getServiceSpec(name)` | full spec, or `null` when the service is not registered |
 | `getOperation(name, key)` | one operation record, or `null` |
 | `listSummary()` | parsed `<keyPrefix>services` hash |
@@ -156,6 +272,150 @@ closes the client) or `client` (the caller owns it; `close()` never quits it).
 `keyPrefix` and `logger` are mandatory and `ttlMs` / `negativeTtlMs` /
 `connectTimeoutMs` are validated: an invalid value throws instead of being
 silently replaced by the module default (`src/defaults.js` owns the defaults).
+`logger` is the platform contract — `info`, `warn`, `error`, `debug`
+(`@onlineapps/logger-contract`) — checked at construction, because the Redis
+client the reader owns logs through the same object. A failed `connect()` on the
+owned path raises the `connectRedis` contract message, which names the endpoint
+with the userinfo stripped and keeps the original error as `cause`.
+
+### Env readers — `requireNumberEnv` vs `requireFloatEnv`
+
+A number from the environment is read by exactly ONE rail:
+`@onlineapps/runtime-config`. The helpers here only hand it a schema and return
+what it resolved — neither the coercion nor the message for a malformed value is
+owned by service-common.
+
+| Helper | Resolver type | For |
+|---|---|---|
+| `requireNumberEnv(name, description, options)` | `number` | whole numbers — ports, counts, budgets, ms/second/minute intervals |
+| `requireFloatEnv(name, description, options)` | `float` | ratios and factors, e.g. a completion threshold in `0.0-1.0` |
+| `requireBoolEnv(name, description, options)` | — | the literal `true` / `false` |
+| `requireEnv(name, description, options)` | — | a string |
+
+### `options.file` — who writes the `Fix:` sentence
+
+`architecture-principles.md` §5 requires a missing key to be reported with
+`Fix: set <ENV_KEY> in env-active/*.env`. Since d.399 **the helper composes that
+sentence**, for every caller and in one shape. Before it, the helper appended
+only `description`, so the sentence existed exactly where a caller had typed it
+into that description by hand — six call sites in
+`infra/api_delivery_endpoint/src/config.js`, and nowhere else on the platform.
+
+```javascript
+requireEnv('REDIS_URL', 'Redis connection URL', { file: 'shared.env' });
+// [ServiceConfig] Missing environment variable - REDIS_URL is required.
+// Redis connection URL Fix: set REDIS_URL in config/env-active/shared.env.
+
+requireEnv('REDIS_URL', 'Redis connection URL');
+// … Fix: set REDIS_URL in env-active/*.env (or pass explicit config).
+```
+
+`file` is a **bare file name** — the helper writes the `config/env-active/`
+prefix, and a value carrying a path or a different suffix is refused at the call
+itself, not the day the key goes missing. It is an INPUT and never a derivation:
+`api/config/shared-env.json` owns the shared key set, but only build-time tooling
+(`oa-sync-template shared-env`) reads it — the file is absent from a service's
+runtime, and a library hunting for it through `__dirname`/cwd would break
+principle 1. So the call site names the file and review checks it against the
+declaration; without one, the sentence is §5's own generic wording, which is
+correct rather than missing.
+
+Choosing between `number` and `float` is a **property of the key**, not of the
+helper, so it belongs at the call site: a fractional value read as `number`
+loses its fraction today, and stops the boot once the whole-number resolver
+(d.253) is pinned.
+
+⚠️ Open cascade: `TRACE_COMPLETION_RATE_THRESHOLD` (api_monitoring
+`index.js:211`, value `0.8`) must move to `requireFloatEnv` in the same cascade
+commit as the service-common pin — otherwise monitoring either loses the alert
+silently (today) or fails to boot (after the wave).
+
+A missing variable is reported by all four in the same shape:
+`[ServiceConfig] Missing environment variable - <NAME> is required. <description>`.
+
+### Monitoring fallback e-mail — `sendMonitoringFailFallbackEmail(subject, text, html, logger)`
+
+The last reporting channel: when the platform's own monitoring path cannot carry
+an alert, this sends it by SMTP. Every outcome is swallowed into the boolean
+return, so the injected `logger` is the only record of what happened — there is
+no console fallback and no throw for a refused send.
+
+**One shared connection.** The transport is pooled (`pool: true`). A burst of
+alerts used to cost one TCP+TLS+AUTH per mail, which is what broke on
+2026-09-11: seven `service_down` episodes in one second, `421 4.7.0 … too many
+connections` 18×, 12 alerts never delivered. The bounds are declared config, not
+literals, and their owner defaults are derived from the relay limits recorded in
+[`alert-smtp-relay` 003](../../docs/governance/confirmations/alert-smtp-relay.md)
+(20 connections / 10 AUTH per 60 s):
+
+| Key | Env | Default | Why that value |
+|---|---|---|---|
+| `infraReportSmtpMaxConnections` | `INFRA_REPORT_SMTP_MAX_CONNECTIONS` | `1` | one connection per burst = one AUTH, not one per mail |
+| `infraReportSmtpMaxMessages` | `INFRA_REPORT_SMTP_MAX_MESSAGES` | `100` | messages carried before nodemailer recycles the connection |
+| `infraReportSmtpRateDeltaMs` | `INFRA_REPORT_SMTP_RATE_DELTA` | `60000` | the window the relay's limits are counted in |
+| `infraReportSmtpRateLimit` | `INFRA_REPORT_SMTP_RATE_LIMIT` | `10` | the AUTH limit, so even one connection per message stays inside it |
+| `infraReportSmtpMaxAttempts` | `INFRA_REPORT_SMTP_MAX_ATTEMPTS` | `3` | bounded retry; below `1` is a fail-fast error, not "no retries" |
+| `infraReportSmtpRetryDelayMs` | `INFRA_REPORT_SMTP_RETRY_DELAY` | `6000` | 60 000 / 10 = one AUTH every 6 s, the tightest limit on record; the backoff doubles from there |
+
+**A temporary refusal is re-tried here, by the transport, and the caller is told
+once.** A 4yz reply (RFC 5321 §4.2.1 — `421`, `450`, …) is the relay saying
+"later": the send is repeated up to `maxAttempts`, spaced by the doubling
+backoff, and the function returns a single verdict when that is over. A 5yz
+reply is permanent and is never repeated. An error carrying **no** reply code (a
+dead socket, a failed TLS handshake) is not guessed to be temporary — a retry
+would spend the relay's rate budget on something the relay never said.
+
+That placement is not a local choice: `delivery-mail-channel` 001 point 5 says
+"retry is layered, not doubled … a refused send is the mail service's provider
+retry". For the alert channel this module IS the mail service, so a retry loop in
+the monitoring consumer on top of this one would be exactly the doubling that
+entry forbids. What the consumer records (`notification_sent`) is this verdict.
+
+The transport also sets `requireTLS: true` unconditionally: the relay offers
+STARTTLS without insisting (`smtpd_tls_security_level = may`), so a client that
+does not insist either hands `AUTH PLAIN` to a downgraded connection.
+
+#### Why this is a second mail rail — accepted justification
+
+> **Status: ACCEPTED** by the owner on 2026-09-14
+> (`api/docs/governance/confirmations/duplicity-justification.md` 002). `delivery-mail-channel`
+> 001 § Conditions requires this duplicate to carry "its own written justification under
+> `duplicity-justification` 001"; this section is that justification. It holds for exactly
+> the shape described below — platform alerts to the operator, one SMTP transport — and a
+> change that widens the rail leaves it and needs a new entry.
+
+The platform has one mail rail by decision: a workflow result that travels by
+mail is handed to the mail service over its workflow queue
+(`delivery-mail-channel` 001, model A). This function is a second one, and
+`change-discipline.md` § One rail per concern makes that a defect by default.
+
+The argument that it is nevertheless the right shape:
+
+1. **The two rails do not serve one concern.** The mail service delivers a
+   *tenant's* result — with the tenant's transport, entitlement check, outbound
+   record, bounce and complaint lifecycle. This function delivers *the
+   platform's own alert about itself*, to the operator, with no tenant, no
+   entitlement and no lifecycle. `markAlertNotified` is the whole record
+   (`monitoring-pg-volume` 003, `biz-readiness-alerting` 002).
+2. **It exists for the case where the first rail cannot run.** An alert is
+   raised precisely when the infrastructure the first rail depends on — the biz
+   layer, MQ, the queue the dispatcher would publish to — is the thing that is
+   broken. A channel whose availability is conditional on the subject of its own
+   message is not a channel. Routing alerts through the mail service would make
+   the report of an outage the first casualty of that outage.
+3. **The dependency direction forbids the reuse.** `service-common` is a shared
+   library used by infrastructure services (layer order,
+   `architecture-principles.md` §7). Reaching the mail service from here would
+   put a biz-service dependency underneath the infrastructure that monitors it.
+4. **It is not a copy of the mail service.** There is no queue, no template
+   engine, no attachment resolution, no provider feedback — one SMTP transport
+   and one `sendMail`. It duplicates the *act* of sending mail, not the
+   mechanism the other rail owns.
+5. **The cost of the alternative is measured, not theoretical.** The rejected
+   alternative (alerts through the mail service) was live on 2026-09-11 in the
+   form of a single relay dependency, and 12 alerts were lost to one burst; the
+   fix documented above is what keeps this rail inside the relay's limits.
+
 
 ## Architecture
 

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis client, business errors, runtime config)",
+  "oa": {
+    "category": "runtime"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest",
+    "test": "npm run test:unit && npm run test:integration",
     "test:unit": "jest tests/unit",
-    "test:integration": "jest --config=jest.integration.config.js",
-    "test:all": "npm run test && npm run test:integration"
+    "test:integration": "jest --config=jest.integration.config.js"
   },
   "keywords": [
     "microservices",
@@ -18,15 +20,16 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/runtime-config": "1.0.3",
+    "@onlineapps/logger-contract": "1.1.0",
+    "@onlineapps/runtime-config": "1.1.0",
     "jsonwebtoken": "^9.0.3",
-    "nodemailer": "^6.9.8",
+    "nodemailer": "^10.0.9",
     "redis": "^4.6.0"
   },
   "devDependencies": {
     "jest": "^29.7.0"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=24.0.0 <25"
   }
 }

package/src/config.js

@@ -33,7 +33,6 @@ const runtimeCfg = createRuntimeConfig({
     infrastructureHealthWaitMaxTimeMs: { env: 'INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME', defaultKey: 'infrastructureHealthWaitMaxTimeMs', type: 'number' },
     infrastructureHealthWaitCheckIntervalMs: { env: 'INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL', defaultKey: 'infrastructureHealthWaitCheckIntervalMs', type: 'number' },
     infrastructureHealthTimeoutMs: { env: 'INFRASTRUCTURE_HEALTH_TIMEOUT', defaultKey: 'infrastructureHealthTimeoutMs', type: 'number' },
-    infrastructureHealthRedisTtlSeconds: { env: 'INFRASTRUCTURE_HEALTH_REDIS_TTL', defaultKey: 'infrastructureHealthRedisTtlSeconds', type: 'number' },
     infrastructureHealthCleanupIntervalMs: { env: 'INFRASTRUCTURE_HEALTH_CLEANUP_INTERVAL', defaultKey: 'infrastructureHealthCleanupIntervalMs', type: 'number' },
     infrastructureHealthQueueWaitMaxTimeMs: { env: 'INFRASTRUCTURE_HEALTH_QUEUE_WAIT_MAX_TIME', defaultKey: 'infrastructureHealthQueueWaitMaxTimeMs', type: 'number' },
     infrastructureHealthQueueWaitCheckIntervalMs: { env: 'INFRASTRUCTURE_HEALTH_QUEUE_WAIT_CHECK_INTERVAL', defaultKey: 'infrastructureHealthQueueWaitCheckIntervalMs', type: 'number' },
@@ -46,6 +45,19 @@ const runtimeCfg = createRuntimeConfig({
     infraReportSmtpPass: { env: 'INFRA_REPORT_SMTP_PASS' },
     infraReportFrom: { env: 'INFRA_REPORT_FROM' },
     infraReportTo: { env: 'INFRA_REPORT_TO' },
+
+    // How the fallback transport treats the relay: one shared connection and a
+    // bounded retry of a TEMPORARY refusal. Unlike the keys above these DO have
+    // owner defaults — they describe how to talk to whatever relay is
+    // configured, not whether the feature is configured at all, and the
+    // defaults are derived from the relay limits recorded in confirmation
+    // `alert-smtp-relay` 003 (see ./defaults.js for the derivation).
+    infraReportSmtpMaxConnections: { env: 'INFRA_REPORT_SMTP_MAX_CONNECTIONS', defaultKey: 'infraReportSmtpMaxConnections', type: 'number' },
+    infraReportSmtpMaxMessages: { env: 'INFRA_REPORT_SMTP_MAX_MESSAGES', defaultKey: 'infraReportSmtpMaxMessages', type: 'number' },
+    infraReportSmtpRateDeltaMs: { env: 'INFRA_REPORT_SMTP_RATE_DELTA', defaultKey: 'infraReportSmtpRateDeltaMs', type: 'number' },
+    infraReportSmtpRateLimit: { env: 'INFRA_REPORT_SMTP_RATE_LIMIT', defaultKey: 'infraReportSmtpRateLimit', type: 'number' },
+    infraReportSmtpMaxAttempts: { env: 'INFRA_REPORT_SMTP_MAX_ATTEMPTS', defaultKey: 'infraReportSmtpMaxAttempts', type: 'number' },
+    infraReportSmtpRetryDelayMs: { env: 'INFRA_REPORT_SMTP_RETRY_DELAY', defaultKey: 'infraReportSmtpRetryDelayMs', type: 'number' },
   }
 });
 

package/src/defaults.js

@@ -15,12 +15,39 @@ module.exports = {
   infrastructureHealthWaitMaxTimeMs: 60000,
   infrastructureHealthWaitCheckIntervalMs: 2000,
   infrastructureHealthTimeoutMs: 15000,
-  infrastructureHealthRedisTtlSeconds: 30,
+  // NOTE: no `infrastructureHealthRedisTtlSeconds` here. The Redis TTL of an
+  // infrastructure-health key belongs to the registry, which is the only code
+  // that writes that key, and it declares the value beside the thresholds the
+  // value has to outlive (`gracePeriod`) — see
+  // infra/api_services_registry/src/config/config.js. This package declared a
+  // second one (30 s) that nothing read and that contradicted the live 90 s.
   infrastructureHealthCleanupIntervalMs: 10000,
 
   infrastructureHealthQueueWaitMaxTimeMs: 60000,
   infrastructureHealthQueueWaitCheckIntervalMs: 2000,
 
+  // Monitoring fallback e-mail transport (see ./reporting/monitoringFallbackEmail.js).
+  //
+  // The values are DERIVED from the relay's documented limits, they are not
+  // taste: confirmation `alert-smtp-relay` 003 § Conditions records
+  // `smtpd_client_connection_rate_limit=20` and `smtpd_client_auth_rate_limit=10`
+  // per 60 s. An alert burst that opens one connection per mail walks straight
+  // into both (measured 2026-09-11: 18× `421 4.7.0 … too many connections`,
+  // 12 alerts undelivered).
+  //
+  // - one connection shared by the whole burst => one AUTH, not one per mail;
+  // - 100 messages on that connection before nodemailer recycles it;
+  // - 10 messages per 60 s, i.e. the AUTH limit, so even the worst case of one
+  //   connection per message stays inside what the relay allows;
+  // - three attempts spaced 6 s and 12 s: 60 000 / 10 is one AUTH every 6 s,
+  //   which is the tightest limit on record.
+  infraReportSmtpMaxConnections: 1,
+  infraReportSmtpMaxMessages: 100,
+  infraReportSmtpRateDeltaMs: 60000,
+  infraReportSmtpRateLimit: 10,
+  infraReportSmtpMaxAttempts: 3,
+  infraReportSmtpRetryDelayMs: 6000,
+
   // registryReader in-memory cache (see ./registryReader.js).
   // Positive entries live 5 minutes; a "service not registered" answer is
   // remembered for 30 s only, so a fresh registration becomes visible quickly.

package/src/index.js

@@ -21,26 +21,13 @@ const { createRegistryReader } = require('./registryReader');
 const {
   requireEnv,
   requireNumberEnv,
+  requireFloatEnv,
   requireBoolEnv,
   optionalEnv,
   optionalNumberEnv,
   getCriticalConfig,
-  getCriticalConfigWithFallbacks,
   getInfrastructureHealthConfig
 } = require('./runtime-config');
-const {
-  BusinessError,
-  NotFoundError,
-  ValidationError,
-  ConflictError,
-  BusinessRuleError,
-  AuthorizationError,
-  ServiceUnavailableError,
-  isBusinessError,
-  ERROR_TYPES,
-  businessErrorHandler,
-  notFoundHandler
-} = require('./errors');
 const {
   verifyAccessToken,
   createJwtValidator,
@@ -52,6 +39,7 @@ const {
   sensitiveFieldsForOperation,
   redactSensitiveDeep
 } = require('./redactSensitive');
+const { redactUrl } = require('./redactUrl');
 const {
   isVisible,
   filterVisible,
@@ -82,28 +70,21 @@ module.exports = {
   // Configuration helpers (NO FALLBACKS for critical infrastructure)
   requireEnv,
   requireNumberEnv,
+  requireFloatEnv,
   requireBoolEnv,
   optionalEnv,
   optionalNumberEnv,
   getCriticalConfig,
-  getCriticalConfigWithFallbacks,
   getInfrastructureHealthConfig,
 
   // Reporting utilities
   sendMonitoringFailFallbackEmail,
 
-  // Business error classes and middleware
-  BusinessError,
-  NotFoundError,
-  ValidationError,
-  ConflictError,
-  BusinessRuleError,
-  AuthorizationError,
-  ServiceUnavailableError,
-  isBusinessError,
-  ERROR_TYPES,
-  businessErrorHandler,
-  notFoundHandler,
+  // The BusinessError hierarchy and the Express error middleware used to sit here.
+  // They left in the 3.0.0 wave: the classes live in @onlineapps/service-wrapper
+  // (the winning class), and the middleware had no mount site anywhere after F6
+  // removed Express from biz services.
+  // See: tests/unit/retiredErrorExports.test.js
 
   // JWT validation utilities (shared across services that accept client HTTP/WS requests)
   // See: docs/standards/JWT_AUTH.md
@@ -118,6 +99,10 @@ module.exports = {
   sensitiveFieldsForOperation,
   redactSensitiveDeep,
 
+  // Credential redaction for connection URLs written to a log
+  // (REDIS_URL carries the Redis password — one rail, INFRA lead 2026-09-10)
+  redactUrl,
+
   // Scoped-registry visibility rule (system ∪ own workspace)
   // See: docs/biz/30-operations/scoped-registry.md
   isVisible,

package/src/infrastructure/prefixedLogger.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * prefixedLogger.js
+ *
+ * Both infrastructure waits (`waitForInfrastructureReady`,
+ * `waitForHealthCheckQueueReady`) need the same thing: the caller's logger, with
+ * every line marked as coming from that wait. They used to build it twice, by
+ * hand, and each hand-built object was a defect of its own — two methods where
+ * the contract asks for four (`@onlineapps/logger-contract`), which `connectRedis`
+ * refused the moment it started validating them.
+ *
+ * One concern, one rail (change-discipline.md § One rail per concern).
+ *
+ * The prefix belongs on the logger rather than in every message string, so a
+ * message written here and a message written by a neighbour this logger is handed
+ * to (`connectRedis`) carry the same mark without either of them knowing it.
+ *
+ * @see api/docs/standards/ERROR_HANDLING.md
+ * @module @onlineapps/service-common/src/infrastructure/prefixedLogger
+ */
+
+const { LOGGER_METHODS, assertLogger } = require('@onlineapps/logger-contract');
+
+/**
+ * Wraps a contract logger so every message is prefixed.
+ *
+ * @param {string} context - Entry-point name for the validation message, e.g. 'waitForInfrastructureReady'
+ * @param {string} prefix - Marker put in front of every message, e.g. '[InfrastructureReady]'
+ * @param {Object} logger - Candidate logger, validated against the four-method contract
+ * @param {string} reason - Why this component needs a logger, in one clause
+ * @returns {Object} a logger implementing the same four methods
+ * @throws {Error} when the logger is absent or does not implement all four
+ */
+function createPrefixedLogger(context, prefix, logger, reason) {
+  const target = assertLogger(context, logger, reason);
+
+  const prefixed = {};
+  for (const level of LOGGER_METHODS) {
+    // `...rest` rather than a named `meta`: a caller that logged a message alone
+    // must not have an `undefined` second argument invented for it on the way
+    // through, because the logger underneath can tell the two apart.
+    prefixed[level] = (message, ...rest) => target[level](`${prefix} ${message}`, ...rest);
+  }
+
+  return prefixed;
+}
+
+module.exports = { createPrefixedLogger };