@oxy.so/services 12.12.0 → 12.14.0

package/src/ui/hooks/queries/useSupervision.ts

@@ -1,25 +1,59 @@
-import { useQuery } from '@tanstack/react-query';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { SUPERVISION_CHANGED_EVENT } from '@oxy.so/contracts/client';
 import { useOxy } from '../../context/oxyRuntimeContext';
+import { useOxyEvent } from '../useOxyEvent';
+
 export const supervisionQueryKeys = {
   all: ['oxy', 'safety', 'supervision'] as const,
   account: (id: string, sessionId: string) =>
     ['oxy', 'safety', 'supervision', id, sessionId] as const,
 };
-/** Advisory UI state only. Every read/write still requires the live server policy. */
+
+/**
+ * The signed-in personal account's supervision (parental-control) state.
+ *
+ * Policy: the SDK keeps the session's supervision state always current — it is
+ * fetched when the session is established, refetched when the app returns to
+ * the foreground, and refetched when the session socket signals
+ * `supervision_changed` (`SupervisionStateObserver`, mounted by `OxyProvider`).
+ * Screens read it from the cache without waiting for the network: no observer
+ * forces its own refetch on mount. `data` is undefined only while the session's
+ * first fetch is pending, when the query is disabled (signed out, or not a
+ * personal account) and after a failed fetch.
+ *
+ * Advisory UI state only. The server keeps enforcing supervision on every
+ * content request; never treat this value as authorization.
+ */
 export function useSupervision() {
-  const { oxyServices, user, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, user, canUsePrivateApi, activeSessionId } = useOxy();
   const result = useQuery({
     queryKey: supervisionQueryKeys.account(user?.id ?? '', activeSessionId ?? ''),
     queryFn: () => oxyServices.safety.supervisionState(),
-    enabled: isAuthenticated && !!activeSessionId && user?.kind === 'personal',
-    staleTime: 0,
-    gcTime: 0,
+    enabled: canUsePrivateApi && !!activeSessionId && user?.kind === 'personal',
+    // Fresh until the socket signal or a return to the foreground says otherwise.
+    staleTime: Number.POSITIVE_INFINITY,
+    // The observer below keeps the current session's entry alive; this only
+    // bounds how long a previous session's entry outlives it.
+    gcTime: 30 * 60 * 1000,
     refetchOnWindowFocus: 'always',
-    refetchOnMount: 'always',
-    retry: false,
   });
   return {
     ...result,
-    data: result.isFetchedAfterMount && !result.isError ? result.data : undefined,
+    data: result.isError ? undefined : result.data,
   };
 }
+
+/**
+ * Keeps the session's supervision state current for every `useSupervision()`
+ * reader: its observer fetches once the session is established and on each
+ * return to the foreground, and the `supervision_changed` socket signal
+ * refetches it. Rendered once by `OxyProvider`.
+ */
+export function SupervisionStateObserver() {
+  const queryClient = useQueryClient();
+  useSupervision();
+  useOxyEvent(SUPERVISION_CHANGED_EVENT, () => {
+    void queryClient.invalidateQueries({ queryKey: supervisionQueryKeys.all });
+  });
+  return null;
+}

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,
+      };
+    },
+  };
+}