@onlineapps/conn-infra-secrets 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog — @onlineapps/conn-infra-secrets
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+### 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).
+- **New blob layout** `format[1] | keyIdLen[1] | key_id | version[4] | iv[12] | authTag[16] | ciphertext`, with the bound context (AAD) `tenant_id | workspace_id | ref | version`. A blob lifted into another tenant, workspace, ref or version no longer opens. The previous layout is not read — a blob without the format byte is refused (owner decision 2026-09-03, `docs/governance/confirmations/secretbox-blob-format.md` 001).
+- `open()` requires the row's version and compares it with the blob's; the Redis projection reader, which has no version, uses the separately named `openWithDeclaredVersion()`.
+
+### Added
+
+- **`reencryptSecrets({ repository, keyring })`** (`src/rotation.js`) — rewrites every stored row that is not yet on the active key, through an injected store adapter (`listSecrets()` / `rewriteSecret(record, blob)`; this package owns no database). Idempotent; the whole store is classified before the first write; a row sealed with a key nobody holds is reported, never written, and does not stop the run. No secret value and no key material reaches its result or its messages.
+- **`checkReadability({ records, keyring })`** (`src/readability.js`) — the mandatory step before a key leaves the list: it OPENS every stored blob with the keys that would remain and reports every row that would not open, with the reason (`key_not_in_list`, `does_not_open`, `malformed_blob`). A blob that cannot be parsed is a finding, not an exception — the point is the complete list. `MasterKeyring.without(id)` builds the list a removal is checked against and refuses to drop the active key.
+- `loadMasterKeys()` + `MasterKeyring` (`activeKeyId`, `keyIds`, `has`, `keyFor`, `activeKey`, `without`), `bindingContext()`, `parseBlob()`, `SecretCryptoError`, and `MASTER_KEYS_ENV` — the one declaration of the configuration key's name and format.
+- `normalizeWorkspaceId` moved to `src/workspaceId.js` (the bound context needs the same rule as the projection key); it stays exported from the package index, unchanged.
+
+## [1.1.0] — 2026-08-29
+
+- Changelog started with this release; the history before it is in git (`git log -- shared/connector/conn-infra-secrets`).

package/README.md

