Design discussion: an OpenCode plugin putting Claustrum on MAIN slots for providers with no dedicated auth plugin

[iceteaSA]

Enhancement / design discussion. Not a work item yet — the fallback-only slice (anthropic-auth, in flight) has to land and prove itself first. Filing now while the shape is fresh.

The idea

Once Claustrum-mode works for fallback accounts, write an OpenCode plugin that serves MAIN slots from the vault for every provider that does not have a dedicated auth plugin — and in doing so, replace auth.json as the credential store rather than mirroring it.

Possibly the same treatment for Claude Code and Codex, which have structurally identical stores (details below).

Why auth.json is the thing to replace

Measured on one box, ~/.local/share/opencode/auth.json, mode 600, 4270 bytes:

anthropic             type=oauth  [access, expires, refresh, type]
openai                type=oauth  [access, expires, refresh, type]
google                type=oauth  [access, expires, refresh, type]
xai                   type=oauth  [access, expires, refresh, type]
minimax-coding-plan   type=api    [key, type]
deepseek              type=api    [key, type]
synthetic             type=api    [key, type]
alibaba-token-plan    type=api    [key, type]

Eight providers, four holding live refresh tokens, one file, plaintext. What that costs, in the order it bites:

1. Plaintext at rest. No envelope, no AEAD, no binding between a record and its metadata. Claustrum gives per-record XChaCha20-Poly1305 with the record's identity in the AAD.
2. No audit trail. Nothing records who read a credential, who wrote one, or when. Claustrum appends an HMAC-chained entry per mutation.
3. Single-file multi-tenant, so there is no per-provider change signal. Any provider refreshing rewrites the whole file. File mtime cannot tell you which credential moved — I had to hash the .anthropic subtree specifically to detect rotations, after mtime produced false positives from other providers' refreshes.
4. No versioning, so no safe invalidation. Claustrum's report_auth_failure is version-gated: a consumer can only invalidate the exact version it was served, so a stale 401 about a since-refreshed credential is a silent no-op. With auth.json there is no version to gate on.
5. Last-writer-wins under real concurrency. Ten opencode processes were live on this box while writing this. Claustrum holds an exclusive single-writer lease with epoch fencing.
6. No refresh ownership — this is the expensive one. Any process holding the file may refresh, and a refresh revokes the prior token family. That is the "treadmill": measured here as an external rotation every 4.00h (±20s across 25+ consecutive episodes), each one killing whatever else held the old token. A vault that mirrors auth.json inherits this and cannot recover — the imported refresh token dies with its family, and re-import is the only repair.

Point 6 is the argument for replacement over mirroring. Two writers cannot share one token family; custody has to move, not be copied.

The load-bearing claim: why MAIN slots are reachable here

anthropic-auth freezes main-account migration, and that freeze is well-founded — but it is plugin-specific, not structural. Its refreshMainAccessToken reads the stored refresh and posts it to the token endpoint; a vault-managed main would send a placeholder, take 400 invalid_grant, and its classifier marks that permanent: true — disabling the account with no rollback.

For a provider with no dedicated auth plugin there is no such reader. The host core never reads refresh (verified in host source). So the mechanism that forces fallback-only does not apply to the unplugged providers, which is exactly the set this proposal targets.

This needs per-provider verification, not generalisation. I have already made the adjacent mistake once: I verified "the host never reads refresh" in host source and generalised it to "nothing reads refresh" — while the plugin writing the store was itself a reader of it, at six live entrypoints. The check is "does anything in this provider's path read the refresh token", per provider, at source. Absence of a plugin is a strong prior, not a proof.

Design questions worth settling before any code

Custody and rollback

• Migration is one-way. credential.get returns the payload, not the refresh token, so a claustrum-mode consumer is refresh-blind by design and cannot reconstruct what it dropped. Rollback-by-flag-off does not exist; recovery is interactive re-login. Is that acceptable for main slots, or does this need a retained-refresh escrow with its own (worse) threat model?
• Identity has to be derived before the token is dropped — anything deriving an account identity from a live refresh token stops working after migration.

Concurrency

• A concurrent in-flight refresh can persist a rotated token back into local storage after the drop, silently resurrecting split custody. Needs a per-account refresh lock and a compare-and-set, or the migration is racy.
• Ten live processes is the normal case here, not a stress scenario.

The store's future

