@onlineapps/conn-infra-secrets 1.1.0 → 3.0.0

package/src/index.js

@@ -9,86 +9,358 @@
  * store (oagen_meta.secret) is owned by biz-meta and never touched on this path.
  *
  * Redis projection (see secretbox.md §5) — flat key (meta StateConnector has no
- * hash ops), value = base64( iv || authTag || ciphertext ):
- *   state:meta:secret:<tenant_id>:<workspace_id|->:<ref>
+ * hash ops), value = the sealed blob described in src/crypto.js:
+ *   state:meta:secret:<tenant_id>:<workspace_id>:<ref>
+ *
+ * The master keys arrive as the declared ORDERED LIST (`SECRETS_MASTER_KEYS`,
+ * owner decision 2026-09-14, confirmation secretbox-master-keys 001): the first
+ * key seals every new write, every key in the list opens what it sealed, selected
+ * by the blob's own `key_id`. That is what makes a rotation a switch rather than a
+ * jump — while both keys are listed, rows on either of them are readable.
  *
  * Contract: get(name, scope) => Promise<string>. The ContextBuilder facade passes
  * the invocation's { tenant_id, workspace_id } as scope. No fallbacks: a missing
- * projection throws SECRET_NOT_FOUND; a bad blob throws SECRET_DECRYPT_FAILED.
+ * projection throws SECRET_NOT_FOUND; a blob sealed with a key that is not in the
+ * list throws SECRET_KEY_UNKNOWN (never a "try every key" pass); a blob that does
+ * not open under its own key — tampered, or lifted out of the tenant/workspace/ref
+ * it was bound to — throws SECRET_DECRYPT_FAILED; a scope that cannot address one
+ * concrete workspace throws SECRET_SCOPE_MISSING before any Redis round trip.
  *
  * @see api/docs/architecture/secretbox.md
+ * @see api/docs/governance/confirmations/secretbox-tenant-wide-scope.md
  */
 
 const Redis = require('ioredis');
-const { loadMasterKey, open } = require('./crypto');
+const {
+  loadMasterKeys, openWithDeclaredVersion, SecretCryptoError, MASTER_KEYS_ENV
+} = require('./crypto');
+const { normalizeWorkspaceId } = require('./workspaceId');
 
 // Meta owns the projection; its StateConnector prefixes keys with `state:meta:`.
 const DEFAULT_KEY_PREFIX = 'state:meta:secret:';
 
-// biz-meta stores tenant-wide secrets with workspace_id 0 (`TENANT_WIDE = 0` in
-// meta/src/handlers/secrets.js) and projects them under the `-` segment. The
-// reader must apply the identical mapping — a caller that legitimately passes 0
-// would otherwise read `:0:`, a key nothing ever writes. Omitted/null means the
-// same thing on the writing side, so all four spellings collapse to `-`.
-const TENANT_WIDE = 0;
+/**
+ * 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'];
 
 /**
- * @param {number|string|null|undefined} workspaceId
- * @returns {string} the key segment: `-` for tenant-wide, the id otherwise
+ * Did the server answer and refuse?
+ * @param {Error|null|undefined} err
+ * @returns {boolean}
  */
