@onlineapps/conn-infra-secrets 1.0.0 → 2.0.0

package/src/crypto.js

@@ -1,56 +1,531 @@
 'use strict';
 
 /**
- * Minimal AES-256-GCM open() for the secrets connector.
+ * AES-256-GCM sealing contract of the SecretBox — this module owns it.
  *
- * Deliberately a small, self-contained copy of the sealing contract owned by
- * api_secrets (`src/lib/crypto.js`) — the two packages cannot import each other.
- * Blob layout MUST stay identical: base64( iv[12] || authTag[16] || ciphertext ).
- * See api/docs/architecture/secretbox.md §4.
+ * Both directions live here: `seal()`/`encrypt()` for the writer (biz-meta) and
+ * `open()` for every reader (`ctx.secrets.get(ref)`). One owner means seal→open
+ * is exercised across the real boundary in this package's tests instead of each
+ * side testing against its own reimplementation of the other.
+ *
+ * ## The blob names its key and its row
+ *
+ *   format[1]=0x02 | keyIdLen[1] | key_id | version[4 BE] | iv[12] | tag[16] | ciphertext
+ *   AAD = utf8("<tenant_id>|<workspace_id>|<ref>|<version>")
+ *
+ * Two owner decisions meet in that layout:
+ *
+ * - `secretbox-blob-format` 001 (2026-09-03) — the blob carries `key_id`, the
+ *   bound context is `tenant_id | workspace_id | ref | version`, and no reader of
+ *   the previous format survives the migration: a blob without the format byte
+ *   is refused, never guessed at.
+ * - `secretbox-master-keys` 001 (2026-09-14) — the library holds an ORDERED LIST
+ *   of master keys (`SECRETS_MASTER_KEYS`). 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 whose `key_id` is not in the list is REFUSED. There is deliberately no
+ *   "try every key" pass: it would be the silent fallback §3 of
+ *   architecture-principles.md forbids, and it would leave the readability check
+ *   (src/readability.js) with nothing to measure — a key could be dropped from the
+ *   list and rows would still open by accident, which is how the August 2026
+ *   rotation lost six rows of `oagen_meta.secret` for two weeks.
+ *
+ * ### Why the version travels inside the blob
+ *
+ * The AAD binds the row's `version`, and the two readers know it from different
+ * places. A tool reading the authoritative store has the `version` column and
+ * passes it: `open()` compares it with the blob's own and refuses a mismatch, so
+ * renumbering a version is a re-encryption (the cost accepted in `secretbox-blob-
+ * format` 001). The Redis projection key is
+ * `state:meta:secret:<tenant>:<workspace>:<ref>` — no version in it — so the
+ * projection reader has no independent version to pass and uses
+ * `openWithDeclaredVersion()`, which takes it from the blob. Two named entry
+ * points rather than one optional argument: each says out loud where its version
+ * came from, and therefore what it does and does not prove.
+ *
+ * Keys are always injected, never read from `process.env` here: principle 1 (DI)
+ * and the connector duty L-CONNECTOR-ENV. `MASTER_KEYS_ENV` below is the ONE
+ * declaration of the variable's name and format; consumers read the variable and
+ * hand the string to `loadMasterKeys()`.
  */
 
 const crypto = require('crypto');
+const { normalizeWorkspaceId } = require('./workspaceId');
 
 const ALGORITHM = 'aes-256-gcm';
 const KEY_BYTES = 32;
 const IV_BYTES = 12;
 const AUTH_TAG_BYTES = 16;
 
