fix(service-settings): repoint sys_setting.value_enc on a secret rotation, and reap the retired ciphertext (#8030)

[huangyiirene]

Fixes#8030

The defect

A secondPUT of a new value for an encrypted setting key answered 200 with a correctly redacted body, advanced updated_at, wrote an audit row and inserted a genuinely new sys_secret row holding the new plaintext — and left sys_setting.value_enc pointing at the first handle. The effective secret never changed.

Every signal an administrator can see said the rotation landed. Rotating a leaked SMTP password or provider API key looked exactly like a rotation that worked, while the leaked credential stayed the one in force. The first write of any secret was correct, so it was invisible until the second.

Root cause — the filer's analysis held, verified end-to-end

sys_setting.value_enc (and updated_by) are declared readonly: true in packages/platform-objects/src/system/sys-setting.object.ts, and the engine strips author-declared read-only columns from a non-system caller's UPDATE payload (stripReadonlyFields, gated on if (!opCtx.context?.isSystem) in packages/objectql/src/engine.ts). SettingsService.upsertRow persisted through a plain, un-elevated engine.update, so the handle could never be repointed. The INSERT path is deliberately exempt from that strip (#3413) — exactly why the first write landed and every later one did not.

The engine's own warning names the fix:

Field 'value_enc' on 'sys_setting' is read-only: the caller-supplied value was DROPPED and the update is being COMMITTED WITHOUT IT — the call returns success while this column keeps its stored value (#2948). Server-side code that legitimately writes read-only columns … must declare itself trusted by passing { context: { isSystem: true } } on the write.

The fix — service side only, no cross-lane change

• upsertRow performs its UPDATE as a system write.SettingsService is a privileged writer: the manifest capability gate (assertPermitted), the env-lock / upper-scope-lock pre-flight and validatePatch have all run by then, and these are columns it owns rather than ones a caller forged. Same posture and same measured reason as ObjectQL.recomputeSummaries' elevation (crud-permission-matrix: an allowed member create of showcase_task returns 500 while the row is written (summary recompute runs under caller context) #7673).
• SettingsEngine.update gains a context member, and the IDataEngine adapter forwards it on both branches. The settings row write takes the multi one (its where is the composite (namespace, key, scope, user_id), never an id), so the by-id branch is the half that would rot unnoticed — it is pinned.
• ⚠️value_enc stays readonly: true. The elevation is scoped to this one write, so an external caller reaching sys_setting through the data layer still cannot repoint a secret handle. That flag is a security control; removing it would have been the wrong direction on this defect. There is a test that fails if someone removes it.

Nothing in packages/platform-objects or packages/objectql is touched — the STOP fork on the card did not fire.

Orphan sys_secret rows — reaped, not accepted

The row a rotated-away handle named is deleted once the repoint has committed. An orphan is a decryptable copy of exactly the credential the admin just retired, accumulating one per rotation (the filer measured 7 → 8 → 9 across three writes) — so the exposure grows with the hygiene we ask operators to practise. Nothing else can reference the handle: ids are minted per encrypt() call, value_enc is the only column that holds one, and the audit trail records digests rather than handles, so it stays readable after the ciphertext is gone.

The store's delete is optional (pre-existing fakes and the legacy inline-crypto path simply have none) and the call is best-effort: the new secret is already in force by then, so a failed cleanup is reported loudly, never raised.

Verification

Tests boot a real ObjectQL over the real SysSetting / SysSecret schemas and drive the real SettingsService through the real adapter — the four pieces the running server bolts together — so the verdict is about the engine's actual strip rule rather than about a fake written to match the fix.

Reverse-verification, with only the fix's two behavioural lines removed and everything else identical:

	rotation test
fix removed	6 failed / 6 passed — expected 'sec_d261eae…' not to be 'sec_d261eae…' at the second write, sys_secret 1 → 2
fix applied	12 passed

The 6 that stayed green with the fix removed are the ones that should: the first-write path, the readonly-for-external-callers pin, and the mask-echo no-op.

• service-settings suite: 413 passed / 20 files (was 401 / 19)
• tsc --noEmit in service-settings: clean (0 errors — the package graduated out of the DEBT ledger in service-settings has no typecheck script — turbo silently no-ops it, and ~5 test files carry pre-existing type errors behind the unwired gate #7925 and stays out)
• check-test-source-alias: OK, registry unchanged — @objectstack/objectql and @objectstack/core are aliased to source in a new vitest.config.ts rather than added to KNOWN_UNALIASED_TEST_IMPORTS
• check:engine-double-contract: OK — 166 pinned, 133 ledgered, 2 exempt (unchanged)
• eslint on the touched files: clean

Not regressed

• Mask-echo no-op ([security] GET /api/settings/:namespace returns encrypted setting values as plaintext — no redaction at the REST read boundary #7522 / PR fix(service-settings): redact encrypted setting values at the REST read boundary (#7522) #7554) — a PUT carrying •••••••• still leaves the stored ciphertext byte-identical; the key is dropped from the patch before the service sees it, so no write happens at all. Pinned.
• First-write path — byte-for-byte unchanged (the INSERT branch is not elevated).
• 409 SETTINGS_LOCKED for env-locked secrets — untouched; the write path's pre-flight runs before any of this.

---

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 12, 2026 2:07pm

[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.