fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors - #28607

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 7 documentable anchor(s).

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

• content/docs/data-modeling/drivers.mdx (via connectionString (literal, a string literal in TOP_LEVEL_CREDENTIAL_KEYS))
• content/docs/deployment/cli.mdx (via unrecognized_keys (literal, a string literal in assertNoTopLevelCredential))
• content/docs/protocol/objectql/types.mdx (via unrecognized_keys (literal, a string literal in assertNoTopLevelCredential))

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

• content/docs/releases/v17/17-0.mdx (via unrecognized_keys (literal, a string literal in assertNoTopLevelCredential))

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.

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

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

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 ce001f97abbe460d9a6cc9a4bde6c6e38c9d37f8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0cc981aa238a292eff24079a3dfcb7a9fe55df1a
Local-runs: none
Scope: packages/services/service-datasource/src/datasource-admin-service.ts, packages/services/service-datasource/src/tests/datasource-admin-top-level-credential.test.ts + packages/spec/src/data/datasource.zod.ts, packages/spec/src/shared/strict-object.ts, packages/spec/src/shared/suggestions.zod.ts, packages/services/service-datasource/src/admin-routes.ts, packages/spec/src/api/error-code-ledger.zod.ts, packages/services/service-datasource/src/contracts/datasource-admin-service.ts, ui/packages/app-shell/src/views/metadata-admin/datasource/DatasourceResourcePage.tsx, packages/client/src/index.ts, docs/qa/platform-checklist/areas/integration-system.json

Inputs read: card #28549 (body, triage 6554155790, claim 6554684433, dev report 6555151884), PR #28607 body, file list and net diff at the head above, the 45 check-runs on that head, and the cited code at origin/main (ce001f97abb). The narrowing face has no path hits; the floor is every non-prose path of the diff, listed first on the Scope: line. Nothing was checked out, built or run.

① Derived judgments

