Instance-per-identity (exploration): one SDK instance = one identity

[orveth]

Instance-per-identity (exploration)

An exploration PR (petar's "examine what it looks like") of binding one SDK instance to exactly one identity. Instead of serializing the cross-user auth transition (sol's B3 / #1166 finding [37]), the instance never transitions identities at all — a session end disposes it and the host builds a fresh one. Stacked on 1167-session-fence-r4.

Not a final build. Scope is the three items below; gaps are flagged as notes, not fixed.

What it shows

SDK (packages/wallet-sdk)

• signIn / signUp / signUpGuest throw a new InstanceAlreadyUsedError once an identity was established (assertUnused). A failed login that never established does not consume the instance.
• The instance is bound to the established identity id. Any applySessionFromServer apply resolving to a different id is refused — even after the session has gone anonymous — and the foreign identity's Open Secret tokens are revoked (os.signOut) so a rebuild can't restore them.
• signOut is terminal: clears per-session caches (endSession) then disposes the instance (requestDispose → AgicashSdk.dispose()); every later call throws DisposedError.

Web (apps/web-wallet)

• sdk.client.ts exposes the singleton as a live binding + rebuildSdk() (dispose current → create fresh; concurrent calls coalesce). All 7 consumers read sdk in-function, so they pick up the replacement with no call-site changes.
• useSessionEndCleanup rebuilds on every session end (sign-out and expiry), before the auth query re-runs init() — so the next sign-in lands on an unused instance.
• The protected subtree is re-keyed on user.id (<Wallet key={user.id}>) — an identity change remounts it, resetting session-derived state and re-subscribing SDK event handlers to the fresh instance.

What it deletes / obviates

• The D5 transition-suspension design is no longer needed: there is no in-instance transition to serialize, so beginTransition/rollback collapses to assertUnused + rebuild.
• The different-user re-key-in-place path in applySessionFromServer is removed.

Cross-model review (run before hand-off)

• codex-review (deep, gpt-5.5) — 1 HIGH: the different-user branch ended only the in-memory session, leaving the foreign identity's tokens in storage → the web rebuild's init() could restore that identity. Fixed: bind-to-id + revoke tokens + refuse-when-anonymous (regression test + red-on-base).
• Adversarial Opus pass — F2 (a foreign identity via unguarded completeGoogleAuth on a used-but-anonymous instance) was the same hole → closed by the same fix. F3 (concurrent rebuildSdk could throw from create()) → fixed (coalescing guard). Everything else held. Its sharpest correctness point is the flag below.

⚠ Flag (not fixed — process-global caches)

The adversarial pass confirmed the charter's suspicion: a fresh instance does NOT sanitize process-global state. dispose()/rebuild clears only per-instance state; the module-global caches — notably cachedCAT (lib/agicash-mint-auth-provider.ts, not keyed by user), the spark-wallet map, and the feature-flag store — are cleared only by onSessionEnded, never by dispose. So identity isolation still rests on onSessionEnded running before every rebuild, not on the rebuild itself. That holds today (every rebuildSdk is reached via useSessionEndCleanup, always preceded by a session-end that wipes those caches), but the "fresh instance = clean slate" intuition is wrong for globals: instance B shares them with disposed instance A. Recommendation: dispose() should defensively run the same process-global wipe (or we narrow the claim). Left as a note per the scope-lock — happy to fix if you want it in.

Open questions for petar / jbojcic

1. completeGoogleAuth is unguarded (scope-lock was signIn/signUp/signUpGuest). The apply-layer fence now refuses a foreign identity it would surface (safe — user lands anonymous, tokens revoked), but the verb itself doesn't throw early. Add assertUnused to it (a clean loud throw instead of a silent refuse), here or follow-up?
2. Guest→full conversion — confirmed safe. The adversarial pass read the Open Secret source: guest→full is an in-place upgrade that preserves user.id, so the different-user fence never trips on conversion and key={user.id} doesn't spuriously remount. Even if it were wrong, it fails safe (session ends, no identity mix). Noted here since the design doc left it open.
3. QueryClient stays root-mounted across rebuilds; existing queryClient.clear() (sign-out) + evictDerivedKeyQueries (cross-user) handle the cache, so the rebuild doesn't touch it. Remounting <Wallet> resets React state, not the query cache — intentional. OK?
4. Live-binding vs accessor. Live-binding keeps the diff minimal but the "instance can change" dependency is implicit; a getSdk() accessor would make it explicit at ~25 call-site edits. Preference?

Verification

• bun run fix:all → rc 0 (2 pre-existing vite-env.d.ts warnings, untouched).
• wallet-sdk 117 pass / 0 fail; web 37 pass / 0 fail.
• Red-on-base (each new guard reverted individually vs the committed change → its test goes red, then restored green): assertUnused; signOut dispose; different-user fence; and the review fix's two halves (revoke-tokens + refuse-when-anonymous).

Reality class: BUILT-BUT-OFF — compiles, unit-suites green, red-on-base proven; not exercised end-to-end in a running app (no e2e run; web remount + rebuild-on-signout belong in web-wallet-e2e, out of scope for the spike).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agicash	Ready	Preview, Comment	Jul 22, 2026 9:24am

[supabase]

This pull request has been ignored for the connected project hrebgkfhjpkbxpztqqke because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.