@onlineapps/conn-infra-secrets 1.1.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog — @onlineapps/conn-infra-secrets
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+## [3.0.0] — 2026-09-16
+
+### Changed — BREAKING
+
+- **The Redis credential and topology come from `redisUrl`, and from nothing else.** The constructor reads `username` (Redis 6 ACL), `password`, host, port and the database index off the URL — `redis://[user:password@]host:port[/db]`, `rediss://` for TLS — decoding percent-escapes exactly once. An absent userinfo means no AUTH at all: `username`/`password` are then not passed to ioredis, never as `''`, which would be sent as `AUTH ""`.
+  Measured reason (INFRA, dev, 2026-09-15 21:20Z): the constructor took `hostname`/`port` only and expected the password beside the URL, so a URL carrying userinfo lost it — ioredis connected without AUTH, the gateway went into a crash loop (RestartCount 51) and the dispatcher and ingest failed on their first secret read. `REDIS_URL` is the platform's one rail for this fact (INFRA-DOCS 2026-09-14; `service-common` 3.0.2 hands the whole URL to node-redis, `mq-client-core` 3.2.0 reads the credential off the URL), so a value beside it was a second rail — `.claude/rules/change-discipline.md` § One rail per concern.
+- **A `redisUrl` that is not a `redis:`/`rediss:` URL is refused at construction**, as is one without a host or without a port. The silent branch that treated such a value as the hostname and defaulted the port to `6379` is gone: it hardcoded topology (principle 2) behind a fallback (principle 3), and it is what let a misspelt value reach a live boot. No message echoes the URL or the refused value — both carry the password.
+
+### Removed
+
+- **`config.password`** — refused by name, not ignored (a retired option that is silently dropped leaves the caller believing a password reached the server). Four questions, `.claude/rules/change-discipline.md` § Removing: (1) it came to exist because the constructor read only host and port off the URL, so a Redis with `requirepass` needed the password from somewhere — `ServiceWrapper` began setting it on 2026-09-11; (2) no part of the concept carried it: the platform decision is that `REDIS_URL` carries endpoint AND credential, and it never sanctioned a second input; (3) after this change nothing reads it — the two callers that set it (`api/shared/connector/service-wrapper/src/ServiceWrapper.js`, `api_biz/ingest/scripts/lib/build-operator-context.js`) each re-derive the value from the very same URL, a copy of the parse rather than a second source; (4) the replacement is more conceptual — one rail, one parse, and a URL with userinfo can no longer lose its password without a word.
+- **`config.db`** — refused by name; the database index is the URL's path. Four questions: (1) it came to exist as `config.db || 0`, so a caller could select a database; (2) nothing in the concept carried it — no platform document declares a non-default database for the SecretBox projection; (3) zero callers pass a value: only `ServiceWrapper` forwards `secretsConfig.db`, which no service config declares (`api_biz/ingest/config/service/config.json` has `"secrets": { "enabled": true }`); (4) the path is more conceptual — the database belongs to the address, and `|| 0` additionally swallowed a malformed declaration into a 0 nobody asked for. With no path declared the connector passes no `db` at all and ioredis selects its own default, database 0 — named here rather than re-implemented.
+
+### Added
+
+- `tests/integration/redisAuthFromUrl.integration.test.js` — a throwaway `redis:7-alpine` with `requirepass` on an ephemeral loopback port (the shared dev cache runs without one and cannot answer this question): the happy path reads a real sealed secret back through an authenticated connection, the failure path shows the same URL without the password refused with `NOAUTH`, and the control case proves the server still required AUTH after the green run.
+
+### Changed — a failed `connect()` carries the server's verdict (d.566)
+
+`connect()` handed the caller ioredis's end-of-socket sentence — `Connection is closed.`,
+no context, no `cause`, no verdict — while the server's own answer reached `_lastError`
+and the log alone. Measured against a `redis:7-alpine --requirepass` on 2026-09-16: a URL
+without the password (`NOAUTH Authentication required.`), a URL with the wrong password
+(`WRONGPASS invalid username-password pair or user is disabled.`) and a port with no
+listener (`connect ECONNREFUSED …`) produced byte-identical caller errors. That is why dev
+incident B88 (gateway crash loop, RestartCount 51) could not be read from the error at all.
+
+The caller is now told which of two things happened:
+
+- the server **ANSWERED and refused** — `NOAUTH`, `WRONGPASS`, `NOPERM`. The message
+  quotes the server's sentence and names the credential in `REDIS_URL` as the fix, and the
+  server's error travels as `cause`.
+- the server **never answered** — the message says exactly that, quotes what the client
+  rejected with, and adds that a refused credential answers NOAUTH/WRONGPASS/NOPERM and is
+  reported as such, so this is not one. That error travels as `cause`.
+
+It is the rule `@onlineapps/mq-client-core` d.295 states for a broker refusal (403/530/406),
+on the same reasoning: an ANSWERED refusal is permanent, because the next attempt asks the
+same question and gets the same answer.
+
+So a refusal also **ends the attempts**, and a failed attempt takes its client with it.
+Measured on all three failure paths: ioredis was left in status `reconnecting` after
+`connect()` rejected, so a credential the server had already refused was asked again on a
+loop, and the connector — which never sets `connected` on a later reconnect — would never
+have used that socket anyway. A refusal on the `error` channel now disconnects the client
+at once, and every failed `connect()` drops it.
+
+Only the endpoint (`host:port`) is named in these messages, never the URL: this package
+keeps the parsed fields and drops the value precisely because the value carries the
+password.
+
+### Added (d.566)
+
+- `tests/unit/connectVerdict.test.js` — both sentences asserted whole, the `cause` as a
+  value, no part of the credential in either, the refusal that ends the attempts, and two
+  controls (an accepted `connect()` still resolves `true` and keeps its client; a
+  transport error after the connection is open is NOT treated as a refusal).
+- `tests/integration/redisAuthFromUrl.integration.test.js` grew the two failure paths this
+  change is about — a wrong password named `WRONGPASS` with no part of it echoed, and a
+  port with no listener reported as "no verdict" with `cause.code` `ECONNREFUSED` — and
+  its NOAUTH path now asserts the verdict the caller gets instead of `Connection is
+  closed.`. The error-message census moved 31 → 33.
+
+### Fixed — a store that comes back is read again (d.573)
+
+`connected` was written once, when `connect()` resolved, and never read off the client
+again. The connector therefore had no idea what the client was doing: a Redis that went
+away mid-run left the flag `true`, so `get()` handed the read to a client with no socket
+instead of naming the missing store — and nothing could ever put the flag back, because
+the reconnection ioredis performs on its own was not watched. One outage decided the fate
+of every secret read for the rest of the process's life.
+
+`connected` is now the client's READY state — socket open, AUTH and SELECT done — one rail
+with `@onlineapps/conn-base-cache` d.572: `ready` sets it, `close` and `end` take it down,
+the next `ready` puts it back. Every handler acts only for the client this connector still
+holds, so the verdict of d.566 stays exactly as terminal as it was: a client the server
+refused is discarded, and nothing it emits afterwards can put the connector back in
+service behind the caller's back.
+
+### Tests (d.573)
+
+Unit 177 → 182, integration 26 → 28. New `tests/unit/connectionLifecycle.test.js` asserts
+the state machine as values: the read that reaches the store answers `SECRET_NOT_FOUND`,
+the one after a `close` answers `SECRET_STORE_UNAVAILABLE` and never touches the client,
+and the flag through an outage reads `[true, false, true]` (it read `[true, true, true]`
+before the fix), with `end` as a second way down and a refusal that survives a `ready`
+from its discarded client as the control. New
+`tests/integration/reconnect.integration.test.js` asks a real server: its own
+`redis:7` container on a fixed loopback port, a value sealed and read back, `docker stop`
+→ `SECRET_STORE_UNAVAILABLE`, `docker start` → the same read succeeds, each step waited
+for on the client's own `close`/`ready` event rather than on a guessed delay, with a
+`WRONGPASS` refusal as the control that stays terminal.
+
+## [2.0.0] — 2026-09-14
+
+### 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,25 +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>` — tenant-wide is the `-` segment,
-and `workspace_id` `0` (the writer's `TENANT_WIDE`), `'0'`, `null` and omitted all
-resolve to it.
+`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, one
-layout `base64( iv[12] || authTag[16] || ciphertext )`. Both directions in one
-module so seal→open is tested across the real boundary, not against a
-reimplementation.
+`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 })
 ```
@@ -27,14 +96,187 @@ await secrets.connect();
 Handlers only ever call `ctx.secrets.get(ref)`; the ContextBuilder facade injects
 the invocation scope.
 
+**The Redis credential lives in the URL and nowhere else.** `redisUrl` carries the
+endpoint, the optional Redis 6 ACL user, the password and the database index —
+`redis://[user:password@]host:port[/db]`, `rediss://` for TLS — exactly as
+`service-common` and `mq-client-core` read it. Percent-encode a password that
+contains `@`, `:` or `/`. The options `password` and `db` beside the URL are
+**refused by name**: they were a second rail for a fact the URL already carries,
+and while they existed a URL with userinfo lost its password silently (INFRA, dev,
+2026-09-15: ioredis connected without AUTH, gateway crash loop, RestartCount 51).
+A value that is not a `redis:`/`rediss:` URL, or one without a host or a port, is
+refused at construction — this package declares no topology default, not even 6379.
+
+**A failed `connect()` says what the server answered.** A server that ANSWERED and
+refused the credential — `NOAUTH`, `WRONGPASS`, `NOPERM` — is permanent: the message
+quotes the server's sentence, names `REDIS_URL` as the fix, carries the original error
+as `cause`, and the attempts END there rather than looping on a question already
+answered. A server that never answered is reported as exactly that and may be retried.
+Only `host:port` appears in these messages; the URL carries the password.
+
+## 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` — seal/open round trip, byte compatibility with a blob
-  sealed by `biz-meta` own implementation, tamper/not-found/bad-key paths,
-  scope mapping, mock.
-- `npm run test:integration` — real Redis. Needs `REDIS_HOST` + `REDIS_PORT`
-  (dev stack: `REDIS_HOST=127.0.0.1 REDIS_PORT=33030`, container `api_node_cache`).
+- `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/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@onlineapps/conn-infra-secrets",
-  "version": "1.1.0",
+  "version": "3.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": "npm run test:unit && npm run test:integration",
     "test:unit": "jest tests/unit",
     "test:integration": "jest --config=jest.integration.config.js"
   },
@@ -24,7 +27,7 @@
     "jest": "^29.7.0"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=24.0.0 <25"
   },
   "publishConfig": {
     "access": "public",