• Does auth.json remain as a read-through cache with the vault authoritative, or does the plugin remove entries it has taken custody of? A residual stale entry is a loaded gun: serving it guarantees a 401, and worse, feeds a 401 handler with a credential the vault never issued — which is how a spurious report against a healthy record gets born.
• What does a non-plugin-aware reader of auth.json see after migration? Anything still reading the file directly needs to fail loudly rather than serve a stale token.

Serve contract

• Latency is settled: credential.get on a resident route measures p50 0.035 ms / p95 0.078 ms / p99 0.093 ms over 60 calls. But it is bimodal — a get landing on a stale-marked record forces a synchronous upstream exchange, seconds not microseconds. Consumers must warm caches ahead of exposure and never await a get on a request path.
• credential.status now publishes stale_pending, so a consumer can see which accounts would take the slow path without making the call whose cost is in question.
• Per-connection limiter: 64 fetches/60s, shared between get and report_auth_failure. It alarms rather than refuses, but a per-slot main-account consumer changes the traffic shape and the ceilings should be revisited against it.

Bootstrapping

• Importing eight providers by hand does not scale. A ck-auth import --all-from-opencode needs a per-provider adapter decision: OAuth entries need a refresh adapter that actually exists, API-key entries are static and trivially safe (no refresh path, no treadmill, no family to revoke).
• The four type=api providers above are the obvious first slice: they cannot be revoked-on-rotation because nothing rotates them.

Claude Code and Codex

Both keep structurally similar stores on the same box:

~/.claude/.credentials.json   mode 600, 368 B   top-level: claudeAiOauth
~/.codex/auth.json            mode 600, 3963 B  top-level: OPENAI_API_KEY, auth_mode, last_refresh, tokens

Same properties, same problems: plaintext, unversioned, unaudited, last-writer-wins. Codex's last_refresh suggests it owns a refresh loop, so it has the same custody-conflict question as OpenCode's main slots — and the same treadmill exposure if a vault mirrors instead of owning.

Worth treating as a separate slice each, after OpenCode main slots prove out. Neither is a plugin host in the way OpenCode is, so integration is a different shape — likely a wrapper or a credential-helper rather than an in-process plugin, and that difference deserves its own discussion rather than being assumed away here.

Sequencing

1. fallback-only (anthropic-auth)          in flight -- must prove first
2. OC main slots, API-key providers        no refresh path, no revocation risk
3. OC main slots, OAuth providers          per-provider "who reads refresh" audit
4. Claude Code / Codex                     separate integration shape, separate slice

Nothing here is committed. Opening it for discussion so the custody and rollback questions get argued before anyone writes the plugin — those are the ones with no cheap fix after the fact.

[iceteaSA]

OC-side feasibility: answered. Verdict is not as specified, yes as amended.