1. Accept-set narrowing at the two write doors — right. POST /api/v1/datasources and PATCH /api/v1/datasources/NAME refuse a body carrying password or connectionString at its top level. Read on main: createDatasource spreads this.toRecord(input) (known keys only: name, label, driver, schemaMode, config, external, pool, active) and updateDatasource merges the same known keys, so both keys vanished before assertValidRecord ran. The premise holds at origin/main, and the diff's assertNoTopLevelCredential runs before any store read or write at both doors.
2. The refusal code is already ledgered at this door — right, no published-surface addition. DATASOURCE_ADMIN_ERROR is registered under @objectstack/service-datasource in packages/spec/src/api/error-code-ledger.zod.ts (the row at line 1374, "lifecycle/validation refusal from the datasource-admin service"), and the route's badRequest relays every plain throw from the admin service as 400 with SERVICE_ERROR_CODE['datasource-admin']. The diff adds no code, no status and no envelope field. The docs ledger pages (content/docs/references/api/error-code-ledger.mdx, contract.mdx) already list it.
3. One spelling of the prescription — right. The door calls DatasourceSchema.safeParse on an object holding only the present key names with null values and keeps the root unrecognized_keys message. That message is composed by strictUnknownKeyError from the schema's own guidance rows (password and connectionString: belongsInConfig('connectionString', 'url') in packages/spec/src/data/datasource.zod.ts), the same path os compile prints through. No prescription text is copied into the service; the test's specRefusal derives the expected text from the spec at run time and throws if the spec stops refusing the key, so a re-inlined copy or a spec drift reds the pin. The heading Invalid datasource 'NAME'. is the one assertValidRecord already uses.
4. Both doors closed consistently — right. Create: after the name rule and the draft credentialsRef refusal, before the driver requirement. Update: after the 404 and the code-defined refusal, before the merge, on every patch including a label/active-only one. That is the correct reading of the [finding] POST /api/v1/datasources (and the PATCH door) never run DatasourceSchema's cross-field refinements — a mongo credentialsRef pairing that os build and PUT /meta refuse is accepted 201, and the bound secret is silently unused #21058 exemption: RECORD_JUDGED_PATCH_KEYS spares a row stored before a gate; a credential in the body being written now is not that row.
5. No value reaches the judgement or the answer — right. Only key names are parsed (values replaced by null); the message cannot carry the credential. The tests assert the placeholder password and the DSN host are absent from the answer and that the record store, secret store and op log are untouched.
6. No legitimate producer sends either key today — right. Console editor draftBody sends label, driver, schemaMode, config, external, secret only, and its test-connection call sends driver, config, secret. packages/client exposes only the datasources/NAME/external/* family (no create or update method). The CLI's datasource commands (introspect, list-tables, validate) are read-only. No seed or fixture under examples/, apps/ or packages/qa posts a top-level password or connectionString; the QA refusal-matrix item prescribes the credential "in the top-level secret, never in config", which the route splits out before the service sees the draft and which stays accepted (control: 201, sys_secret: ref bound).
7. DatasourceDraft and every export unchanged — right. The contract never declared password or connectionString; the new constant and method are module-private.
8. Metadata-protocol: none — right. DatasourceSchema, the surface a metadata author writes against, does not move; the admin REST body is not that surface, and what it now refuses the schema already refused.

② Semver level

.changeset/28549-datasource-top-level-credential.md: '@objectstack/service-datasource': patch, a BREAKING banner, Clause-②: no (narrowing) and Metadata-protocol: none as line-initial declarations, and exactly one ADR-0087 marker (not-required (no-migration-prescription)) with its reason. This matches the diff: a non-protocol breaking change on a released package ships patch and keeps the banner and disposition; nothing at rest needs a migration because a refused body was never stored. The PR body carries the same Clause-②: no (narrowing) line at the start of a line. Check Changeset and Governed Surface Queue Guard both concluded success on this head. The Clause-②: line reads no (narrowing) — the one spelling this face is keyed on; it is exact on the PR body and the changeset alike.

③ Boundary flags

open_questions: []. The report's three deviations, each answered:

• Control premise changed (the order's "valid body with external.credentialsRef still answers 201" does not hold on main): confirmed in the cited code — assertNoDraftCredentialsRef (secrets: confirm the other stored-reference families (settings-service handles, datasource external.credentialsRef) apply the #27582 own-reference rule at their write doors #27722) refuses a draft naming external.credentialsRef on create. The substituted controls (create with secret bound at external.credentialsRef, edit keeping a bound ref) are the right ones. Answered.
• connectionString answers with the config.url prescription, not the credentialsRef one: that is the spec's own guidance row for that key, so it is "the same prescription the build door gives" for that key. A DSN carrying userinfo then meets the driver contract's refusal at config.url — a two-step the spec text already implies and the changeset's remedy line states up front ("without userinfo"). The spec is read here, not reviewed; no change asked of this PR. Answered.
• test:repo not run locally: CI's Test Core shards own it; they are in progress on this head at the time of this record (see the gate reading below). Answered as an honest reading, not a local run.

Check-runs on 0cc981aa at the time of writing: 45 runs, 0 failures; 30 completed (success or skipped — among them Check Changeset, Governed Surface Queue Guard, PR-body guards, Check PR Size, Lint · ESLint, Lint · scoped · query-options erasure, Lint · scoped · tooling self-tests, Lint · PM dispatch-gates, Type Check · debt ledger, Type Check · source gates, Dogfood Regression Gate, Test UI, Live E2E UI); 15 still in_progress (Test Core 1–8, Build Core, Type Check · workspace, Type Check · consumer gates, and four scoped lint lanes). Those conclusions are the gate verdicts for their families; this record does not pre-empt them, and the queue stays gated on them. The dev's local readings (61 derived families run, service suite 1110/1110, dogfood 2934 passed, ablation red/green) are the PR's account, read but not relied on.

④ Design judgment

The narrowing, judged against the published spec on main: DatasourceSchema is a strictObject whose guidance names password ("must never be inlined … bind through external.credentialsRef") and connectionString (belongs in config as url). The build door and the meta door already refuse these keys by name; the admin door alone accepted the body and dropped them. Nothing declared is taken away at the consumer: DatasourceDraft never carried either key, no stored record ever held one, and the only observable before was a success answer over a datasource that could not connect. This makes the spec's own refusal real at the last door that did not give it. Right.

Attempts to break it, each read in the diff and the cited code:

• { password: null } is refused (presence is !== undefined), as the build door refuses the key whatever its value. Consistent.
• A body with secret beside password: the route's splitSecret removes secret first, so the draft the service judges still carries password and is refused; the secret channel itself is unchanged (control green). Consistent.
• A code-defined datasource patched with a password: the code-defined refusal fires first. Acceptable ordering — the row is read-only before the body is judged.
• Spec drift: if DatasourceSchema ever declared one of these keys, detail.length === 0 returns and the door falls open silently — but the test's specRefusal throws "fixture premise broken" in exactly that case, so the pin goes red rather than the door going quiet. Sound.
• Direct service callers with a malformed input: assertValidName(input?.name) throws before the new check reads input; updateDatasource already dereferenced patch.label, so an undefined patch was never accepted. No regression.
• The route answers every thrown Error from this service as 400 DATASOURCE_ADMIN_ERROR unless it carries the 503 or 404 envelope; the new throw carries neither. Right code, right status.

Findings:

• should-fix (follow-up card, not this PR): POST /api/v1/datasources/test (testConnection) still projects a draft through toRecord before judging it, so a top-level password or connectionString on the probe is dropped silently and the probe tests a different connection than the one the author described — green on a server that needs no password, a driver-side failure otherwise, with no mention of the key. It writes nothing and the card scoped the write doors, so it is not a must-fix here, but the same spec refusal is owed at that door for the same reason.
• should-fix (give it a carrier): the dev's out-of-scope finding that every other undeclared top-level key (url with userinfo among them) is still dropped silently at these doors has carrier: none. A general closed body at the admin door is a change of its own (it must tolerate the GET round-trip keys origin, hasSecret, redactedConfigKeys, definedIn); it should be filed so it is not lost in a PR's acceptance notes.
• No must-fix.

Implemented-by: claude/project-thread-9kvath
Reviewed-by: session_01FEkQ5kE5BrPUPNMMyv6oCH

VERDICT: PASS

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

席位核对 · ACCEPT · PR #28607 · 2026-11-01T08:06Z

Head-sha: 0cc981aa238a292eff24079a3dfcb7a9fe55df1a

维护者速读(席位终稿)

• 改了什么:数据源接口的创建和编辑，现在拒收写在请求体顶层的 password 或 connectionString:400 DATASOURCE_ADMIN_ERROR，点名这个键、不回显值、什么都不存。拒收文字直接取自 DatasourceSchema，和 os compile 打印的一样。
• 为什么改:以前这两个键被悄悄丢掉、仍答 201，作者拿到连不上的数据源却没有任何说明(Datasources: POST /api/v1/datasources accepts and silently drops a top-level password or connectionString that os compile refuses, answering 201 #28549)。
• 风险与回滚:只收窄这两个顶层键;控制台表单从不发它们(已核)。回滚即 revert。
• 先看:datasource-admin-service.ts 的 assertNoTopLevelCredential 与 create / update 两处调用。
• 两分钟验证:pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/datasource-admin-top-level-credential.test.ts → 10/10。
• 需要你做的:无。席位按常设授权落地。
• 席位意见:契约复核 PASS;测试从 spec 现取期望文字，spec 漂移即红。可落。

核对六项

1. 形态:draft → main;Fixes #28549,本 PR 交付卡上两扇写门，合并即关卡正确;其余闭合关键词零命中(已扫)。文件 3 个，在认领申报面内。
2. 前提实测:红先在 base 上 7/10 红(两键两门均 201/200 且不存);消融逐门恢复 201/200。
3. 门禁:本 head check-runs 48 个，35 success、13 skipped、0 失败;Lint & Repo Gates、TypeScript Type Check 皆 success。dev 本地 61 族全测、0 NOT-MEASURED;收窄 PR 的 dogfood 电池钉本 head 0cc981aa:364 文件过、3 跳过、无失败。
4. 接受的偏差:派发令的对照「带 external.credentialsRef 的草稿创建答 201」在 main 上不成立(创建拒收草稿自带的 credentialsRef),dev 换成「secret 绑定创建 201」与「保留已绑 ref 的编辑 200」,接受;connectionString 答的是 schema 为该键给的 config.url 处方，即构建门对该键的同一处方，接受。
5. 范围外去向:测试门 POST /datasources/test 仍丢顶层键、其余未声明顶层键仍被两门静默丢弃 → filed Datasources: the test door and every undeclared top-level key still bypass the refusal DatasourceSchema gives (the rest of #28549) #28612(Datasources: POST /api/v1/datasources accepts and silently drops a top-level password or connectionString that os compile refuses, answering 201 #28549 的子卡，已派发，基于本 PR 叠加);GET 回显字段的往返容忍写入 Datasources: the test door and every undeclared top-level key still bypass the refusal DatasourceSchema gives (the rest of #28549) #28612 的读物(本 PR Acceptance notes)。Metadata-protocol: none,无 Skills-docs: 欠账。
6. 落地条款:Clause-②: no (narrowing) ⇒ 契约复核达档 PASS 在案:comment 6555221422(CONTRACT_REVIEW_TIER,同 head 0cc981aa)。check-governed-merges --pr 28607:NOT governed,340 行。落地授权，维护者原话:「按照 pm-dispatch 规则复核过的都授权」(2026-10-25T11:35Z)。