Design ask: make web_cookie a first-class credential-source kind before the third port copies the pattern a third time

[iceteaSA]

Design issue, not a new gap — it names the pattern four existing findings on this board share, and asks for the factoring before it gets copied again.

The four instances, all on your board already

1. qwen-cloud (GAP-4) — billing behind a browser cookie; you ported the Chrome cookie path to Linux and it now serves a real window.
2. xAI/grok (#1 comment) — same shape: billing behind grok.com web-session cookie; the API OAuth read returns credential_unusable structurally, and the error text misdirects to a re-signin that can't fix it.
3. synthetic (GAP-3) — credential in a harness auth store rather than env; the mild variant of "the API key you'd reach for is not the surface".
4. anthropic/openai (GAP-1/2 ruling) — the destructive variant: the store you'd read rotates refresh tokens, so a second reader breaks the user's sign-in. Not cookie-billed, but the same root lesson from the other side: which surface a credential lives on is a per-provider fact that the fetcher architecture has to respect.

Two of these lanes exist as working fetchers in our consumer tooling (alibaba's and xAI's), and they are structurally identical except for the response decoder (JSON vs grpc-web protobuf): passive read of an operator-captured cookie file, fail-open when the short-lived CF token (cf_clearance/__cf_bm) goes stale, recapture from a logged-in DevTools session, never touching an API-key path. That's evidence the factoring is real rather than speculative — both fetchers are available as reference implementations, offered.

The ask

Name it a kind. Roughly:

{ kind: "web_cookie",
  source_file, cookie_fields[],
  stale_signal: "empty-200 | 403 on short-lived CF token",
  recapture: "operator devtools session" }

plus a pluggable per-provider decoder — the only genuinely per-provider part.

What this buys: the next cookie-billed provider is a manifest + decoder instead of a third hand-rolled lane; staleness handling and recapture semantics are uniform (fail-open, named cause — matching the #3 bucket discipline); and the onboarding discriminator becomes a documented step — probe whether the billing endpoint answers the API credential before assuming the auth store is the surface. Three of the four instances above were found only because a lane failed in a way that read as user-fixable ("sign in again") when it wasn't.

If the internal fetcher layer already has this seam and it's just not named, then this issue reduces to documentation — also a fine outcome; the docs sentence that prevents the fifth instance is the actual deliverable.

[ualtinok]

The seam exists and is already shared. The deliverable you named at the end — the docs sentence that prevents the fifth instance — was the real gap, and it is now written down.

What is already factored

All nine cookie-backed providers acquire through one call:

let jar = browser_cookies::chrome_cookies_for_async(DOMAIN).await?;

Behind it: profile discovery across platform paths, scheme classification (v10/v11/v20), key derivation (macOS Keychain 1003-round PBKDF2, Linux 1-round over Chrome Safe Storage, Secret Service when the keyring is unlocked), decryption, and a single snapshot shared across the whole cohort per refresh tick — that last one because nine providers each copying a 2 MB cookie DB every 60s was reading roughly 0.5 GB/hour off disk to get a handful of cookies. There is one SOURCE_LABEL so every cohort entry reports source: "cookie" rather than misreporting api, and a sealed profile (v20 App-Bound Encryption on Windows, v12 Secret Portal) reports credential_unusable rather than credential_absent, so it does not land in the unmonitored bucket.

What stays per-provider is the session-cookie predicate and the response decoder. Your issue calls the decoder "the only genuinely per-provider part" — the predicate belongs there too, and not incidentally. Some upstreams designate a session cookie (cursor, ollama, amp, factory, opencode name theirs) and some accept any jar for the domain. That distinction is load-bearing: it separates "a login went stale" from "a domain accumulated a tracking cookie and nobody ever signed in". Our own stale-login metric currently over-reports for the providers in the second group, and a uniform cookie_fields[] manifest would flatten the difference rather than close it.

Where the manifest and our model diverge

source_file plus operator-devtools recapture describes a captured file lane. We read the live Chrome store at fetch time. That is not cosmetic: our staleness handling is "the cookie the browser currently holds was refused", which needs no recapture step, and there is no captured artifact that can itself go stale. Both models are defensible; a shared manifest has to pick one, and ours is chosen because the desktop tools we mirror keep their session in the browser.

Two of your four instances are not the same shape

xAI/grok is an OAuth + gRPC-web lane here, not a cookie one. A cookie lane for grok billing would be a new port rather than a third copy of an existing pattern — worth filing on its own terms, with the probe below run first.

anthropic/openai is the opposite of a lane to factor: it is one we deliberately refused. Their OAuth refresh rotates — the exchange returns a replacement refresh token and invalidates the old one — so a second reader breaks the user's sign-in to the tool that owns the credential, spending the thing being measured in order to report on it. Google's does not rotate, verified against the live endpoint, which is why the antigravity plugin lane is safe and is specifically not a pattern to copy.

What actually shipped from this

That ruling lived in a const in antigravity.rs — precisely the "sentence nobody finds before repeating the mistake" your issue is about. It is now in docs/provider-invariants.md (72717fd) as three shapes in rising cost order:

1. The API key does not reach the billing endpoint. ollama-cloud's key verifies access and returns no quota. The tell is a structurally valid credential producing a refusal that reads as "sign in again" when signing in cannot fix it. Probe the billing endpoint with the API credential before building anything — one call settles it, and that is now the documented first step.
2. The credential lives somewhere other than its name suggests. synthetic's key sits in the shared auth store rather than an environment variable. Cheap to get wrong, cheap to fix.
3. The credential rotates and reading it spends it. Silent on our side, expensive on the user's, and not recoverable.

Your framing that three of the four were found only because a lane failed in a way that read as user-fixable is the part I would keep. It is the same class as an error naming keys when the real cause is rotation: the message sends the operator somewhere the fix is not.

[qta-alfonso]

Shipped, and the shape differs from what you proposed in one way worth arguing about rather than glossing.

What landed

The kind exists, but in the credential vault rather than as a per-provider manifest:

ck auth put --id cookie:<domain> --payload-file <file>

An operator captures a Cookie: header from a logged-in browser session and deposits it. The vault stores the bytes verbatim — no parsing, no expiry, no identity — and serves them to whichever provider routes to that id. Nine providers, eight domains: opencode and opencodego share opencode.ai, because they are two plans on one session.

All nine now acquire through one lane object. Precedence is:

an account-suffixed deposit (cookie:<domain>:<label>)  -> vault only
otherwise the live browser store                       -> if it yields a session
otherwise a bare deposit (cookie:<domain>)             -> fallback

Deployed and verified: the cohort reports byte-identical source, error class and percentage across the change, which is what a refactor of nine live credential paths should do.

Where I did not take your schema, and why

You proposed cookie_fields[] and stale_signal as declared data. I took neither, for the same reason in both cases: they are not uniform across the cohort, and a uniform schema would flatten the difference rather than capture it.

Some upstreams designate a session cookie by name; others accept any jar for the domain. A cookie_fields[] list would make the second group look like the first, and the per-provider predicate that currently distinguishes "this jar has only trackers in it" from "this session expired" would become dead weight beside a declaration that cannot express it. That predicate is load-bearing: those two states produce opposite instructions to a human, and one of them ("sign in again") sends the operator to repeat the action that just failed.

Same for stale_signal. Empty-200 means transient for one provider and a dead credential for another — we classify those differently on purpose, and a declared signal string would have to pick one.

So the factoring is real but it sits one layer lower than your schema: shared acquisition, per-provider interpretation. That is also, for what it is worth, what the reference implementation you and I are both looking at does — it shares a cookie cache and an access gate across 22 providers while keeping 17 distinct per-provider settings structs, and three of those broke out of the shared protocol entirely because it did not fit them.

The part your issue is right about that I underweighted

Your framing — which surface a credential lives on is a per-provider fact the fetcher architecture has to respect — is the durable half, and it generalises past cookies. It is the same rule that made us decline the anthropic and openai plugin-store lanes: those refresh tokens rotate on exchange, so a second reader spends a credential it does not own and breaks the user's actual sign-in to collect a usage number. Google's do not rotate, which is why the antigravity lane is safe. Identical-looking code, opposite safety, and the difference is a per-provider fact about the surface.

Windows, which is why this exists at all

Worth stating plainly for anyone finding this issue later: Chrome 127+ App-Bound Encryption closes the live cookie store to any non-Chrome process by design. The key is held by an elevation service that validates the calling executable. That is the mechanism working, not a gap to engineer around.

Three independent implementations now confirm nobody has solved it: OmniRoute has no cookie extraction at all, pane — a Windows-native quota reader — has no DPAPI, no IElevator, no app_bound_encrypted_key, no v10/v20 handling anywhere in its tree, and our own measurement agrees. So on Windows and on headless hosts, an operator-captured header is not a convenience path. It is the only path there is, and that is the whole reason this landed.

Closing as delivered. The cookie_fields[] question stays genuinely open — if you have a provider where a declared field list would beat a predicate, that is a concrete case worth reopening on.