@onlineapps/conn-infra-secrets 1.1.0 → 2.0.0

package/src/index.js

@@ -9,50 +9,77 @@
  * 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;
+class SecretResolutionError extends Error {
+  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 {number|string|null|undefined} workspaceId
- * @returns {string} the key segment: `-` for tenant-wide, the id otherwise
+ * @param {*} workspaceId
+ * @returns {string} the key segment for one concrete workspace
+ * @throws {SecretResolutionError} SECRET_SCOPE_MISSING for any unusable value
  */
 function workspaceSegment(workspaceId) {
-  if (workspaceId === null || workspaceId === undefined) return '-';
-  if (workspaceId === TENANT_WIDE || workspaceId === String(TENANT_WIDE)) return '-';
-  return String(workspaceId);
-}
-
-class SecretResolutionError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = 'SecretResolutionError';
-    this.code = code;
+  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}`;
 }
@@ -61,7 +88,8 @@ 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.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
    */
@@ -69,7 +97,7 @@ class SecretsConnector {
     if (!config.redisUrl) {
       throw new Error('[conn-infra-secrets] redisUrl is required - Fix: pass REDIS_URL.');
     }
-    this._key = loadMasterKey(config.masterKeyBase64);
+    this._keyring = loadMasterKeys(config.masterKeys);
     this._keyPrefix = config.keyPrefix || DEFAULT_KEY_PREFIX;
 
     let host = config.redisUrl;
@@ -104,15 +132,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 +159,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 +203,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 +219,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 };

package/src/rotation.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * Re-encryption — the half of a master-key rotation that carries the rows across.
+ *
+ * WHY IT EXISTS. Re-encrypting the stored rows is a NECESSARY PART of rotating the
+ * master key, not a follow-up (owner decision 2026-09-09,
+ * api/docs/governance/confirmations/secret-leak-rotation.md 001), and with a list
+ * of keys it is the step that lets the outgoing key be dropped at all. There is
+ * deliberately no lazy re-encryption on write to lean on: a row nobody writes to
+ * would stay on the old key forever, so "zero rows on the old key" would never
+ * hold (owner decision 2026-09-14, `secretbox-master-keys` 001). The August 2026
+ * rotation is what that costs: the key was replaced, the rows were left alone, and
+ * six of ten rows of `oagen_meta.secret` were unreadable for two weeks.
+ *
+ * WHAT IT DOES NOT DO. It owns no store. The rows come from an injected repository
+ * and go back through it (principle 1, DI) — this package has no database and must
+ * not grow one; the adapter over `oagen_<svc>.secret` belongs to the service that
+ * owns those rows.
+ *
+ * THE STORE IS CLASSIFIED BEFORE THE FIRST WRITE. A store where some rows answer
+ * to the outgoing key and some to the incoming one is worse than one that answers
+ * wholly to either, so everything that can be refused while nothing has been
+ * written is refused there — a malformed row, a missing identity, a blob that is
+ * not a blob. Classification needs no key: the blob names its own.
+ *
+ * THE PLAINTEXT LIVES BETWEEN ONE open() AND THE seal() ON THE NEXT LINE. Nothing
+ * this module returns, renders or throws carries a value or a key — pinned by a
+ * control case in tests/unit/rotation.test.js rather than left to a reader's care.
+ *
+ * @see src/crypto.js — the sealing contract and the key list
+ * @see src/readability.js — the check that has to be green before a key is dropped
+ */
+
+const { MasterKeyring, SecretCryptoError, open, seal, parseBlob } = require('./crypto');
+
+const IDENTITY_FIELDS = ['tenant_id', 'workspace_id', 'ref', 'version'];
+
+function refuse(code, problem, detail) {
+  throw new SecretCryptoError(code, `[conn-infra-secrets] ${problem} - Fix: ${detail}`);
+}
+
+/**
+ * The repository this tool needs, checked before it reads anything.
+ *
+ * `listSecrets()` returns every stored record — an array or an async iterable, so
+ * a store that streams does not have to materialize its table.
+ * `rewriteSecret(record, blob)` writes the new blob onto THAT row: same tenant,
+ * same workspace, same ref, SAME version. The blob is bound to the record's
+ * version (the AAD covers it), so a store that answered by creating a new version
+ * would write a blob bound to the wrong one.
+ */
+function assertRepository(repository) {
+  if (repository === null || typeof repository !== 'object') {
+    refuse(
+      'SECRET_ROTATION_INVALID',
+      `Missing repository - a store exposing listSecrets() and rewriteSecret() is required, got `
+      + `${repository === null ? 'null' : typeof repository}`,
+      'inject the adapter over the table that holds the sealed rows; this package owns no store.'
+    );
+  }
+  for (const method of ['listSecrets', 'rewriteSecret']) {
+    if (typeof repository[method] !== 'function') {
+      refuse(
+        'SECRET_ROTATION_INVALID',
+        `Repository cannot serve the rotation - ${method}() is missing`,
+        `implement ${method}() on the injected repository: listSecrets() yields every stored record `
+        + '{ tenant_id, workspace_id, ref, version, blob }, rewriteSecret(record, blob) writes the new '
+        + 'blob onto that same row and version.'
+      );
+    }
+  }
+}
+
+function assertKeyring(keyring) {
+  if (!(keyring instanceof MasterKeyring)) {
+    refuse(
+      'SECRET_KEYS_INVALID',
+      `Missing keyring - a MasterKeyring is required, got ${keyring === null ? 'null' : typeof keyring}`,
+      'pass loadMasterKeys(SECRETS_MASTER_KEYS); its FIRST key is the one every row is rewritten under.'
+    );
+  }
+}
+
+/** The identity of one row, in words. Metadata only, never a value. */
+function identity(record) {
+  return `tenant ${record.tenant_id} / workspace ${record.workspace_id} "${record.ref}" (v${record.version})`;
+}
+
+function assertRecord(record, index) {
+  if (record === null || typeof record !== 'object') {
+    refuse(
+      'SECRET_ROTATION_INVALID',
+      `Unusable record at position ${index} - got ${record === null ? 'null' : typeof record}`,
+      'listSecrets() yields objects { 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_ROTATION_INVALID',
+        `Record at position ${index} carries no ${field} - every row has to name the tenant, workspace, `
+        + 'ref and version it belongs to, because all four are part of the bound context the value is '
+        + 'sealed under',
+        `select ${field} alongside the sealed blob. The run is refused now, before anything is written: `
+        + 'a refusal halfway through leaves the store half rotated.'
+      );
+    }
+  }
+  if (typeof record.blob !== 'string' || record.blob === '') {
+    refuse(
+      'SECRET_ROTATION_INVALID',
+      `Record ${identity(record)} carries no blob - the sealed value is required`,
+      'select the sealed blob for that row; a store keeping the parts in separate columns joins them '
+      + 'with sealBlob() in its adapter.'
+    );
+  }
+}
+
+/**
+ * Re-encrypt every row that is not yet on the active key.
+ *
+ * @param {Object} deps
+ * @param {{ listSecrets: Function, rewriteSecret: Function }} deps.repository injected store
+ * @param {MasterKeyring} deps.keyring the list; its first key is the one rows are rewritten under
+ * @returns {Promise<{
+ *   total: number,
+ *   active_key_id: string,
+ *   rewritten: Array<{tenant_id, workspace_id, ref, version, from_key_id, to_key_id}>,
+ *   skipped: Array<{tenant_id, workspace_id, ref, version, key_id}>,
+ *   unreadable: Array<{tenant_id, workspace_id, ref, version, key_id}>
+ * }>}
+ */
+async function reencryptSecrets({ repository, keyring } = {}) {
+  assertRepository(repository);
+  assertKeyring(keyring);
+
+  // ---- Phase 1: classify the whole store. Nothing is written here. ----------
+  const listed = await repository.listSecrets();
+  if (listed === null || typeof listed !== 'object') {
+    refuse(
+      'SECRET_ROTATION_INVALID',
+      `listSecrets() returned ${listed === null ? 'null' : typeof listed} - an array or an async `
+      + 'iterable of records is required',
+      'return the rows; an empty store returns an empty array, never null.'
+    );
+  }
+
+  const plan = { rotate: [], skipped: [], unreadable: [] };
+  let index = 0;
+  for await (const record of listed) {
+    assertRecord(record, index);
+    index += 1;
+    // The blob names its own key, so classification needs no key at all — and no
+    // decryption, so no plaintext exists during this phase.
+    const { keyId } = parseBlob(record.blob);
+    const row = {
+      tenant_id: record.tenant_id,
+      workspace_id: record.workspace_id,
+      ref: record.ref,
+      version: record.version,
+      key_id: keyId
+    };
+    if (keyId === keyring.activeKeyId) plan.skipped.push(row);
+    else if (keyring.has(keyId)) plan.rotate.push({ row, blob: record.blob });
+    else plan.unreadable.push(row);
+  }
+
+  // ---- Phase 2: the only phase that writes. ---------------------------------
+  const rewritten = [];
+  for (const { row, blob } of plan.rotate) {
+    const context = {
+      tenant_id: row.tenant_id, workspace_id: row.workspace_id, ref: row.ref, version: row.version
+    };
+    try {
+      // The plaintext exists here and nowhere else: opened on one line, sealed on
+      // the next, out of scope after the write.
+      const value = open(blob, keyring, context);
+      // eslint-disable-next-line no-await-in-loop
+      await repository.rewriteSecret({ ...context }, seal(value, keyring, context));
+    } catch (error) {
+      throw new SecretCryptoError(
+        'SECRET_ROTATION_STOPPED',
+        `[conn-infra-secrets] Re-encryption stopped at ${identity(row)} - the store is now PARTLY `
+        + `rotated: ${rewritten.length} row(s) already carry "${keyring.activeKeyId}", this row and `
+        + 'everything after it still carry the key they had. The run is idempotent: fix the fault and '
+        + 'run it again - a row already rewritten is skipped, so a second run finishes exactly what is '
+        + `left. Do NOT drop any key from SECRETS_MASTER_KEYS meanwhile. Underlying fault: ${error.message}`,
+        { cause: error }
+      );
+    }
+    rewritten.push({ ...row, from_key_id: row.key_id, to_key_id: keyring.activeKeyId });
+  }
+
+  for (const entry of rewritten) delete entry.key_id;
+
+  return {
+    total: plan.rotate.length + plan.skipped.length + plan.unreadable.length,
+    active_key_id: keyring.activeKeyId,
+    rewritten,
+    skipped: plan.skipped,
+    unreadable: plan.unreadable
+  };
+}
+
+module.exports = { reencryptSecrets };

package/src/workspaceId.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * Which `workspace_id` can address a secret — the rule, in one place.
+ *
+ * Every secret belongs to ONE concrete workspace. `workspace_id = 0` is not a
+ * value, and the "tenant-wide" scope it used to stand for — projected under a
+ * `-` segment — is retired (owner decision 2026-09-03, confirmation
+ * secretbox-tenant-wide-scope-001, resolving the doc conflict in favour of
+ * api/docs/biz/20-tenancy/multitenancy.md §1.6).
+ *
+ * Reader and writer apply ONE rule, and this module is where it lives: it is
+ * exported from the package's index as part of the public API, so the writing
+ * side imports it rather than keeping a second copy (owner decision 2026-09-04 —
+ * one rail per concern, .claude/rules/change-discipline.md). A connector library
+ * cannot depend on a biz service, so the dependency runs this way round: the
+ * library owns the rule, its consumers import it.
+ *
+ * It sits in its own module rather than in `index.js` because `crypto.js` needs
+ * it too: the workspace id is one of the four fields of the bound context (AAD),
+ * and a context built with `'3'` on the writing side and `3` on the reading side
+ * would be two different contexts — the blob would simply stop opening. One rule,
+ * one normalization, both sides.
+ */
+
+/**
+ * @param {*} value
+ * @returns {number|null} the normalized id, or null if the value is unusable
+ */
+function normalizeWorkspaceId(value) {
+  if (typeof value !== 'number' && typeof value !== 'string') return null;
+  if (typeof value === 'string' && value.trim() === '') return null;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) return null;
+  return n;
+}
+
+module.exports = { normalizeWorkspaceId };