@@ -1,17 +1,94 @@
+> Status: current
+> Owns: the resolution of `ctx.secrets.get(ref)` — reading the SecretBox Redis projection and decrypting it in-process
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/connector](../conn-orch-validator/manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `connector`: L-CONNECTOR-ENV
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/conn-infra-secrets
 
 Resolution connector for `ctx.secrets.get(ref)`. Reads the encrypted Redis
 projection written by `biz-meta` (SecretBox) and decrypts it in-process with the
 injected AES-256-GCM master key. Authoritative store (`oagen_meta.secret`) is owned
 by `biz-meta` and never touched here. Projection key contract:
-`state:meta:secret:<tenant>:<workspace|->:<ref>`.
+`state:meta:secret:<tenant>:<workspace>:<ref>`.
+
+**Every secret belongs to one concrete workspace.** A usable `workspace_id` is an
+integer >= 1 (as a number or its decimal string); `0`, `'0'`, `null` and an omitted
+value are all **refused** with `SECRET_SCOPE_MISSING`, before any Redis round trip.
+There is no tenant-wide scope and no `-` segment: `workspace_id = 0` is not a value
+(owner decision 2026-09-03,
+[`secretbox-tenant-wide-scope.md`](../../../docs/governance/confirmations/secretbox-tenant-wide-scope.md)
+001, resolving the doc conflict in favour of
+[`multitenancy.md`](../../../docs/biz/20-tenancy/multitenancy.md) §1.6). Reader and
+writer apply ONE rule, and this package owns it: `normalizeWorkspaceId` is exported
+(see **Public API** below) so the writing side imports it instead of keeping a second
+copy (owner decision 2026-09-04 — one rail per concern,
+[`change-discipline.md`](../../../../.claude/rules/change-discipline.md)). A key this
+reader refuses to build is therefore a key nothing writes.
+
+This package also owns the **sealing contract** (`src/crypto.js`): `seal()` /
+`encrypt()` + `sealBlob()` for the writing side, `open()` for every reader. Both
+directions in one module so seal→open is tested across the real boundary, not
+against a reimplementation.
+
+```
+format[1]=0x02 | keyIdLen[1] | key_id | version[4 BE] | iv[12] | authTag[16] | ciphertext
+AAD = "<tenant_id>|<workspace_id>|<ref>|<version>"
+```
+
+The blob **names the key that sealed it**, so a list of keys opens it without
+guessing, and the **bound context (AAD)** ties the ciphertext to the one row it
+belongs to: a blob lifted into another tenant, workspace, ref or version does not
+open, even with the right key (owner decision 2026-09-03,
+[`secretbox-blob-format.md`](../../../docs/governance/confirmations/secretbox-blob-format.md)
+001). The layout before `key_id` is **not read** — a blob without the format byte
+is refused, never guessed at; no reader for it survived the migration.
+
+## Master keys — a list, and a rotation that is a switch
+
+`SECRETS_MASTER_KEYS` is an **ordered list**, and this package owns both its name
+and its format (owner decision 2026-09-14,
+[`secretbox-master-keys.md`](../../../docs/governance/confirmations/secretbox-master-keys.md)
+001):
+
+```
+SECRETS_MASTER_KEYS="k3:<base64 32-byte key>,k2:<base64 32-byte key>"
+```
+
+- the **first** entry is the active key — every new write is sealed with it;
+- **every** entry decrypts, selected by the blob's own `key_id`;
+- a blob whose `key_id` is not in the list is **refused** (`SECRET_KEY_UNKNOWN`).
+  There is no "try every key" pass: it would be the silent fallback
+  [`architecture-principles.md`](../../../../.claude/rules/architecture-principles.md)
+  §3 forbids, and it would leave the readability check with nothing to measure.
+
+So a rotation is a **switch of the list**, not a jump: put the incoming key first,
+re-encrypt (`reencryptSecrets`), check that everything still opens without the
+outgoing key (`checkReadability`), and only then drop it. There is deliberately
+**no lazy re-encryption on write** — a row nobody writes to would stay on the old
+key forever, so "zero unreadable rows" would never hold. What that costs when it
+is skipped is measured: the August 2026 rotation replaced the key and left the
+rows alone, and six of ten rows of `oagen_meta.secret` were unreadable for two
+weeks before anyone noticed.
+
+The keys themselves are **injected, never read from the environment here**
+(principle 1, and the connector duty `L-CONNECTOR-ENV`): the consumer reads
+`SECRETS_MASTER_KEYS` and hands the string to `loadMasterKeys()` or to the
+connector's `masterKeys` option. `MASTER_KEYS_ENV` is exported so the name lives
+in one place.
 
 Canonical design: [`api/docs/architecture/secretbox.md`](../../../docs/architecture/secretbox.md).
 
 ## Usage (wired by ServiceWrapper)
 ```js
 const SecretsConnector = require('@onlineapps/conn-infra-secrets');
-const secrets = new SecretsConnector({ redisUrl: process.env.REDIS_URL, masterKeyBase64: process.env.SECRETS_MASTER_KEY });
+const secrets = new SecretsConnector({ redisUrl: process.env.REDIS_URL, masterKeys: process.env.SECRETS_MASTER_KEYS });
 await secrets.connect();
 // ContextBuilder facade calls: secrets.get(ref, { tenant_id, workspace_id })
 ```
@@ -19,10 +96,169 @@ await secrets.connect();
 Handlers only ever call `ctx.secrets.get(ref)`; the ContextBuilder facade injects
 the invocation scope.
 
+## Public API
+```js
+const SecretsConnector = require('@onlineapps/conn-infra-secrets');            // default = the connector
+const {
+  SecretsConnector, MockSecretsConnector, SecretResolutionError,
+  projectionKey, normalizeWorkspaceId, create,
+} = require('@onlineapps/conn-infra-secrets');
+
+// the sealing contract and the key list
+const {
+  loadMasterKeys, MasterKeyring, SecretCryptoError, MASTER_KEYS_ENV,
+  bindingContext, seal, open, openWithDeclaredVersion,
+  encrypt, decrypt, sealBlob, parseBlob,
+} = require('@onlineapps/conn-infra-secrets/src/crypto');
+```
+
+### `loadMasterKeys(spec) => MasterKeyring`
+Parses `SECRETS_MASTER_KEYS`. The keyring is immutable and answers
+`activeKeyId`, `keyIds`, `size`, `has(id)`, `keyFor(id)`, `activeKey()` and
+`without(id)` — the last one is the list a key removal is checked against, and it
+refuses to drop the active key. Every refusal names the problem and the fix, and
+**no message ever carries key material**.
+
+### `seal(value, keyring, context)` / `open(blob, keyring, context)`
+`context` is the row: `{ tenant_id, workspace_id, ref, version }`. `open()`
+compares the context's version with the blob's and refuses a mismatch — so
+renumbering a version is a re-encryption, the cost accepted in
+`secretbox-blob-format` 001.
+
+### `openWithDeclaredVersion(blob, keyring, { tenant_id, workspace_id, ref })`
+For the Redis projection, whose key (`…:<tenant>:<workspace>:<ref>`) carries no
+version: the version is taken from the blob and bound into the context with it.
+It is a separate name, not an optional argument, because it proves strictly less
+— the tenant, workspace and ref are still bound, the version is the blob's own
+claim.
+
+### `normalizeWorkspaceId(value) => number|null`
+The rule "which `workspace_id` can address a secret", in one place. Accepts an
+integer >= 1 as a number or as its decimal string and returns it **as a number**;
+every other value — `0`, `'0'`, negative, fractional, non-numeric, empty/blank
+string, `null`, `undefined`, boolean, `NaN`, `Infinity`, object, array — is
+unusable and yields `null`.
+
+It **never throws**: refusal is a return value, so each caller decides what
+refusing means. This connector turns it into `SECRET_SCOPE_MISSING` before any
+Redis round trip (`projectionKey`); a writer of the projection refuses to build
+the key at all. Import it — do not reimplement it: a second copy of this rule is
+a defect by default ([`change-discipline.md`](../../../../.claude/rules/change-discipline.md)
+§ One rail per concern).
+
+```js
+const { normalizeWorkspaceId } = require('@onlineapps/conn-infra-secrets');
+normalizeWorkspaceId(7);     // 7
+normalizeWorkspaceId('10');  // 10
+normalizeWorkspaceId('0');   // null  → the caller must refuse
+```
+
+## Re-encryption — `reencryptSecrets({ repository, keyring })`
+
+The step that makes the outgoing key droppable. It reads every stored record,
+rewrites the ones still on an old key under the **active** key, and reports the
+ones it cannot open.
+
+```js
+const { loadMasterKeys } = require('@onlineapps/conn-infra-secrets/src/crypto');
+const { reencryptSecrets } = require('@onlineapps/conn-infra-secrets/src/rotation');
+
+const result = await reencryptSecrets({
+  keyring: loadMasterKeys(process.env.SECRETS_MASTER_KEYS),
+  repository,   // the store adapter — see below
+});
+// { total, active_key_id, rewritten: [...], skipped: [...], unreadable: [...] }
+```
+
+**The store is injected** (principle 1): this package owns no database, and the
+adapter over `oagen_<service>.secret` belongs to the service that owns those rows.
+It has to provide exactly two methods:
+
+| method | contract |
+|---|---|
+| `listSecrets()` | every stored record `{ tenant_id, workspace_id, ref, version, blob }` — an array or an async iterable, so a store that streams need not materialize its table |
+| `rewriteSecret(record, blob)` | write the new blob onto **that same row and 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 |
+
+Properties, each pinned by a test:
+
+- **Idempotent** — a second run writes nothing; rows already on the active key are
+  skipped, so a run interrupted by a failing store is finished simply by running
+  it again.
+- **The whole store is classified before the first write** — a malformed record or
+  an unreadable blob refuses the run while nothing has been written, because a
+  half-rotated store answers wholly to no key.
+- **A row on a key nobody holds is reported, never written, and does not stop the
+  run** — it was already unreadable before the rotation started, and it needs its
+  value rewritten from its source. (The six such rows of `oagen_meta.secret` are
+  `biz-meta`'s data decision.)
+- **Nothing it returns or throws carries a secret value or key material.**
+
+## Readability — `checkReadability({ records, keyring })`
+
+The mandatory step **before a key is removed from the list**: it answers, for a
+given key list, whether every stored blob still opens.
+
+```js
+const { checkReadability } = require('@onlineapps/conn-infra-secrets/src/readability');
+
+const keyring = loadMasterKeys(process.env.SECRETS_MASTER_KEYS);
+const result = await checkReadability({ records, keyring: keyring.without('k1') });
+// { total, readable, unreadable: [{ tenant_id, workspace_id, ref, version, key_id, reason }] }
+// drop "k1" only while result.unreadable is empty
+```
+
+`records` are the same records `listSecrets()` yields. The check **opens** every
+blob rather than only comparing its `key_id`, so a row whose key is listed but
+whose blob is corrupt or bound to another context is reported too. A blob that
+cannot be parsed at all is a finding (`malformed_blob`), never an exception: the
+point is the complete list of what will not open. Nothing it returns carries a
+value or a key.
+
+The order of a rotation, then, with nothing left to remember:
+
+1. put the incoming key FIRST in `SECRETS_MASTER_KEYS`, keep the outgoing one;
+2. `reencryptSecrets(...)` — every row moves to the incoming key;
+3. `checkReadability({ records, keyring: keyring.without('<outgoing id>') })` —
+   it must report `unreadable: []`;
+4. only then remove the outgoing key from `SECRETS_MASTER_KEYS`.
+
+Step 3 is what was missing in August 2026, and skipping it is what left six rows
+of `oagen_meta.secret` sealed with a key that no longer exists anywhere.
+
 ## Errors (no fallbacks)
 - `SECRET_NOT_FOUND` — no projection for the ref/scope.
-- `SECRET_DECRYPT_FAILED` — master key mismatch or corrupted blob.
-- `SECRET_SCOPE_MISSING` / `SECRET_REF_INVALID` — bad call.
+- `SECRET_KEY_UNKNOWN` — the blob names a `key_id` that is not in
+  `SECRETS_MASTER_KEYS`. The row is still on a key this service does not hold:
+  put it back and re-encrypt, or rewrite the value.
+- `SECRET_DECRYPT_FAILED` — the blob does not open under the key it names:
+  corrupt, or sealed for another tenant, workspace or ref.
+- `SECRET_SCOPE_MISSING` — the scope cannot address one concrete secret: missing
+  `tenant_id`, or a `workspace_id` that is not a positive integer (`0`, `'0'`,
+  `null`, omitted).
+- `SECRET_REF_INVALID` — bad call.
+
+Every message opens with `[conn-infra-secrets]`, names the problem and ends with
+the fix — the format of `.claude/rules/architecture-principles.md` §5,
+`[Context] Problem - Expected/Fix`. `SECRET_DECRYPT_FAILED` additionally carries
+the `node:crypto` error as `cause`, which is what separates a wrong master key
+from a truncated blob; the other codes have no cause because nothing under them
+failed.
 
 ## Test
-`npm run test:unit` — decrypt round-trip, tamper/not-found, scope, mock.
+- `npm run test:unit` — the key list (parsing, refusals, immutability), seal/open
+  round trip against a frozen layout fixture built by an outside generator, the
+  bound context (a blob moved to another tenant / workspace / ref / version does
+  not open), key selection by `key_id` and the refusal of an unlisted one,
+  tamper/not-found paths, scope refusal, the exported `normalizeWorkspaceId`
+  contract, mock.
+- `npm run test:unit` (rotation/readability) — re-encryption and the readability
+  check against REAL crypto over an injected in-memory store: idempotence, the
+  classify-before-write order, the row on a dropped key, the failed write, and
+  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.

package/jest.integration.config.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Separate Jest runner for the integration tier: it carries the `globalSetup`
+ * that probes the live Redis and aborts the run when it is absent, so the tier
+ * can never report a result on an environment that cannot serve it.
+ *
+ * @see tests/integration/setup.js
+ */
+
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/integration/**/*.test.js'],
+  testTimeout: 30000,
+  globalSetup: './tests/integration/setup.js',
+  coverageDirectory: 'coverage-integration',
+  verbose: true
+};

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@onlineapps/conn-infra-secrets",
-  "version": "1.0.0",
+  "version": "2.0.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"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest",
-    "test:unit": "jest tests/unit"
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest --config=jest.integration.config.js"
   },
   "keywords": [
     "secrets",
@@ -23,7 +27,7 @@
     "jest": "^29.7.0"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=24.0.0 <25"
   },
   "publishConfig": {
     "access": "public",