fix(spec): redact mongo CSFLE kmsProviders key material on datasource reads

[os-warren]

Fixes #13602

What

redactDatasourceConfig('mongodb', ...) served mongo CSFLE KMS key material inside the options passthrough back in cleartext with no redactedKeys entry. Five client-measured positions join passthroughSecretPaths in packages/spec/src/data/datasource-credential-redaction.ts, with the measurement quoted in the table docblock:

• options.autoEncryption.kmsProviders.aws.secretAccessKey
• options.autoEncryption.kmsProviders.aws.sessionToken
• options.autoEncryption.kmsProviders.azure.clientSecret
• options.autoEncryption.kmsProviders.gcp.privateKey
• options.autoEncryption.kmsProviders.local.key

Table rows only. The #13405 mirrored-spelling derivation is untouched and no new credential name spellings were invented — these are the client-measured residue the table exists for.

Premise measurement (#9040 discipline — measured, never inferred from documentation)

Instrumented new MongoClient(url, { ..., ...options }) — the exact spread @objectstack/driver-mongodb performs — against mongodb@7.5.0, with the autoEncryption record, the kmsProviders record and every family object wrapped in read-logging Proxies. Both states of the optional mongodb-client-encryption dependency were measured, and the answers differ:

• With mongodb-client-encryption installed (7.2.1, inside the pin's ^7.2.0 optional-peer range): construction reads every one of the five leaves — the kmsProviders record is BSON-serialized into the native MongoCrypt. Observed reads: aws.secretAccessKey, aws.sessionToken, azure.clientSecret, gcp.privateKey, local.key, plus the identity halves aws.accessKeyId, azure.tenantId, azure.clientId, gcp.email. connect() then proceeds into live CSFLE machinery (mongocryptd spawn attempt).
• Without it (the repo's own install state — the dependency is absent from the lockfile): the same construction throws MongoMissingDependencyError before reading any of the positions. The stored copy performs no function but sits cleartext at rest — the AWS_SESSION_TOKEN posture already on the table: a loud client failure does not make serving the secret back acceptable.

Boundary kept deliberately narrow: the identity halves the client also reads (aws.accessKeyId, azure.tenantId, azure.clientId, gcp.email) are not credential material (the #8876 asymmetry) and stay served; unmeasured neighbours (kmip.endpoint, keyVaultNamespace, schemaMap, bypassAutoEncryption) mirror no credential spelling, are not on the table, and are pinned untouched by a negative-control test.

Round-trip answer (the card's third question)

• An untouched Save keeps a working CSFLE config byte-identical. restoreRedactedConfig mirrors the redactor structurally — it computes the served projection from the stored row and grafts every stored leaf back where the patch still matches — so the new rows are covered by construction, with nothing to forget. Pinned end-to-end at the admin service door: read serves the config with the five leaves withheld and named in redactedConfigKeys; an untouched update writes the stored config back deep-equal to the original.
• The served projection handed straight to the client (restore bypassed) fails loudly, not silently. Measured with the dependency installed: construction throws TypeError: Failed to parse KMS provider aws: expected UTF-8 secretAccessKey (azure and gcp equivalents measured identically); local served as an empty object constructs, but encryption stays armed — the client proceeds into the mongocryptd path, and no silently-unencrypted operation was observed. Redaction therefore creates no silent-downgrade path, and no new write-back semantics were needed.

Clause ②: no

Table entries plus tests only. No accept/reject behaviour changes: the write door refuses and accepts exactly what it did before (these positions were and remain writable — the binder's one secret slot is the login password, the proxyPassword posture), and no public export was added, removed or re-typed.

Verification (all runs at HEAD 3520ba2, after the final commit)

• pnpm --filter @objectstack/spec exec vitest run src/data/datasource-credential-redaction.test.ts src/kernel/metadata-type-redaction.test.ts — Test Files 2 passed, Tests 47 passed.
• pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/datasource-config-redaction.test.ts — Tests 36 passed (includes the new CSFLE round-trip pin).
• Reverse verification, fix committed first: the redaction module was reverted to the branch base (mutation proven on disk — autoEncryption occurrence count 6 to 0), the new CSFLE pin went red exactly (1 failed, 36 passed; the negative control stayed green), then restored from HEAD with byte-identity proven (git diff HEAD empty; worktree blob hash equals the HEAD blob). The suite resolves relative src imports, so no dist build participates in either leg.
• pnpm --filter @objectstack/spec typecheck and pnpm --filter @objectstack/service-datasource typecheck — green; both edited test files confirmed inside their tsc programs via a listFiles probe (1 hit each).
• scripts/pm/dispatch-gates.mjs (no paths — changeset derived from merge-base; answer asserted for objectstack-ai/objectstack at commit 3520ba2) derived 46 families for this diff, path-matched plus convention-triggered test-file families. 44 PASS — including check:type-check-debt re-measure ("29 ledger entries re-measured, none above its recorded number"), check:authorable-surface, check:docs, check:engine-double-contract, check:where-matcher, check:cross-package-test-inputs. 2 declared PREREQUISITE NOT MET by their own exit-3 text (NOT MEASURED, not red): check-test-completeness (grades a saved CI turbo test log that does not exist locally) and check-half-states (needs repo-scoped REST reads; this session's gate answers 403 — CI-owned).
• Changeset: .changeset/csfle-kms-providers-redacted.md, @objectstack/spec patch.

Measurement scripts and full logs are excerpted in the report comment on #13602. Session: https://claude.ai/code/session_01PBjwYLS6BciTQW3c9xQiD2

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 6 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/authentication.mdx (via clientSecret (literal, a string literal in mongodb))
• content/docs/permissions/sso.mdx (via clientSecret (literal, a string literal in mongodb))
• content/docs/plugins/index.mdx (via clientSecret (literal, a string literal in mongodb))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via clientSecret (literal, a string literal in mongodb))

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.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 126 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json d7ca6dc77edc2e158fb31b24176e6bf2341f9d1b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from b14d242215f66c8a2e6a1698f313d8f72210de7b — the merge of head 3520ba2dac649ab533c3525d7b89ca82dce37e4e into base d7ca6dc77edc2e158fb31b24176e6bf2341f9d1b, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin b14d242215f66c8a2e6a1698f313d8f72210de7b && git checkout b14d242215f66c8a2e6a1698f313d8f72210de7b
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d7ca6dc77edc2e158fb31b24176e6bf2341f9d1b 3520ba2dac649ab533c3525d7b89ca82dce37e4e && git checkout -B drift-repro d7ca6dc77edc2e158fb31b24176e6bf2341f9d1b && git merge --no-ff 3520ba2dac649ab533c3525d7b89ca82dce37e4e

node scripts/docs-audit/affected-docs.mjs --json d7ca6dc77edc2e158fb31b24176e6bf2341f9d1b

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs d7ca6dc77edc2e158fb31b24176e6bf2341f9d1b → pass the list as
args.docs, on the commit named under Which tree this was computed on.