@oxy.so/services 12.13.0 → 12.14.0

package/src/ui/context/OxyContext.tsx

@@ -59,7 +59,8 @@ import {
   hasPersistedSessionCredential,
   loadPersistedDeviceCredential,
 } from '../utils/deviceCredential';
-import { createTokenLossRecovery } from '../session/tokenLossRecovery';
+import { createTokenLossRecovery, TOKEN_RECOVERY_BACKOFF_MS } from '../session/tokenLossRecovery';
+import { createCachedBootStore, type CachedBootStore } from '../session/cachedBoot';
 import { bindAuthStoreToRuntime } from '../stores/authStore';
 import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
@@ -222,8 +223,19 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     clientId: string | undefined;
     services: OxyServices;
     lane: 'device' | 'oauth' | null;
+    /**
+     * `lane` is this device's cached verdict, standing in until the registry
+     * answers (a painted cold boot). A fresh lookup keeps it meanwhile.
+     */
+    provisional: boolean;
     pending: Promise<'device' | 'oauth'> | null;
-  }>({ clientId: clientIdProp, services: oxyServices, lane: null, pending: null });
+  }>({
+    clientId: clientIdProp,
+    services: oxyServices,
+    lane: null,
+    provisional: false,
+    pending: null,
+  });
   if (
     registeredLaneRef.current.clientId !== clientIdProp ||
     registeredLaneRef.current.services !== oxyServices
@@ -232,6 +244,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       clientId: clientIdProp,
       services: oxyServices,
       lane: null,
+      provisional: false,
       pending: null,
     };
   }
@@ -372,6 +385,15 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   }
   const storageReady = storageReadyRef.current;
 
