@oxy.so/services 1.0.0

package/src/ui/context/commitSessionFlow.ts

@@ -0,0 +1,193 @@
+import type { User } from '@oxy.so/core';
+import { logger as loggerUtil } from '@oxy.so/core';
+import { allowsAutomaticIdpRedirect } from '../oauth/legacyRedirectLanes';
+import type { WebAuthMode } from '../oauth/types';
+import { isWebBrowser } from '../utils/isWebBrowser';
+import { isUnauthorizedStatus } from './oxyContextHelpers';
+
+const LOG_CONTEXT = { component: 'OxyContext', method: 'commitSession' } as const;
+
+export interface CommitDeviceSetAndResolveDeps {
+  /**
+   * Whether this commit is a deliberate sign-in on THIS device (activates the
+   * account and BLOCKS on the device-set reconcile before resolving) vs. a
+   * cold-boot restore (resolves auth from the profile fetch FIRST, then
+   * reconciles the device set in the background).
+   */
+  activate: boolean;
+  /** Cold boot already carries authoritative device state from the mint. */
+  hasDeviceState?: boolean;
+  /** The committing account id (only used by `registerAndActivate`). */
+  userId?: string;
+  /** Minimal user carried by the commit input; used if the profile fetch fails. */
+  fallbackUser: User | null;
+  /** Deliberate sign-in: register + activate the account in the device set. */
+  registerAndActivate: (userId?: string) => Promise<void>;
+  /** Cold boot: ensure membership only; the server's `activeAccountId` wins. */
+  addCurrentAccount: () => Promise<void>;
+  /** Start the device-scoped socket. */
+  startSocket: () => Promise<void>;
+  /** Project the server-authoritative device state onto local sessions. */
+  syncFromClient: () => Promise<void>;
+  /** Hydrate the full profile (the commit input carries only minimal data). */
+  getCurrentUser: () => Promise<User | null>;
+  loginSuccess: (user: User) => void;
+  onAuthStateChange?: (user: User | null) => void;
+  markAuthResolved: () => void;
+}
+
+/**
+ * Device-set registration + full-user hydration + auth-resolution gate flip.
+ *
+ * On a deliberate sign-in (`activate: true`) the device-set reconcile is awaited
+ * BEFORE hydrating and resolving — unchanged legacy ordering. On a cold boot
+ * (`activate: false`) auth resolves from the profile fetch FIRST so the app can
+ * paint an authenticated shell without waiting on device-set registration, the
+ * socket connect, and the authoritative sessions projection — those reconcile in
+ * a DETACHED background task a moment later.
+ */
+export async function commitDeviceSetAndResolve(
+  deps: CommitDeviceSetAndResolveDeps,
+): Promise<void> {
+  const {
+    activate,
+    hasDeviceState = false,
+    userId,
+    fallbackUser,
+    registerAndActivate,
+    addCurrentAccount,
+    startSocket,
+    syncFromClient,
+    getCurrentUser,
+    loginSuccess,
+    onAuthStateChange,
+    markAuthResolved,
+  } = deps;
+
+  // Register into the device set, start the socket, then project server truth. A
+  // deliberate sign-in ACTIVATES the account (`registerAndActivate`); the cold
+  // boot only ensures membership and lets the server's own `activeAccountId` win
+  // (`addCurrentAccount`).
+  const reconcileDeviceSet = async (): Promise<void> => {
+    if (activate) {
+      await registerAndActivate(userId);
+    } else if (!hasDeviceState) {
+      await addCurrentAccount();
+    }
+    await startSocket();
+    await syncFromClient();
+  };
+
+  const logReconcileError = (registrationError: unknown): void => {
+    // A 401 here is the EXPECTED signed-out edge: the bearer was stale/cleared, so
+    // the device-set registration (`POST /session/device/add`) cannot carry auth.
+    // This is not a failure — the cold boot re-registers on the next load once a
+    // valid session is minted. Log at debug; warn only on genuine unexpected
+    // failures (network, 5xx, malformed).
+    if (isUnauthorizedStatus(registrationError)) {
+      loggerUtil.debug('commitSession: device-set registration skipped (signed out)', LOG_CONTEXT, registrationError);
+      return;
+    }
+    loggerUtil.warn('commitSession: device-set registration failed', LOG_CONTEXT, registrationError);
+  };
+
+  // Hydrate the full user then flip the auth-resolution gate. Falls back to the
+  // minimal commit-input shape if the profile fetch fails — never leaves auth
+  // unresolved.
+  const hydrateAndResolve = async (): Promise<void> => {
+    let fullUser: User | null = null;
+    try {
+      fullUser = await getCurrentUser();
+    } catch (profileError) {
+      if (__DEV__) {
+        loggerUtil.debug('Failed to fetch full user on commit; using minimal fallback', LOG_CONTEXT, profileError);
+      }
+      fullUser = fallbackUser;
+    }
+    if (!fullUser) {
+      fullUser = fallbackUser;
+    }
+    if (fullUser) {
+      loginSuccess(fullUser);
+      onAuthStateChange?.(fullUser);
+    }
+    markAuthResolved();
+  };
+
+  if (activate) {
+    // Deliberate sign-in: block on the device-set reconcile (unchanged ordering)
+    // before hydrating + resolving, so the account is fully registered/active.
+    try {
+      await reconcileDeviceSet();
+    } catch (registrationError) {
+      logReconcileError(registrationError);
+    }
+    await hydrateAndResolve();
+    return;
+  }
+
+  // Cold boot: resolve auth from the profile fetch FIRST; reconcile the device
+  // set (membership when the mint did not already return it, socket + sessions
+  // projection) in a DETACHED background
+  // task so first paint is not blocked behind those round-trips.
+  await hydrateAndResolve();
+  void reconcileDeviceSet().catch(logReconcileError);
+}
+
+export interface MaybeSyncHubAfterCommitDeps {
+  /** Deliberate sign-in (`true`) vs. a cold-boot / background commit (`false`). */
+  activate: boolean;
+  /** Per-commit opt-in — `commitSession`'s `options.hubSync`. */
+  hubSyncRequested: boolean;
+  /** Provider-level opt-out — `OxyProviderProps.hubSync`. */
+  hubSyncEnabled: boolean;
+  /**
+   * The provider's web sign-in transport — `OxyProviderProps.webAuthMode`.
+   * A first-class input: `'popup'` forbids the redirect outright.
+   */
+  webAuthMode: WebAuthMode;
+  /**
+   * Starts the full-page hop to `auth.oxy.so/sync`; resolves `true` when the
+   * navigation was actually started.
+   */
+  syncHub: () => Promise<boolean>;
+}
+
+/**
+ * Post-sign-in hub sync: plant this device's credential on the IdP hub so OTHER
+ * official origins can silently restore a session on their next cold boot.
+ *
+ * The tail of the ONE commit funnel (`commitSession`), extracted so every gate
+ * on this legacy lane lives — and is tested — in one place. Returns whether the
+ * full-page redirect was started; a failure is non-fatal and never propagates
+ * (the sign-in itself already succeeded).
+ *
+ * Four gates, all of which must pass:
+ * 1. `activate` — only a deliberate sign-in syncs; a cold-boot restore never does.
+ * 2. `hubSyncRequested` — the in-place lanes (account switch, popup OAuth) opt out.
+ * 3. `hubSyncEnabled` — the provider-level `hubSync` prop.
+ * 4. `allowsAutomaticIdpRedirect(webAuthMode)` — hub sync REPLACES the document
+ *    with `auth.oxy.so`, so `webAuthMode: 'popup'` forbids it: a redirect that
+ *    bounces the tab defeats the entire point of the mode, no matter which
+ *    commit path produced the session (issue #691, "Cold boot and cross-domain
+ *    behavior"). Redirect mode — the default and the compatibility path — is
+ *    unchanged, and this whole function disappears with it in phase 7b.
+ */
+export async function maybeSyncHubAfterCommit(
+  deps: MaybeSyncHubAfterCommitDeps,
+): Promise<boolean> {
+  const { activate, hubSyncRequested, hubSyncEnabled, webAuthMode, syncHub } = deps;
+
+  if (!activate || !hubSyncRequested || !hubSyncEnabled) return false;
+  if (!allowsAutomaticIdpRedirect(webAuthMode)) return false;
+  if (!isWebBrowser()) return false;
+
+  try {
+    return await syncHub();
+  } catch (hubError) {
+    if (__DEV__) {
+      loggerUtil.debug('Hub sync after sign-in failed (non-fatal)', LOG_CONTEXT, hubError);
+    }
+    return false;
+  }
+}

