@onlineapps/conn-infra-secrets 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,115 @@ 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
+
+- **The Redis credential and topology come from `redisUrl`, and from nothing else.** The constructor reads `username` (Redis 6 ACL), `password`, host, port and the database index off the URL — `redis://[user:password@]host:port[/db]`, `rediss://` for TLS — decoding percent-escapes exactly once. An absent userinfo means no AUTH at all: `username`/`password` are then not passed to ioredis, never as `''`, which would be sent as `AUTH ""`.
+  Measured reason (INFRA, dev, 2026-09-15 21:20Z): the constructor took `hostname`/`port` only and expected the password beside the URL, so a URL carrying userinfo lost it — ioredis connected without AUTH, the gateway went into a crash loop (RestartCount 51) and the dispatcher and ingest failed on their first secret read. `REDIS_URL` is the platform's one rail for this fact (INFRA-DOCS 2026-09-14; `service-common` 3.0.2 hands the whole URL to node-redis, `mq-client-core` 3.2.0 reads the credential off the URL), so a value beside it was a second rail — `.claude/rules/change-discipline.md` § One rail per concern.
+- **A `redisUrl` that is not a `redis:`/`rediss:` URL is refused at construction**, as is one without a host or without a port. The silent branch that treated such a value as the hostname and defaulted the port to `6379` is gone: it hardcoded topology (principle 2) behind a fallback (principle 3), and it is what let a misspelt value reach a live boot. No message echoes the URL or the refused value — both carry the password.
+
+### Removed
+
+- **`config.password`** — refused by name, not ignored (a retired option that is silently dropped leaves the caller believing a password reached the server). Four questions, `.claude/rules/change-discipline.md` § Removing: (1) it came to exist because the constructor read only host and port off the URL, so a Redis with `requirepass` needed the password from somewhere — `ServiceWrapper` began setting it on 2026-09-11; (2) no part of the concept carried it: the platform decision is that `REDIS_URL` carries endpoint AND credential, and it never sanctioned a second input; (3) after this change nothing reads it — the two callers that set it (`api/shared/connector/service-wrapper/src/ServiceWrapper.js`, `api_biz/ingest/scripts/lib/build-operator-context.js`) each re-derive the value from the very same URL, a copy of the parse rather than a second source; (4) the replacement is more conceptual — one rail, one parse, and a URL with userinfo can no longer lose its password without a word.
+- **`config.db`** — refused by name; the database index is the URL's path. Four questions: (1) it came to exist as `config.db || 0`, so a caller could select a database; (2) nothing in the concept carried it — no platform document declares a non-default database for the SecretBox projection; (3) zero callers pass a value: only `ServiceWrapper` forwards `secretsConfig.db`, which no service config declares (`api_biz/ingest/config/service/config.json` has `"secrets": { "enabled": true }`); (4) the path is more conceptual — the database belongs to the address, and `|| 0` additionally swallowed a malformed declaration into a 0 nobody asked for. With no path declared the connector passes no `db` at all and ioredis selects its own default, database 0 — named here rather than re-implemented.
+
+### Added
+
+- `tests/integration/redisAuthFromUrl.integration.test.js` — a throwaway `redis:7-alpine` with `requirepass` on an ephemeral loopback port (the shared dev cache runs without one and cannot answer this question): the happy path reads a real sealed secret back through an authenticated connection, the failure path shows the same URL without the password refused with `NOAUTH`, and the control case proves the server still required AUTH after the green run.
+
+### Changed — a failed `connect()` carries the server's verdict (d.566)
+
+`connect()` handed the caller ioredis's end-of-socket sentence — `Connection is closed.`,
+no context, no `cause`, no verdict — while the server's own answer reached `_lastError`
+and the log alone. Measured against a `redis:7-alpine --requirepass` on 2026-09-16: a URL
+without the password (`NOAUTH Authentication required.`), a URL with the wrong password
+(`WRONGPASS invalid username-password pair or user is disabled.`) and a port with no
+listener (`connect ECONNREFUSED …`) produced byte-identical caller errors. That is why dev
+incident B88 (gateway crash loop, RestartCount 51) could not be read from the error at all.
+
+The caller is now told which of two things happened:
+
+- the server **ANSWERED and refused** — `NOAUTH`, `WRONGPASS`, `NOPERM`. The message
+  quotes the server's sentence and names the credential in `REDIS_URL` as the fix, and the
+  server's error travels as `cause`.
+- the server **never answered** — the message says exactly that, quotes what the client
+  rejected with, and adds that a refused credential answers NOAUTH/WRONGPASS/NOPERM and is
+  reported as such, so this is not one. That error travels as `cause`.
+
+It is the rule `@onlineapps/mq-client-core` d.295 states for a broker refusal (403/530/406),
+on the same reasoning: an ANSWERED refusal is permanent, because the next attempt asks the
+same question and gets the same answer.
+
+So a refusal also **ends the attempts**, and a failed attempt takes its client with it.
+Measured on all three failure paths: ioredis was left in status `reconnecting` after
+`connect()` rejected, so a credential the server had already refused was asked again on a
+loop, and the connector — which never sets `connected` on a later reconnect — would never
+have used that socket anyway. A refusal on the `error` channel now disconnects the client
+at once, and every failed `connect()` drops it.
+
+Only the endpoint (`host:port`) is named in these messages, never the URL: this package
+keeps the parsed fields and drops the value precisely because the value carries the
+password.
+
+### Added (d.566)
+
+- `tests/unit/connectVerdict.test.js` — both sentences asserted whole, the `cause` as a
+  value, no part of the credential in either, the refusal that ends the attempts, and two
+  controls (an accepted `connect()` still resolves `true` and keeps its client; a
+  transport error after the connection is open is NOT treated as a refusal).
+- `tests/integration/redisAuthFromUrl.integration.test.js` grew the two failure paths this
+  change is about — a wrong password named `WRONGPASS` with no part of it echoed, and a
+  port with no listener reported as "no verdict" with `cause.code` `ECONNREFUSED` — and
+  its NOAUTH path now asserts the verdict the caller gets instead of `Connection is
+  closed.`. The error-message census moved 31 → 33.
+
+### Fixed — a store that comes back is read again (d.573)
+
+`connected` was written once, when `connect()` resolved, and never read off the client
+again. The connector therefore had no idea what the client was doing: a Redis that went
+away mid-run left the flag `true`, so `get()` handed the read to a client with no socket
+instead of naming the missing store — and nothing could ever put the flag back, because
+the reconnection ioredis performs on its own was not watched. One outage decided the fate
+of every secret read for the rest of the process's life.
+
+`connected` is now the client's READY state — socket open, AUTH and SELECT done — one rail
+with `@onlineapps/conn-base-cache` d.572: `ready` sets it, `close` and `end` take it down,
+the next `ready` puts it back. Every handler acts only for the client this connector still
+holds, so the verdict of d.566 stays exactly as terminal as it was: a client the server
+refused is discarded, and nothing it emits afterwards can put the connector back in
+service behind the caller's back.
+
+### Tests (d.573)
+
+Unit 177 → 182, integration 26 → 28. New `tests/unit/connectionLifecycle.test.js` asserts
+the state machine as values: the read that reaches the store answers `SECRET_NOT_FOUND`,
+the one after a `close` answers `SECRET_STORE_UNAVAILABLE` and never touches the client,
+and the flag through an outage reads `[true, false, true]` (it read `[true, true, true]`
+before the fix), with `end` as a second way down and a refusal that survives a `ready`
+from its discarded client as the control. New
+`tests/integration/reconnect.integration.test.js` asks a real server: its own
+`redis:7` container on a fixed loopback port, a value sealed and read back, `docker stop`
+→ `SECRET_STORE_UNAVAILABLE`, `docker start` → the same read succeeds, each step waited
+for on the client's own `close`/`ready` event rather than on a guessed delay, with a
+`WRONGPASS` refusal as the control that stays terminal.
+
+## [2.0.0] — 2026-09-14
+
 ### Changed — BREAKING
 
 - **`SECRETS_MASTER_KEYS` replaces `SECRETS_MASTER_KEY`**: the package reads an ordered LIST of master keys (`<key_id>:<base64 key>[,…]`). The first key seals every new write; every key in the list opens what it sealed, selected by the blob's `key_id`. A blob naming a key that is not in the list is refused with `SECRET_KEY_UNKNOWN` — there is no "try every key" pass. `SecretsConnector` takes `masterKeys` instead of `masterKeyBase64` (owner decision 2026-09-14, `docs/governance/confirmations/secretbox-master-keys.md` 001).

