feat(spec): refuse a credential in the mongo options passthrough (config.options.auth.password) at publish (#9040)

[os-zhuang]

Fixes#9040

Route ① — refuse at publish (the inherited #8082/#8337 direction)

config.options.auth.password was the FOURTH spelling of the inline credential (#7990 top-level key, #8082 URL userinfo, #8337 URL query params). Measured on origin/main @ 479ec31c9 before editing (premise re-probed, still valid): the config parsed green, the password persisted cleartext, redactDatasourceConfig('mongodb', …) served it back with redactedKeys: [] — and mongodb@7.5.0 transforms the block into MongoCredentials, so it genuinely authenticated.

The refusal set is a CLOSED measured list, not a heuristic scan (MONGO_OPTIONS_CREDENTIAL_PATHS in driver/common.zod.ts): a non-empty string options.auth.password. Why each candidate is in or out — every claim measured against mongodb@7.5.0, the client @objectstack/driver-mongodb spreads config.options into:

• auth.password — REFUSED.OPTIONS.auth resolves it into MongoCredentials (measured: c.options.credentials.password carries it verbatim); the binder remedy genuinely works and wins at connect (A bound external.credentialsRef is silently dropped on the DSN branches of the mysql and mongodb driver arms #8696's pin). Issue pathed at options.auth.password, code: 'custom', message naming the secret binder / sys_secret / external.credentialsRef — re-pathed under config.options.auth.password on the authored artefact (the publish door wraps every schema refusal as 422 INVALID_METADATA per the family's documented envelope; status does not exist at the schema layer — the sibling [Decision] URL-embedded credentials (user:password@host in driver config.url) remain a live cleartext door after #7990 — refuse at publish, or accept as residual risk? #8082/turso: ?authToken= in an authored config.url / config.syncUrl query string is credential material the #8082 userinfo refusal does not cover #8337 pins document the same).
• auth.username alone — NOT refused (dispatch fence, @objectstack/spec/data owns the userinfo grammar but exports only its password half — the mongo DSN arm cannot inject a bound credential without a username accessor #8876 asymmetry). Pinned accepted. (The client itself throws on a username-only auth block — its own loud contract, not this door's.)
• Empty auth.password — NOT refused (the passthrough twin of user:@host, [Decision] URL-embedded credentials (user:password@host in driver config.url) remain a live cleartext door after #7990 — refuse at publish, or accept as residual risk? #8082). Pinned.
• authMechanismProperties.AWS_SESSION_TOKEN — NOT refused: under authMechanism: 'MONGODB-AWS' the v7 client itself throws on it (MongoAPIError, measured); under any other mechanism nothing reads it. Refusing would be turso: ?authToken= in an authored config.url / config.syncUrl query string is credential material the #8082 userinfo refusal does not cover #8337's "speculative widening". Redacted on read instead.
• proxyPassword, tlsCertificateKeyFilePassword, key, passphrase — NOT refused: honoured client secrets (SOCKS5 auth, TLS key material) with NO binder slot — the binder injects exactly one secret (the login password), so a refusal would point at a remedy that cannot work and remove the only way to configure an authenticated proxy / passphrase-protected key. Turso-encryptionKey posture ([services half of #7990] Close the datasource/connector credential write/read paths: scrub getDatasource().config, fix the false "credential-stripped" claim, and write the stored-cleartext-rows migration story #8081 item 4). Redacted on read; the open at-rest half is filed as a finding (see below).
• Legitimate passthrough (replicaSet, tls, timeouts) — byte-identical pins, including the redacted round-trip shape (auth with only a username), which keeps an untouched "Save" on a legacy row working.

False-positive analysis for a generic deep key-name walk (the alternative the card allowed if strictly safer): it is not safer here — the client's OPTIONS table is a closed set, only the paths above resolve into secrets, and a name-walk would judge author-typed junk the client never reads while adding nothing over the measured list. Closed list chosen.

Composition with placeholderFreeDeep (PM-mechanism assumption, verified): both checks are independent superRefines on the same slot; a ${…} password reports BOTH issues at options.auth.password (pinned: exactly 2 issues, one naming #9040, one #8336). The wrapper's own semantics are unchanged.

Route ② — redaction, additive (measured cheap because the carry-forward machinery already generalizes)

• redactDatasourceConfig now drops the measured passthrough secret paths (table PASSTHROUGH_SECRET_PATHS, mongo-only, alias-resolved so legacy driver: 'mongo' rows scrub identically), reporting dotted redactedKeys (options.auth.password) — the exact shape the metadata write door's generic carryForwardRedactedValues already walks (probed: nested round-trip preserves the stored credential; a deleted container is never re-grafted; zero changes in metadata-protocol).
• restoreRedactedConfig (service-datasource) mirrors per leaf with the module's own narrow rule: restore only when the leaf's container exists in the patch and the patch does not speak to the leaf. Pinned: untouched Save keeps the credential; sibling-option edits keep it; deleting the auth block wins; a typed-in password wins and is refused by the write gate on its own merits; no aliasing back into the caller's patch object.
• The Migration story for stored cleartext datasource credentials: operator-initiated re-homing into sys_secret (blocked by the managed-schemaMode refusal) #8155 credential-migration planner refuses a stored passthrough-credential row with a per-row remedy (dropping only the nested leaf would leave an auth block the client refuses at construction, measured) — the same arm shape turso: ?authToken= in an authored config.url / config.syncUrl query string is credential material the #8082 userinfo refusal does not cover #8337 added for query-token rows.

Scope measurement (the card's question): is the door mongo-only?

Yes — measured, not assumed. postgres/mysql/turso/sqlite/sqlite-wasm/memory ship closed strictObject config contracts with no client-bound record slot; memory's initialData is seed DATA (deliberately unjudged — redacting a seeded row's own password field would corrupt served data). Pinned in the redaction suite (passthroughSecretPaths(driver) empty for every non-mongo builtin). No equally-open sibling door exists, so no shared rule is warranted; the helper still lives in driver/common.zod.ts beside credentialFreeUrl so a future passthrough joins the same mechanism.

ADR-0087 / changeset

Semantic entry 18.datasource-config-mongo-options-credential-refused (registry regenerated via gen:migration-registry); changeset minor for spec with BREAKING annotation + patch for service-datasource, following #8337's convention. No automatic rewrite, same reason as the three siblings (a source transform cannot encrypt into sys_secret; auto-dropping the leaf alone would brick the auth block).

Verification (union run at final commit e3b754e23)

• pnpm --filter @objectstack/spec test — 406 files / 10777 passed. pnpm --filter @objectstack/service-datasource test — 453 passed (includes A bound external.credentialsRef is silently dropped on the DSN branches of the mysql and mongodb driver arms #8696's bound-secret-dsn-branches precedence pin, untouched). pnpm --filter @objectstack/metadata-protocol test — 112 files / 1565 passed. pnpm --filter @objectstack/driver-mongodb test — 385 passed / 143 skipped (mongod-gated). Typecheck green on spec + service-datasource; examples validate green.
• Reverse verification (direction decided beforehand — write door only, red): mongo.zod.ts restored to origin/main ⇒ exactly the 3 write-door pins red (refusal, placeholder-composition, artefact re-path), 143 others green ⇒ restored from the committed branch, suite green again.
• Forward probe on rebuilt dist/: the issue's own snippet now answers success: false at options.auth.password, and redaction serves auth: { username } with redactedKeys: ['options.auth.password'].
• Gates: derived via scripts/pm/dispatch-gates.mjs against the actual diff — beyond the dispatch-named set it added docs-audit-scope, docs-redirects, objectui-changeset, quick-reference-counts, role-word, test-source-alias, adr-0087-registration, changeset-no-major, empty-changeset; ALL green, plus cross-package-test-inputs, doc-formula-expressions, merge-driver, spec-parsed-alias, type-source-resolution, dev-prereqs (green after full closure build — first red was stale-worktree, 45 unbuilt packages), nul-bytes, query-options-erasure, engine-double-contract, where-matcher, type-check-coverage, type-check-debt --re-measure (33 entries, none above measurement), and check:generated — all 13 artifacts up to date (api-surface, export-origins, references regenerated).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-datasource, @objectstack/spec.

106 hand-written doc(s) reference the affected code — list omitted above 15 rows. Re-derive: node scripts/docs-audit/affected-docs.mjs --json origin/main.

⛔ 7 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

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.