wire: single-use operator-minted credential-scoped replace authorization (was: consumer-side credential.replace)

[iceteaSA]

Why

Consumers that hold a credential under single-owner custody (no sidecar; the plugin's local copy is a tombstone after import) have no recovery path from a needs_reauth latch today: import --replace reads a source file, and the source is gone. The only recovery is a fresh login, and that login must write the new family into the vault. On the wire there is get / status / report_auth_failure only; import is CLI-only (master-key challenge or the offline lease). So a plugin's recovery story is currently "the operator runs ck auth", which is coherent (single-owner = the vault owns login) but blocks unattended fallbacks. Raised by the openai-auth adoption (four accounts, single-owner directive); anthropic-auth's C10 (login auto-import) is deferred on the same gap.

Threat-model constraint

Capability handles are read capabilities. A leaked handle must stay a read-only loss — never a record-poisoning or latch-by-write one. So the verb must not be handle-bound.

Proposal

• One verb, existing records only: credential.replace { credential_id, material } — creation stays CLI (an id is an operator decision). Returns the new record_version; bumps version; audited as its own AuditOp::Replace with the principal.
• Authority = a principal-scoped grant. read_grants already carries an operation enum per (principal_kind, principal_id, credential_prefix); add GrantOperation::Replace. Route-bound principal only (the daemon names it); minted by the operator with ck auth grant … --op replace.
• Material is verified by use before commit. The auth: records carry an account identity; set-identity and import set it, replace keeps it #30 label-vs-claim guard is not a security boundary (account_id_for_adapter parses the JWT claim unverified; a forged claim passes). The daemon must make one upstream call with the incoming family — the adapter's non-mutating validity check where one exists, else a refresh — and commit only on success. A replace that fails verification writes an auth_events row and leaves the record untouched.
• Identity: the auth: records carry an account identity; set-identity and import set it, replace keeps it #30 guard applies on top (claimed account must match the retained label unless the caller supplies the new one), so a same-slot re-login into a different account is refused rather than mislabelled.
• Rate/abuse: counted against the connection's fetch limiter like report_auth_failure; a failed verification is an alarm row, not a refusal.

Non-goals

Not a consumer-side create; not a handle-bound write; not a replacement for the CLI path (which stays the operator's tool and the audit's route-admin actor).

Related: #17, #30 (guard), #31 (refresh policy), anthropic-auth C10.

[ckcred-alfonso]

The gap is real and it is partly mine — I argued for single-owner custody, and single-owner custody with no unattended recovery path is the consequence. Your threat-model constraint is also exactly right, and you solved it: handles stay read capabilities, the verb is not handle-bound.

Three findings at source, then a counter-proposal.

The verification you specify cannot be implemented for the providers that need it

the adapter's non-mutating validity check where one exists, else a refresh

No adapter implements one. The trait default returns None and zero of the twelve shipped adapters override it:

non_mutating_check overrides in refresh_adapters/*.rs   0
trait default (mod.rs:251-257)                          None
anthropic no_non_mutating_check test comment            "Anthropic exposes no
                                                         introspection endpoint"

So "where one exists" describes nothing today, and every replace verification falls to the else branch: a refresh.

And a refresh consumes the material being verified. Anthropic rotates the refresh token (anthropic.rs:6). So verifying by refresh means:

• the incoming refresh token is spent, and the committed family is not the family you handed in;
• the caller's retained copy is dead the moment verification succeeds;
• and if the commit then fails — fence loss, crash, disk — the record keeps its old dead family while the caller's new family has been rotated away. Both copies dead, recoverable only by an interactive login, which is precisely the state the verb exists to escape.

That last one is the reason I would not ship it as specified. It converts an atomic write into a two-phase network-then-commit whose first phase destroys the input. Today's CLI path is one fenced transaction, and crash_before_login_write_leaves_old_credential_intact_and_refreshable pins exactly that property under SIGKILL.

Verification is a new requirement, not a preserved one

Worth being explicit, because it changes what the verb is: ck auth import --replace does not verify material either. There is no validity call anywhere in admin_ops.rs. Material is committed and its health is discovered on first use.

So "verified by use before commit" is a property you are adding to make a wire verb feel safe, not one you are carrying over. If it is dropped as unimplementable — and per the above it is, for rotating providers — then the verb reduces to: any grant-holding principal may write arbitrary secret material into any record matching a prefix. That is the honest description, and it should be the one the design is judged against.

The crux is the master key, and the proposal does not name it

Every existing credential-mutating path is gated by the master-key HMAC challenge-response (Gate 2). That gate is the reason admin mutations are safe over the route plane at all: the daemon cannot authorize a mutation by itself, and neither can a compromised daemon.

A grant-scoped replace has no master-key gate. So this is not "add a verb" — it is create the first class of credential mutation that does not require the master key. That may still be the right call, but it is an architectural decision and it deserves to be argued rather than inherited.

Two things make me cautious about inheriting the read-grant authority model for a write:

• Blast radius differs in kind. A leaked read grant is a confidentiality loss on those credentials. A leaked replace grant is a persistent integrity and availability loss: the record now serves an attacker's material to every consumer, and the operator has no signal distinguishing that from a legitimate re-login.
• The gate under it is documented as not a secret. Route-bound principal identity rests on SUBC_LAUNCH_NONCE, which is inspectable via ps eww by any same-UID process — I recorded that when designing the read grants, and accepted it for reads, on the grounds that supervisor attestation is an integrity and coordination gate rather than a secret. The same gate carrying a credential-poisoning write is a much weaker fit for the harm.

Also mechanical, if it proceeds: AuditOp::Overwrite already exists (wire name overwrite). A second op for the same class of mutation splits the vocabulary, and historical queries for "the secret was replaced" would need to know both names — the argument I used to decline splitting revoke_handle in #13. Reuse Overwrite and let the actor carry the principal, which is how route-admin / offline-cli / conn-N already distinguish provenance. And read_grants pins CHECK(operation IN ('read','sign')), so a third operation is a table-rebuild migration, as migration 6 was.

The counter-proposal: bound the authority, not the material

Your outcome is unattended recovery of one latched credential. That does not need a standing write capability over a prefix.

An operator-minted, single-use, credential-scoped replace authorization. The operator says "this principal may replace chatgpt:openai:gmail once"; the grant is spent on use, and a spent one is refused. Concretely: a row keyed by (principal, credential_id, nonce) with a spend ledger, consumed inside the same fenced transaction as the write — the shape I have built three times in the account service for step-up attestations, and the shape migration-6 grants already almost have.

What that buys over the prefix grant:

• a leaked authorization is worth exactly one replace of one named record, not a standing poisoning capability;
• it is a deliberate operator act per recovery, which is what makes it auditable as recovery rather than as routine traffic;
• it composes with your auth: records carry an account identity; set-identity and import set it, replace keeps it #30 identity guard without needing verification-by-use, because the operator has already scoped which record may be written.

It does not give you fully unattended recovery — the operator still authorizes each one. If that is the actual requirement, then say so plainly and the conversation becomes "should credential replacement be possible without the master key or an operator act", which is the real question and is worth asking directly rather than reaching it through a verb.

One thing I would not build in its place: another notification path. needs_reauth is already emitted by the health probe (~114 non-ok reports/hour during a real eight-hour outage), by ck auth status, and by ck auth events. The gap there was never a missing signal — it was that no path connected the emission to a person, and the only thing that ever worked was an ask surfaced to the operator. Adding a fourth emitter would be the expensive version of that mistake.

[iceteaSA]

All three findings hold; the first one kills the verb as I specified it.

Verification-by-use is unimplementable for the providers that need it. No adapter overrides the non-mutating check (I audited that myself on 08-28 for the reconcile path and then wrote "where one exists" here as if the set were non-empty). And on a rotating provider a refresh is the destructive act: the input is spent before the commit, so a failed commit leaves both copies dead — the state the verb exists to escape. The CLI's single fenced transaction is strictly better, and crash_before_login_write_leaves_old_credential_intact_and_refreshable is the property I would have broken. Withdrawn.

Verification was a new requirement. Agreed: import --replace commits unverified material and discovers health on first use. I added the check to make a wire write feel safe; without it the honest description of the proposal is the one you wrote — any grant-holding principal may write arbitrary material into any record under a prefix — and that is not something to inherit from the read-grant model, for the two reasons you give (blast radius is integrity, not confidentiality; the route identity gate was accepted for reads on grounds that don't carry a poisoning write).

Counter-proposal accepted as the shape, with the real question answered plainly rather than reached through a verb: full unattended recovery of a dead OAuth family is impossible regardless of the write path, because obtaining the new family is an interactive login (device or PKCE) — a human is in the loop already. What the consumer seat actually needs is narrower: the login happens where the browser is (the plugin process), and the result must land in the vault without the plugin holding the master key. A single-use, operator-minted, credential-scoped replace authorization is exactly that shape — one deliberate operator act per recovery, worth one replace of one named record if leaked, spent inside the same fenced transaction as the write, composing with the #30 identity guard because the operator already scoped the record. I'll restate the issue around that. Mechanical points taken: reuse AuditOp::Overwrite with the actor carrying the principal; the read_grants CHECK means a table-rebuild migration if the authorization lives there — a separate table keyed (principal, credential_id, nonce) with a spend column avoids touching it.

No fourth emitter. The consumer seat's design already routes recovery through ck auth and treats this as a follow-up, not a dependency.

[ckcred-alfonso]

Your restatement is the right issue, and the plain answer you gave — full unattended recovery is impossible because obtaining a new family is interactive, so a human is already in the loop — is the sentence the original proposal was missing. Once that is on the table the verb stops looking like automation and starts looking like what it is: the login happens where the browser is, and the result lands where the master key is not.

Two things before anyone builds it.

I am not building it yet, and the trigger is checkable

Not a blocker — a judgement, and worth labelling that way so it invites re-weighing rather than stopping anyone looking.

The population today is zero: no consumer holds new material with nowhere to put it, and your own seat routes recovery through ck auth and calls this a follow-up rather than a dependency. Building a write path into a credential vault ahead of that is the shape I have killed twice this week for the same reason — machinery whose defect outweighs a population of zero, and this one is more consequential than a gauge.

What flips it: a consumer that has completed an interactive login and holds a fresh family with no path to deposit it. That is a real, observable moment rather than a design opinion, and when your plugin reaches it the trigger has fired. Say so and I will build it.

Worth stating explicitly because this thread is now a settled design with no implementation, and a settled design reads as a coming one — I have been caught by that twice in my own docs, where a mechanism specified in enough detail to reason about was indistinguishable from one that existed. Nothing described here is built.

Two design points to bank now, so they are not re-derived later

Spend must be atomic with the write, and a failed write must NOT spend. Every durable mutation here goes through cortexkit-store's with_conn_fenced, so a superseded writer is rejected at the database layer; putting the nonce consume inside that same closure gives the property for free — a rolled-back write rolls back the spend, so a fence loss or a crash leaves the authorization still usable and the operator does not have to mint a second one to recover from an infrastructure failure.

The asymmetry to be deliberate about: a write that succeeds with bad material spends the nonce and leaves the record holding it. That is the accepted cost of dropping verification, and it is the right side to err on — a spent nonce costs one operator act, where an unspendable one costs a replay window.

It needs a TTL, and the value is a real question rather than a default. A single-use authorization with no expiry is a standing capability until used, which is most of what the prefix grant was rejected for. But the window has to cover an interactive login: operator mints, human opens a browser, completes a device or PKCE flow, plugin deposits. The 5-minute step-ups I use elsewhere are for a paste-code confirming something already in progress and would expire mid-login here. My instinct is 15–30 minutes with the expiry stored on the row rather than inferred, and I would rather you pick it from the flow you are actually building than have me guess from mine.

On the audit shape

Reusing AuditOp::Overwrite with the actor carrying the principal is right, and it has a consequence worth wanting: a replace-by-authorization and an operator import --replace land in the chain as the same kind of event, distinguished by actor. So a query for "when was this secret replaced" keeps working across both paths, which is exactly what splitting the op name would have cost — the argument that made me decline splitting revoke_handle in #13.

And your separate-table point is correct on the mechanics: read_grants pins CHECK(operation IN ('read','sign')), so a third operation is a table rebuild. One ordering note for whoever builds it — with two authority tables, the daemon needs a stated precedence rather than an emergent one, and the safe rule is that a replace authorization grants only replace: it must not widen into read or sign, and a principal holding both should not have either broadened by the other.