+  // What a returning session's first paint needs (the app's classification and
+  // the account's profile), kept in the same storage as the account query cache.
+  const cachedBoot = useMemo(
+    () => (storage ? createCachedBootStore(storage, storageKeyPrefix) : null),
+    [storage, storageKeyPrefix],
+  );
+  const cachedBootRef = useRef<CachedBootStore | null>(cachedBoot);
+  cachedBootRef.current = cachedBoot;
+
   useEffect(() => {
     // `null` means the public provider owns initialization and has not resolved
     // it yet. `undefined` means this internal provider was mounted directly and
@@ -535,11 +557,17 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     if (selected.clientId !== clientIdProp || selected.services !== oxyServices)
       throw new Error('Provider classification was superseded');
     if (selected.pending) return selected.pending;
-    selected.lane = null;
+    if (!selected.provisional) selected.lane = null;
     const pending = (async () => {
       const lane = await resolveApplicationSessionLane(oxyServices, clientIdProp);
       if (registeredLaneRef.current !== selected)
         throw new Error('Provider classification was superseded');
+      if (clientIdProp) void cachedBootRef.current?.saveLane(clientIdProp, lane);
+      if (selected.provisional) {
+        // The registry has answered: its verdict replaces the cached one now.
+        selected.provisional = false;
+        selected.lane = lane;
+      }
       if (lane === 'oauth' && !hasIsolatedOAuthSession(runtime)) {
         sessionClient.resetLocalState();
         sessionClientHost.setDeviceCredential(null);
@@ -1284,6 +1312,115 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     if (!accountDialogOpen) clearSignInFlows(accountDialogControllerRef.current);
   }, [accountDialogOpen]);
 
+  // ── Cached first paint ───────────────────────────────────────────────────
+  // Keep the profile the runtime holds for the signed-in account, so the next
+  // cold boot can paint it before the network answers. Only for a device-lane
+  // account session: an identity-bound client and an isolated OAuth session
+  // always boot through the network. A sign-out deletes it.
+  const cachedAccountJsonRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!cachedBoot || identity) return;
+    if (user === null) {
+      if (cachedAccountJsonRef.current !== null) {
+        cachedAccountJsonRef.current = null;
+        void cachedBoot.clearAccount();
+      }
+      return;
+    }
+    if (registeredLaneRef.current.lane !== 'device' || hasIsolatedOAuthSession(runtime)) return;
+    const json = JSON.stringify(user);
+    if (json === cachedAccountJsonRef.current) return;
+    cachedAccountJsonRef.current = json;
+    void cachedBoot.saveAccount(user);
+  }, [cachedBoot, identity, user, runtime]);
+
+  // Paint the session saved on this device: the bearer it left (when still
+  // valid), the session mirror, the account from its cached profile, auth
+  // resolved. Local reads only; the boot checks it all in the background.
+  const paintCachedSession = useCallback(async (): Promise<boolean> => {
+    const cache = cachedBootRef.current;
+    if (identity || !clientIdProp || !cache) return false;
+    const cached = await cache.readSession(clientIdProp, authStore);
+    const selected = registeredLaneRef.current;
+    if (
+      !cached ||
+      selected.clientId !== clientIdProp ||
+      selected.services !== oxyServices ||
+      selected.lane === 'oauth'
+    ) {
+      return false;
+    }
+    if (selected.lane === null) {
+      // The cached verdict stands in for the registry until it answers, so the
+      // refresh handler, lost-token recovery and sign-in treat this app as the
+      // device lane it was on last run.
+      selected.lane = 'device';
+      selected.provisional = true;
+    }
+    if (cached.warmToken) oxyServices.session.setAccessToken(cached.warmToken);
+    await syncDeviceCredentialToHost();
+    const now = new Date();
+    runtime.batch(() => {
+      runtime.mergeSessions(
+        [
+          {
+            sessionId: cached.sessionId,
+            deviceId: cached.deviceId,
+            expiresAt: new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
+            lastActive: now.toISOString(),
+            userId: cached.userId,
+            isCurrent: true,
+          },
+        ],
+        { merge: true },
+      );
+      runtime.setActiveSessionId(cached.sessionId);
+      runtime.setAccount(cached.user);
+    });
+    onAuthStateChangeRef.current?.(cached.user);
+    markAuthResolvedRef.current();
+    return true;
+  }, [identity, clientIdProp, authStore, oxyServices, runtime, syncDeviceCredentialToHost]);
+
+  // A painted session the server could not be asked about yet stays on screen
+  // and is asked again: on the lost-token backoff, and at once when the device
+  // comes back online. Signed out meanwhile, there is nothing left to ask.
+  const cachedSessionCheckRef = useRef<{
+    timer: ReturnType<typeof setTimeout> | null;
+    attempt: number;
+    runNow: (() => void) | null;
+  }>({ timer: null, attempt: 0, runNow: null });
+  const scheduleCachedSessionCheck = useCallback(
+    (retry: () => Promise<void>): void => {
+      const check = cachedSessionCheckRef.current;
+      if (check.timer !== null) clearTimeout(check.timer);
+      const run = (): void => {
+        if (check.timer !== null) clearTimeout(check.timer);
+        check.timer = null;
+        check.runNow = null;
+        if (runtime.getSnapshot().account === null) return;
+        retry().catch((retryError) => {
+          logger('Failed to check the cached session', retryError);
+        });
+      };
+      const delay =
+        TOKEN_RECOVERY_BACKOFF_MS[Math.min(check.attempt, TOKEN_RECOVERY_BACKOFF_MS.length - 1)];
+      check.attempt += 1;
+      check.runNow = run;
+      check.timer = setTimeout(run, delay);
+    },
+    [runtime, logger],
+  );
+  useEffect(
+    () => () => {
+      const check = cachedSessionCheckRef.current;
+      if (check.timer !== null) clearTimeout(check.timer);
+      check.timer = null;
+      check.runNow = null;
+    },
+    [],
+  );
+
   // ── Cold boot ────────────────────────────────────────────────────────────
   // Device-first session restore via `runProviderColdBoot` (see boot/runProviderColdBoot.ts).
   const runColdBoot = useCallback(async (): Promise<void> => {
@@ -1314,6 +1451,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       commitSession: (input, options) => commitSessionRef.current(input, options),
       markAuthResolved: () => markAuthResolvedRef.current(),
       setTokenReady,
+      paintCachedSession,
+      onCachedSessionRejected: () => clearSessionStateRef.current(),
+      onCachedSessionUnconfirmed: scheduleCachedSessionCheck,
     });
     // The boot may have (re-)established the identity session or cleared a pin
     // whose key no longer exists, so re-resolve rather than trusting the memo
