Migration story for stored cleartext datasource credentials: operator-initiated re-homing into sys_secret (blocked by the managed-schemaMode refusal)

[huangyiirene]

Split out of #8081 scope item 3 by the domain:services PM seat. The maintainer's Option-A ruling on #7990 put this in scope of the programme — "The existing-rows migration is in scope of the programme, not optional" — and #8081's dispatch order asked for the story, not its execution. This card carries the proposal the dev produced. ⛔ Not graded by me; no domain:* label.

Blocked-by: #8153

An inventory already exists, and it is free

/meta re-parses every stored row and badges it _diagnostics: {valid:false, errors:[…]} carrying the full refusal message. Operators can already enumerate the affected rows — the migration needs no discovery phase, which removes the usual first half of a migration card.

⚠️ That also creates a coupling worth stating: #8154 (redacting the /meta read path) must not strip or break _diagnostics, or this inventory disappears.

Recommended shape — (b) admin tooling, per-datasource, operator-initiated

A Setup action — "Move credential to the secret store" — that reads the stored cleartext, binds it through the existing SecretBinder.bind(), writes external.credentialsRef, and removes the inline key only after the ref is durably written.

Is it destructive? No, and deliberately so. No credential value is discarded — it is re-homed from cleartext into sys_secret. The inline key is deleted only once the encrypted row exists. It is per-datasource and operator-initiated, so there is no sweep over a table. That matters: the ruling's "escalate if destructive" clause is what this shape is designed to stay clear of.

Rejected, with reasons

• (c) one-time boot script — decides the secret's identity with no operator present and mutates rows at boot. That is precisely the destructive-sweep shape sys_secret: rotations that happened BEFORE #8030's fix left decryptable orphans on deployed instances, and nothing reaps them #8103 split out of [security] Rotating an encrypted setting silently does nothing — the new ciphertext is written but sys_setting.value_enc still points at the old handle, so a leaked credential stays live after a 200 #8030 for the same reason. The ruling's escalate-if-destructive clause points straight at it.
• (a) read-time refusal + re-entry prompt — non-destructive, but it breaks working datasources in order to prompt a human, and it is unnecessary once (b) exists. Worth keeping only as a fallback for rows (b) cannot bind.

⚠️ Sequencing — this is blocked, and running it early makes things worse

The migration's entire output is external.credentialsRef on an existing row. Per #8153, writing that onto a row whose schemaMode defaults to 'managed' is exactly the shape that fails re-parse.

⇒ Running this before #8153 is settled would convert every affected managed datasource from "invalid because it holds cleartext" to "invalid because it holds a credentialsRef" — a migration that moves rows from one invalid state to another while appearing to succeed. #8153 first.

Constraints

• ⛔ No sweep over the credential table without an operator. If the shape drifts back toward (c), it needs escalation per the ruling, not a lane decision.
• The ref must be durably written before the inline key is removed — a crash between the two must leave the row working, not credential-less.
• ⚠️ Re-running must be idempotent and must not mint a second sys_secret row for an already-migrated datasource (the orphan-accumulation failure mode measured in sys_secret: rotations that happened BEFORE #8030's fix left decryptable orphans on deployed instances, and nothing reaps them #8103 and guarded in PR fix(plugin-webhooks): move webhook custom headers onto the encrypted channel (#7986) #8114's headersPatch).
• Rows (b) cannot bind need a stated outcome — that is where fallback (a) earns its place.

Provenance: #8081 dev report (comment 5269923121, §③), #7990 maintainer ruling (comment 5266068845), my ACCEPT receipt (#8081 comment 5270102954). Related: #8103 (the same destructive-sweep boundary, for sys_secret orphans), #8154, #8152.

[hotlong]

Triage: lands in the services lane (Setup action over the existing SecretBinder.bind() path in service-datasource) ⇒ domain:services, type Feature, pm:blocked on the Blocked-by: #8153 line already in the body. The maintainer's #7990 Option-A ruling already puts the migration in scope, and the recommended shape (b) — operator-initiated, per-datasource, ref durably written before the inline key is removed — is designed to stay clear of the escalate-if-destructive clause, so no new decision is needed here; what gates it is purely the #8153 contract question (now escalated as needs-user-decision), because running the migration first would move rows from one invalid state to another.

For the unlock re-check when #8153 resolves: re-verify that the _diagnostics.valid:false inventory still exists (the #8154 redaction work is under an explicit constraint not to break it) and that the idempotency/no-second-secret-row constraint from #8103's measurements is in the dispatch order verbatim.

---

Generated by Claude Code