@onlineapps/conn-infra-secrets 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-10-03
+
+### Changed — an unusable `keyPrefix` is refused instead of replaced, and a `connect()` rejected with an `AggregateError` says why (d.1136, d.1116)
+
+- **The exported `projectionKey()` refuses an unusable `keyPrefix` too.** Its parameter default `keyPrefix = DEFAULT_KEY_PREFIX` let `''` through as a key with no prefix and `null` as the literal prefix `"null"`. It now goes through the constructor's rail: left out (`undefined`) = `DEFAULT_KEY_PREFIX`, a non-empty string = used as is, anything else refused with the same message (d.1136). The dead `pathname || ''` in the `redisUrl` database parse is gone — `URL.pathname` is always a string.
+- **An unusable `keyPrefix` is refused instead of replaced by the default.** `config.keyPrefix || DEFAULT_KEY_PREFIX` swapped an explicit `''` (and `null`) for the default without a word, and let a truthy non-string — `42`, an object — through as a prefix (principle 3, No Fallbacks; INFRA-DOCS W46, d.1136). Left out (`undefined`) still means `DEFAULT_KEY_PREFIX`, the prefix meta writes — the default is the concept, not a guess: no caller passes one (`ServiceWrapper`, `api_gateway`, `api_delivery_dispatcher`). A given non-empty string is used as is; anything else throws `[conn-infra-secrets] Invalid config - "keyPrefix" must be a non-empty string, got …`. Unit cases for `''`, `null`, a number and an object plus two controls; integration cases against the live store (refusal of `''`, and a given prefix reading only its own keys).
+- **A `connect()` rejected with an `AggregateError` now says why.** A host name with more than one address (`localhost` → `::1`, `127.0.0.1`) makes Node try each of them — the locked ioredis 5.11.1 defaults to `family: 0` — and reject with an `AggregateError` whose own `message` is `""`; the caller read `the client rejected with ""`, a refusal with no reason in it (d.1116, measured on this package in d.1123). The message now carries each attempt's reason from `errors[]` — `AggregateError with no message of its own; its 2 attempts failed with: connect ECONNREFUSED ::1:1; connect ECONNREFUSED 127.0.0.1:1` — in the shape of `describeTransportFailure()` in `@onlineapps/service-common`. Unit case plus an integration case against `redis://localhost:1`.
+
+### Tests — the integration tier: one deadline for every `docker` call, no password in its errors, Redis awaited where the connector dials it (d.1140)
+
+- **Every `docker` call of the integration tier runs under one deadline** (d.1140, 2/2). `reconnect.integration.test.js` ran `execFileSync('docker', …)` with no timeout — a stuck daemon hung the run with nothing named, and Jest's per-test timeout cannot fire while `execFileSync` blocks — while `redisAuthFromUrl` kept the timeout in a second copy of the same helper. Both now go through `tests/dockerCli.js`: `docker(args)` under the named `DOCKER_TIMEOUT_MS`, and a call that outlives it ends with `[conn-infra-secrets/integration] "docker <subcommand>" did not finish within … ms - … Fix: …`. The integration contract pins the rail per suite.
+- **A failed `docker` call of the integration tier no longer prints the password its command line carries** (d.1140, 3/3). The `child_process` error quotes the whole line (`Command failed: …`) and keeps it in `spawnargs`/`cmd`; re-thrown as it was, or attached as `cause`, it carried `--requirepass <password>` / `redis-cli -a <password>` into the run's output — measured on the timeout, the non-zero-exit and the did-not-start path alike. Every failure of `tests/dockerCli.js` is now its own error naming `docker <subcommand>` and how it ended (`did not finish within … ms`, `exited with status N`, `did not run (code …)`), with `cause` = `{ code, status, signal }` and nothing else; stdout and stderr are left out. Unit cases on real processes assert that no rendering of the error — message, stack, JSON, `util.inspect` to depth 5 — contains the argument that stands for the password.
+- **The integration suites that run a Redis of their own wait for it where the connector dials it** (d.1140). `reconnect.integration.test.js` asked `docker exec … redis-cli PING` — the server on the container's own loopback — while the connector connects to the port the daemon publishes, and under load the two disagreed: lead d.1123 (load 31–37) saw no `ready` for 60 s after an in-container PONG and `Connection is closed.` in place of `WRONGPASS` in the CONTROL; worker d.1123 (load 26) saw `ECONNREFUSED` there. Both suites that own a Redis (`reconnect`, `redisAuthFromUrl`, which kept a second copy of the wait loop) now wait through one rail, `tests/redisPing.js` — PING at the published endpoint with a deadline named `REDIS_PING_DEADLINE_MS` — after `docker run`, after every `docker start`, and before each `reconnect` test's first connection. No assertion changed. The unit tier's integration contract pins the rail per suite, with a control that administering the server (`CONFIG SET requirepass`) stays a `docker exec`.
+
 ## [3.0.0] — 2026-09-16
 
 ### Changed — BREAKING