package/README.md

@@ -96,6 +96,30 @@ await secrets.connect();
 Handlers only ever call `ctx.secrets.get(ref)`; the ContextBuilder facade injects
 the invocation scope.
 
+**The Redis credential lives in the URL and nowhere else.** `redisUrl` carries the
+endpoint, the optional Redis 6 ACL user, the password and the database index —
+`redis://[user:password@]host:port[/db]`, `rediss://` for TLS — exactly as
+`service-common` and `mq-client-core` read it. Percent-encode a password that
+contains `@`, `:` or `/`. The options `password` and `db` beside the URL are
+**refused by name**: they were a second rail for a fact the URL already carries,
+and while they existed a URL with userinfo lost its password silently (INFRA, dev,
+2026-09-15: ioredis connected without AUTH, gateway crash loop, RestartCount 51).
+A value that is not a `redis:`/`rediss:` URL, or one without a host or a port, is
+refused at construction — this package declares no topology default, not even 6379.
+
+**A failed `connect()` says what the server answered.** A server that ANSWERED and
+refused the credential — `NOAUTH`, `WRONGPASS`, `NOPERM` — is permanent: the message
+quotes the server's sentence, names `REDIS_URL` as the fix, carries the original error
+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
@@ -257,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": "2.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

@@ -39,6 +39,70 @@ const { normalizeWorkspaceId } = require('./workspaceId');
 // Meta owns the projection; its StateConnector prefixes keys with `state:meta:`.
 const DEFAULT_KEY_PREFIX = 'state:meta:secret:';
 
