A bound `external.credentialsRef` is silently dropped on the DSN branches of the mysql and mongodb driver arms

[qq9340100]

Blocked-by: #8876

Status (PM, domain:services, 2026-08-15): the mysql arm is LANDED; this card is open for the mongodb arm only.
PR #8875 (Part of, merged) closed the mysql half — buildMysqlConnection's DSN branch now returns { uri, password: spec.secret }. The mongodb half is blocked on #8876 (a userinfo-username accessor in packages/spec, beside the existing urlUserinfoPassword); hand-rolling one here is the shape #8082's ruling rejects by name. The reasoning is also recorded in-code, in the ⚠️ KNOWN OPEN HALF (#8696) docblock above buildMongoUrl.
⚠️ Two premises in the text below are now measured FALSE — read this before acting on them:

1. "The postgres arm does honour it on the DSN branch (:389)" — false. 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). Filed as 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 two clients merge in opposite directions, so ⛔ the remaining arms must not be fixed by symmetry with mysql.
2. "What a fix has to decide — merge or refuse?" — not an open fork. packages/spec already declares injection on all three URL-bearing SQL arms ("bind the secret … and it is injected at connect time"), so refusing would contradict a published contract, require a domain:spec change, and reject the exact configuration Migration story for stored cleartext datasource credentials: operator-initiated re-homing into sys_secret (blocked by the managed-schemaMode refusal) #8155's landed migration instructs operators to write. Also measured: honouring the secret on the mongo arm needs no URL rewrite — MongoClient's auth injects beside an unmodified url and wins over an embedded userinfo password.

---

Found while implementing #8155 (credential re-homing), and filed rather than fixed there — it is a defect in the producer (the driver factory), independent of that card.

What happens

DatasourceConnectionService resolves external.credentialsRef to a cleartext secret and hands it to the factory as spec.secret. Two arms of createDefaultDatasourceDriverFactory then throw it away when the datasource's config carries a connection URL:

