fix(service-datasource): a bound credentialsRef reaches the mysql client on the DSN branch (#8696)

[qq9340100]

Part of #8696 — the mysql arm only. The mongodb arm named in that card is not implemented here and #8696 remains open for it; see "What is deliberately not in this PR" below.

Premise re-verified first (the card was deferred behind #8081)

#8696 was held for a day because #8081 was rewriting the datasource credential read/write paths this defect sits on, so the first deliverable was a measurement, not a fix. Measured on origin/main @ 20067c56b, driver arm by driver arm, with a bound secret injected exactly as DatasourceConnectionService injects it:

mysql    config.url = mysql://app@db.internal:3306/app
         knex connection: typeof=string  value="mysql://app@db.internal:3306/app"   secret ABSENT
mongodb  config.url = mongodb://app@db.internal:27017/app
         driver.config.url = mongodb://app@db.internal:27017/app                    secret ABSENT
postgres config.url = postgresql://app@db.internal:5432/app
         connection.password = the bound secret                                     secret PRESENT

The premise still holds. #8081 did not touch these branches — the three sites the card cites (:442, :542, :389) are unchanged, and DatasourceConnectionService still resolves external.credentialsRef into spec.secret and hands it to the factory.

The fork the card left open is settled by the spec, not by preference

The card asked whether to inject the secret or refuse loudly, and the dispatch treated refusal as presumptive. Both readings turned out to be answerable from the contract rather than by taste: packages/spec already declares injection on all three URL-bearing SQL arms. MysqlConfigSchema.url, verbatim:

Credential-free by contract since #8082: a user:password@ userinfo is refused at publish exactly like an inline password (#7990) — bind the secret (external.credentialsRef / the connection form's secret field) and it is injected at connect time. A bare username (user@host) stays writable.

The same sentence appears on MongoConfigSchema.url and PostgresConfigSchema.url. So this is not a fork between two defensible behaviours — it is Prime Directive #10 one layer down: the contract says injected at connect time, and the runtime dropped it. Refusing loudly would have required changing the spec, which is a domain:spec contract decision, and would additionally have rejected the exact configuration datasource-credential-migration.ts (landed today in #8155) instructs operators to write:

Edit the datasource in Setup → Datasources: remove the password from the URL (a bare user@host is accepted) and enter it in the connection form's secret field, which binds it into the secret store.

That same file names the remedy this PR implements — "the driver factory's DSN branches would have to honour the injected secret" — as the producer-side change its own refusal is waiting on.

The dispatch's stop-condition did not fire. It was "stop and report if a URL rewrite is required for mongo": measured false. MongoClient's auth option injects beside an unmodified url and wins over an embedded userinfo password (mongodb 7.5.0), so no rewrite and no URL-encoding of the secret is involved on either arm.

The change

buildMysqlConnection's DSN branch was if (url) return url; — the DSN string became the whole knex connection, which has no key a credential could live in. It now hands mysql2 the DSN and the secret together:

if (url) {
  if (!spec.secret) return url;
  return { uri: url, password: spec.secret };
}

{ uri, password } rather than a hand-parsed URL is the point of the shape: mysql2 keeps owning its own DSN grammar, so there is no second dialect of mysql://… in this repo, no re-encoding, and no place for a parser bug to change which host is connected to. Measured on mysql2 3.23.1 / knex 3.3.0 / pg 8.22.0:

mysql2 ConnectionConfig({uri:'mysql://app@db.internal:3306/app', password:'INJECTED'})
  -> user=app host=db.internal port=3306 database=app password=INJECTED
mysql2 ConnectionConfig({uri:'mysql://app:embedded@db.internal:3306/app', password:'INJECTED'})
  -> password=INJECTED        # bound secret wins, as the postgres arm's comment already declares
knex   connectionSettings for {uri, password}
  -> Object.keys = ['uri'] ; getOwnPropertyNames = ['uri','password'] ; cs.password = 'INJECTED'

That last line is a trap worth naming: knex stores password as a non-enumerable own property (setHiddenProperty), so JSON.stringify and Object.keys both report a bare {uri}. A serialising probe reads as "the secret was dropped" when it was not — every assertion in the pin uses direct property access instead.

Blast radius is exactly the broken class. A DSN with nothing bound still returns the bare string it always did, so any datasource that binds no secret is byte-for-byte unaffected. The only datasources whose behaviour changes are the ones that bound a credential and were connecting without it.

Verification

• New pin bound-secret-dsn-branches.test.ts — 5 cases: injection on the DSN branch, bound-wins-over-embedded-legacy-DSN, the no-secret passthrough, and two controls on the discrete branch.
• Reverse verification, direction predicted in writing before running. Predicted: restoring if (url) return url; turns the two DSN cases RED and leaves the no-secret and both discrete cases GREEN — branch-local, so a whole-arm regression would mean the pin measures the wrong thing. Measured exactly that set, 2 failed / 3 passed:

  × injects the bound secret beside the DSN instead of dropping it
      AssertionError: expected 'string' to be 'object'
  × lets the bound secret win over a legacy password embedded in a stored DSN
      AssertionError: expected undefined to be 's3cr3t-from-sys_secret'
  

• @objectstack/service-datasource: 426 tests / 19 files pass, typecheck clean.
• Gate union re-derived from the actual changed paths with scripts/pm/dispatch-gates.mjs and run at 9e0e95f87, which is this branch's head (the union was re-run after merging origin/main, since the merge commit moved the head): check:test-source-alias, check:type-source-resolution, check:nul-bytes, check:error-code-casing, check:changeset-gate-self-tests, check:objectui-changeset, check:query-options-erasure, check:type-check-coverage, check:type-check-debt --re-measure, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset — all green. The re-derivation added seven families beyond the dispatch list (the changeset family and the test-file convention ratchets).

No new error code is minted, so nothing lands on the ADR-0112 surface: the refusals this file already raises are plain errors carrying a fix instruction, and this change adds none.

What is deliberately not in this PR

The mongodb arm — #8696 stays open for it. buildMongoUrl's if (explicit) return explicit; still drops the bound secret, so a mongo DSN datasource still reaches MongoClient with an empty password (measured). The remedy is known and cheap — options.auth, which MongoDBDriver already forwards verbatim — but auth requires a username as well as a password, and reading the url's userinfo username needs the platform's own DSN grammar: new URL() rejects the multi-host form MongoConfigSchema documents (mongodb://app@h1:27017,h2:27017/app throws ERR_INVALID_URL, measured), which is precisely why @objectstack/spec/data owns urlUserinfoPassword / redactUrlPassword instead of using WHATWG parsing. Those two export the password half of that grammar and no username half. Adding one belongs beside them in packages/spec, which is outside the file surface this card was dispatched with, and hand-rolling a second copy of the userinfo boundaries here is the shape #8082's ruling rejected by name ("a single value-level parse as the mechanism, precisely so no second copy exists to disagree with this one"). Left for an explicit decision rather than guessed at; the reasoning is recorded on buildMongoUrl itself so the next author does not have to re-derive it.

Two defects measured in passing, filed unassigned rather than fixed here:

• A bound external.credentialsRef reaches the knex config but NOT the server on the postgres DSN branch — pg overrides it with the connection string #8873 — the postgres arm passes the equivalent assertion at the config layer and is broken one layer below it. pg merges parse(connectionString) over the explicit config, so the injected password resolves to the DSN's own — effective password: null on a credential-free DSN (pg 8.22.0). This falsifies the "postgres is the reference implementation" premise that A bound external.credentialsRef is silently dropped on the DSN branches of the mysql and mongodb driver arms #8696 and its triage both carry, and it is why the pin here asserts what it does. The two clients merge in opposite directions, so that arm must not be fixed by symmetry with this one.
• A declared ssl block is silently dropped on the mysql arm's DSN branch (postgres honours it there) #8874 — the same mysql DSN branch also drops a declared ssl block (resolveSslOption is computed and then returned past), while the postgres branch carries it deliberately. Not folded in here: making TLS appear only for datasources that happen to bind a credential would be a stranger asymmetry than the one being fixed.

---

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 15, 2026 12:37pm

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 1 changed package(s). ✅