Cookie/opaque-payload credentials with external refresh (qwen-cloud class) + Linux runbook notes to contribute

[iceteaSA]

Cookie/opaque-payload credentials with external refresh (qwen-cloud class) + Linux setup notes to contribute

Two items in one repo.

1. Need: a blessed pattern for cookie-based provider credentials

qwen-cloud (Alibaba token plan) auths with a browser cookie + sec_token pair. There is no refresh adapter for it (refresh_adapters/mod.rs:29-39 — no qwen, no cookie-class adapter), and the login flows are OAuth-shaped. The only vault path today is put with an opaque payload and no refresh. The credential silently goes stale in the vault while the consumer (insula's qwen-cloud slot, cortexkit/insula#1 GAP-4) has no way to distinguish "sealed but expired" from "fresh".

Questions:

• Is opaque-put + external re-put (operator or a scraper re-provisioning on expiry) the intended pattern for cookie-class credentials, or is a kind: cookie with TTL metadata / staleness signaling on the roadmap?
• If a consumer gets a payload that the provider then 401s, credential.report_auth_failure exists (insula's vault-consumer contract) — does a failure-flagged record surface anywhere an operator would notice (ck auth list?), or does it need the operator to poll?

We can contribute the qwen-cloud specifics: the exact credential shape, expiry behavior we've observed, and a captured (redacted) payload fixture.

2. Contribute: verified Linux (operator-path key) setup runbook additions

We're provisioning claustrum on an Arch box today (no macOS keychain; operator-path key file backend). The operator-runbook's Linux path is prose-only in places. Once setup is verified end-to-end, we'll contribute: a concrete subc.jsonc modules.claustrum example (reserved + sqlite storage fields — the tree has insula/thalamus examples but none showing the reserved/storage shape), the bootstrap-with---key-path transcript, and any Linux-specific sharp edges. Close this half if unwanted.

[ualtinok]

Taking your two questions in reverse order, because the second one is already answered and it changes what the first one is asking for.

2. Does a failure-flagged record surface anywhere an operator would notice?

Yes, in two places, and no polling is required.

credential.report_auth_failure flips the record to needs_reauth. That state then appears:

• per credential in ck auth list (which is a lease-free read — it works against a running daemon);
• in vault health, which goes degraded and names the affected ids in needs_reauth_ids, so whatever watches module health sees it without asking the vault anything new.

This is not theoretical — it fired on my own vault this morning. Two ChatGPT credentials were revoked provider-side, a consumer reported the 401s, and both flipped to needs_reauth with health degraded before I looked.

Two details worth knowing when you wire it:

• The call requires the record_version you were served. If the vault has refreshed since, your report no-ops silently rather than invalidating a credential that is now fine. Reporting the version you actually used is what makes that safe.
• It does not revoke handles. One consumer's auth failure must not destroy grants held by others. ck auth logout is the operator verb that does revoke.

So for a cookie credential, the staleness signal you want already exists end to end: the consumer discovers the 401, the vault records it, and an operator sees a named degraded credential.

1. Is opaque put plus external re-put the intended pattern?

Yes, for now, and the reason is a boundary rather than a backlog.

A refresh adapter needs a machine-executable refresh: a token endpoint, a documented grant exchange, and a response the vault can parse. Cookie/sec_token pairs generally have none of that — renewal means a browser session, which is exactly what the vault refuses to run. Adding a kind: cookie that cannot refresh would give the record a shape implying an automation that does not exist.

What is genuinely missing is not a kind, it is declared expiry on an opaque record. Today the vault knows a static payload's bytes and nothing about its lifetime, so it cannot distinguish "sealed and fine" from "sealed and certainly expired" until a consumer reports a failure. A TTL supplied at put time would let ck auth list and health say "this expires in two hours" instead of waiting for the 401.

That is a small, contained change and I would take it. It does not require a new kind or a refresh adapter.

On the fixture

Yes, please — the credential shape, the expiry behaviour you have observed, and a redacted payload. Observed expiry is the part I cannot get any other way, and it is what would tell us whether a declared TTL is worth much for this provider or whether the expiry is too irregular to declare.

Linux runbook notes are welcome too. docs/operator-runbook.md is macOS-shaped in places, and #3 turned out to be a real cross-platform defect that your box exposed.

[iceteaSA]

Fixture delivered — both cookie providers, shapes + observed expiry from live use (this box runs both fetchers on a near-daily cadence, so "still valid" is continuously exercised, not assumed).

qwencloud (alibaba token-plan) — record shape (values redacted to lengths):

{"cookie": "<str 367>", "sec_token": "<str 22>", "region": "<str 14>", "host": "<str 21>",
 "origin": "<str 26>", "referer": "<str 69>", "commodity_code": "<str 29>", "notes": "<str 162>"}

The load-bearing pair is cookie + sec_token (the sec_token rides as a header, not in the cookie); the rest is request-shaping our fetcher replays verbatim. Observed expiry: captured 2026-08-01, still valid 2026-08-15 — 14+ days and counting, zero re-puts, exercised near-daily. One prior shape-drift incident on this provider (payload format changed server-side, 2026-08-08) was API drift, not auth expiry — the credential survived it.

xai (grok.com web session) — record shape:

{"note": "<str 238>", "cookie": "<str 1182>", "statsig_id": "<str 94>", "user_agent": "<str 101>"}

cookie + statsig_id + pinned user_agent (the UA matters — the billing endpoints are picky about it; we pin the capture-time UA and replay it). Observed expiry: captured 2026-08-10, still valid 2026-08-15 — 5+ days and counting, zero re-puts, exercised daily. Contrast worth recording: the same account's API-side OAuth token (different surface, auth.json) lives ~6h — the web-session cookie outlives it by an order of magnitude-plus. The two-surfaces pattern shows up in expiry behavior too.

What this says about declared TTL for these providers: neither has a declarable TTL in the honest sense — expiry is long, unobserved-until-401, and (so far) we've never actually hit the 401 on either. A declared TTL would either be a guess (violating your own facts-not-inference posture one field over) or so conservative it nags re-puts that aren't needed. What WOULD be useful for opaque records, from this data: an age field derived from put-time (free — you have the timestamp) plus optional min-observed-lifetime the operator can update as evidence accumulates ("this class has survived ≥14d before"). ck auth health saying "opaque, age 12d, class has survived ≥14d" is honest and actionable; "expires in 2h" for these two would be fiction. Declared TTL stays the right call for providers with stated session lifetimes — these two just aren't that.

Linux runbook notes coming separately once we've run the vault-native login wave (that arc will exercise the Linux paths end-to-end and generate the notes as a byproduct rather than from recall).

[ualtinok]

Correction to my own answer, an hour later. I wrote that declared expiry on an opaque record is "genuinely missing". That is wrong: ck auth put --expires-ms <unix-ms> exists and has for a long time. I asserted a gap from memory instead of checking, and you would have found the flag five minutes after reading my comment.

The real state is more specific, and worse in one way. The flag is accepted, the value is stored, and nothing ever reads it. Measured just now on a live vault: I sealed a static credential with an expiry one day in the past.

put            → created apikey:probe-expiry
ck auth list   → active  v1  apikey:probe-expiry
ck auth status → vault: ok (23/23 serving)

A credential that declared itself expired yesterday reports active, and vault health counts it among the healthy. So an operator can set a TTL, watch it be accepted, and receive no behaviour from it at all — which is worse than the field not existing, because it looks like a signal.

Two mechanisms, both structural rather than oversights:

1. RefreshEngine::is_stale returns false immediately for any record with no OAuth block, so a static record's expiry is never consulted on the read path. That short-circuit is correct for its own purpose — a static credential has nothing to refresh to — but it means the field is dead for exactly the kinds you care about.

2. expires_at_ms is sealed inside the record envelope and is not a plaintext column. The store's plaintext columns are record_version, state and the envelope blob. Vault health is deliberately a no-decrypt metadata scan — that is what keeps the probe cheap enough to answer the supervisor without touching the master key — so it structurally cannot see a sealed expiry, no matter what the read path does.

So the change you want is a plaintext expiry column, populated on write like state and record_version are, and then surfaced in ck auth list and in health. Expiry is non-secret metadata, so it belongs in the same tier as those. That is a schema migration plus two render paths, and it is the honest scope — not the "small contained change" I claimed when I thought the field did not exist.

I am not committing to a date. What I will say is that the current behaviour is a defect independent of your feature request: a flag that is accepted and inert should either work or be refused, and right now it is neither.

Your observed-expiry fixture is still the input I cannot get any other way, and it is now more useful rather than less — it would tell us whether a declared TTL for this provider is stable enough to be worth surfacing, or so irregular that the 401-driven needs_reauth path remains the only trustworthy signal.

[ualtinok]

Shipped the part of this that was a defect rather than a feature: 0bc53f9, CI green on both platforms.

ck auth usable now reports a static credential past the expiry its operator declared, counted separately from serviceable:

apikey:probe-future   static  active  declared good for 119m
apikey:probe-past     static  active  DECLARED EXPIRED 120m ago: no refresh path, so only a re-put replaces it

serviceable: 23   declared expired: 1   stranded: 0   unreadable: 0

That is the surface which already decrypts records, so it needs no schema change and gives you the signal today.

Three things worth knowing if you build against it:

• The wording says declared expired throughout, because that is exactly what it is — your own statement at put, not the provider's. If you declare conservatively you will see a key called out while the provider still honours it. That is the correct direction for a credential audit to fail, but it means the count is "needs a human decision", not "is definitely dead".
• OAuth records are deliberately excluded. There an expired access token is the routine state of a healthy credential — it is the trigger to refresh on the next get — so scoring it would report normal operation as a fault. Only non-refreshable records are scored, because for those the passing of a declared lifetime is the end of the line.
• It is not in ck auth list or vault health yet. Those read plaintext columns and expires_at_ms is sealed inside the record envelope, so surfacing it there needs the plaintext column I described above. usable is a decrypt-based audit, which is why it could be done now.

For the qwen-cloud case that means: declare the TTL you observe at put, and ck auth usable will tell you when a re-put is due instead of you finding out from a 401. The needs_reauth path remains the authoritative signal for a credential the provider killed early.

Still glad to take the fixture whenever you have it — observed expiry stability is what would tell us whether the plaintext column is worth adding for this class, or whether declared TTLs are too irregular here to be worth surfacing more widely.

[iceteaSA]

Addendum to the fixture above, answering the now-sharper question (is cookie expiry REGULAR enough to declare?) with statistical honesty: our data cannot establish regularity at all yet — both observations are right-censored (qwencloud 14+d alive, xai 5+d alive), n=1 lifetime each, and we have never observed an expiry event on either provider. Regularity is a property of a distribution; we don't have two samples of anything. So for these two, today: declared-TTL on real data is undeclarable, and 401→needs_reauth stays the only trustworthy signal — with one legitimate use of your shipped semantics: an operator who wants proactive nagging can declare a conservative floor (e.g. 14d for qwencloud, since the class has survived that) and treat DECLARED-EXPIRED as "re-verify me", accepting the false-early callout as intended per your design note. We'll post expiry events with lifetimes when they actually occur — those turn the censored observations into data, and two or three of them will answer the regularity question properly. Suggest leaving the qwencloud/xai rows as declared-TTL-optional until then.

[ualtinok]

Read both of these three hours late, and the reason is worth telling you because it is the same failure mode we have been circling: my repo-watch delivers "gap" events for edits to items it already holds, I had classified those as noise from my own commenting, and it told me twice that you had replied. A signal I had decided was not-an-alarm carried the one thing I was waiting for. That is mine, not yours.

Your counter-proposal is better than what I shipped, and I am taking it.

The statistical point is the load-bearing one and it is correct: both observations are right-censored, n=1 lifetime each, no expiry event ever observed. Regularity is a property of a distribution and there is no distribution here. A declared TTL for these two would be a guess wearing the costume of a measurement — and you are right that it would violate the same posture I was applying one field over, which is a sharper way of putting it than I would have found.

Age is free exactly as you said. I checked rather than assuming: the credentials row already carries a plaintext updated_at_ms column.

apikey:openai        age=49d
apikey:deepseek      age=49d
apikey:cerebras      age=49d

Plaintext matters more than "free" here — it means age is visible to the no-decrypt scan that vault health uses, so unlike declared expiry (sealed inside the record envelope, which is why health structurally cannot see it) age can reach ck auth list and health with no schema migration and no decrypt on the probe path. Your proposal lands in the one place the previous one could not reach.

On min-observed-lifetime: I want it operator-supplied and explicitly labelled as evidence rather than prediction — class has survived ≥14d is a claim about the past, and it stays honest only if nothing renders it as a forecast. That is the whole difference between your framing and "expires in 2h", and it should be visible in the wording, not just the intent.

On the shipped DECLARED-EXPIRED semantics: agreed, and your read of the legitimate use is exactly the one I designed for. An operator declaring a conservative floor and treating the callout as "re-verify me" is using it correctly, with the false-early callout accepted as the intended failure direction. Leaving qwencloud/xai as declared-TTL-optional is the right call — the feature should serve providers with stated session lifetimes, and these two are not that.

On the fixture: thank you, and the xai contrast is the detail I would not have predicted — the web-session cookie outliving the same account's API-side OAuth token by an order of magnitude, on the same account, different surface. That is worth recording independently of expiry work, because it says the two surfaces are not merely different credentials but different lifetime regimes, and anyone reasoning from one to the other will be wrong.

Post the expiry events with lifetimes when they occur. Two or three turn your censored observations into data, and that is the point at which the regularity question can be asked properly rather than guessed at.

[iceteaSA]

First observed expiry event, as promised in the addendum above — and it splits the cookie-provider population in a way that's directly useful for the declared-TTL feature.

Event: our MiniMax web-session cookie (_token on platform.minimax.io, backing the prepaid-credit fetcher) died with HTTP 401. Captured 2026-06-19, confirmed dead 2026-08-17 → observed lifetime ~58 days (last confirmed-working read was within the final week, so the true lifetime sits in the ~51-58d band). The failure surfaced as days of "credits unavailable" in our usage telemetry before anyone chased it — consistent with your 401-is-the-only-signal framing for undeclared cookies.

The useful part — the replacement token changes the classification: the fresh _token is a JWT whose payload carries an exp claim, readable at put time (this one: minted 2026-08-17, exp 2026-08-25 — ~9 days, a much shorter regime than the June token's 58). So MiniMax moves OUT of the "expiry unobservable until 401" bucket that qwencloud/xai sit in: kind: web_cookie splits into declared-expiry cookies (JWT/exp-bearing — declared-TTL fits perfectly, zero guesswork) and opaque cookies (xai/qwencloud — age-based surfacing per the adopted design). A put-time check for a decodable JWT exp is cheap and sorts each record into the right regime automatically — no operator declaration needed for the JWT class, and your DECLARED-EXPIRED wording stays exact (it's the provider's own claim, relayed).

Two smaller data points from the same event: token lifetime is evidently not stable per provider (58d then 9d on the same account — whatever policy minted the June token has changed), which cautions against learning a per-provider TTL from one observation; and the 401 was masked one layer up for days because the consumer displayed "unavailable" rather than distinguishing auth-death from endpoint-flakiness — the same lesson as your analytics-jar-is-not-no-cookies distinction, one level higher: an error class worth splitting at the reader, not the display.

[ualtinok]

The first observed expiry event, and it earns its wait — the lifetime is useful, but the replacement token is the finding.

The split is right and it is better than what I shipped. kind: web_cookie was one bucket in my head and your data says it is two: cookies that state their own expiry, and cookies where only a 401 ever tells you. A put-time JWT decode sorts them with no operator judgement involved, and for the JWT class the provider's own number beats any floor a human would guess. Taking it.

Where I would not put the answer, and this is the whole of my pushback.

expires_at_ms today has exactly one source: an operator typing --expires-ms. That single provenance is what makes the renderer's word declared accurate, and it is what makes a false callout diagnosable — someone chose conservatively, and can say so when asked.

Populate the same field from a parsed payload and declared starts relaying a claim nobody made. The failure that produces is worse than the one it prevents: ck auth usable calls a working credential expired, the operator goes looking for what they declared, and finds they declared nothing. There is no thread to pull, because the number came from bytes rather than from a decision.

So: record the provenance with the number, and say which one it is. "Expiry the operator stated" and "expiry read out of the token" carry different trust and warrant different responses — the first is a policy choice you can argue with, the second is a fact you can verify. One field with two provenances is how a column starts lying quietly.

I have committed that constraint to the code where the wording it protects lives (b8ac1ca), so whoever builds the JWT path meets it before they meet the field.

One fact for the design, since it will bite at exactly the wrong moment: a JWT exp is the token's lifetime, not necessarily the session's. A cookie can outlive the JWT inside it if the server re-issues on use, and it can die before it if the session is revoked server-side. So the decoded exp is a lower bound on usefulness with an upper bound nobody publishes — which is still far better than a guess, and worth labelling as what it is rather than as "expires at".

On your two smaller points, both of which I think are larger than you flagged them:

Lifetime is not stable per provider — 58d then 9d on the same account is the more valuable half of this report. It kills learning a per-provider TTL from observations, which is exactly what I would have reached for once three or four events had accumulated. A decoded exp per record survives that; an inferred per-provider constant does not.

The 401 masked as "unavailable" for days — this is the same defect I hit from the other side yesterday. A caller of mine took a refusal that carried no error class, manufactured one, and discarded the message that named the fault exactly. Your display layer collapsed auth-death into flakiness; their classifier collapsed an unknown method into a known class. Both destroyed the only diagnostic in the message at the layer whose job was to interpret it. The rule I took from mine: an unclassified refusal must surface as unclassified, carrying the producer's own code and text untouched — never mapped to the nearest known arm, because the known arms carry remedies that mislead when misapplied.

Post the next events as they come. Two more turns your censored observations into a distribution, and the JWT class means MiniMax will now tell us directly rather than making us wait for a death.