package/README.md

@@ -114,6 +114,12 @@ as `cause`, and the attempts END there rather than looping on a question already
 answered. A server that never answered is reported as exactly that and may be retried.
 Only `host:port` appears in these messages; the URL carries the password.
 
+**`keyPrefix` is optional, and only left out means the default.** Leave it out and
+the connector reads the prefix meta writes — `DEFAULT_KEY_PREFIX` in `src/index.js`
+is its one owner; no caller in the platform passes one. A given value is used as
+is. A given value that is not a non-empty string (`''`, `null`, a number, an
+object) is refused at construction, never replaced by the default.
+
 ## Public API
 ```js
 const SecretsConnector = require('@onlineapps/conn-infra-secrets');            // default = the connector
@@ -275,8 +281,22 @@ failed.
   controls that no value and no key material reaches a result or a message.
 - `npm run test:integration` — real Redis. The re-encryption run uses the live
   projection as its store and reads the rewritten rows back through
-  `SecretsConnector.get()` with the key list that remains. Needs `REDIS_HOST` +
-  `REDIS_PORT` (dev stack: `REDIS_HOST=127.0.0.1 REDIS_PORT=33030`, container
-  `api_node_cache`). **NOT RUN here:** the authoritative store — the rows live in
-  `oagen_<service>.secret` (MySQL) and this package has no database dependency by
-  design, so that adapter and its integration test belong to the owning service.
+  `SecretsConnector.get()` with the key list that remains. Needs `REDIS_URL` and
+  nothing else (`tests/config.js` refuses the run before the first describe tree
+  when it is missing) — the one value that carries the endpoint AND the
+  credential. Two suites need no variable of their own beyond it: they start a
+  throwaway Redis whose password they set themselves
+  (`redisAuthFromUrl`, `reconnect`). Derive the value, never write it out:
+
+  ```bash
+  # from shared/connector/conn-infra-secrets/
+  REDIS_URL="$(node -p "const f=require('fs'),u=new URL(/^REDIS_URL=(.*)/m.exec(f.readFileSync('../../../config/env-active/shared.env','utf8'))[1]);u.host='127.0.0.1:'+/^REDIS_PORT=(.*)/m.exec(f.readFileSync('../../../infra/.env','utf8'))[1];u.toString()")" \
+  npm run test:integration
+  ```
+
+  `api/config/env-active/shared.env` owns the in-network URL (`api_node_cache`),
+  `api/infra/.env` the published port; neither is in git, and a copy here would be
+  a second source for a secret. **NOT RUN here:** the authoritative store — the
+  rows live in `oagen_<service>.secret` (MySQL) and this package has no database
+  dependency by design, so that adapter and its integration test belong to the
+  owning service.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-infra-secrets",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Secret resolution connector for ctx.secrets.get(ref) — reads the SecretBox Redis projection and decrypts in-process (AES-256-GCM)",
   "oa": {
     "category": "connector"

package/src/index.js

@@ -75,6 +75,34 @@ function isServerRefusal(err) {
   return SERVER_REFUSAL_PREFIXES.some((prefix) => err.message.startsWith(prefix));
 }
 
+/**
+ * The reason a failed connect attempt carries, in words — including one whose own
+ * message is empty.
+ *
+ * A host name with more than one address (A + AAAA) makes Node >= 20 try each of them
+ * (`autoSelectFamily`) and reject with an `AggregateError` whose own `message` is `""`;
+ * the reasons are in `errors[]`, one per attempt (measured d.1116: `localhost:1` ->
+ * `errors: [connect ECONNREFUSED ::1:1, connect ECONNREFUSED 127.0.0.1:1]`). Embedding
+ * `message` alone then printed `rejected with ""` — a refusal with no reason in it.
+ * The shape is `describeTransportFailure()` of `@onlineapps/service-common`
+ * (`src/redisClient.js`) and `describeCause()` of `@onlineapps/content-resolver`
+ * (`src/errors.js`).
+ *
+ * @param {*} cause - What the connect attempt rejected with.
+ * @returns {string}
+ */
+function describeTransportFailure(cause) {
+  if (cause && cause.message) {
+    return cause.message;
+  }
+  if (cause && Array.isArray(cause.errors) && cause.errors.length > 0) {
+    const reasons = cause.errors.map((attempt) => attempt.message).join('; ');
+    return `${cause.name} with no message of its own; its ${cause.errors.length} attempts `
+      + `failed with: ${reasons}`;
+  }
+  return String(cause);
+}
+
 class SecretResolutionError extends Error {
   constructor(code, message, options) {
     super(message, options);
@@ -109,7 +137,9 @@ function workspaceSegment(workspaceId) {
   return String(ws);
 }
 
-function projectionKey(tenantId, workspaceId, ref, keyPrefix = DEFAULT_KEY_PREFIX) {
+function projectionKey(tenantId, workspaceId, ref, keyPrefix) {
+  // One rail with the constructor: left out = DEFAULT_KEY_PREFIX, unusable = refused.
+  const prefix = resolveKeyPrefix(keyPrefix);
   if (tenantId === undefined || tenantId === null) {
     throw new SecretResolutionError(
       'SECRET_SCOPE_MISSING',
@@ -117,7 +147,7 @@ function projectionKey(tenantId, workspaceId, ref, keyPrefix = DEFAULT_KEY_PREFI
       + 'belongs to. Fix: pass scope.tenant_id from the operation context.'
     );
   }
-  return `${keyPrefix}${tenantId}:${workspaceSegment(workspaceId)}:${ref}`;
+  return `${prefix}${tenantId}:${workspaceSegment(workspaceId)}:${ref}`;
 }
 
 // `REDIS_URL` is the platform's single rail for the Redis endpoint AND its
@@ -160,7 +190,8 @@ function refuseRetiredOptions(config) {
  * declaration into a 0 nobody asked for (principle 3, No Fallbacks).
  */
 function databaseFromPath(pathname) {
-  const declared = String(pathname || '').replace(/^\//, '');
+  // `URL.pathname` is always a string ('' when the URL declares no path).
+  const declared = pathname.replace(/^\//, '');
   if (declared === '') return null;
   if (!/^\d+$/.test(declared)) {
     throw new Error(
@@ -231,6 +262,27 @@ function redisOptionsFromUrl(redisUrl) {
   return options;
 }
 
+/**
+ * The projection key prefix: left out means DEFAULT_KEY_PREFIX, the one meta
+ * writes; a given value is used as is. A given value that cannot be a prefix is
+ * refused rather than replaced — `config.keyPrefix || DEFAULT_KEY_PREFIX` swapped
+ * an explicit `''` for the default without a word, and let `42` or an object
+ * through as a prefix (principle 3, No Fallbacks; INFRA-DOCS W46). The exported
+ * projectionKey() goes through the same rail — its parameter default let '' and
+ * null through as well.
+ */
+function resolveKeyPrefix(keyPrefix) {
+  if (keyPrefix === undefined) return DEFAULT_KEY_PREFIX;
+  if (typeof keyPrefix !== 'string' || keyPrefix === '') {
+    const shown = typeof keyPrefix === 'string' ? '""' : (keyPrefix === null ? 'null' : typeof keyPrefix);
+    throw new Error(
+      `[conn-infra-secrets] Invalid config - "keyPrefix" must be a non-empty string, got ${shown}. `
+      + 'Fix: pass config.keyPrefix or leave it out (default: see DEFAULT_KEY_PREFIX in src/index.js).'
+    );
+  }
+  return keyPrefix;
+}
+
 class SecretsConnector {
   /**
    * @param {Object} config
@@ -240,7 +292,8 @@ class SecretsConnector {
    *        refused by name.
    * @param {string} config.masterKeys - the declared list, `<key_id>:<base64 32-byte key>[,…]`
    *        (required; the value of SECRETS_MASTER_KEYS, first entry = the active key)
-   * @param {string} [config.keyPrefix] - projection key prefix (defaults to the one meta writes)
+   * @param {string} [config.keyPrefix] - projection key prefix; left out (`undefined`) = DEFAULT_KEY_PREFIX,
+   *        the one meta writes. A given value must be a non-empty string, otherwise it is refused.
    */
   constructor(config = {}) {
     if (!config.redisUrl) {
@@ -248,7 +301,7 @@ class SecretsConnector {
     }
     refuseRetiredOptions(config);
     this._keyring = loadMasterKeys(config.masterKeys);
-    this._keyPrefix = config.keyPrefix || DEFAULT_KEY_PREFIX;
+    this._keyPrefix = resolveKeyPrefix(config.keyPrefix);
 
     this._redisOptions = redisOptionsFromUrl(config.redisUrl);
     // What a message of this package may say about the store: host and port,
@@ -352,7 +405,7 @@ class SecretsConnector {
       }
       throw new Error(
         `[conn-infra-secrets] Failed to connect to Redis at ${this._endpoint} - the server sent `
-        + `no verdict; the client rejected with "${reported.message}". Fix: check that Redis is `
+        + `no verdict; the client rejected with "${describeTransportFailure(reported)}". Fix: check that Redis is `
         + 'listening at that endpoint and that the host and port in REDIS_URL '
         + '(api/config/env-active/shared.env) are the right ones. A refused credential answers '
         + 'NOAUTH, WRONGPASS or NOPERM and is reported as such, so this is not one. Only the '