fix(auth): make clear* hydration-safe, migrate raw-key blobs, doc keepalive/memo caveats

Address round-1 @claude review of #1592:

- OAuthStorageBase.clear* no longer mutate the pre-hydration (empty) store —
  a clear issued before hydration is deferred until it lands, so it merges
  onto the real persisted state instead of (a) being resurrected by the late
  rehydrate merge or (b) persisting a near-empty blob that clobbers every
  other server's on-disk credential. Already-hydrated clears stay synchronous.
- store.setServerState migrates a pre-normalization raw-key blob onto the
  canonical key on first partial write (was: shadowed it with a fresh
  canonical entry, orphaning the raw blob's other fields). clearServerState
  now also drops the raw-key orphan.
- Document the keepalive 64KB combined-body ceiling on the remote-storage
  write, the getRemoteOAuthStorage memo key intentionally omitting fetchFn,
  and the real ordering invariant behind the sync getScope.
- Tests for the clear-before-hydration and raw-key-migration paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX
This commit is contained in:
cliffhall 2026-07-01 19:20:49 -04:00
commit 8c10b8eb8e

View file

@ -30,7 +30,18 @@ export function getWebOAuthBaseUrl(): string {
export const webOAuthFetch: typeof fetch = (...args) =>
globalThis.fetch(...args);
/** Memoized `RemoteOAuthStorage` for the given backend + auth token. */
/**
* Memoized `RemoteOAuthStorage` for the given backend + auth token.
*
* The cache key is intentionally `{baseUrl, authToken}` only — `fetchFn` is NOT
* part of it. Whichever call constructs an instance first wins, so a later
* caller's `fetchFn` is ignored. This is safe today because every call site
* either omits `fetchFn` (defaulting to {@link webOAuthFetch}) or passes an
* `environmentFactory` wrapper that is functionally identical (`globalThis.fetch`),
* so the shared-instance goal (one whole-blob writer per backend) matters more
* than which wrapper is used. A future caller needing a genuinely different
* transport must key on it (or bypass the cache).
*/
export function getRemoteOAuthStorage(
baseUrl: string,
authToken: string | undefined,