[huangyiirene]

Fixes #7522

What was exposed

GET /api/settings/:namespace returned the plaintext of every encrypted setting in the namespace:

• in values.[key].value, and
• repeated once more inside every cascadeChain entry (global / tenant / user / env).

Both specifier flavours were affected — type: 'password' and an explicit encrypted: true.

Storage was never the problem, and the issue's root-cause reading held up against the tree I checked out: sys_setting.value is null, value_enc holds a sec_ handle, sys_secret holds the aes-256-gcm ciphertext. The leak was entirely on the way out. materialiseRow() (settings-service.ts:1870) dereferences the handle and decrypts; get() copies that plaintext into each chain entry (:1068 / :1082 / :1094); getNamespace() (:1118) returns it; and the GET handler in settings-routes.ts handed the payload straight to sendOk — no redaction anywhere on the path.

The endpoint requires setup.access, so this is defense-in-depth, not privilege escalation. It is still a real exposure: any operator or integration holding setup access — and any log, proxy, browser cache or HAR capture on that response path — received the cleartext of every secret in the namespace, which is exactly what the value_enc + sys_secret split exists to prevent.

What is now redacted

At the REST boundary only. The mask shape is not invented here — it reuses the convention ADR-0100 pins for encrypted fields on the generic CRUD path (SECRET_MASK in @objectstack/objectql, the read-mask + no-op-echoed-mask pair the records-forms.encrypted-field-behavior checklist item exercises):

• Read. A set secret is served as SETTINGS_SECRET_MASK — ••••••••, byte-identical to objectql's mask. An unset one stays null, so the redaction is presence-preserving and the console still renders "configured vs not configured". cascadeChain is masked entry by entry rather than dropped, so "global sets this, your user overrides it" still renders — only the values go.
• Write. A submitted value equal to the mask means "unchanged", so the key is dropped from the patch instead of being persisted as the mask's literal text. Scoped to secret keys: a plain setting whose value genuinely is eight bullets still writes verbatim.
• PUT's own response is redacted the same way. It carries resolved values too — including cascade entries the caller never submitted (an upper-scope secret it may not have set), so it is the same boundary.

source, locked, lockedReason and the 409 SETTINGS_LOCKED env-lock behaviour are untouched, and pinned by tests.

What deliberately still returns plaintext

SettingsService keeps decrypting. materialiseRow(), get(), getNamespace(), snapshotOf() and createClient() all still hand back real plaintext, because the mail / sms / storage / auth plugins read their credentials through exactly that path. A test pins that round-trip so this cannot later be "fixed" one layer down — which would break every in-process consumer.

The boundary, stated plainly: decryption is the service's job; not-emitting-it is the route's.

Where the encrypted-key set comes from

SettingsService.secretKeysOf(namespace) publishes the registry's own encryptedKeys set — literally the set setMany consults to decide what gets encrypted. The route reads that rather than re-deriving spec.encrypted || spec.type === 'password', because re-deriving the predicate at the boundary is how the two sides drift into "encrypted on write, cleartext on read". It throws UnknownNamespaceError for an unregistered namespace rather than answering an empty set: "I don't know this namespace" must never read as "nothing here is secret".

Verification

pnpm --filter @objectstack/service-settings test — 395 passed / 18 files, 10 of them new, all at the route level:

✓ GET /:ns leaks no ciphertext-backed cleartext — both flavours, value AND cascadeChain
✓ redaction is presence-preserving: an UNSET secret stays null, not a mask
✓ `source` and `locked` survive the redaction unchanged
✓ an env-locked secret is masked while `source: env` / `locked` / 409 SETTINGS_LOCKED are unchanged
✓ PUTting the echoed mask back is a NO-OP — the stored secret is not overwritten
✓ the echoed mask inside the read-shape {values:{k:{value}}} envelope is a no-op too
✓ a REAL new secret still writes, and the write RESPONSE is redacted too
✓ a non-encrypted key whose value genuinely IS the mask is written verbatim
✓ in-process consumers still receive REAL plaintext (createClient / snapshotOf)
✓ secretKeysOf reports both flavours and refuses an unknown namespace

The leak case is asserted whole-body (JSON.stringify(response) contains none of the three plaintexts, one of them seeded at global scope so cascadeChain carries a second ciphertext-backed entry) and per-surface, so a regression names which surface broke rather than just "a string appeared". The secrets are real ciphertext — LocalCryptoProvider + a sys_secret store, sec_ handles, the production code path.

Reverse verification — direction predicted before running. Took the route fix out with git checkout origin/main -- settings-routes.ts (never git stash) and re-ran: 6 of the 10 went red, and the 4 that stayed green are exactly those whose subject the route revert does not touch — the source/locked passthrough, the non-secret verbatim write, the in-process plaintext guard, and secretKeysOf (which lives in the service). Restored and re-ran green.

Type surface:

• tsc --noEmit -p packages/services/service-settings → 13 errors, the ledgered count in scripts/check-type-check-coverage.mjs, i.e. this change adds none. (One was introduced en route — InMemoryCryptoProvider is a value-only alias and cannot be spelled as a type — and fixed by using LocalCryptoProvider in the test.)
• Downstream consumer sweep, prefix direction (--filter '...@objectstack/service-settings' = the 9 packages that consume it, not its upstream deps): turbo run typecheck → 72 tasks successful, 72 total. No reverse type-verification is reported because the change is purely additive to the public type surface (a new module, a new method) — nothing was narrowed, so there is no key a rebuilt .d.ts should now reject.
• node scripts/check-nul-bytes.mjs → OK.

No objectui change is required: the mask is presence-preserving and the echoed-mask write is a no-op, so today's console keeps working unmodified.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 11, 2026 5:21am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-settings.

5 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services/service-settings)
• content/docs/kernel/runtime-services/index.mdx (via packages/services/service-settings)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services/service-settings)
• content/docs/plugins/packages.mdx (via @objectstack/service-settings)
• content/docs/protocol/kernel/config-resolution.mdx (via @objectstack/service-settings)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/service-settings)
• content/docs/releases/v9.mdx (via @objectstack/service-settings)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.