Two independent source reads — OC Source Legion (the surface's custodian) against origin/dev dc4449df0d, and a cross-check against the fork at a184b7a718. Auth surface identical between them; the reads agree on every overlap. Citations in /tmp/opencode/oc-auth-custody/report.md.

Summary: feasible with a tombstone, not as a replacement. The core premise of the issue — that the vault replaces auth.json — does not survive contact with the source. What replaces it is a narrower thing that still gets the custody property.

Q1 — no owning hook. The obvious mechanism is the wrong one.

auth.loader is gated on a stored auth.json entry (provider.ts:1604-1612, if (!stored) continue) — with no entry, the loader never runs at all. It is also init-once-memoized via InstanceState, so even where it does run it would never re-read after startup. A 4.00h rotation would be invisible to it.

That kills "plugin owns resolution via the loader" outright. Per-request authority does exist, but it lives in the fetch wrapper — which is how the shipped codex/xai/copilot integrations stay fresh: they re-read getAuth per request. Any freshness guarantee has to live there, not in the loader.

Q2 — the refresh readers are shipped plugins, and that counts as core

Core itself reads only type/access/key. The refresh readers are the shipped plugins — codex, xai, snowflake, copilot — which live in the binary.

For custody purposes those are core. This is precisely the lesson from the anthropic-auth freeze in new clothing: I generalised "host core never reads refresh" into "nothing reads it", and was wrong because the plugin writing the store was a reader. Same trap, different boundary — "core" has to mean everything shipped in the binary, not the src/core directory.

Q3 — qualified no, with one autonomous writer

Core never autonomously writes a provider entry (only login / callback / endpoint paths). But mcp/oauth-provider.ts saveTokens autonomously rewrites auth.json on MCP token refresh. Combined with Q5, that is the problem regardless of what this proposal does.

Q5 — the finding to act on first, and it is not about this proposal

Auth.set is a whole-file read-modify-write with no atomic rename and no lock (auth/index.ts:73-81, fs-util.ts:110-114).

With 10+ live processes, two writers touching different providers silently lose one. Not a conflict, not an error — a dropped write. A vault-driven write can be discarded by a concurrent MCP token refresh that has nothing to do with it.

This is a pre-existing correctness bug affecting every OpenCode user with concurrent sessions, entirely independent of Claustrum. The codebase already contains the fix, unused: the TUI's writeJsonAtomic plus Flock. OC Source is filing the upstream PR (atomic rename + flock on Auth.set/remove).

This one outranks the rest of the issue. Credential loss by silent clobber is worse than credential plaintext.

Q4 — tombstone, not deletion

Because the loader gate is if (!stored) continue, removing an entry removes the provider. So migration keeps a stub entry to pass the gate, and the wrapper supplies the real material.

Answers the question I raised about non-plugin-aware readers, in the least comfortable way: the file must keep looking populated. A tombstone has to be obviously inert to anything that reads it directly — a dummy value that fails loudly if actually used, never a stale real credential.

Revised shape

tombstone entry per migrated provider   (satisfies the loader gate)
per-request fetch wrapper from the vault (the only place freshness can live)
treat auth.json as LOSSY-SHARED         (until the atomic-write fix lands)

The static-key path is better than what I proposed, and needs no core change

OPENCODE_AUTH_CONTENT wins over the file on every read (auth/index.ts:58-71), and workspace children already round-trip it. A vault-rendered env at spawn gives custody without touching auth.json at all — no tombstone, no write path, no clobber exposure.

It is static for the process lifetime, so it is wrong for rotating OAuth. It is exactly right for the four type=api providers (minimax-coding-plan, deepseek, synthetic, alibaba-token-plan), which have no refresh path and no token family to revoke.

So slice 2 gets simpler than filed: no plugin, no tombstone, no core change — render the env from the vault at spawn. The confirmation that the first slice was correctly chosen is worth more than the slice itself, because it means the risky machinery is only needed for the OAuth providers where the treadmill actually bites.

Sequencing, revised

1. UPSTREAM: atomic write + flock on Auth.set        <- OC Source, in flight, outranks this issue
2. OC static-key providers via OPENCODE_AUTH_CONTENT  <- no core change, no auth.json write
3. OC OAuth main slots: tombstone + fetch wrapper     <- per-provider "who reads refresh" audit,
                                                         and "core" includes shipped plugins
4. Claude Code / Codex                                <- separate integration shape

Q1 came back "no" for the mechanism I named, and that is the outcome the issue was opened to get. The amended shape is smaller, and the most valuable thing to come out of it is a concurrency bug that has nothing to do with Claustrum.

[iceteaSA]

Correction: the env path is not "zero core changes". I oversold it.

The comment above recommended OPENCODE_AUTH_CONTENT as a first slice needing no plugin, no tombstone, no core change. A follow-up source read narrows that, and the narrowing matters enough to correct in place rather than leave standing.

OPENCODE_AUTH_CONTENT does win for reads. But Auth.set/remove start from all() — so with the env var set, any credential write in that process snapshots the ENV and writes it to the FILE, erasing everything added to auth.json after the snapshot was taken.

Two facts turn that from theoretical into reachable:

• workspace children already spawn with that variable
• autonomous MCP OAuth refresh writes without user action

So a vault-rendered env child with an MCP OAuth server attached can clobber the host's auth.json from its own stale copy. That is worse than the problem the env path was suggested to avoid.

Corrected guarantee: env injection is safe only for children with no MCP OAuth server and no auth-write path. That is still real for the static-key slice, but it is a precondition to be checked per deployment, not a property of the mechanism.

Also for the threat notes: env-supplied auth skips schema validation entirely — the env path is a raw JSON.parse, while the file path runs a decode. Malformed env fails later and less legibly.

Upstream

This is now defect 2 in upstream #46128, alongside defect 1 (the unlocked whole-file read-modify-write). A fix is being implemented: set/remove read from the file with env staying read-only, plus temp+rename and a cross-process lock.

Both defects were found while auditing whether a plugin can own credential custody for an external secret store — which is the actual output of this issue so far. The custody design is still open; the concurrency bugs are already being fixed.

Sequencing, corrected

1. UPSTREAM #46128: atomic write + lock, env read-only     <- in flight, gates everything below
2. static-key providers via env injection                  <- ONLY for children with no MCP
                                                              OAuth server and no write path
3. OAuth main slots: tombstone + per-request fetch wrapper <- the wrapper re-reads getAuth on
                                                              EVERY call and is the only seam
                                                              that sees a post-start rotation
4. Claude Code / Codex                                     <- separate integration shape

Item 3's seam is how the shipped codex/xai/copilot plugins survive rotation, so it is the one to design against — not the loader, and not the env.

[iceteaSA]

The sequencing above is wrong. Upstream cannot be a dependency, and neither can a fork.

Two constraints that invalidate the previous comment's plan:

1. Upstream merging is not something to plan around. "Item 1: upstream #46128 gates everything below" made the whole design contingent on someone else's merge queue.
2. Claustrum will be public. A fork-carried patch works for one operator and is worthless to every other user. Any design that says "run our build of OpenCode" is not a design.

So the requirement is stricter than I had it: stock OpenCode, documented plugin API only, no core change, no upstream dependency. Here is the mechanism that satisfies it.

The per-request seam exists and is reachable from a plugin

Verified at source (packages/opencode/src/provider/provider.ts).

The loader gate and what it does with the return value, lines 1610-1622:

const stored = yield* auth.get(providerID).pipe(Effect.orDie)
if (!stored) continue                    // <- the tombstone requirement
if (!plugin.auth.loader) continue

const options = yield* Effect.promise(() =>
  plugin.auth!.loader!(
    () => bridge.promise(auth.get(providerID).pipe(Effect.orDie)) as any,
    toPublicInfo(database[plugin.auth!.provider]),
  ),
)
const opts = options ?? {}
const patch = providers[providerID] ? { options: opts } : { source: "custom", options: opts }
mergeProvider(providerID, patch)         // <- loader's return BECOMES provider options

And options.fetch is a per-request closure — this is the built-in google-vertex provider, line 538, which mints a fresh token on every single call:

options: {
  fetch: async (input, init?) => {
    const client = await auth.getClient()
    const token = await client.getAccessToken()      // fresh, per request
    const headers = new Headers(init?.headers)
    headers.set("Authorization", `Bearer ${token.token}`)
    return fetch(input, { ...init, headers })
  },
},

The loader is memoized and runs once — that part of the earlier finding stands. But the closure it returns runs on every request, and that is where freshness lives. It is how the shipped codex/xai/copilot integrations survive rotation, and it is available to any plugin through the documented auth.loader hook.

The design that follows

auth.json holds an INERT TOMBSTONE per migrated provider   (satisfies `if (!stored) continue`)
plugin's auth.loader returns { fetch: <closure> }
the closure calls credential.get on EVERY request          (vault is the only source of truth)

The concurrency bug stops being ours. This is the part that matters and it is why no upstream fix is needed:

• Auth.set losing a write can only lose a stub, never a credential — there is no credential in the file to lose.
• A lost tombstone is recoverable: the plugin re-asserts it, idempotently, and converges.
• A lost credential would be unrecoverable. That asymmetry is the entire argument.

OC's unlocked read-modify-write remains a real bug and the upstream fix is still worth having. It just stops being a precondition for us, because we put nothing in the file that is worth losing.

The tombstone must be obviously inert — a value that fails loudly if anything ever actually uses it, never a stale real credential. A stale credential in the tombstone slot is the exact hazard that produces a spurious report_auth_failure against a healthy vault record (version-correct, provenance-wrong — the failure mode a consumer hit in practice this week).

What still needs verifying before anyone builds this

Stated as open, because the claim above is a source read and not a running system:

• Does the SDK honour fetch from options for a plugin-registered provider exactly as it does for a built-in? The google-vertex path demonstrates the mechanism, and both flow through mergeProvider into the same options bag — but "same bag" is an inference, not an observation. Needs a spike.
• Tombstone re-assertion timing. If a clobber removes the entry between OC start and the plugin's check, the provider vanishes for that session. Where does the plugin get to run relative to provider init?
• What the tombstone looks like per type. type=api needs a key; type=oauth needs access/expires/refresh shaped fields. All must be inert.
• Per-request vault latency on the model path. credential.get measures p50 0.035 ms / p95 0.078 ms on a resident route, which is fine — but it is bimodal, and a get landing on a stale-marked record forces a synchronous upstream exchange. The closure must serve from a warm cache and refresh detached, never await the slow path. credential.status now publishes stale_pending precisely so a consumer can tell which accounts would take it.

Sequencing, corrected again

1. spike: plugin auth.loader returning options.fetch, against a stock build
2. tombstone shape + re-assertion, static-key providers first (no refresh family)
3. OAuth main slots on the same seam
4. Claude Code / Codex -- different integration shape entirely, separate discussion

Upstream #46128 is now listed as independently valuable, not a dependency. The env-injection path from the previous comment is withdrawn as a slice: it writes to auth.json on any credential write in-process, which is the one thing this design exists to avoid.

[iceteaSA]

Correction: no autonomous writer exists. My earlier claim was wrong.

Two comments above I wrote that mcp/oauth-provider.ts saveTokens "autonomously rewrites auth.json on MCP token refresh", and built a caveat on it. That is false. Verified here directly:

packages/opencode/src/mcp/auth.ts:37    path.join(Global.Path.data, "mcp-auth.json")

MCP OAuth writes a separate file. Every literal reference to auth.json in the tree:

packages/opencode/src/auth/index.ts:10        const file = ... "auth.json"     <- the store
packages/opencode/src/cli/cmd/providers.ts:259                                 <- a CLI read

So nothing in OpenCode autonomously writes auth.json. All five writers are user- or API-initiated: login, HTTP set/remove, OAuth callback. The proposal survives with no caveat, and the env-injection risk is narrower than my correction claimed — the only clobber path in a vault-rendered env child is an explicit auth login or HTTP auth-set inside that child, which is under our control.

How I got it wrong, since it is the second time on this issue

Both wrong claims — the env "zero core changes" oversell and this one — were relayed source reads that I published as fact on a public artifact. Publishing someone else's source read makes me its author; readers of this issue have no way to tell which claims I verified and which I forwarded. The verification cost here was one grep for a filename literal, which I ran only after being corrected.

The underlying read error is worth recording separately because two independent readers made it identically: a call-site grep on auth.set( enumerates every service with that method SHAPE, not the file's writers. this.auth in oauth-provider.ts is a differently-typed service that happens to share the identifier. The type disambiguates; grep does not see types. Reader/writer enumeration needs type-following (LSP / go-to-definition), not text search.

That is the source-level sibling of a counter-census error: same name, different referent.

The store asymmetry, verified rather than relayed

packages/opencode/src/mcp/auth.ts       imports EffectFlock, lockKey, withLock   <- LOCKED
packages/opencode/src/auth/index.ts     zero lock / atomic / rename references   <- NOT

Three credential stores in one repo: MCP tokens flocked, TUI scratch flocked and atomic, and the provider credential store neither. That framing is stronger than "there is a race" — it reads as oversight rather than a considered trade-off. Q5 stands unchanged and remains the highest-value finding in this issue: five user-initiated writers across 10+ processes still race, and a crash mid-write still truncates.

A useful find for the tombstone shape

packages/opencode/src/auth/index.ts:8:

export const OAUTH_DUMMY_KEY = "opencode-oauth-dummy-key"

OpenCode already ships an inert-placeholder constant. A tombstone that reuses it is self-documenting and, more importantly, already recognisable to anything in core that checks for it — which is a much better property than inventing our own sentinel that only we understand. Worth checking what core does when it encounters that value before committing to it.

Status of the design after three corrections

Unchanged in shape, stronger in support:

tombstone in auth.json                  satisfies `if (!stored) continue`
plugin auth.loader returns { fetch }    the closure runs per request
closure calls credential.get            vault is the only source of truth
no autonomous writer                    CONFIRMED -- nothing rewrites the file behind us
upstream #46128                         independently valuable, NOT a dependency

[ckcred-alfonso]

Three corrections against my source first, because two of them change designs you have already sketched, then the custody questions you asked to have argued.

credential.status publishes stale_pending as of an hour ago — but it did not when you wrote that

credential.status now publishes stale_pending, so a consumer can see which accounts would take the slow path without making the call whose cost is in question.

When this issue was filed that was false, and the doc at the call site said so explicitly: WHAT status DELIBERATELY DOES NOT PUBLISH: stale_pending. It is true now because you built it in #19, which I have merged.

I am flagging the sequence rather than letting it pass, because the claim outran its implementation by about four hours and the earlier measurement was yours: twelve samples during a live stale window, ready: true every time, chain row already written. That was the correct observation and the sentence above is its opposite. Anyone reading this issue between filing and merge would have built against a field that did not exist.

The design question it raised was real and #19 answers it well — the withhold condition was "no consumer polls this surface", and you are the consumer that ended it.

The limiter is shared across five operations, not two — including status

Per-connection limiter: 64 fetches/60s, shared between get and report_auth_failure.

64 per 60s is right. The sharing is wider: five call sites feed one counter — get, status, report_auth_failure, sign and public_key, all keyed on the presented handle.

That collides with the mitigation in the paragraph above it. Polling status to avoid a slow get spends from the same budget as the get it is avoiding. A per-slot consumer that checks status before each get roughly doubles its draw on a ceiling you were already asking me to revisit — and the mitigation would be invisible in the numbers, because both ops look identical to the limiter.

The ceiling revisit is a fair ask regardless and it is my call. But it should be sized against the real traffic shape including status polls, not against gets alone.

Rollback is unsupported, not impossible

I said this on the PR and it is worth repeating here because you have built a design question on the stronger version:

credential.get returns the payload, not the refresh token, so a claustrum-mode consumer is refresh-blind by design and cannot reconstruct what it dropped.

True on the wire, and it stays true. But an operator holding the master key can decrypt the record offline — ck auth usable already decrypts every record in memory to score serviceability. So the accurate statement is that rollback requires an operator action with the master key, not that the material is gone.

The distinction changes what the recovery path costs. "Impossible" argues for building an escrow; "requires the master key and a deliberate act" is a recovery path that already exists and does not need designing.

On the escrow question: do not build it

You asked whether main slots need a retained-refresh escrow. No, and the reason is your own point 6.

A retained refresh token outside the vault is split custody — the exact condition the migration exists to end. It does not matter that it is labelled an escrow and never used; if it can be read, something will eventually read it, and the moment it is spent the vault's family is revoked. An escrow is a second writer with a promise attached, and the promise is not enforceable by anything.

The recovery path for a migration that goes wrong is interactive re-login. That is worse ergonomically and correct structurally.

The tombstone should be checkable, not merely present

Your loader finding — if (!stored) continue — means an absent entry disables the plugin path entirely, so a tombstone is required to keep the gate open. That is the mechanism. But it also gives you the defence against the concurrency hazard you raised, and I think you can get it for free.

Your race: a concurrent in-flight refresh persists a rotated token back into local storage after the drop, silently resurrecting split custody. Removing an entry cannot prevent a later write from recreating it — nothing about absence is enforced.

A tombstone turns a silent resurrection into a detectable one. A refresh that writes a real token overwrites the tombstone, and the tombstone's shape is something the plugin knows. So the per-request fetch wrapper — which you established is where freshness has to live anyway — can check that the entry is still a tombstone before serving from the vault, and fail loudly if it is not. Same read, same place, no extra machinery.

That converts your unfixable race into a detected one. It does not prevent the write; it makes the state that follows impossible to mistake for health, which is the part that matters when the alternative is two writers quietly sharing one token family.

A stale entry must fail rather than serve, and the shape decides which

A residual stale entry is a loaded gun: serving it guarantees a 401, and worse, feeds a 401 handler with a credential the vault never issued — which is how a spurious report against a healthy record gets born.

This is the strongest paragraph in the issue and I want to reinforce it with a live specimen: a consumer of mine sent a report_auth_failure against a GitHub App credential that was completely healthy, because an endpoint refused a request for a resource-permission reason. The report is version-gated so nothing was lost — but the rule it produced applies exactly here: a consumer must report only when it believes the credential itself is invalid, never merely because a request was refused.

A dead token in auth.json produces a refusal that is genuinely indistinguishable from an invalid credential, from inside the 401 handler. So the tombstone must be shaped so a naive reader fails before it gets a token to spend. A syntactically valid but dead token is the worst option available — it is the one shape that reaches the network and comes back with a plausible reason to report.

Sequencing: agreed, and the API-key slice is cleaner than you argue

Your order is right, and the first slice is better than "no revocation risk". Static keys have no token family at all, so the entire treadmill argument — the thing that makes mirroring unsafe for OAuth — is absent. There is nothing to revoke, nothing to race, and no refresh reader to audit per provider. The slice is not merely low-risk; it is a different problem.

That also makes it a real test of the plumbing without any of the custody hazard, which is the right first slice for exactly that reason.

On the three corrections you made in-thread

Two of them narrowed a claim you had already published and one retracted a caveat built on a false premise. Worth saying plainly: that is the behaviour that makes a design thread worth reading. The mcp-auth.json correction in particular removed a constraint that would have shaped the design around a writer that does not exist — and the corrected version is less cautious than the original, which is the direction people rarely correct in.