@oxyhq/services 28.0.0 → 29.0.0

package/src/ui/session/authStore.ts

@@ -1,25 +1,66 @@
 /**
  * Platform `AuthStateStore` for `@oxyhq/services`.
  *
- * The zero-cookie device model persists the durable device credential
- * (`deviceId` + `deviceSecret`) per origin (web) / per device (native), and the
- * SDK re-mints the access token from that credential on cold boot. `@oxyhq/core`
- * owns the store shape + logic (`createWebAuthStateStore` /
- * `createNativeAuthStateStore`); this module only selects the platform storage
- * seam:
+ * The device model persists the durable device credential (`deviceId` +
+ * `deviceSecret`) per origin (web) / per device (native), and the SDK re-mints
+ * the access token from that credential on cold boot. `@oxyhq/core` owns the
+ * store shape + logic (`createWebAuthStateStore` / `createNativeAuthStateStore` /
+ * `createMemoryAuthStateStore`); this module only selects the seam:
  *
+ *  - `storage: 'ephemeral'` → `createMemoryAuthStateStore()`, on EVERY platform.
  *  - web  → `createWebAuthStateStore()` (localStorage, in-memory fallback).
  *  - native → `createNativeAuthStateStore(secureKV)` for the SESSION blob over
  *    the shared `createNativeSecureKeyValueStorage()` adapter
- *    (`expo-secure-store`, AsyncStorage fallback).
+ *    (`expo-secure-store`, AsyncStorage fallback), WRAPPED so every credential
+ *    it persists is also mirrored into the device-wide shared slot.
+ *
+ * The native wrapper is how several official apps end up on ONE `DeviceSession`
+ * (and therefore one active context): whichever app proves a credential publishes
+ * it, and a later-installed sibling adopts it during cold boot instead of asking
+ * for the Commons identity key. The mirror is additive — it can neither change
+ * nor fail the app's own durable write.
  */
 import {
   createWebAuthStateStore,
   createNativeAuthStateStore,
+  createMemoryAuthStateStore,
+  createSharedMirroringAuthStateStore,
   type AuthStateStore,
+  type SessionMode,
 } from '@oxyhq/core';
 import { isReactNative } from '../utils/storageHelpers';
 import { createNativeSecureKeyValueStorage } from './nativeSecureStorage';
+import { createPlatformSharedDeviceCredentialStore } from './sharedDeviceCredentialStore';
+
+export interface PlatformAuthStateStoreOptions {
+  /**
+   * Who owns the session this provider resolves. Only `'account'` mirrors into
+   * the device-wide shared slot.
+   *
+   * `'identity'` (the vault) is deliberately excluded, which keeps its storage
+   * behaviour byte-for-byte what it is today. The vault's credential is a
+   * perfectly valid device credential, so publishing it would arguably be
+   * correct — but it would also let every ordinary app on the device join the
+   * vault's device session as a side effect of the vault persisting a token, and
+   * "a background write changes which session five other apps boot into" is not
+   * a decision a storage seam gets to make.
+   */
+  sessionMode?: SessionMode;
+  /**
+   * Whether this origin/app may persist a durable device credential AT ALL.
+   *
+   * `'ephemeral'` stores nothing durable and mirrors nothing: the session lives
+   * in memory for the lifetime of the page and is gone on reload. Its one caller
+   * is `auth.oxy.so` with the browser hub enabled (issue #937 Phase 5, ADR 0003),
+   * where the durable credential for the browser profile is the server-side
+   * DeviceSession behind the `__Host-oxy-device` handle.
+   *
+   * See `OxyProviderProps.deviceCredentialStorage` for why the answer to "let the
+   * hub be authoritative" is to stop persisting the other credential rather than
+   * to consult it second.
+   */
+  storage?: 'persistent' | 'ephemeral';
+}
 
 /**
  * Build the platform {@link AuthStateStore} for this runtime.
@@ -27,11 +68,39 @@ import { createNativeSecureKeyValueStorage } from './nativeSecureStorage';
  * Native persists the SESSION blob (`deviceId` + `deviceSecret` + cached access
  * token) per-app in SecureStore; the SDK re-mints the access token from the
  * device credential on the next cold boot.
+ *
+ * ## The ephemeral check is FIRST, and the order is load-bearing
+ *
+ * It short-circuits above the `isReactNative()` branch so an ephemeral caller can
+ * never reach the native path — and therefore can never reach the shared-slot
+ * mirroring wrapper. Checked after that branch instead, an origin that has
+ * declined to persist a credential would publish one into the device-wide slot
+ * every sibling app adopts on cold boot: it would keep nothing itself while
+ * deciding which session five other apps boot into.
+ *
+ * That is unreachable today because the only ephemeral caller is a web origin, so
+ * `isReactNative()` is false there anyway. Unreachable today is exactly the kind
+ * of guarantee that stops holding when someone adds the second caller, so it is
+ * structural here rather than incidental, and
+ * `__tests__/session/authStoreEphemeral.test.ts` holds the ordering directly.
  */