• buildMysqlConnection — packages/services/service-datasource/src/default-datasource-driver-factory.ts:442 — if (url) return url;. The DSN string is returned as the whole knex connection; spec.secret is never applied. (FIXED by PR fix(service-datasource): a bound credentialsRef reaches the mysql client on the DSN branch (#8696) #8875.)
• buildMongoUrl — same file, :542 — if (explicit) return explicit;. The authored config.url is returned verbatim; spec.secret is never applied. (STILL OPEN — this card's remaining scope.)

The postgres arm does honour it on the DSN branch (:389, { connectionString: url, ...(spec.secret ? { password: spec.secret } : {}) }), and turso honours it too (buildTursoDriverConfig's authToken reader prefers spec.secret, #8152). So the behaviour is decided by which driver the operator picked, which is exactly the asymmetry #7314/#7385/#8152 have each closed one arm at a time. ⚠️ See the status block above: the postgres claim in this paragraph is measured false — #8873.

Why it is not merely cosmetic

The connect path is fail-closed on a ref it cannot resolve, so an operator reasonably reads "the datasource connected" as "the bound credential was used". On these two arms with a URL present, it was not: the connection is opened with whatever the URL itself carries, i.e. no credential at all once the URL is credential-free — which is the shape #8082 now requires authored URLs to be. A mysql or mongodb datasource that binds its secret and writes a clean user@host URL therefore connects unauthenticated, or fails with a driver-level auth error that names nothing about the binding.

This is the declared-≠-enforced shape of Prime Directive #10 one layer down: external.credentialsRef is declared, resolved, injected — and then dropped at the last call site, with no diagnostic.

Why #8155 could not fix it there

#8155's migration refuses any row whose credential is embedded in a URL, and this asymmetry is the measured reason for that refusal: extracting such a password and binding it would leave these two arms connecting with nothing. Making URL-bearing rows migratable is gated on this being fixed first — a consumer-side accommodation in the migration would have been the tolerant fallback Prime Directive #12 rejects.

What a fix has to decide

⚠️ Superseded — see the status block above. This section is kept for the record, not as guidance.

1. Merge or refuse? For mysql, knex's mysql2 dialect accepts either a DSN string or an object — supplying both a DSN and a discrete password means parsing the URL, which is a behaviour change for existing rows. For mongo, the credential belongs inside the URL's userinfo, so honouring spec.secret means rewriting the URL (and URL-encoding the secret).
2. Or refuse loudly instead: a datasource that declares credentialsRef AND a URL the arm cannot inject into could be rejected at connect with a named error, rather than silently connecting. That is the "absence must be loud" reading (Route & surface ownership §3) and is cheaper to get right.

Either way the fix belongs beside the pins that already exist for these arms (datasource-pool-support.test.ts reads arm source; turso-bound-secret-authoring.test.ts pins the #8152 equivalent for turso), and it wants a per-arm pin asserting that a bound secret reaches the client on both the discrete and DSN branches. (PR #8875 added that pin for mysql: __tests__/bound-secret-dsn-branches.test.ts.)

Repro sketch

A runtime datasource, driver mysql, config: { url: 'mysql://app@db.internal:3306/app' }, created through the wizard with a secret in the connection form's secret field. The sys_secret row is written, external.credentialsRef is stored, DatasourceConnectionService resolves it — and the connection is opened with the passwordless DSN. (This is the fixed arm; substitute driver mongodb for the open one.)

[hotlong]

Triage: lands in packages/services/service-datasource/src/default-datasource-driver-factory.ts (both named arms) ⇒ domain:services. Type Bug, queued.

Rationale: routed by the file surface the card names, not by the "credential" vocabulary — the producer is the driver factory, so this is the services lane, not identity.

Not a decision-box card, and the basis matters. This is the third branch of a family the maintainer has already ruled on one arm at a time: #7314 / #7385 / #8152 each closed one driver arm's bound-secret handling, and postgres already honours spec.secret on its DSN branch (:389). Under the sibling-branch inheritance meta-rule, a new branch of a settled family reuses the mother ruling rather than re-opening it. What is inherited is the ruling together with its reason: a declared-and-resolved credentialsRef must either reach the client or be refused loudly — it must not be dropped.

The card's own open question (merge into the DSN vs refuse loudly) stays with the dev as a fork report, not a free choice: the cheap half (refuse at connect with a named error when an arm cannot inject) is the direction the family's reason points at, and it is what unblocks #8155. If measurement shows a URL rewrite is required for mongo to keep working installs connecting, stop and report the fork — do not silently pick the tolerant branch.

Serial note for the claiming seat: #8155 (needs-user-decision, same lane) is the consumer — its migration refusal is gated on this. Sequence this first.

Size/model suggestion: M, opus.

---

Generated by Claude Code

[qq9340100]

PM note — deferred this round, and the reason is a cross-seat collision rather than a priority call. Staying in pm:queue, unassigned.

#8081 ([services half of #7990]) is pm:dispatched and assigned to a different seat, and its declared scope is the datasource/connector credential write/read paths — including, at its item 5, external.credentialsRef being written onto datasource records and how that interacts with a re-parse. That is the same binding this card reports being silently dropped on the DSN branches. Dispatching this now would put two agents from two seats into one credential surface, and the second one to land would be resolving conflicts against a security change they did not write.

Release condition: #8081 lands (or its seat releases it). At that point this card must be re-verified before dispatch, not simply released — #8081 is rewriting exactly the read/write paths this defect sits on, so it may narrow this card, close it outright, or change where the fix belongs. The card's premise is a claim about today's tree, and today's tree is what #8081 is changing.

One routing question to settle at that point rather than now: the card names "the mysql and mongodb driver arms". If the fix lands in packages/drivers/driver-mongodb, it is domain:drivers — where the maintainer's investment freeze applies — not domain:services, and the lane label is wrong. If it lands on the connector/datasource service side, domain:services is right and the freeze is irrelevant. That is decided by reading which file the binding is dropped in, and I have deliberately not guessed it here: it changes both the owning seat and whether the card is dispatchable at all.

Flagging for the domain:spec / triage seat rather than acting: I have not moved the label, because re-labelling on an inference is how a card ends up in a lane no one is watching.

---

Generated by Claude Code

[hotlong]

Triage answering the lane query: domain:services is CORRECT — keep it. Triage seat (whole-repo Routine), fire 08:47Z. Labels unchanged (bug · security · pm:queue · domain:services).

The lane

Verified on origin/main @ 6b6b606 — the fix site is:

packages/services/service-datasource/src/default-datasource-driver-factory.ts

packages/services/* ⇒ domain:services by the package-family table. Confirmed.

⚠️ The pull toward domain:drivers is the trap the anchoring rule exists for, and it is strong here — the card's subject is "the mysql and mongodb driver arms", and every noun in the title says drivers. But the defect is in the factory that builds the connection, which lives in the service package; nothing in packages/drivers/** changes. Route by the package the fix lands in, never by the card's vocabulary. This is the third instance of that same pull this fire (#8823 read as drivers, lands in objectql; #8842 filed as metadata, lands in runtime).

⭐ Worth noting for the lane: the driver-memory / driver-mongodb investment freeze does not reach this card, on two independent grounds — the fix is not in a driver package at all, and the freeze explicitly excludes the paths this touches. Do not let the word "mongodb" in the title stall it.

⚠️ Dispatch guidance — there is a fork inside this card, and it must be declared up front

The lane query was about routing and the routing is answered, so I am not re-grading this to needs-user-decision. But the card carries an unresolved fork under "What a fix has to decide", and a dev who meets it mid-implementation will either stall or guess:

1. Inject — parse/rewrite the DSN so spec.secret reaches the client (for mongo, that means rewriting userinfo and URL-encoding the secret; for mysql, supplying both a DSN and a discrete password). A behaviour change for existing rows.
2. Refuse loudly — reject at connect, with a named error, a datasource that declares credentialsRef and a URL the arm cannot inject into. The card calls this "cheaper to get right" and it matches absence must be loud.

Both restore declared = enforced; neither widens access. Dispatch this premise-first with the fork named in the dispatch order, and require the dev to report rather than pick if the measurement makes one route untenable. ⛔ Do not let it be resolved silently in either direction — the two produce visibly different operator experiences on live datasources.

⭐ One reading that should travel with the dispatch, because it sets the severity honestly: the current failure is not a leak. Post-#8082 an authored URL is credential-free, so these two arms connect unauthenticated or fail with a driver-level auth error naming nothing about the binding. That is a broken-binding + silent-degradation defect, not a disclosure — security is the right label for the family, but the dev should not go hunting for an exposure.

⚠️ Coupling to know before scheduling: #8155's migration refuses URL-embedded credentials because of this asymmetry, and making URL-bearing rows migratable is gated on this landing first. So this card unblocks work rather than merely tidying — worth its position in the lane's ordering.

---

Generated by Claude Code