+/**
+ * The sentences with which a Redis server ANSWERS a connection attempt and
+ * REFUSES it — an answer, not a silence:
+ *
+ *   NOAUTH    the server requires AUTH and this connection sent none
+ *   WRONGPASS the credential the URL carries is not the server's
+ *   NOPERM    the ACL user the URL names may not run the command
+ *
+ * The distinction is the one `@onlineapps/mq-client-core` draws for a broker
+ * (`_isBrokerRefusal()`, reply codes 403/530/406, d.295): an ANSWERED refusal is
+ * permanent — the next attempt asks the same question and gets the same answer,
+ * so the attempts end and the caller is told what the server said. Anything else
+ * is transient by design: nobody answered, and giving up forever on a server that
+ * may come back is a different defect.
+ *
+ * The list holds only sentences a live Redis 6/7 actually sends on this path:
+ * NOAUTH and WRONGPASS were measured against `redis:7-alpine --requirepass`
+ * (2026-09-16), NOPERM is the same class for the ACL user the URL may name. Redis
+ * 5's `ERR invalid password` is deliberately absent — the platform runs Redis 7,
+ * and a ban nothing can trigger is silence pretending to be coverage
+ * (`automation-gates.md` §5). `ERR Client sent AUTH, but no password is set` is
+ * absent for the same reason: ioredis warns on it and does not fail the
+ * connection (`ioredis/built/redis/event_handler.js`, `connectHandler`).
+ */
+const SERVER_REFUSAL_PREFIXES = ['NOAUTH', 'WRONGPASS', 'NOPERM'];
+
+/**
+ * Did the server answer and refuse?
+ * @param {Error|null|undefined} err
+ * @returns {boolean}
+ */
+function isServerRefusal(err) {
+  if (!err || typeof err.message !== 'string') return false;
+  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);
@@ -73,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',
@@ -81,42 +147,273 @@ 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
+// credential (`service-common` 3.0.2 hands the whole URL to node-redis;
+// `mq-client-core` 3.2.0 reads the credential off the URL). Anything else this
+// package might accept beside it would be a second rail for the same fact.
+const REDIS_URL_PROTOCOLS = new Set(['redis:', 'rediss:']);
+
+/**
+ * Options beside `redisUrl` that used to carry a fact the URL already carries.
+ * They are REFUSED by name rather than ignored: an ignored option looks accepted
+ * and leaves the caller believing a password reached the server
+ * (`.claude/rules/change-discipline.md` § One rail per concern; principle 11,
+ * clean break — no shim that keeps reading them).
+ */
+const RETIRED_OPTIONS = {
+  password: 'the Redis password comes from the userinfo of redisUrl (redis://user:password@host:port)',
+  db: 'the Redis database index comes from the path of redisUrl (redis://host:port/3)'
+};
+
+function refuseRetiredOptions(config) {
+  for (const [name, replacement] of Object.entries(RETIRED_OPTIONS)) {
+    if (config[name] === undefined) continue;
+    throw new Error(
+      `[conn-infra-secrets] Option "${name}" is not accepted - ${replacement}. `
+      + `Fix: drop "${name}" from the SecretsConnector config and put the value in REDIS_URL `
+      + '(api/config/env-active/shared.env); a value beside the URL is a second rail for a fact '
+      + 'the URL already carries. The refused value is not echoed here.'
+    );
+  }
+}
+
+/**
+ * The database index the URL declares, or `null` when it declares none.
+ *
+ * No path (`redis://h:6379`) and an empty path (`redis://h:6379/`) declare
+ * nothing, and the connector then passes no `db` at all — ioredis selects its own
+ * default, database 0. That default belongs to ioredis and is named here rather
+ * than re-implemented as `config.db || 0`, which would also swallow a malformed
+ * declaration into a 0 nobody asked for (principle 3, No Fallbacks).
+ */
+function databaseFromPath(pathname) {
+  // `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(
+      `[conn-infra-secrets] redisUrl declares database "${declared}" - Expected a non-negative `
+      + 'integer as the URL path, e.g. redis://host:6379/3. Fix: correct the path of REDIS_URL in '
+      + 'shared.env, or drop it to use the default database.'
+    );
+  }
+  return Number.parseInt(declared, 10);
+}
+
+/**
+ * Build the ioredis options from the URL — endpoint, ACL user and password alike.
+ *
+ * Measured reason this function exists (INFRA, dev, 2026-09-15 21:20Z): the
+ * constructor used to take `hostname`/`port` only and expect the password in a
+ * separate `config.password`, so a URL carrying userinfo lost it and ioredis
+ * connected without AUTH — gateway crash loop (RestartCount 51), dispatcher and
+ * ingest failing on the first secret read.
+ *
+ * Nothing here echoes the URL or any part of its userinfo: these messages reach
+ * logs, and the value carries the password.
+ */
+function redisOptionsFromUrl(redisUrl) {
+  let parsed;
+  try {
+    parsed = new URL(redisUrl);
+  } catch (err) {
+    throw new Error(
+      '[conn-infra-secrets] redisUrl is not a URL - Expected redis://[user:password@]host:port[/db] '
+      + '(or rediss:// for TLS), the one rail that carries both the endpoint and the credential. '
+      + 'Fix: set REDIS_URL in api/config/env-active/shared.env to the full URL; a bare host:port '
+      + 'is not accepted. The value is not echoed here because it carries the password.',
+      { cause: err }
+    );
+  }
+  if (!REDIS_URL_PROTOCOLS.has(parsed.protocol)) {
+    throw new Error(
+      `[conn-infra-secrets] redisUrl has scheme "${parsed.protocol}" - Expected redis: or rediss:. `
+      + 'Fix: set REDIS_URL in api/config/env-active/shared.env to redis://host:port (rediss:// for TLS).'
+    );
+  }
+  if (!parsed.hostname) {
+    throw new Error(
+      '[conn-infra-secrets] redisUrl declares no host - Expected redis://host:port. '
+      + 'Fix: set REDIS_URL in api/config/env-active/shared.env to the full endpoint.'
+    );
+  }
+  if (!parsed.port) {
+    throw new Error(
+      '[conn-infra-secrets] redisUrl declares no port - Expected redis://host:port; the port is '
+      + 'topology and this package declares no default for it. Fix: set REDIS_URL in '
+      + 'api/config/env-active/shared.env to the full endpoint, e.g. redis://api_node_cache:6379.'
+    );
+  }
+
+  const options = {
+    host: parsed.hostname,
+    port: Number.parseInt(parsed.port, 10),
+    lazyConnect: true
+  };
+  // Redis 6 ACL: the URL may name a user as well as a password. An absent one is
+  // ABSENT — never `''`, which ioredis would send as `AUTH ""`.
+  if (parsed.username) options.username = decodeURIComponent(parsed.username);
+  if (parsed.password) options.password = decodeURIComponent(parsed.password);
+  const db = databaseFromPath(parsed.pathname);
+  if (db !== null) options.db = db;
+  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
-   * @param {string} config.redisUrl - redis://host:port (required)
+   * @param {string} config.redisUrl - `redis://[user:password@]host:port[/db]` or `rediss://…`
+   *        (required). The URL is the ONLY rail: endpoint, ACL user, password and
+   *        database index all come off it. `config.password` and `config.db` are
+   *        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.password] - Redis password
-   * @param {number} [config.db=0] - Redis database index
+   * @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) {
       throw new Error('[conn-infra-secrets] redisUrl is required - Fix: pass REDIS_URL.');
     }