-function loadMasterKey(masterKeyBase64) {
-  if (typeof masterKeyBase64 !== 'string' || masterKeyBase64.length === 0) {
-    throw new Error(
-      '[conn-infra-secrets] Missing master key - base64-encoded 32-byte key required. ' +
-      'Fix: set SECRETS_MASTER_KEY (or pass explicit key).'
+/** Blob format marker. 1 was the pre-`key_id` layout and is not read (see above). */
+const BLOB_FORMAT = 2;
+
+/** The ONE declaration of the configuration key that carries the list. */
+const MASTER_KEYS_ENV = 'SECRETS_MASTER_KEYS';
+
+/**
+ * `SECRETS_MASTER_KEYS=<key_id>:<base64 32-byte key>[,<key_id>:<key>…]`
+ *
+ * Neither separator can occur inside a base64 key, so the spec parses without
+ * escaping; a `key_id` is restricted to the same alphabet for the same reason,
+ * and because it is written into every blob.
+ */
+const ENTRY_SEPARATOR = ',';
+const ID_SEPARATOR = ':';
+const KEY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** The AAD's field separator — refused inside a `ref` so the context is unambiguous. */
+const CONTEXT_SEPARATOR = '|';
+
+const SPEC_SHAPE = `${MASTER_KEYS_ENV}="<key_id>:<base64 32-byte key>[,<key_id>:<key>]" `
+  + '(the FIRST entry is the active one, the one every new write is sealed with)';
+
+/**
+ * Every refusal this module raises carries a machine code, so a caller can react
+ * to "this key is not in my list" differently from "this blob is corrupt".
+ */
+class SecretCryptoError extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = 'SecretCryptoError';
+    this.code = code;
+  }
+}
+
+/** An ordered, immutable list of master keys. First seals, all open. */
+class MasterKeyring {
+  /**
+   * @param {Array<{ keyId: string, key: Buffer }>} entries ordered, already validated
+   */
+  constructor(entries) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new SecretCryptoError(
+        'SECRET_KEYS_INVALID',
+        `[conn-infra-secrets] Empty master key list - at least one key is required, because the first entry is `
+        + `the key every new write is sealed with. Fix: build the keyring with loadMasterKeys(${MASTER_KEYS_ENV}).`
+      );
+    }
+    this._entries = entries.map(({ keyId, key }) => Object.freeze({ keyId, key }));
+    this._byId = new Map(this._entries.map((e) => [e.keyId, e.key]));
+    Object.freeze(this._entries);
+    Object.freeze(this);
+  }
+
+  /** The key every new write is sealed with — the first in the declared order. */
+  get activeKeyId() { return this._entries[0].keyId; }
+
+  /** A copy: the list a keyring holds cannot be widened after it is loaded. */
+  get keyIds() { return this._entries.map((e) => e.keyId); }
+
+  get size() { return this._entries.length; }
+
+  has(keyId) { return this._byId.has(keyId); }
+
+  activeKey() { return this._entries[0].key; }
+
+  /**
+   * @param {string} keyId as written in the blob
+   * @returns {Buffer} the 32 raw bytes
+   * @throws {SecretCryptoError} SECRET_KEY_UNKNOWN — never a "try them all" pass
+   */
+  keyFor(keyId) {
+    const key = this._byId.get(keyId);
+    if (key === undefined) {
+      throw new SecretCryptoError(
+        'SECRET_KEY_UNKNOWN',
+        `[conn-infra-secrets] Unknown master key id "${keyId}" - the blob was sealed with a key that is not in `
+        + `${MASTER_KEYS_ENV}, which holds ${this.keyIds.join(', ')}. `
+        + `Fix: put that key back into ${MASTER_KEYS_ENV} and re-encrypt the rows still on it `
+        + '(reencryptSecrets), or rewrite the value from its source. A key is only ever removed from '
+        + 'the list after checkReadability() reports zero unreadable rows without it.'
+      );
+    }
+    return key;
+  }
+
+  /**
+   * The same list without one key — what a key removal is checked against.
+   * @param {string} keyId
+   * @returns {MasterKeyring}
+   */
+  without(keyId) {
+    if (!this.has(keyId)) {
+      throw new SecretCryptoError(
+        'SECRET_KEY_UNKNOWN',
+        `[conn-infra-secrets] Cannot drop key id "${keyId}" - it is not in the list, which holds `
+        + `${this.keyIds.join(', ')}. Fix: name one of those, or leave the list as it is.`
+      );
+    }
+    if (keyId === this.activeKeyId) {
+      throw new SecretCryptoError(
+        'SECRET_KEYS_INVALID',
+        `[conn-infra-secrets] Cannot drop the active key "${keyId}" - it is the first entry, the key every new `
+        + 'write is sealed with, so a list without it could not write at all. '
+        + `Fix: put the incoming key first in ${MASTER_KEYS_ENV}, re-encrypt, and only then drop the `
+        + 'outgoing one.'
+      );
+    }
+    return new MasterKeyring(this._entries.filter((e) => e.keyId !== keyId).map((e) => ({ ...e })));
+  }
+}
+
+function refuseSpec(problem, detail) {
+  throw new SecretCryptoError(
+    'SECRET_KEYS_INVALID',
+    `[conn-infra-secrets] Invalid ${MASTER_KEYS_ENV} - ${problem}. Expected ${SPEC_SHAPE}. Fix: ${detail}`
+  );
+}
+
+/**
+ * Parse the declared list into a keyring. No key material ever reaches a message.
+ *
+ * @param {string} spec the value of SECRETS_MASTER_KEYS
+ * @returns {MasterKeyring}
+ * @throws {SecretCryptoError} SECRET_KEYS_INVALID
+ */
+function loadMasterKeys(spec) {
+  if (typeof spec !== 'string' || spec.trim() === '') {
+    refuseSpec(
+      `the value is ${spec === null ? 'null' : typeof spec === 'string' ? 'blank' : typeof spec}`,
+      `set ${MASTER_KEYS_ENV} in env-active/*.env, or pass the string explicitly.`
+    );
+  }
+
+  const entries = [];
+  const seen = new Set();
+
+  for (const rawEntry of spec.split(ENTRY_SEPARATOR)) {
+    const entry = rawEntry.trim();
+    if (entry === '') {
+      refuseSpec('an entry is empty', `remove the stray "${ENTRY_SEPARATOR}" from the list.`);
+    }
+    const at = entry.indexOf(ID_SEPARATOR);
+    if (at < 0) {
+      refuseSpec(
+        'an entry carries no key id',
+        `write every entry as <key_id>${ID_SEPARATOR}<base64 key>; the id is what the blob records, `
+        + 'so a key without one cannot be selected on read.'
+      );
+    }
+    const keyId = entry.slice(0, at).trim();
+    const material = entry.slice(at + 1).trim();
+
+    if (!KEY_ID_PATTERN.test(keyId)) {
+      refuseSpec(
+        `the key id "${keyId}" is not usable`,
+        'use 1-64 characters of [A-Za-z0-9._-] starting with a letter or digit; the id is written into '
+        + 'every blob, so it has to be stable and printable.'
+      );
+    }
+    if (seen.has(keyId)) {
+      refuseSpec(
+        `the key id "${keyId}" appears twice`,
+        'give every key its own id - two keys under one id cannot both be selected, and the blobs would '
+        + 'name a key nobody can identify.'
+      );
+    }
+    if (material === '') {
+      refuseSpec(`the key id "${keyId}" has no key`, 'write the base64-encoded 32-byte key after the colon.');
+    }
+    const key = Buffer.from(material, 'base64');
+    if (key.length !== KEY_BYTES) {
+      refuseSpec(
+        `the key "${keyId}" decodes to ${key.length} bytes, expected ${KEY_BYTES}`,
+        'generate it with `openssl rand -base64 32`.'
+      );
+    }
+
+    seen.add(keyId);
+    entries.push({ keyId, key });
+  }
+
+  return new MasterKeyring(entries);
+}
+
+function assertKeyring(keyring) {
+  if (!(keyring instanceof MasterKeyring)) {
+    throw new SecretCryptoError(
+      'SECRET_KEYS_INVALID',
+      `[conn-infra-secrets] Missing keyring - a MasterKeyring is required, got `
+      + `${keyring === null ? 'null' : typeof keyring}. `
+      + `Fix: pass loadMasterKeys(${MASTER_KEYS_ENV}); a bare key Buffer is not accepted, because the `
+      + 'blob has to record WHICH key sealed it.'
+    );
+  }
+}
+
+function refuseContext(problem, detail) {
+  throw new SecretCryptoError(
+    'SECRET_CONTEXT_INVALID',
+    `[conn-infra-secrets] Invalid bound context - ${problem}. Expected { tenant_id, workspace_id, ref, version } `
+    + 'naming the ONE row this value belongs to (owner decision 2026-09-03, '
+    + `api/docs/governance/confirmations/secretbox-blob-format.md 001). Fix: ${detail}`
+  );
+}
+
+/**
+ * The bound context (AAD), in one place: `tenant | workspace | ref | version`.
+ *
+ * Normalizing here is what keeps writer and reader on one string: a workspace id
+ * arrives as a number from one driver and as its decimal string from another, and
+ * two spellings would seal a blob nobody can open.
+ *
+ * @param {{ tenant_id: number|string, workspace_id: number|string, ref: string, version: number|string }} context
+ * @returns {string}
+ */
+function bindingContext(context) {
+  if (context === null || typeof context !== 'object') {
+    refuseContext(
+      `got ${context === null ? 'null' : typeof context}`,
+      'pass the four fields of the row the secret belongs to.'
+    );
+  }
+  const { tenant_id: tenantId, workspace_id: workspaceId, ref, version } = context;
+
+  if (tenantId === undefined || tenantId === null || String(tenantId).trim() === '') {
+    refuseContext('tenant_id is missing', 'pass scope.tenant_id from the operation context.');
+  }
+  const workspace = normalizeWorkspaceId(workspaceId);
+  if (workspace === null) {
+    refuseContext(
+      `workspace_id "${workspaceId}" is not a positive integer`,
+      '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).'
+    );
+  }
+  if (typeof ref !== 'string' || ref.trim() === '') {
+    refuseContext('ref is missing or blank', 'pass the secret ref, not the secret value.');
+  }
+  if (ref.includes(CONTEXT_SEPARATOR)) {
+    refuseContext(
+      `the ref "${ref}" contains "${CONTEXT_SEPARATOR}"`,
+      `rename the ref: "${CONTEXT_SEPARATOR}" separates the four fields of the bound context, so a ref `
+      + 'carrying one could bind two different rows to the same context.'
+    );
+  }
+  const versionNumber = Number(version);
+  if (typeof version === 'boolean' || version === null || version === undefined
+      || String(version).trim() === '' || !Number.isInteger(versionNumber) || versionNumber < 1) {
+    refuseContext(
+      `version "${version}" is not a positive integer`,
+      'pass the row\'s version column; it is part of the bound context, so renumbering a version is a '
+      + 're-encryption (the cost accepted in secretbox-blob-format 001).'
+    );
+  }
+
+  return [String(tenantId).trim(), String(workspace), ref, String(versionNumber)].join(CONTEXT_SEPARATOR);
+}
+
+/** The version a context names, normalized — the blob header stores it as uint32. */
+function contextVersion(context) {
+  return Number(bindingContext(context).split(CONTEXT_SEPARATOR).pop());
+}
+
+/**
+ * Encrypt to the parts the authoritative store keeps in its own columns.
+ *
+ * @param {string} plaintext
+ * @param {MasterKeyring} keyring first entry seals
+ * @param {Object} context the bound context, see bindingContext()
+ * @returns {{ keyId: string, version: number, iv: Buffer, authTag: Buffer, ciphertext: Buffer }}
+ */
+function encrypt(plaintext, keyring, context) {
+  if (typeof plaintext !== 'string') {
+    throw new SecretCryptoError(
+      'SECRET_PLAINTEXT_INVALID',
+      `[conn-infra-secrets] seal requires a string plaintext - Expected the secret value as a string, got `
+      + `${plaintext === null ? 'null' : typeof plaintext}. Fix: stringify the value before sealing it.`
     );
   }
-  const key = Buffer.from(masterKeyBase64, 'base64');
-  if (key.length !== KEY_BYTES) {
-    throw new Error(
-      `[conn-infra-secrets] Invalid master key length - decoded ${key.length} bytes, expected ${KEY_BYTES}.`
+  assertKeyring(keyring);
+  const aad = Buffer.from(bindingContext(context), 'utf8');
+  const version = contextVersion(context);
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(ALGORITHM, keyring.activeKey(), iv, { authTagLength: AUTH_TAG_BYTES });
+  cipher.setAAD(aad);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  return { keyId: keyring.activeKeyId, version, iv, authTag: cipher.getAuthTag(), ciphertext };
+}
+
+/**
+ * Concatenate the parts into the wire blob (Redis projection).
+ * @param {{ keyId: string, version: number, iv: Buffer, authTag: Buffer, ciphertext: Buffer }} parts
+ * @returns {string} base64
+ */
+function sealBlob({ keyId, version, iv, authTag, ciphertext }) {
+  if (!KEY_ID_PATTERN.test(String(keyId))) {
+    throw new SecretCryptoError(
+      'SECRET_BLOB_INVALID',
+      `[conn-infra-secrets] Cannot seal a blob under key id "${keyId}" - Expected 1-64 characters of `
+      + '[A-Za-z0-9._-]. Fix: seal with a keyring from loadMasterKeys(), which refuses any other id.'
+    );
+  }
+  if (!Number.isInteger(version) || version < 1 || version > 0xffffffff) {
+    throw new SecretCryptoError(
+      'SECRET_BLOB_INVALID',
+      `[conn-infra-secrets] Cannot seal a blob for version "${version}" - Expected a positive 32-bit integer, `
+      + 'the row version the value belongs to. Fix: pass the parts encrypt() returned, unchanged.'
     );
   }
-  return key;
+  const id = Buffer.from(String(keyId), 'utf8');
+  const versionBytes = Buffer.alloc(4);
+  versionBytes.writeUInt32BE(version);
+  return Buffer.concat([
+    Buffer.from([BLOB_FORMAT]), Buffer.from([id.length]), id, versionBytes, iv, authTag, ciphertext
+  ]).toString('base64');
 }
 
 /**
+ * Encrypt straight to the wire blob (`encrypt` + `sealBlob`).
+ * @returns {string} base64
+ */
+function seal(plaintext, keyring, context) {
+  return sealBlob(encrypt(plaintext, keyring, context));
+}
+
+function refuseBlob(problem, detail) {
+  throw new SecretCryptoError(
+    'SECRET_BLOB_INVALID',
+    `[conn-infra-secrets] Unreadable sealed blob - ${problem}. Fix: ${detail}`
+  );
+}
+
+/**
+ * Split a wire blob into its parts WITHOUT decrypting it — this is what tells a
+ * caller which key it needs before it needs it.
+ *
  * @param {string} blobBase64
- * @param {Buffer} key
- * @returns {string} plaintext
+ * @returns {{ keyId: string, version: number, iv: Buffer, authTag: Buffer, ciphertext: Buffer }}
+ * @throws {SecretCryptoError} SECRET_BLOB_INVALID
  */
-function open(blobBase64, key) {
+function parseBlob(blobBase64) {
   if (typeof blobBase64 !== 'string' || blobBase64.length === 0) {
-    throw new Error('[conn-infra-secrets] open requires a non-empty base64 blob.');
+    throw new SecretCryptoError(
+      'SECRET_BLOB_INVALID',
+      `[conn-infra-secrets] open requires a non-empty base64 blob - Expected the sealed value read from the `
+      + 'SecretBox. Fix: check that the row or projection key exists and holds the sealed blob.'
+    );
   }
-  const blob = Buffer.from(blobBase64, 'base64');
-  if (blob.length < IV_BYTES + AUTH_TAG_BYTES) {
-    throw new Error('[conn-infra-secrets] Blob too short - not a valid sealed secret.');
+  const raw = Buffer.from(blobBase64, 'base64');
+  if (raw.length < 2) {
+    refuseBlob(`the blob is ${raw.length} byte(s) long`, 'it is truncated; re-read it from the store.');
   }
-  const iv = blob.subarray(0, IV_BYTES);
-  const authTag = blob.subarray(IV_BYTES, IV_BYTES + AUTH_TAG_BYTES);
-  const ciphertext = blob.subarray(IV_BYTES + AUTH_TAG_BYTES);
-  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
-  decipher.setAuthTag(authTag);
-  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+  if (raw[0] !== BLOB_FORMAT) {
+    refuseBlob(
+      `the blob opens with format byte 0x${raw[0].toString(16).padStart(2, '0')}, expected `
+      + `0x${BLOB_FORMAT.toString(16).padStart(2, '0')}`,
+      'this is not a SecretBox blob of the current format. The pre-key_id layout is not read - no '
+      + 'reader for it survived the migration (owner decision 2026-09-03, '
+      + 'api/docs/governance/confirmations/secretbox-blob-format.md 001). Rewrite the value with '
+      + 'set-secret, or run the re-encryption tool.'
+    );
+  }
+  const idLength = raw[1];
+  if (idLength < 1) {
+    refuseBlob('the blob declares a zero-length key id', 'rewrite the value; it names no key.');
+  }
+  const fixed = 2 + idLength + 4 + IV_BYTES + AUTH_TAG_BYTES;
+  if (raw.length < fixed) {
+    refuseBlob(
+      `the blob is ${raw.length} bytes, shorter than the ${fixed} bytes its own header describes`,
+      'it is truncated; re-read it from the store, or rewrite the value.'
+    );
+  }
+  const keyId = raw.subarray(2, 2 + idLength).toString('utf8');
+  if (!KEY_ID_PATTERN.test(keyId)) {
+    refuseBlob(`the blob declares an unusable key id "${keyId}"`, 'rewrite the value; the blob is corrupt.');
+  }
+  let offset = 2 + idLength;
+  const version = raw.readUInt32BE(offset); offset += 4;
+  const iv = raw.subarray(offset, offset + IV_BYTES); offset += IV_BYTES;
+  const authTag = raw.subarray(offset, offset + AUTH_TAG_BYTES); offset += AUTH_TAG_BYTES;
+  return { keyId, version, iv, authTag, ciphertext: raw.subarray(offset) };
+}
+
+/**
+ * Decrypt the parts of one sealed value.
+ *
+ * @param {{ keyId: string, version: number, iv: Buffer, authTag: Buffer, ciphertext: Buffer }} parts
+ * @param {MasterKeyring} keyring
+ * @param {Object} context the bound context; its version must be the one the parts carry
+ * @returns {string} plaintext
+ */
+function decrypt(parts, keyring, context) {
+  assertKeyring(keyring);
+  if (parts === null || typeof parts !== 'object') {
+    refuseBlob(
+      `got ${parts === null ? 'null' : typeof parts} instead of the sealed parts`,
+      'pass what parseBlob() or encrypt() returned.'
+    );
+  }
+  const expected = contextVersion(context);
+  if (parts.version !== expected) {
+    throw new SecretCryptoError(
+      'SECRET_VERSION_MISMATCH',
+      `[conn-infra-secrets] Version mismatch - the blob was sealed for version ${parts.version}, the context `
+      + `names version ${expected}. The version is part of the bound context, so the two have to be the `
+      + 'same value. Fix: read the version from the same row as the blob; if the row was renumbered, '
+      + 're-encrypt it (renumbering a version is a re-encryption - secretbox-blob-format 001).'
+    );
+  }
+  const key = keyring.keyFor(parts.keyId);
+  const aad = Buffer.from(bindingContext(context), 'utf8');
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, parts.iv, { authTagLength: AUTH_TAG_BYTES });
+  decipher.setAAD(aad);
+  decipher.setAuthTag(parts.authTag);
+  return Buffer.concat([decipher.update(parts.ciphertext), decipher.final()]).toString('utf8');
+}
+
+/**
+ * Open a wire blob against a context that names the version — the reader that
+ * has the authoritative row, so the blob's version is CHECKED, not trusted.
+ *
+ * @param {string} blobBase64
+ * @param {MasterKeyring} keyring
+ * @param {{ tenant_id, workspace_id, ref, version }} context
+ * @returns {string} plaintext
+ */
+function open(blobBase64, keyring, context) {
+  assertKeyring(keyring);
+  return decrypt(parseBlob(blobBase64), keyring, context);
+}
+
+/**
+ * Open a wire blob whose version the caller cannot know — the Redis projection
+ * reader, whose key is `…:<tenant>:<workspace>:<ref>` with no version in it.
+ *
+ * The version is taken from the blob and bound into the context, so the blob is
+ * still tied to its tenant, workspace and ref; what this entry point does NOT
+ * prove is that the version is the one the authoritative row carries. Nothing on
+ * this path could prove it, and saying so here is the point of having two names.
+ *
+ * @param {string} blobBase64
+ * @param {MasterKeyring} keyring
+ * @param {{ tenant_id, workspace_id, ref }} scope
+ * @returns {string} plaintext
+ */
+function openWithDeclaredVersion(blobBase64, keyring, scope) {
+  assertKeyring(keyring);
+  const parts = parseBlob(blobBase64);
+  return decrypt(parts, keyring, { ...scope, version: parts.version });
 }
 
-module.exports = { loadMasterKey, open, ALGORITHM, KEY_BYTES, IV_BYTES, AUTH_TAG_BYTES };
+module.exports = {
+  MasterKeyring,
+  SecretCryptoError,
+  loadMasterKeys,
+  bindingContext,
+  encrypt,
+  decrypt,
+  sealBlob,
+  seal,
+  parseBlob,
+  open,
+  openWithDeclaredVersion,
+  MASTER_KEYS_ENV,
+  ALGORITHM,
+  KEY_BYTES,
+  IV_BYTES,
+  AUTH_TAG_BYTES,
+  BLOB_FORMAT,
+  CONTEXT_SEPARATOR
+};