@onlineapps/conn-infra-secrets 1.1.0 → 3.0.0

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 };