Skip to content

Commit 6a21c37

Browse files
committed
docs(custody): source the host-write race and collapse unobservable main-slot states
auth/index.ts:73-89 is all() -> spread -> writeJson with no lock, no CAS, and a non-atomic in-place write (util/filesystem.ts:61-84); the gap is tracked as anomalyco/opencode#46128. Record the whole-file last-writer-wins across providers, the deterministic OPENCODE_AUTH_CONTENT clobber as a checkable precondition, the provider-specific severity (unverified for Anthropic), the four fence-free mitigation candidates, and the strictness resolution proposed for the raced-login question. Through the SDK an unparseable main slot is indistinguishable from an absent one, so GONE collapses to SLOT_ABSENT for main; the distinction survives only for fallback rows in our own store.
1 parent e67afbb commit 6a21c37

1 file changed

Lines changed: 58 additions & 8 deletions

File tree

‎docs/custody-state-machine.md‎

Lines changed: 58 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ Evaluated independently for main and for **each enabled OAuth fallback**.
9999
|---|---|---|
100100
| `mode` | `local` · `claustrum` | global, durable; the only global write in the barrier |
101101
| `binding` | `VALID` · `INVALID` · `ABSENT` | the account's entry `{label, handle, credentialId}` in our provider block of the shared handle manifest. `INVALID` = entry present, handle or credentialId fails validation |
102-
| `local` | `REAL` · `INERT` · `GONE` | main: `REAL` = usable material, `INERT` = recognise-set tombstone, `GONE` = `SLOT_ABSENT` or `SLOT_UNPARSEABLE`. Fallback: `REAL` = usable refresh material, `INERT` = refresh material absent, row otherwise valid, `GONE` = `ROW_UNPARSEABLE` (a row that is *absent* while a binding exists is the discovery operation, §7, not a coordinate) |
102+
| `local` | `REAL` · `INERT` · `GONE` | main: `REAL` = usable material, `INERT` = recognise-set tombstone, `GONE` = slot absent **as observed through the SDK**. An unparseable main slot is unobservable: `Auth.all()` runs `Record.filterMap(decode)` (`auth/index.ts:65-66`), so a slot failing the `Info` schema reads as `undefined` and any later host write rewrites the file without it; for main, `GONE ≡ SLOT_ABSENT`. Fallback: `REAL` = usable refresh material, `INERT` = refresh material absent, row otherwise valid, `GONE` = `ROW_UNPARSEABLE` (our own store, so the distinction survives there; a row that is *absent* while a binding exists is the discovery operation, §7, not a coordinate) |
103103
| `vault` | `USABLE` · `COLD` · `REAUTH` · `N/A` | resolved through the binding's handle. `COLD` = daemon unreachable or credential not resident (transient). `REAUTH` = record latched `needs_reauth`. `N/A` ⇔ `binding ∈ {ABSENT, INVALID}` |
104104

105105
Two facts about `GONE` for main, both from OpenCode source (`339536bc22`), change what it means:
@@ -163,7 +163,7 @@ vault-owned family.
163163
| C6 | ABSENT | REAL | N/A | `NOT_ENROLLED` | **no** | **no** (this mode has no local refreshers) | none | none | `ck auth bind` after import, or `local` |
164164
| C7 | ABSENT | INERT | N/A | `ORPHAN_TOMBSTONE` (main) / `ORPHAN_INERT` (fallback) | **no** | nothing to refresh | none | none | `bind`, or `local` + re-login |
165165
| C8 | INVALID | any | N/A | `CORRUPT_BINDING` | **no** | **inert** | **none**: never auto-repair a manifest entry | none | `ck auth bind --replace`, or `local` |
166-
| C9 | VALID | GONE (main) | USABLE · COLD · REAUTH | `RESTORE_TOMBSTONE` → re-classify as C1 / C3 / C4 | per re-class | inert | `auth.json` ← WRITE set, **awaited in the factory before the loader pass**. `SLOT_UNPARSEABLE` logs a `warn` naming the fact, never the content, before overwriting. Write failure → `FAIL_CLOSED`, typed `main unavailable: slot unrestorable` | next boot | none on success |
166+
| C9 | VALID | GONE (main) | USABLE · COLD · REAUTH | `RESTORE_TOMBSTONE` → re-classify as C1 / C3 / C4 | per re-class | inert | `auth.json` ← WRITE set, **awaited in the factory before the loader pass**. **BLOCKED under §13.1** (same host-write race as the install). Write failure → `FAIL_CLOSED`, typed `main unavailable: slot unrestorable`. (An unparseable slot cannot be distinguished from an absent one through the SDK, so no separate warn is possible; the host itself drops such an entry on its next write) | next boot | none on success |
167167
| C10 | VALID | GONE (fallback = `ROW_UNPARSEABLE`) | any | `CORRUPT_ROW` | **no** | inert | **none**; state secrets retained | next reconcile | repair the row, or remove + re-discover |
168168

169169
Invariants pinning the combinations not rowed:
@@ -341,10 +341,51 @@ Everything the barrier fences is ours: config, sidecar, manifest, per-account re
341341
- `RESTORE_TOMBSTONE` (C9) has the same race in the other direction: a login can land in the absent
342342
slot between the factory's read and its awaited write.
343343