-function workspaceSegment(workspaceId) {
-  if (workspaceId === null || workspaceId === undefined) return '-';
-  if (workspaceId === TENANT_WIDE || workspaceId === String(TENANT_WIDE)) return '-';
-  return String(workspaceId);
+function isServerRefusal(err) {
+  if (!err || typeof err.message !== 'string') return false;
+  return SERVER_REFUSAL_PREFIXES.some((prefix) => err.message.startsWith(prefix));
 }
 
 class SecretResolutionError extends Error {
-  constructor(code, message) {
-    super(message);
+  constructor(code, message, options) {
+    super(message, options);
     this.name = 'SecretResolutionError';
     this.code = code;
   }
 }
 
+// The rule "which workspace_id can address a secret" moved into its own module,
+// src/workspaceId.js: src/crypto.js needs the same normalization for the bound
+// context (AAD), and a second copy of the rule is exactly what
+// .claude/rules/change-discipline.md § One rail per concern forbids. It stays
+// part of this package's public API — re-exported at the bottom of this file —
+// so the writing side keeps importing it from here.
+
+/**
+ * @param {*} workspaceId
+ * @returns {string} the key segment for one concrete workspace
+ * @throws {SecretResolutionError} SECRET_SCOPE_MISSING for any unusable value
+ */
+function workspaceSegment(workspaceId) {
+  const ws = normalizeWorkspaceId(workspaceId);
+  if (ws === null) {
+    throw new SecretResolutionError(
+      'SECRET_SCOPE_MISSING',
+      `[conn-infra-secrets] Invalid workspace_id "${workspaceId}" - Expected a positive integer naming `
+      + 'the workspace the secret belongs to. Fix: pass the concrete workspace_id; the tenant-wide '
+      + 'scope was retired by owner decision 2026-09-03 '
+      + '(api/docs/governance/confirmations/secretbox-tenant-wide-scope.md 001).'
+    );
+  }
+  return String(ws);
+}
+
 function projectionKey(tenantId, workspaceId, ref, keyPrefix = DEFAULT_KEY_PREFIX) {
   if (tenantId === undefined || tenantId === null) {
-    throw new SecretResolutionError('SECRET_SCOPE_MISSING', '[conn-infra-secrets] tenant_id is required to resolve a secret.');
+    throw new SecretResolutionError(
+      'SECRET_SCOPE_MISSING',
+      '[conn-infra-secrets] tenant_id is required to resolve a secret - Expected the tenant the secret '
+      + 'belongs to. Fix: pass scope.tenant_id from the operation context.'
+    );
   }
   return `${keyPrefix}${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) {
+  const declared = String(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;
+}
+
 class SecretsConnector {
   /**
    * @param {Object} config
-   * @param {string} config.redisUrl - redis://host:port (required)
-   * @param {string} config.masterKeyBase64 - base64 32-byte AES-256-GCM key (required)
-   * @param {string} [config.password] - Redis password
-   * @param {number} [config.db=0] - Redis database index
+   * @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.keyPrefix] - projection key prefix (defaults to the one meta writes)
    */
   constructor(config = {}) {
     if (!config.redisUrl) {
       throw new Error('[conn-infra-secrets] redisUrl is required - Fix: pass REDIS_URL.');
     }
-    this._key = loadMasterKey(config.masterKeyBase64);
+    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._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 "${reported.message}". 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;
   }
@@ -104,15 +376,23 @@ class SecretsConnector {
   /**
    * Resolve a secret ref to plaintext for the given invocation scope.
    * @param {string} name - opaque secret ref
-   * @param {{ tenant_id: number|string, workspace_id?: number|string|null }} [scope]
+   * @param {{ tenant_id: number|string, workspace_id: number|string }} scope
+   *        Both ids are required; `workspace_id` must be a positive integer.
    * @returns {Promise<string>}
    */
   async get(name, scope = {}) {
     if (typeof name !== 'string' || name.length === 0) {
-      throw new SecretResolutionError('SECRET_REF_INVALID', '[conn-infra-secrets] secret ref must be a non-empty string.');
+      throw new SecretResolutionError(
+        'SECRET_REF_INVALID',
+        '[conn-infra-secrets] secret ref must be a non-empty string - Expected the ref name declared in '
+        + 'the SecretBox. Fix: pass the ref, not the secret value.'
+      );
     }
     if (!this.client || !this.connected) {
-      throw new SecretResolutionError('SECRET_STORE_UNAVAILABLE', '[conn-infra-secrets] not connected - call connect() first.');
+      throw new SecretResolutionError(
+        'SECRET_STORE_UNAVAILABLE',
+        '[conn-infra-secrets] not connected - Expected an open Redis connection. Fix: call connect() first.'
+      );
     }
     const key = projectionKey(scope.tenant_id, scope.workspace_id, name, this._keyPrefix);
     const blob = await this.client.get(key);
@@ -123,11 +403,29 @@ class SecretsConnector {
       );
     }
     try {
-      return open(blob, this._key);
+      // The projection key carries no version, so the version comes from the blob
+      // and is bound into the context with it — src/crypto.js says what that does
+      // and does not prove.
+      return openWithDeclaredVersion(blob, this._keyring, {
+        tenant_id: scope.tenant_id,
+        workspace_id: scope.workspace_id,
+        ref: name
+      });
     } catch (err) {
+      if (err instanceof SecretCryptoError && err.code === 'SECRET_KEY_UNKNOWN') {
+        throw new SecretResolutionError(
+          'SECRET_KEY_UNKNOWN',
+          `[conn-infra-secrets] Unknown master key for secret "${name}" at ${key} - ${err.message}`,
+          { cause: err }
+        );
+      }
       throw new SecretResolutionError(
         'SECRET_DECRYPT_FAILED',
-        `[conn-infra-secrets] Failed to decrypt secret "${name}" for scope ${key} - master key mismatch or corrupted blob.`
+        `[conn-infra-secrets] Failed to decrypt secret "${name}" for scope ${key} - the blob does not `
+        + 'open under the master key it names: it is corrupt, or it was sealed for another tenant, '
+        + `workspace or ref. Fix: check that ${MASTER_KEYS_ENV} holds the key this value was sealed `
+        + 'with, then re-seal the value via the biz-meta set-secret operation.',
+        { cause: err }
       );
     }
   }
@@ -149,7 +447,13 @@ class MockSecretsConnector {
   isConnected() { return this.connected; }
   async get(name, scope = {}) {
     const v = this.store.get(MockSecretsConnector._k(scope, name));
-    if (v === undefined) throw new SecretResolutionError('SECRET_NOT_FOUND', `mock: ${name} not found`);
+    if (v === undefined) {
+      throw new SecretResolutionError(
+        'SECRET_NOT_FOUND',
+        `[conn-infra-secrets] Secret ref "${name}" not found in MockSecretsConnector - Expected a value `
+        + 'seeded for this scope. Fix: call seed(scope, name, value) before get() in the test.'
+      );
+    }
     return v;
   }
 }
@@ -159,4 +463,5 @@ module.exports.SecretsConnector = SecretsConnector;
 module.exports.MockSecretsConnector = MockSecretsConnector;
 module.exports.SecretResolutionError = SecretResolutionError;
 module.exports.projectionKey = projectionKey;
+module.exports.normalizeWorkspaceId = normalizeWorkspaceId;
 module.exports.create = (config) => new SecretsConnector(config);

package/src/readability.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * Readability — the question "is anything still sealed with a key I am about to
+ * drop", asked on purpose instead of by accident.
+ *
+ * Owner decision 2026-09-14, confirmation
+ * api/docs/governance/confirmations/secretbox-master-keys.md 001: a readability
+ * check — every stored blob opens with the keys that would REMAIN — is a mandatory
+ * step BEFORE a key is removed from `SECRETS_MASTER_KEYS`.
+ *
+ * WHAT IT COSTS TO SKIP IT, measured: in August 2026 the master key was replaced
+ * and the old one simply stopped being used. Nobody asked what was still sealed
+ * with it. Six of ten rows of `oagen_meta.secret` became unreadable and stayed
+ * that way for two weeks, until someone noticed while checking something else.
+ * The old key no longer exists anywhere, so those rows are unrecoverable.
+ *
+ * IT OPENS EVERY BLOB, it does not merely read the `key_id` off the header. A row
+ * whose key is listed but whose blob is corrupt, or bound to another tenant,
+ * workspace, ref or version, is just as unreadable — and a check that trusted the
+ * header would report it as fine.
+ *
+ * IT NEVER STOPS HALFWAY. A blob that cannot even be parsed is reported as a
+ * finding, not raised as an exception: the whole point is the complete list of
+ * what will not open, and a check that dies on the first bad row cannot give one.
+ * What it DOES refuse is a record it cannot ask the question about at all — one
+ * that does not name its tenant, workspace, ref or version — because that is a
+ * defect in the caller's query, not a finding about the store.
+ *
+ * @see src/rotation.js — the run that makes the list shorter safely
+ * @see src/crypto.js — the sealing contract; `keyring.without(id)` builds the list
+ *      a removal is checked against
+ */
+
+const { MasterKeyring, SecretCryptoError, open, parseBlob } = require('./crypto');
+
+const IDENTITY_FIELDS = ['tenant_id', 'workspace_id', 'ref', 'version'];
+
+/** Why a row does not open. Three causes, three different repairs. */
+const REASONS = Object.freeze({
+  /** The blob names a key that is not in the list — put it back, or rewrite the value. */
+  KEY_NOT_IN_LIST: 'key_not_in_list',
+  /** The key is there and the blob still does not open — corrupt, or bound to another row. */
+  DOES_NOT_OPEN: 'does_not_open',
+  /** Not a blob of the current format at all — rewrite the value from its source. */
+  MALFORMED_BLOB: 'malformed_blob'
+});
+
+function refuse(code, problem, detail) {
+  throw new SecretCryptoError(code, `[conn-infra-secrets] ${problem} - Fix: ${detail}`);
+}
+
+function assertRecord(record, index) {
+  if (record === null || typeof record !== 'object') {
+    refuse(
+      'SECRET_READABILITY_INVALID',
+      `Unusable record at position ${index} - got ${record === null ? 'null' : typeof record}`,
+      'pass the records listSecrets() yields: { tenant_id, workspace_id, ref, version, blob }.'
+    );
+  }
+  for (const field of IDENTITY_FIELDS) {
+    if (record[field] === undefined || record[field] === null || String(record[field]).trim() === '') {
+      refuse(
+        'SECRET_READABILITY_INVALID',
+        `Record at position ${index} carries no ${field} - the check cannot ask whether a row opens `
+        + 'without knowing which row it is: all four fields are part of the bound context the value is '
+        + 'sealed under',
+        `select ${field} alongside the sealed blob.`
+      );
+    }
+  }
+  if (typeof record.blob !== 'string' || record.blob === '') {
+    refuse(
+      'SECRET_READABILITY_INVALID',
+      `Record at position ${index} carries no blob - there is nothing to open`,
+      'select the sealed blob for that row; a store keeping the parts in separate columns joins them '
+      + 'with sealBlob() in its adapter.'
+    );
+  }
+}
+
+/**
+ * Does every stored blob open with this key list?
+ *
+ * @param {Object} deps
+ * @param {Array<Object>|AsyncIterable<Object>} deps.records the stored records
+ * @param {MasterKeyring} deps.keyring the list to ask about — typically
+ *        `keyring.without('<the key you want to drop>')`
+ * @returns {Promise<{ total: number, readable: number, unreadable: Array<{
+ *   tenant_id, workspace_id, ref, version, key_id: string|null, reason: string }> }>}
+ */
+async function checkReadability({ records, keyring } = {}) {
+  if (!(keyring instanceof MasterKeyring)) {
+    refuse(
+      'SECRET_KEYS_INVALID',
+      `Missing keyring - a MasterKeyring is required, got ${keyring === null ? 'null' : typeof keyring}`,
+      'pass the list you intend to keep, e.g. loadMasterKeys(SECRETS_MASTER_KEYS).without("<key id>").'
+    );
+  }
+  if (records === null || records === undefined || typeof records !== 'object') {
+    refuse(
+      'SECRET_READABILITY_INVALID',
+      `Missing records - an array or an async iterable of stored records is required, got `
+      + `${records === null ? 'null' : typeof records}`,
+      'pass what the store adapter listSecrets() yields; an empty store is an empty array.'
+    );
+  }
+
+  let total = 0;
+  let readable = 0;
+  const unreadable = [];
+
+  for await (const record of records) {
+    assertRecord(record, total);
+    total += 1;
+    const identity = {
+      tenant_id: record.tenant_id,
+      workspace_id: record.workspace_id,
+      ref: record.ref,
+      version: record.version
+    };
+
+    let keyId = null;
+    try {
+      keyId = parseBlob(record.blob).keyId;
+    } catch {
+      unreadable.push({ ...identity, key_id: null, reason: REASONS.MALFORMED_BLOB });
+      continue;
+    }
+    if (!keyring.has(keyId)) {
+      unreadable.push({ ...identity, key_id: keyId, reason: REASONS.KEY_NOT_IN_LIST });
+      continue;
+    }
+    try {
+      // Opened, not merely inspected: this is the only answer that counts. The
+      // plaintext is discarded on the same line it is produced.
+      open(record.blob, keyring, identity);
+      readable += 1;
+    } catch {
+      unreadable.push({ ...identity, key_id: keyId, reason: REASONS.DOES_NOT_OPEN });
+    }
+  }
+
+  return { total, readable, unreadable };
+}
+
+module.exports = { checkReadability, REASONS };