package/src/ui/context/hooks/useAuthOperations.ts

@@ -0,0 +1,425 @@
+import { useCallback } from 'react';
+import type { ApiError, AuthStateStore, IdentityBinding, SessionClient, User } from '@oxy.so/core';
+import type { ClientSession, SessionLoginResponse } from '@oxy.so/core';
+import type { OxyRuntime } from '../../runtime';
+import { DeviceManager } from '@oxy.so/core';
+import { fetchSessionsWithFallback } from '../../utils/sessionHelpers';
+import { handleAuthError, isInvalidSessionError } from '../../utils/errorHandlers';
+import type { StorageInterface } from '../../utils/storageHelpers';
+import type { OxyServices } from '@oxy.so/core';
+import { SignatureService } from '@oxy.so/core';
+
+export interface UseAuthOperationsOptions {
+  oxyServices: OxyServices;
+  storage: StorageInterface | null;
+  /**
+   * The device-first persisted auth-state store. On EXPLICIT full sign-out the
+   * session blob is cleared (`store.clear()`) so a reload's cold boot finds no
+   * device credential to restore; on sign-in the returned zero-cookie device
+   * credential (`deviceId` + `deviceSecret`) is persisted so the next boot
+   * warm-restores without a redirect.
+   */
+  store: AuthStateStore;
+  /**
+   * The one owner of the session facts. Reads (`activeSessionId`) and writes
+   * (the account, the session mirror, the loading/error gates) both go through
+   * it, so this hook holds no copy of anything to fall out of step.
+   */
+  runtime: OxyRuntime;
+  saveActiveSessionId: (sessionId: string) => Promise<void>;
+  clearSessionState: () => Promise<void>;
+  /** Used only by `performSignIn`'s same-user duplicate-session dedup (legacy session-validate path; unrelated to the SessionClient device-account set). */
+  switchSession: (sessionId: string) => Promise<User>;
+  /**
+   * The Phase 3-A/3-B `SessionClient` (server-authoritative device account
+   * set). Device-scoped sign-out routes through `sessionClient.signOut(...)`.
+   * `logoutAll` additionally uses the global bearer endpoint so sessions on
+   * other devices and their refresh-token families are revoked.
+   */
+  sessionClient: SessionClient;
+  /** Reprojects `sessionClient.getState()` onto sessions/activeSessionId/user (Task 1's callback). Awaited after a partial `signOut` so the exposed state reflects the server truth before the call resolves. */
+  syncFromClient: () => Promise<void>;
+  onAuthStateChange?: (user: User | null) => void;
+  onError?: (error: ApiError) => void;
+  logger?: (message: string, error?: unknown) => void;
+  /**
+   * Identity-bound session (`sessionMode: 'identity'`). When set, a successful
+   * key sign-in writes the durable `{publicKey, accountId}` pin so pinned
+   * re-mints and projections bind immediately instead of waiting for a second
+   * `establishIdentitySession` round-trip.
+   */
+  identityBinding?: IdentityBinding;
+  /** Refreshes the provider's memoised pinned account id after the pin lands. */
+  refreshPinnedAccountId?: () => Promise<string | null>;
+}
+
+export interface UseAuthOperationsResult {
+  /** Sign in with existing public key */
+  signIn: (publicKey: string, deviceName?: string) => Promise<User>;
+  /** Logout from current session */
+  logout: (targetSessionId?: string) => Promise<void>;
+  /** Logout from all sessions */
+  logoutAll: () => Promise<void>;
+}
+
+const LOGIN_ERROR_CODE = 'LOGIN_ERROR';
+const LOGOUT_ERROR_CODE = 'LOGOUT_ERROR';
+const LOGOUT_ALL_ERROR_CODE = 'LOGOUT_ALL_ERROR';
+
+/**
+ * Clear the persisted device credential on an explicit full sign-out.
+ * Best-effort and non-blocking: sign-out must never fail because a storage
+ * write threw. Exported so `OxyContext`'s zero-account branch (a REMOTE full
+ * sign-out pushed over the socket) runs the EXACT same cleanup as the local
+ * `logout` / `logoutAll` paths — a remote sign-out is indistinguishable from a
+ * local one to the next cold boot.
+ */
+export function clearPersistedAuthSafe(
+  store: AuthStateStore,
+  logger?: (message: string, error?: unknown) => void,
+): void {
+  store.clear().catch((clearError) => {
+    logger?.('Failed to clear persisted auth state on sign-out', clearError);
+  });
+}
+
+/**
+ * Authentication operations using public key cryptography.
+ * Accepts public key as parameter - identity management is handled by the app layer.
+ */
+export const useAuthOperations = ({
+  oxyServices,
+  store,
+  runtime,
+  saveActiveSessionId,
+  clearSessionState,
+  switchSession,
+  sessionClient,
+  syncFromClient,
+  onAuthStateChange,
+  onError,
+  logger,
+  identityBinding,
+  refreshPinnedAccountId,
+}: UseAuthOperationsOptions): UseAuthOperationsResult => {
+  /**
+   * Internal function to perform challenge-response sign in.
+   */
+  const performSignIn = useCallback(
+    async (publicKey: string): Promise<User> => {
+      const deviceFingerprintObj = DeviceManager.getDeviceFingerprint();
+      const deviceFingerprint = JSON.stringify(deviceFingerprintObj);
+      const deviceInfo = await DeviceManager.getDeviceInfo();
+      const deviceName = deviceInfo.deviceName || DeviceManager.getDefaultDeviceName();
+
+      const challengeResponse = await oxyServices.requestChallenge(publicKey);
+      const challenge = challengeResponse.challenge;
+
+      // Note: Biometric authentication check should be handled by the app layer
+      // (e.g., accounts app) before calling signIn. The biometric preference is stored
+      // in local storage as 'oxy_biometric_enabled' and can be checked there.
+
+      // Sign the challenge
+      const { challenge: signature, timestamp } = await SignatureService.signChallenge(challenge);
+
+      let fullUser: User;
+      let sessionResponse: SessionLoginResponse;
+
+      // `verifyChallenge` plants the first access token internally, mirroring
+      // `claimSessionByToken`, so the client is authenticated as soon as this
+      // resolves.
+      sessionResponse = await oxyServices.verifyChallenge(
+        publicKey,
+        challenge,
+        signature,
+        timestamp,
+        deviceName,
+        deviceFingerprint,
+      );
+
+      // Persist the durable device credential so a reload warm-restores this
+      // session without a redirect. `verifyChallenge` plants the access token
+      // internally; when the response also carries the zero-cookie device
+      // credential (`deviceId` + `deviceSecret`), persist the durable blob so the
+      // next cold boot re-mints an access token from it. Best-effort — a failed
+      // persist never fails the sign-in.
+      const deviceSecret = sessionResponse.deviceSecret;
+      if (sessionResponse.deviceId && deviceSecret) {
+        try {
+          await store.save({
+            sessionId: sessionResponse.sessionId,
+            userId: sessionResponse.user.id,
+            deviceId: sessionResponse.deviceId,
+            deviceSecret,
+            ...(sessionResponse.accessToken ? { accessToken: sessionResponse.accessToken } : {}),
+            ...(sessionResponse.expiresAt ? { expiresAt: sessionResponse.expiresAt } : {}),
+          });
+        } catch (persistError) {
+          logger?.('Failed to persist auth state after sign-in', persistError);
+        }
+      }
+
+      if (identityBinding) {
+        try {
+          await identityBinding.pinStore.save({
+            publicKey: publicKey.toLowerCase(),
+            accountId: sessionResponse.user.id,
+          });
+          await refreshPinnedAccountId?.();
+        } catch (pinError) {
+          logger?.('Failed to persist identity pin after sign-in', pinError);
+        }
+      }
+
+      // Register this recovered account+session into the server-authoritative
+      // device-session set AND make it active: `registerAndActivate()` adds via
+      // `POST /session/device/add` (identity derived from the bearer
+      // `verifyChallenge` already planted) then switches to it, and
+      // `syncFromClient()` reprojects the resulting server state onto the
+      // exposed sessions/activeSessionId/user. Best-effort: a failure here must
+      // NEVER fail the sign-in itself — cold boot re-registers this account into
+      // the device set on the next load regardless.
+      try {
+        await sessionClient.registerAndActivate(sessionResponse.user.id);
+        await syncFromClient();
+      } catch (registrationError) {
+        logger?.('Failed to register sign-in into device session set', registrationError);
+      }
+
+      // Hydrate the full user from the bearer (`GET /users/me`) — `verifyChallenge`
+      // has already planted the access token for this session, so the bearer IS
+      // the session identity. Avoids a second, session-id-keyed source of truth
+      // (`GET /session/user/:sessionId`) that can disagree with the bearer.
+      fullUser = await oxyServices.getCurrentUser();
+
+      // Fetch device sessions
+      let allDeviceSessions: ClientSession[] = [];
+      try {
+        allDeviceSessions = await fetchSessionsWithFallback(oxyServices, sessionResponse.sessionId, {
+          fallbackDeviceId: sessionResponse.deviceId,
+          fallbackUserId: fullUser.id,
+          logger,
+        });
+      } catch (error) {
+        if (__DEV__ && logger) {
+          logger('Failed to fetch device sessions after login', error);
+        }
+      }
+
+      // Check for existing session for same user and switch to it to avoid duplicates
+      const existingSession = allDeviceSessions.find(
+        (session) =>
+          session.userId?.toString() === fullUser.id?.toString() &&
+          session.sessionId !== sessionResponse.sessionId,
+      );
+
+      if (existingSession) {
+        // Switch to existing session instead of creating duplicate
+        try {
+          await oxyServices.logoutSession(sessionResponse.sessionId, sessionResponse.sessionId);
+        } catch (logoutError) {
+          // Non-critical - continue to switch session even if logout fails
+          if (__DEV__ && logger) {
+            logger('Failed to logout duplicate session, continuing with switch', logoutError);
+          }
+        }
+        await switchSession(existingSession.sessionId);
+        runtime.mergeSessions(
+          allDeviceSessions.filter((session) => session.sessionId !== sessionResponse.sessionId),
+          { merge: false },
+        );
+        onAuthStateChange?.(fullUser);
+        return fullUser;
+      }
+
+      // One transition: the active id, the session mirror and the account all
+      // land together, so nothing is woken holding two of the three.
+      runtime.batch(() => {
+        runtime.setActiveSessionId(sessionResponse.sessionId);
+        runtime.mergeSessions(allDeviceSessions, { merge: true });
+        runtime.setAccount(fullUser);
+      });
+      await saveActiveSessionId(sessionResponse.sessionId);
+      onAuthStateChange?.(fullUser);
+
+      return fullUser;
+    },
+    [
+      logger,
+      onAuthStateChange,
+      oxyServices,
+      runtime,
+      saveActiveSessionId,
+      sessionClient,
+      store,
+      switchSession,
+      syncFromClient,
+      identityBinding,
+      refreshPinnedAccountId,
+    ],
+  );
+
+  /**
+   * Sign in with existing public key
+   */
+  const signIn = useCallback(
+    async (publicKey: string, deviceName?: string): Promise<User> => {
+      runtime.batch(() => {
+        runtime.setLoading(true);
+        runtime.setError(null);
+      });
+
+      try {
+        return await performSignIn(publicKey);
+      } catch (error) {
+        const message = handleAuthError(error, {
+          defaultMessage: 'Sign in failed',
+          code: LOGIN_ERROR_CODE,
+          onError,
+          setAuthError: (msg: string) => runtime.setError(msg),
+          logger,
+        });
+        runtime.setError(message);
+        throw error;
+      } finally {
+        runtime.setLoading(false);
+      }
+    },
+    [runtime, performSignIn, onError, logger],
+  );
+
+  /**
+   * Logout from session
+   */
+  const logout = useCallback(
+    async (targetSessionId?: string): Promise<void> => {
+      const activeSessionId = runtime.getSnapshot().activeSessionId;
+      if (!activeSessionId) return;
+
+      const sessionToLogout = targetSessionId || activeSessionId;
+
+      try {
+        // Resolve the device account backing this session from the
+        // server-authoritative `SessionClient` state — SERVER revocation now
+        // goes through `sessionClient.signOut(...)` instead of the
+        // bearer/cookie logout endpoints.
+        const targetAccountId = sessionClient
+          .getState()
+          ?.accounts.find((account) => account.sessionId === sessionToLogout)?.accountId;
+        if (!targetAccountId) {
+          throw new Error(`No device account found for session "${sessionToLogout}"`);
+        }
+
+        await sessionClient.signOut({ accountId: targetAccountId });
+
+        // The server has already decided what (if anything) remains active on
+        // this device; reproject that truth onto the exposed sessions /
+        // activeSessionId / user before deciding whether additional LOCAL
+        // teardown is needed.
+        const remainingAccounts = sessionClient.getState()?.accounts ?? [];
+        await syncFromClient();
+
+        if (sessionToLogout === activeSessionId && remainingAccounts.length === 0) {
+          // Genuine FULL sign-out (no sessions remain): clear the persisted
+          // device credential so a reload's cold boot finds nothing to restore,
+          // then tear down local state.
+          clearPersistedAuthSafe(store, logger);
+          await clearSessionState();
+        }
+      } catch (error) {
+        const isInvalid = isInvalidSessionError(error);
+
+        // Compare the RESOLVED target, not the raw optional parameter: every
+        // in-app sign-out affordance calls `logout()` with no argument, which
+        // would otherwise never match `activeSessionId` and would leave the UI
+        // "signed in" against a bearer the 401 lane has already cleared.
+        if (isInvalid && sessionToLogout === activeSessionId) {
+          // The active session is invalid → full sign-out; clear persisted state.
+          clearPersistedAuthSafe(store, logger);
+          await clearSessionState();
+          return;
+        }
+
+        handleAuthError(error, {
+          defaultMessage: 'Logout failed',
+          code: LOGOUT_ERROR_CODE,
+          onError,
+          setAuthError: (msg: string) => runtime.setError(msg),
+          logger,
+          status: isInvalid ? 401 : undefined,
+        });
+      }
+    },
+    [
+      clearSessionState,
+      store,
+      logger,
+      onError,
+      runtime,
+      sessionClient,
+      syncFromClient,
+    ],
+  );
+
+  /**
+   * Logout from all sessions
+   */
+  const logoutAll = useCallback(async (): Promise<void> => {
+    const activeSessionId = runtime.getSnapshot().activeSessionId;
+    if (!activeSessionId) {
+      const error = new Error('No active session found');
+      runtime.setError(error.message);
+      onError?.({ message: error.message, code: LOGOUT_ALL_ERROR_CODE, status: 404 });
+      throw error;
+    }
+
+    try {
+      // Revoke the user's sessions on every other device and every refresh-
+      // token family first. SessionClient's `{ all: true }` operation is only
+      // device-scoped and therefore cannot implement "sign out everywhere" by
+      // itself. The global endpoint deliberately preserves the current
+      // session long enough for the device-scoped cleanup below to authenticate.
+      await oxyServices.logoutAllSessions(activeSessionId);
+      await sessionClient.signOut({ all: true });
+      // logoutAll is ALWAYS a full sign-out: clear the persisted device
+      // credential so the next cold boot finds no session to restore, then tear
+      // down local state.
+      clearPersistedAuthSafe(store, logger);
+      await clearSessionState();
+    } catch (error) {
+      if (isInvalidSessionError(error)) {
+        // An already-invalid bearer means the sessions this call would have
+        // revoked are ALREADY gone — the sign-out happened, it just happened
+        // before we asked. This is the normal tail of an account deletion
+        // (`DELETE /users/me` revokes every session and detaches the account
+        // from every device before returning) and of any remote revocation.
+        // `HttpService` has cleared the tokens and emitted
+        // `onTokensChanged(null)` by now, so rejecting here would contradict
+        // the SDK's own authoritative 401 lane and hand the caller a failure
+        // for work that is complete. Finish the local teardown and resolve.
+        clearPersistedAuthSafe(store, logger);
+        await clearSessionState();
+        return;
+      }
+
+      const message = handleAuthError(error, {
+        defaultMessage: 'Logout all failed',
+        code: LOGOUT_ALL_ERROR_CODE,
+        onError,
+        setAuthError: (msg: string) => runtime.setError(msg),
+        logger,
+      });
+      // `HttpService` rejects with the plain `ApiError` object `handleHttpError`
+      // builds, never an `Error` instance — so rethrow the message
+      // `handleAuthError` already resolved instead of a generic placeholder that
+      // would erase the server's reason from every caller's toast.
+      throw error instanceof Error ? error : new Error(message);
+    }
+  }, [clearSessionState, store, logger, onError, oxyServices, runtime, sessionClient]);
+
+  return {
+    signIn,
+    logout,
+    logoutAll,
+  };
+};

package/src/ui/context/oxyContextHelpers.ts

@@ -0,0 +1,28 @@
+/** Local display hint when a session lacks explicit `expiresAt` (7 days). */
+export const DEFAULT_SESSION_VALIDITY_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function getHttpStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  if ('status' in error) {
+    const status = (error as { status?: unknown }).status;
+    if (typeof status === 'number') {
+      return status;
+    }
+  }
+  if ('response' in error) {
+    const response = (error as { response?: unknown }).response;
+    if (response && typeof response === 'object' && 'status' in response) {
+      const status = (response as { status?: unknown }).status;
+      if (typeof status === 'number') {
+        return status;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function isUnauthorizedStatus(error: unknown): boolean {
+  return getHttpStatus(error) === 401;
+}