344-
The fingerprint is therefore **crash reconciliation only** (§4). What is needed is a
345-
synchronisation mechanism grounded in OpenCode source: a lock `Auth.set` honours, a compare-and-set
346-
primitive on the slot, an event that observes the write, or a host-side change. None was found in
347-
`339536bc22`; the search was not exhaustive.
344+
The fingerprint is therefore **crash reconciliation only** (§4).
345+
346+
**Source of the race** (OpenCode `339536bc22`, `packages/opencode/src/auth/index.ts:73-89`):
347+
`Auth.set` is `all()` → spread → `writeJson`. No lock, no compare-and-set, no expected-value check,
348+
and the write itself is **not atomic**: `util/filesystem.ts:61-84` is an in-place `writeFile`, not
349+
temp-and-rename, so a concurrent reader can observe a partial file. No write event exists, and the
350+
loader is memoised init-once. There is nothing at the host to honour; the gap is tracked upstream as
351+
[anomalyco/opencode#46128](https://github.com/anomalyco/opencode/issues/46128) ("auth.json writes
352+
are unlocked whole-file rewrites", open). Consequences beyond our slot:
353+
354+
- it rewrites the **whole file**, so two concurrent `set`s on *different* keys are last-writer-wins.
355+
A tombstone write on `anthropic` can clobber a concurrent `openai` login and vice versa; any
356+
plugin that writes its slot during another plugin's login loses one of them. This is a property
357+
of the host's auth store, not of custody.
358+
- a fresh login that lands in the window is **lost** if the tombstone overwrites it (ordering B).
359+
Whether that also kills the vault's family is provider-specific and, for Anthropic, **unverified**:
360+
if a fresh Anthropic login invalidates the prior refresh lineage, ordering B leaves the account
361+
dark; if lineages coexist (as they do for OpenAI), the cost is one re-login. The fingerprint
362+
preserves the single-refresher invariant in both orderings; only losslessness differs. Either
363+
way the transition stays blocked (§13.1).
364+
- **`OPENCODE_AUTH_CONTENT` is a deterministic clobber, not a race.** A child process started with
365+
that variable (`workspace.ts:532-533`) reads auth from the env snapshot in preference to the file
366+
(`auth/index.ts:59-61`), and every `Auth.set` it performs rewrites the file from that snapshot,
367+
restoring pre-tombstone material for the child's whole lifetime. This is a **checkable
368+
precondition** (scan `/proc/*/environ` for the variable before the transition), which is what §8's
369+
"fail loudly" concretely means.
370+
371+
**Mitigations that do not need a host primitive** (candidates; none closes the cross-process case):
372+
(1) a process-local mutex shared by the barrier and every plugin-owned login entry, the login
373+
holding it until a `client.auth.get` readback observes the host's write, which closes the
374+
same-process race because both sides are our code; (2) a post-write readback after each tombstone
375+
write, so ordering A is detected in the same run rather than on the next boot; (3) the cross-process
376+
residual (a login in another OpenCode window) **declared** in the transition's confirmation text,
377+
never hidden; (4) a **convergent write** for the main-slot install, proposed by the Claustrum seat on
378+
the #196 thread and buildable inside `ck auth migrate-plugin --allow-main` where the imported bytes
379+
are already in hand: import first → write the tombstone → settle → re-read; a slot **byte-equal to
380+
the imported material** means a clobber by an env-snapshot child (rewrite, bounded retries), while
381+
**different real material** means a newer family landed (refuse loud, never overwrite). The residual
382+
is detected, bounded, and loud, which is the most a host without a fence can give. Whether that
383+
satisfies §13.1's "source-backed synchronisation" is the maintainer's call.
384+
385+
**What closes it** is small and belongs in OpenCode: a per-key compare-and-set,
386+
`Auth.set(key, info, { expect })` rejecting when `current[key] ≠ expect`, or an advisory lock that
387+
`set`/`remove` take. Not filed; a change to a third-party repo is the operator's and maintainer's
388+
call.
348389

349390
### 12.2 A raced login versus "bindings clear only after verified login"
350391

@@ -355,8 +396,17 @@ not complete through **our** path with an in-process record, so under `local` it
355396
(`DARK_PENDING_VERIFIED_LOGIN`), not L1, and its binding does not clear. Either the verified-login
356397
rule admits some evidence other than our in-process record (and then what, and how is it
357398
distinguished from a restored backup, which is the case the rule exists for), or a raced login is
358-
never allowed to stand and the only resolution is a fresh vault import. The two rules are both
359-
individually correct and jointly unreconciled here.
399+
never allowed to stand and the only resolution is a fresh vault import.
400+
401+
**Resolution proposed (strictness), for the maintainer's ruling:** a login that landed outside the
402+
plugin's own path (raced, restored backup, another process) is **never** verified. It lands L5; its
403+
binding never auto-clears; the only exits are the plugin's own in-process verified login (new
404+
family, clears) or `ck auth`. The rule exists to reject restored backups, and a raced login is
405+
indistinguishable from one by content, so it gets the same treatment. The openai-auth port adopted
406+
this. One sub-question stays open: whether L5 **serves** its access token until expiry (no refresh,
407+
which still satisfies §13.2) or refuses as the table currently says; both are consistent with the
408+
rulings, and the difference is availability versus caution on a credential the vault may have
409+
rotated.
360410

361411
### 12.3 Smaller
362412

0 commit comments

Comments
 (0)