-export function createPlatformAuthStateStore(): AuthStateStore {
+export function createPlatformAuthStateStore(
+  options: PlatformAuthStateStoreOptions = {},
+): AuthStateStore {
+  // FIRST, above every platform branch — see the docblock for why the ordering
+  // is the guarantee and not a coincidence.
+  if (options.storage === 'ephemeral') {
+    return createMemoryAuthStateStore();
+  }
+
   if (!isReactNative()) {
     return createWebAuthStateStore();
   }
 
-  return createNativeAuthStateStore(createNativeSecureKeyValueStorage());
+  const local = createNativeAuthStateStore(createNativeSecureKeyValueStorage());
+  if (options.sessionMode === 'identity') {
+    return local;
+  }
+  const shared = createPlatformSharedDeviceCredentialStore();
+  return shared ? createSharedMirroringAuthStateStore({ local, shared }) : local;
 }

package/src/ui/session/sharedDeviceCredentialStore.ts

@@ -0,0 +1,318 @@
+/**
+ * The platform half of the shared native DeviceSession credential.
+ *
+ * `@oxyhq/core` owns the rules (`sharedDeviceCredential.ts`: when to adopt, when
+ * to publish, and above all that an unreadable slot is never an empty one). This
+ * module owns only where the bytes live, which is genuinely different per
+ * platform:
+ *
+ *  - **iOS** — one `expo-secure-store` item in the approved Keychain Access Group
+ *    `group.so.oxy.shared`, under its OWN `keychainService`
+ *    ({@link IOS_DEVICE_SESSION_KEYCHAIN_SERVICE}). Every identity slot uses a
+ *    different service (`oxy_identity`, `oxy_identity_backup`,
+ *    `oxy_identity_mnemonic`) and the legacy cross-app identity keypair uses the
+ *    same group with NO service at all — so this item cannot alias any of them.
+ *    That separation is the point of the whole phase: the group-shared identity
+ *    key and the group-shared device-session credential are different secrets
+ *    with different blast radii and must not be conflated.
+ *  - **Android** — the signature-protected `OxyDeviceSession` broker (its own
+ *    EncryptedSharedPreferences file, its own ContentProvider, its own
+ *    `signature`-level permission). It carries a session credential; it can NOT
+ *    reach the identity keypair, which lives in a different file behind a
+ *    different provider.
+ *  - **web / anything else** — no shared slot. Each origin is its own device by
+ *    design, so the factory returns `null` and the cold boot simply omits the
+ *    lane.
+ *
+ * ## What is written here, and what is not
+ *
+ * Only `{deviceId, deviceSecret}`. No access token, no account id, no user id,
+ * and never any identity key material.
+ *
+ * ## Accessibility
+ *
+ * `WHEN_UNLOCKED_THIS_DEVICE_ONLY`: a device credential must not travel to
+ * another handset in an iCloud/encrypted backup restore — the restored device is
+ * a different device and has to establish its own session. It also keeps the item
+ * out of reach while the phone is locked, which is why a read can legitimately
+ * fail and why the `unavailable` verdict exists at all.
+ */
+import { Platform } from 'react-native';
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import {
+  normalizeSharedDeviceSessionRead,
+  type SharedDeviceCredential,
+  type SharedDeviceCredentialRead,
+  type SharedDeviceCredentialStore,
+} from '@oxyhq/core';
+
+/**
+ * The iOS Keychain Access Group every official Oxy app declares in its
+ * entitlements. Shared with the identity slots — the group is the app-group
+ * boundary, not the secret's identity.
+ */
+export const IOS_KEYCHAIN_ACCESS_GROUP = 'group.so.oxy.shared';
+
+/**
+ * The iOS `keychainService` for the DEVICE SESSION credential. Deliberately
+ * distinct from every identity and recovery service; do not reuse one of those
+ * here, and do not drop it (an item written with no service shares the legacy
+ * identity slot's namespace inside the group).
+ */
+export const IOS_DEVICE_SESSION_KEYCHAIN_SERVICE = 'oxy_device_session';
+
+/** The single key holding the JSON-encoded `{deviceId, deviceSecret}` pair. */
+export const SHARED_DEVICE_SESSION_STORAGE_KEY = 'oxy_shared_device_session_v1';
+
+// Variable indirection so Metro's static analyzer never traces expo-secure-store
+// into the web bundle; the module is native-only and optional.
+const SECURE_STORE_MODULE = 'expo-secure-store';
+
+/**
+ * The subset of `expo-secure-store` this module needs. Unlike the adapter in
+ * `nativeSecureStorage.ts` it must pass OPTIONS — the access group and the
+ * dedicated service are the entire mechanism here, so an options-less wrapper
+ * would silently write a package-private item that no sibling app can see.
+ */
+interface KeychainGroupStore {
+  getItemAsync(key: string, options?: object): Promise<string | null>;
+  setItemAsync(key: string, value: string, options?: object): Promise<void>;
+  deleteItemAsync(key: string, options?: object): Promise<void>;
+  readonly WHEN_UNLOCKED_THIS_DEVICE_ONLY: number;
+}
+
+let keychainStorePromise: Promise<KeychainGroupStore | null> | null = null;
+
+function loadKeychainGroupStore(): Promise<KeychainGroupStore | null> {
+  if (!keychainStorePromise) {
+    const moduleName = SECURE_STORE_MODULE;
+    keychainStorePromise = import(moduleName)
+      .then((mod: Partial<KeychainGroupStore>) => {
+        if (
+          typeof mod.getItemAsync === 'function' &&
+          typeof mod.setItemAsync === 'function' &&
+          typeof mod.deleteItemAsync === 'function' &&
+          typeof mod.WHEN_UNLOCKED_THIS_DEVICE_ONLY === 'number'
+        ) {
+          return {
+            getItemAsync: mod.getItemAsync.bind(mod),
+            setItemAsync: mod.setItemAsync.bind(mod),
+            deleteItemAsync: mod.deleteItemAsync.bind(mod),
+            WHEN_UNLOCKED_THIS_DEVICE_ONLY: mod.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+          } satisfies KeychainGroupStore;
+        }
+        return null;
+      })
+      .catch(() => null);
+  }
+  return keychainStorePromise;
+}
+
+/** Parse the stored JSON into a credential, or `null` for anything malformed. */
+function parseStoredCredential(raw: string | null): SharedDeviceCredential | null {
+  if (!raw) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  const candidate = parsed as Record<string, unknown>;
+  if (
+    typeof candidate.deviceId !== 'string' ||
+    candidate.deviceId.length === 0 ||
+    typeof candidate.deviceSecret !== 'string' ||
+    candidate.deviceSecret.length === 0
+  ) {
+    return null;
+  }
+  return { deviceId: candidate.deviceId, deviceSecret: candidate.deviceSecret };
+}
+
+/**
+ * The iOS store: one keychain item in the shared access group.
+ *
+ * A THROWN read is `unavailable`, a `null` read is `absent`. That mapping is the
+ * whole safety contract — `expo-secure-store` returns `null` for a genuinely
+ * missing item and throws when the keychain itself refuses, and collapsing the
+ * two is what would let a locked phone look like a device that never had a
+ * session.
+ */
+function createKeychainGroupCredentialStore(): SharedDeviceCredentialStore {
+  const readOptions = {
+    keychainService: IOS_DEVICE_SESSION_KEYCHAIN_SERVICE,
+    keychainAccessGroup: IOS_KEYCHAIN_ACCESS_GROUP,
+  };
+
+  return {
+    read: async (): Promise<SharedDeviceCredentialRead> => {
+      const store = await loadKeychainGroupStore();
+      if (!store) {
+        return { state: 'unsupported' };
+      }
+      let raw: string | null;
+      try {
+        raw = await store.getItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, readOptions);
+      } catch (error) {
+        return { state: 'unavailable', cause: error };
+      }
+      if (raw === null) {
+        return { state: 'absent' };
+      }
+      const credential = parseStoredCredential(raw);
+      if (!credential) {
+        // Something IS stored and we cannot read it. Reporting `absent` would
+        // authorise overwriting whatever a newer build put there.
+        return {
+          state: 'unavailable',
+          cause: new Error('shared device session item is present but not parseable'),
+        };
+      }
+      return { state: 'present', credential };
+    },
+
+    publish: async (credential): Promise<boolean> => {
+      const store = await loadKeychainGroupStore();
+      if (!store) {
+        return false;
+      }
+      const value = JSON.stringify(credential);
+      try {
+        await store.setItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, value, {
+          ...readOptions,
+          keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+        // Read-back verify. A keychain write can resolve without the item having
+        // landed under the access group (a missing entitlement is the usual
+        // cause), and a phantom credential would send a fresh install into a mint
+        // that can never succeed.
+        return (await store.getItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, readOptions)) === value;
+      } catch {
+        return false;
+      }
+    },
+
+    clear: async (): Promise<void> => {
+      const store = await loadKeychainGroupStore();
+      if (!store) {
+        return;
+      }
+      try {
+        await store.deleteItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, readOptions);
+      } catch {
+        // Best-effort: the slot is a join point, not a source of truth.
+      }
+    },
+  };
+}
+
+/**
+ * The Android broker's JS surface. `read` returns an UNTRUSTED payload that
+ * {@link normalizeSharedDeviceSessionRead} narrows; `write` reports whether the
+ * native read-back confirmed the bytes.
+ */
+interface OxyDeviceSessionNativeModule {
+  read(): Promise<unknown>;
+  write(deviceId: string, deviceSecret: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+
+let brokerModule: OxyDeviceSessionNativeModule | null | undefined;
+
+/**
+ * Resolve the `OxyDeviceSession` broker, or `null` when it is not autolinked.
+ *
+ * `requireOptionalNativeModule` (a static import Metro always resolves) rather
+ * than a dynamic `import(moduleName)`: the latter compiles to `require(variable)`
+ * in the CJS build, which Metro cannot resolve inside a consuming app — it
+ * silently returns `null` there, which is exactly how the cross-app identity
+ * bridge broke once. Same reasoning as `backgroundSession.ts` next door.
+ */
+function loadBrokerModule(): OxyDeviceSessionNativeModule | null {
+  if (brokerModule === undefined) {
+    const native = requireOptionalNativeModule<Partial<OxyDeviceSessionNativeModule>>('OxyDeviceSession');
+    brokerModule =
+      native && typeof native.read === 'function' && typeof native.write === 'function' && typeof native.clear === 'function'
+        ? {
+            read: native.read.bind(native),
+            write: native.write.bind(native),
+            clear: native.clear.bind(native),
+          }
+        : null;
+  }
+  return brokerModule;
+}
+
+/**
+ * The Android store: the signature-protected `OxyDeviceSession` broker.
+ *
+ * The broker already answers with an explicit status, so the only work here is
+ * narrowing an UNTRUSTED payload — `normalizeSharedDeviceSessionRead` resolves
+ * anything it does not recognise to `unavailable`, never `absent`.
+ */
+function createBrokerCredentialStore(): SharedDeviceCredentialStore {
+  return {
+    read: async (): Promise<SharedDeviceCredentialRead> => {
+      const broker = loadBrokerModule();
+      if (!broker) {
+        return { state: 'unsupported' };
+      }
+      try {
+        return normalizeSharedDeviceSessionRead(await broker.read());
+      } catch (error) {
+        return { state: 'unavailable', cause: error };
+      }
+    },
+
+    publish: async (credential): Promise<boolean> => {
+      const broker = loadBrokerModule();
+      if (!broker) {
+        return false;
+      }
+      try {
+        // The broker read-back-verifies natively and returns the verdict.
+        return await broker.write(credential.deviceId, credential.deviceSecret);
+      } catch {
+        return false;
+      }
+    },
+
+    clear: async (): Promise<void> => {
+      const broker = loadBrokerModule();
+      if (!broker) {
+        return;
+      }
+      try {
+        await broker.clear();
+      } catch {
+        // Best-effort — see the iOS store.
+      }
+    },
+  };
+}
+
+/**
+ * The shared DeviceSession credential slot for this runtime, or `null` when
+ * there is none.
+ *
+ * The branch is on the PLATFORM, not on which module happens to load, because
+ * `expo-secure-store` loads perfectly well on Android — it would just quietly
+ * ignore `keychainAccessGroup` and read a package-private item, which looks
+ * exactly like an empty shared slot. This is the same iOS-vs-Android split
+ * `KeyManager` makes for the shared identity, for the same reason.
+ *
+ * Any other native platform gets the broker, which answers `unsupported` when
+ * the module is not linked — so the lane is simply off, which is the safe
+ * direction.
+ */
+export function createPlatformSharedDeviceCredentialStore(): SharedDeviceCredentialStore | null {
+  if (Platform.OS === 'web') {
+    return null;
+  }
+  return Platform.OS === 'ios' ? createKeychainGroupCredentialStore() : createBrokerCredentialStore();
+}

package/src/ui/stores/authStore.ts

@@ -1,63 +1,191 @@
-import { create } from 'zustand';
-import { createLogger, normalizeUserIdentity } from '@oxyhq/core';
+import { useCallback, useRef, useSyncExternalStore } from 'react';
 import type { User } from '@oxyhq/core';
+import type { OxyRuntime } from '../runtime';
 
-const log = createLogger('AuthStore');
-
+/**
+ * The signed-in user, as a zustand-shaped read/write surface.
+ *
+ * It used to BE a zustand store, and that made it a second owner of the
+ * session: the provider wrote `user`/`isAuthenticated` here, `SessionClient`
+ * wrote the same facts into its device state, and nothing reconciled them —
+ * when they disagreed, which one was right was not answerable. It is now a
+ * projection of the ONE `OxyRuntime` (ADR 0004): reads come off the runtime
+ * snapshot and writes go into the runtime, so there is nothing left to drift.
+ *
+ * The zustand SHAPE is kept deliberately — `useAuthStore(selector)`,
+ * `.getState()`, `.setState()`, `.subscribe()` — because a dozen call sites
+ * across this package and the Commons app read the user out of band, from
+ * mutation success handlers and cache helpers that are not inside a render.
+ * Rewriting them is Phase 8's cut, not this one's.
+ *
+ * `fetchUser` and `lastUserFetch` are GONE rather than projected: they were a
+ * five-minute profile cache with zero readers anywhere in the monorepo, and the
+ * Query cache has owned that job since long before this change.
+ */
 export interface AuthState {
   user: User | null;
   isAuthenticated: boolean;
   isLoading: boolean;
   error: string | null;
-  lastUserFetch: number | null; // Timestamp of last user fetch for caching
-  
+
   loginSuccess: (user: User) => void;
   loginFailure: (error: string) => void;
   logout: () => void;
-  fetchUser: (oxyServices: { getCurrentUser: () => Promise<User> }, forceRefresh?: boolean) => Promise<void>;
-  setUser: (user: User) => void; // Direct user setter for caching
+  /** Replace the signed-in profile after a write (a rename, a new avatar). */
+  setUser: (user: User) => void;
 }
 
-export const useAuthStore = create<AuthState>((set: (state: Partial<AuthState>) => void, get: () => AuthState) => ({
+/** The subset of `AuthState` a caller may push back in through `setState`. */
+export type AuthStatePatch = Partial<Pick<AuthState, 'user' | 'isLoading' | 'error'>>;
+
+let boundRuntime: OxyRuntime | null = null;
+let unbindRuntime: (() => void) | null = null;
+const listeners = new Set<() => void>();
+
+const loginSuccess = (user: User): void => {
+  boundRuntime?.setAccount(user);
+};
+
+const loginFailure = (error: string): void => {
+  boundRuntime?.batch(() => {
+    boundRuntime?.setLoading(false);
+    boundRuntime?.setError(error);
+  });
+};
+
+const logout = (): void => {
+  boundRuntime?.clearSession();
+};
+
+const setUser = (user: User): void => {
+  boundRuntime?.setAccount(user);
+};
+
+const SIGNED_OUT: AuthState = Object.freeze({
   user: null,
   isAuthenticated: false,
   isLoading: false,
   error: null,
-  lastUserFetch: null,
-
-  loginSuccess: (user: User) => set({
-    isLoading: false,
-    isAuthenticated: true,
-    user: normalizeUserIdentity(user),
-    lastUserFetch: Date.now(),
-  }),
-  loginFailure: (error: string) => set({ isLoading: false, error }),
-  logout: () => set({
-    user: null,
-    isAuthenticated: false,
-    lastUserFetch: null,
-  }),
-  setUser: (user: User) => set({ user: normalizeUserIdentity(user), lastUserFetch: Date.now() }),
-  fetchUser: async (oxyServices, forceRefresh = false) => {
-    const state = get();
-    const now = Date.now();
-    const cacheAge = state.lastUserFetch ? now - state.lastUserFetch : Number.POSITIVE_INFINITY;
-    const cacheValid = cacheAge < 5 * 60 * 1000; // 5 minutes cache
-
-    // Use cached data if available and not forcing refresh
-    if (!forceRefresh && state.user && cacheValid) {
-      log.info('Using cached user data', { cacheAge });
+  loginSuccess,
+  loginFailure,
+  logout,
+  setUser,
+});
+
+let state: AuthState = SIGNED_OUT;
+
+function project(runtime: OxyRuntime | null): AuthState {
+  if (runtime === null) {
+    return SIGNED_OUT;
+  }
+  const snapshot = runtime.getSnapshot();
+  return Object.freeze({
+    user: snapshot.account,
+    isAuthenticated: snapshot.account !== null,
+    isLoading: snapshot.isLoading,
+    error: snapshot.error?.message ?? null,
+    loginSuccess,
+    loginFailure,
+    logout,
+    setUser,
+  });
+}
+
+function republish(): void {
+  const next = project(boundRuntime);
+  if (
+    next.user === state.user &&
+    next.isAuthenticated === state.isAuthenticated &&
+    next.isLoading === state.isLoading &&
+    next.error === state.error
+  ) {
+    return;
+  }
+  state = next;
+  for (const listener of [...listeners]) {
+    listener();
+  }
+}
+
+/**
+ * Point this surface at the provider's runtime. Called once by
+ * `OxyRuntimeProvider`; the returned function detaches it again on unmount.
+ *
+ * With nothing bound, reads answer signed-out and writes are dropped. That is
+ * the honest answer for the two places it happens — the SSR shim, and a unit
+ * test poking the store with no provider mounted — and it is why binding is an
+ * explicit call rather than a lazily-created default runtime, which is exactly
+ * the fabricated-forever-loading runtime ADR 0004 deleted.
+ */
+export function bindAuthStoreToRuntime(runtime: OxyRuntime): () => void {
+  unbindRuntime?.();
+  boundRuntime = runtime;
+  unbindRuntime = runtime.subscribe(republish);
+  republish();
+  return () => {
+    if (boundRuntime !== runtime) {
       return;
     }
+    unbindRuntime?.();
+    unbindRuntime = null;
+    boundRuntime = null;
+    republish();
+  };
+}
 
-    set({ isLoading: true, error: null });
-    try {
-      const user = normalizeUserIdentity(await oxyServices.getCurrentUser());
-      set({ user, isLoading: false, isAuthenticated: true, lastUserFetch: now });
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Failed to fetch user';
-      log.error('Error fetching user', error);
-      set({ error: errorMessage, isLoading: false });
+const getState = (): AuthState => state;
+
+const setState = (patch: AuthStatePatch): void => {
+  boundRuntime?.batch(() => {
+    if (patch.isLoading !== undefined) {
+      boundRuntime?.setLoading(patch.isLoading);
+    }
+    if (patch.error !== undefined) {
+      boundRuntime?.setError(patch.error);
+    }
+    if (patch.user !== undefined) {
+      if (patch.user === null) {
+        boundRuntime?.clearSession();
+      } else {
+        boundRuntime?.setAccount(patch.user);
+      }
     }
-  },
-}));
+  });
+};
+
+const subscribe = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+function useAuthStoreHook<T>(selector: (state: AuthState) => T): T {
+  // The selection is cached against the state object it came from, so a
+  // selector returning a fresh object cannot make `useSyncExternalStore` see a
+  // new value on every call and loop.
+  const cache = useRef<{ state: AuthState; value: T } | null>(null);
+  const getSelection = useCallback((): T => {
+    const cached = cache.current;
+    if (cached !== null && cached.state === state) {
+      return cached.value;
+    }
+    const value = selector(state);
+    cache.current = { state, value };
+    return value;
+  }, [selector]);
+  return useSyncExternalStore(subscribe, getSelection, getSelection);
+}
+
+/**
+ * Read the signed-in user. Zustand-shaped, projected from the runtime.
+ *
+ * A selector that builds an object must be wrapped in `useShallow` (as every
+ * call site here already does) — otherwise a structurally-equal result reads as
+ * a change on every publish.
+ */
+export const useAuthStore = Object.assign(useAuthStoreHook, {
+  getState,
+  setState,
+  subscribe,
+});