@@ -1329,6 +1469,8 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     syncDeviceCredentialToHost,
     sessionClient,
     setTokenReady,
+    paintCachedSession,
+    scheduleCachedSessionCheck,
   ]);
 
   useEffect(() => {
@@ -1427,6 +1569,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       if (!online || !wasOffline) {
         return;
       }
+      cachedSessionCheckRef.current.runNow?.();
       void (async () => {
         if (hasIsolatedOAuthSession(runtime)) return;
         if (oxyServices.session.accessToken || !sessionClientHost.getDeviceCredential()) {

package/src/ui/session/__tests__/cachedBoot.test.ts

@@ -0,0 +1,32 @@
+import type { User } from '@oxy.so/core';
+import type { AuthStateStore, PersistedAuthState } from '@oxy.so/core/session';
+import { createCachedBootStore } from '../cachedBoot';
+import { createMemoryStorage } from '../../utils/storageHelpers';
+
+function authStore(state: PersistedAuthState): AuthStateStore {
+  return {
+    load: async () => state,
+    save: async () => true,
+    clear: async () => undefined,
+  };
+}
+
+it('offers a cached session only for the account the saved session belongs to', async () => {
+  const cache = createCachedBootStore(createMemoryStorage(), 'oxy_session');
+  const saved = { sessionId: 's1', userId: 'u1', deviceId: 'd1', deviceSecret: 'secret' };
+  await cache.saveLane('client', 'device');
+  await cache.saveAccount({ id: 'u2', username: 'other' } as User);
+
+  expect(await cache.readSession('client', authStore(saved))).toBeNull();
+
+  await cache.saveAccount({ id: 'u1', username: 'me' } as User);
+  expect(await cache.readSession('client', authStore(saved))).toMatchObject({
+    sessionId: 's1',
+    user: { id: 'u1' },
+    warmToken: null,
+  });
+  // Another app's classification, or an OAuth-only one, never paints.
+  expect(await cache.readSession('another-client', authStore(saved))).toBeNull();
+  await cache.saveLane('client', 'oauth');
+  expect(await cache.readSession('client', authStore(saved))).toBeNull();
+});

package/src/ui/session/cachedBoot.ts

@@ -0,0 +1,139 @@
+/**
+ * What a returning session needs for its first paint, kept on this device.
+ *
+ * A cold boot used to wait on two round trips before it showed anything: the
+ * registry's classification of this app and the profile of the signed-in
+ * account. With a session saved on the device, the app now paints at once from
+ * what the last run left here, and the boot verifies both in the background
+ * (`runProviderColdBoot`). This module is that cache:
+ *
+ * - the registry's last verdict on this app (`device` or `oauth`), tied to the
+ *   `clientId` it was given for;
+ * - the last account profile the runtime held, tied to that account's id.
+ *
+ * Both live in the provider's ordinary storage (AsyncStorage on native,
+ * `localStorage` on web), next to the per-account query cache, which already
+ * holds the same profile under the SDK's `users` queries. Neither is a
+ * credential: the device secret and the access token stay in the auth store.
+ *
+ * A cached session is offered only when it matches the auth store: the profile
+ * must belong to the account the persisted session is for, so a switch or a
+ * sign-out on a previous run can never paint somebody else.
+ */
+import type { User } from '@oxy.so/core';
+import { TOKEN_REFRESH_LEAD_MS, type AuthStateStore } from '@oxy.so/core/session';
+import type { StorageInterface } from '../utils/storageHelpers';
+
+export type SessionLane = 'device' | 'oauth';
+
+/** A persisted session the app can show before the network answers. */
+export interface CachedSession {
+  sessionId: string;
+  userId: string;
+  deviceId: string;
+  /** The account profile the last run held for {@link userId}. */
+  user: User;
+  /** The persisted access token, when it is still valid past the refresh lead. */
+  warmToken: string | null;
+}
+
+export interface CachedBootStore {
+  saveLane(clientId: string, lane: SessionLane): Promise<void>;
+  saveAccount(user: User): Promise<void>;
+  clearAccount(): Promise<void>;
+  /**
+   * The cached session for this `clientId`, or `null` when anything a first
+   * paint needs is missing or does not match the auth store.
+   */
+  readSession(clientId: string, authStore: AuthStateStore): Promise<CachedSession | null>;
+}
+
+const SCHEMA_VERSION = 1;
+
+function parse(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    return value && typeof value === 'object' ? (value as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isUser(value: unknown): value is User {
+  return (
+    Boolean(value) &&
+    typeof value === 'object' &&
+    typeof (value as { id?: unknown }).id === 'string' &&
+    (value as { id: string }).id.length > 0
+  );
+}
+
+export function createCachedBootStore(
+  storage: StorageInterface,
+  prefix: string,
+  now: () => number = Date.now,
+): CachedBootStore {
+  const laneKey = `${prefix}_boot_lane`;
+  const accountKey = `${prefix}_boot_account`;
+  // Storage failures are never fatal here: a missing entry only means the next
+  // boot waits for the network, as every boot did before this cache existed.
+  const write = (key: string, value: unknown) =>
+    storage.setItem(key, JSON.stringify({ v: SCHEMA_VERSION, ...(value as object) })).catch(() => {
+      /* best effort */
+    });
+
+  return {
+    saveLane: (clientId, lane) => write(laneKey, { clientId, lane }),
+    saveAccount: (user) => write(accountKey, { user }),
+    clearAccount: () =>
+      storage.removeItem(accountKey).catch(() => {
+        /* best effort */
+      }),
+
+    async readSession(clientId, authStore) {
+      const [laneEntry, accountEntry] = await Promise.all([
+        storage.getItem(laneKey).then(parse, () => null),
+        storage.getItem(accountKey).then(parse, () => null),
+      ]);
+      if (
+        laneEntry?.v !== SCHEMA_VERSION ||
+        laneEntry.clientId !== clientId ||
+        laneEntry.lane !== 'device'
+      ) {
+        return null;
+      }
+      const user = accountEntry?.v === SCHEMA_VERSION ? accountEntry.user : null;
+      if (!isUser(user)) return null;
+
+      const persisted = await authStore.load();
+      // Only the app's OWN holder: the background check mints with it, which is
+      // the only way the server can confirm or end this session.
+      if (
+        !persisted?.sessionId ||
+        !persisted.deviceId ||
+        !persisted.deviceSecret ||
+        persisted.userId !== user.id
+      ) {
+        return null;
+      }
+      // A recorded sign-out on this device restores nothing automatically.
+      if (await authStore.isAutomaticIdentitySignInSuppressed?.()) return null;
+
+      const expiresAtMs = persisted.expiresAt ? new Date(persisted.expiresAt).getTime() : NaN;
+      const warmToken =
+        persisted.accessToken &&
+        Number.isFinite(expiresAtMs) &&
+        expiresAtMs > now() + TOKEN_REFRESH_LEAD_MS
+          ? persisted.accessToken
+          : null;
+      return {
+        sessionId: persisted.sessionId,
+        userId: persisted.userId,
+        deviceId: persisted.deviceId,
+        user,
+        warmToken,
+      };
+    },
+  };
+}