+    refuseRetiredOptions(config);
     this._keyring = loadMasterKeys(config.masterKeys);
-    this._keyPrefix = config.keyPrefix || DEFAULT_KEY_PREFIX;
-
-    let host = config.redisUrl;
-    let port = 6379;
-    if (config.redisUrl.startsWith('redis://')) {
-      const parsed = new URL(config.redisUrl);
-      host = parsed.hostname;
-      port = parseInt(parsed.port, 10) || 6379;
-    }
-    this._redisOptions = { host, port, password: config.password, db: config.db || 0, lazyConnect: true };
+    this._keyPrefix = resolveKeyPrefix(config.keyPrefix);
+
+    this._redisOptions = redisOptionsFromUrl(config.redisUrl);
+    // What a message of this package may say about the store: host and port,
+    // never the URL. The connector keeps the parsed fields and drops the value
+    // precisely because the value carries the password, so there is no URL here
+    // to redact — and nothing to redact it with (this package declares one
+    // dependency, ioredis).
+    this._endpoint = `${this._redisOptions.host}:${this._redisOptions.port}`;
     this.client = null;
+    // Whether the CLIENT is ready — socket open, AUTH and SELECT done. It is not
+    // a latch set once by connect(): it follows the client through an outage and
+    // back (d.573), one rail with `@onlineapps/conn-base-cache` d.572.
     this.connected = false;
+    this._lastError = null;
   }
 
+  /**
+   * Open the connection, or say what the server answered.
+   *
+   * Until d.566 this method handed the caller ioredis's end-of-socket sentence —
+   * `Connection is closed.`, no `cause`, no verdict — while the server's actual
+   * answer reached `_lastError` and nothing else. That is how dev incident B88
+   * (gateway crash loop, RestartCount 51) could not be read from the error at
+   * all: the log said the socket closed, and the `NOAUTH` that closed it was a
+   * field nobody printed.
+   *
+   * Two outcomes now, told apart by `isServerRefusal()` and said in the caller's
+   * error: the server ANSWERED and refused (permanent — the attempts end here),
+   * or it never answered (transient — the caller may try again). Either way the
+   * original error travels as `cause`, so the stack survives the sentence.
+   *
+   * A failed attempt also takes its client with it. ioredis keeps retrying in the
+   * background after `connect()` rejects — measured 2026-09-16: status
+   * `reconnecting` on all three failure paths — so a connector that gives up
+   * without disconnecting leaves a socket loop nobody owns, and this one never
+   * reports `connected` again for it: the lifecycle handlers below act only for
+   * the client this connector still holds, so nothing that client emits after it
+   * has been discarded can put the connector back in service.
+   *
+   * What `connected` means afterwards is the client's own READY state, watched
+   * rather than assumed (d.573): a Redis that goes away mid-run takes the flag
+   * down, so `get()` names the missing store instead of walking into a client
+   * with no socket, and the reconnection ioredis performs on its own puts the
+   * flag back. Before d.573 the flag was written once and never read off the
+   * client again, so an outage decided the fate of every secret read that
+   * followed it.
+   *
+   * @returns {Promise<true>}
+   * @throws {Error} naming the server's verdict, with the original error as `cause`
+   */
   async connect() {
     if (this.connected) return true;
-    this.client = new Redis(this._redisOptions);
-    this.client.on('error', (err) => { /* surfaced on get() */ this._lastError = err; });
-    await this.client.connect();
+    this._lastError = null;
+    const client = new Redis(this._redisOptions);
+    this.client = client;
+
+    // `ready`, not `connect`: ioredis emits `connect` when the socket opens,
+    // which is before AUTH and before SELECT, so it would report a usable store
+    // for a connection the server is about to refuse (the same rule as
+    // `@onlineapps/conn-base-cache` d.572). Every handler checks that this is
+    // still THE client of this connector: a discarded one keeps emitting for a
+    // while, and its events belong to nobody.
+    const mine = () => this.client === client;
+    client.on('ready', () => { if (mine()) this.connected = true; });
+    // `close` is the socket going away with a reconnection still to come; `end`
+    // is the client giving up for good. Both mean the store is not readable now.
+    client.on('close', () => { if (mine()) this.connected = false; });
+    client.on('end', () => { if (mine()) this.connected = false; });
+
+    client.on('error', (err) => {
+      // Surfaced on get(), and read below as the verdict of a failed connect().
+      this._lastError = err;
+      // A refusal the server has already spoken does not change on the next
+      // attempt: end the reconnection rather than ask again in a loop.
+      if (isServerRefusal(err)) client.disconnect();
+    });
+
+    try {
+      await client.connect();
+    } catch (rejection) {
+      // The verdict comes from whichever error carries it: ioredis delivers the
+      // server's sentence on the `error` channel and rejects connect() with the
+      // state of the socket, but a rejection that carries the verdict itself is
+      // read the same way.
+      const refusal = [this._lastError, rejection].find(isServerRefusal) || null;
+      const reported = refusal || this._lastError || rejection;
+
+      client.disconnect();
+      this.client = null;
+      this.connected = false;
+
+      if (refusal) {
+        throw new Error(
+          `[conn-infra-secrets] Failed to connect to Redis at ${this._endpoint} - the server `
+          + `answered and refused it with "${refusal.message}". Fix: correct the credential in `
+          + 'REDIS_URL (api/config/env-active/shared.env) — the ACL user too, if the URL names '
+          + 'one; a server that answers this way refuses every retry, so the connector stopped '
+          + 'instead of looping. Only the endpoint is named here; the URL carries the password.',
+          { cause: refusal }
+        );
+      }
+      throw new Error(
+        `[conn-infra-secrets] Failed to connect to Redis at ${this._endpoint} - the server sent `
+        + `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 '
+        + 'endpoint is named here; the URL carries the password.',
+        { cause: reported }
+      );
+    }
+
     this.connected = true;
     return true;
   }