@oxyhq/services 10.5.0 → 11.1.0

package/src/ui/hooks/mutations/useAccountMutations.ts

@@ -40,10 +40,10 @@ export const useUpdateProfile = () => {
     // Optimistic update
     onMutate: async (updates) => {
       // Cancel outgoing refetches
-      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current() });
+      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current(activeSessionId) });
 
       // Snapshot previous value
-      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
 
       // Optimistically update
       if (previousUser) {
@@ -54,7 +54,7 @@ export const useUpdateProfile = () => {
             ? { ...previousUser.name, ...updates.name }
             : previousUser.name,
         };
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), optimisticUser);
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), optimisticUser);
 
         // Also update profile query if sessionId is available
         if (activeSessionId) {
@@ -74,9 +74,9 @@ export const useUpdateProfile = () => {
           return acc;
         }, {});
 
-        const current = queryClient.getQueryData<User>(queryKeys.accounts.current());
+        const current = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
         if (current) {
-          queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+          queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
             ...current,
             ...partialRollback,
           });
@@ -96,7 +96,7 @@ export const useUpdateProfile = () => {
     // On success, invalidate and refetch
     onSuccess: (data, updates) => {
       // Update cache with server response
-      queryClient.setQueryData(queryKeys.accounts.current(), data);
+      queryClient.setQueryData(queryKeys.accounts.current(activeSessionId), data);
       if (activeSessionId) {
         queryClient.setQueryData(queryKeys.users.profile(activeSessionId), data);
       }
@@ -143,8 +143,8 @@ export const useUploadAvatar = () => {
       });
     },
     onMutate: async (file) => {
-      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current() });
-      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current(activeSessionId) });
+      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
 
       // Optimistically set a temporary avatar (using file URI as placeholder)
       if (previousUser) {
@@ -152,7 +152,7 @@ export const useUploadAvatar = () => {
           ...previousUser,
           avatar: file.uri, // Temporary, will be replaced with fileId
         };
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), optimisticUser);
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), optimisticUser);
         if (activeSessionId) {
           queryClient.setQueryData<User>(queryKeys.users.profile(activeSessionId), optimisticUser);
         }
@@ -164,9 +164,9 @@ export const useUploadAvatar = () => {
       // Avatar upload only mutates the `avatar` field — restore only that key
       if (context?.previousUser) {
         const previousAvatar = context.previousUser.avatar;
-        const current = queryClient.getQueryData<User>(queryKeys.accounts.current());
+        const current = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
         if (current) {
-          queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+          queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
             ...current,
             avatar: previousAvatar,
           });
@@ -184,7 +184,7 @@ export const useUploadAvatar = () => {
       toast.error(error instanceof Error ? error.message : 'Failed to upload avatar');
     },
     onSuccess: (data) => {
-      queryClient.setQueryData(queryKeys.accounts.current(), data);
+      queryClient.setQueryData(queryKeys.accounts.current(activeSessionId), data);
       if (activeSessionId) {
         queryClient.setQueryData(queryKeys.users.profile(activeSessionId), data);
       }
@@ -270,10 +270,10 @@ export const useUpdateAccountSettings = () => {
     },
     onMutate: async ({ updates }) => {
       await queryClient.cancelQueries({ queryKey: queryKeys.accounts.settings() });
-      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
 
       if (previousUser) {
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
           ...previousUser,
           privacySettings: {
             ...previousUser.privacySettings,
@@ -294,9 +294,9 @@ export const useUpdateAccountSettings = () => {
           return acc;
         }, {});
 
-        const current = queryClient.getQueryData<User>(queryKeys.accounts.current());
+        const current = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
         if (current) {
-          queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+          queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
             ...current,
             privacySettings: {
               ...(current.privacySettings ?? {}),
@@ -308,7 +308,7 @@ export const useUpdateAccountSettings = () => {
       toast.error(error instanceof Error ? error.message : 'Failed to update settings');
     },
     onSuccess: (data) => {
-      queryClient.setQueryData(queryKeys.accounts.current(), data);
+      queryClient.setQueryData(queryKeys.accounts.current(activeSessionId), data);
 
       // Update authStore so frontend components see the changes immediately
       useAuthStore.getState().setUser(data);
@@ -328,7 +328,7 @@ export const useUpdateAccountSettings = () => {
   return {
     ...mutation,
     mutate: (updates: Partial<PrivacySettings>): void => {
-      const currentUser = user ?? queryClient.getQueryData<User>(queryKeys.accounts.current());
+      const currentUser = user ?? queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
       if (!currentUser) {
         toast.error('Cannot update account settings: no current user');
         return;
@@ -336,7 +336,7 @@ export const useUpdateAccountSettings = () => {
       mutation.mutate({ updates, currentUser });
     },
     mutateAsync: async (updates: Partial<PrivacySettings>): Promise<User> => {
-      const currentUser = user ?? queryClient.getQueryData<User>(queryKeys.accounts.current());
+      const currentUser = user ?? queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
       if (!currentUser) {
         throw new Error('Cannot update account settings: no current user');
       }
@@ -373,11 +373,11 @@ export const useUpdatePrivacySettings = () => {
 
       // Cancel outgoing refetches
       await queryClient.cancelQueries({ queryKey: queryKeys.privacy.settings(targetUserId) });
-      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current() });
+      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current(activeSessionId) });
 
       // Snapshot previous values
       const previousPrivacySettings = queryClient.getQueryData(queryKeys.privacy.settings(targetUserId));
-      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
 
       // Optimistically update privacy settings
       if (previousPrivacySettings) {
@@ -389,7 +389,7 @@ export const useUpdatePrivacySettings = () => {
 
       // Also update user query if available
       if (previousUser) {
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
           ...previousUser,
           privacySettings: {
             ...previousUser.privacySettings,
@@ -431,9 +431,9 @@ export const useUpdatePrivacySettings = () => {
           (acc as Record<string, unknown>)[key as string] = previousPrivacy[key as string];
           return acc;
         }, {});
-        const current = queryClient.getQueryData<User>(queryKeys.accounts.current());
+        const current = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
         if (current) {
-          queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+          queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
             ...current,
             privacySettings: {
               ...(current.privacySettings ?? {}),
@@ -479,7 +479,7 @@ export const useUpdatePrivacySettings = () => {
         }),
       );
 
-      const currentUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      const currentUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
       if (currentUser) {
         const updatedUser: User = {
           ...currentUser,
@@ -489,7 +489,7 @@ export const useUpdatePrivacySettings = () => {
             ...incoming,
           },
         };
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), updatedUser);
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), updatedUser);
         useAuthStore.getState().setUser(updatedUser);
       }
       // Deliberately NOT invalidating any queries here. invalidateAccountQueries
@@ -538,11 +538,11 @@ export const useUpdateNotificationPreferences = () => {
       );
     },
     onMutate: async (preferences) => {
-      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current() });
-      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current(activeSessionId) });
+      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
 
       if (previousUser) {
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
           ...previousUser,
           notificationPreferences: {
             ...previousUser.notificationPreferences,
@@ -555,9 +555,9 @@ export const useUpdateNotificationPreferences = () => {
     },
     onError: (error, _preferences, context) => {
       if (context?.previousUser) {
-        const current = queryClient.getQueryData<User>(queryKeys.accounts.current());
+        const current = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
         if (current) {
-          queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+          queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
             ...current,
             notificationPreferences: context.previousUser.notificationPreferences,
           });
@@ -570,7 +570,7 @@ export const useUpdateNotificationPreferences = () => {
       );
     },
     onSuccess: (data) => {
-      queryClient.setQueryData(queryKeys.accounts.current(), data);
+      queryClient.setQueryData(queryKeys.accounts.current(activeSessionId), data);
       useAuthStore.getState().setUser(data);
       invalidateAccountQueries(queryClient);
     },
@@ -596,11 +596,11 @@ export const useUpdateUserPreferences = () => {
       );
     },
     onMutate: async (preferences) => {
-      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current() });
-      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current());
+      await queryClient.cancelQueries({ queryKey: queryKeys.accounts.current(activeSessionId) });
+      const previousUser = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
 
       if (previousUser) {
-        queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+        queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
           ...previousUser,
           userPreferences: {
             ...previousUser.userPreferences,
@@ -613,9 +613,9 @@ export const useUpdateUserPreferences = () => {
     },
     onError: (error, _preferences, context) => {
       if (context?.previousUser) {
-        const current = queryClient.getQueryData<User>(queryKeys.accounts.current());
+        const current = queryClient.getQueryData<User>(queryKeys.accounts.current(activeSessionId));
         if (current) {
-          queryClient.setQueryData<User>(queryKeys.accounts.current(), {
+          queryClient.setQueryData<User>(queryKeys.accounts.current(activeSessionId), {
             ...current,
             userPreferences: context.previousUser.userPreferences,
           });
@@ -624,7 +624,7 @@ export const useUpdateUserPreferences = () => {
       toast.error(error instanceof Error ? error.message : 'Failed to update preferences');
     },
     onSuccess: (data) => {
-      queryClient.setQueryData(queryKeys.accounts.current(), data);
+      queryClient.setQueryData(queryKeys.accounts.current(activeSessionId), data);
       useAuthStore.getState().setUser(data);
       invalidateAccountQueries(queryClient);
     },

package/src/ui/hooks/mutations/useServicesMutations.ts

@@ -17,12 +17,12 @@ export const useSwitchSession = () => {
     mutationFn: async (sessionId: string) => {
       return await switchSession(sessionId);
     },
-    onSuccess: (user) => {
+    onSuccess: (user, sessionId) => {
       // Invalidate all session queries
       invalidateSessionQueries(queryClient);
       
       // Update current user query
-      queryClient.setQueryData(queryKeys.accounts.current(), user);
+      queryClient.setQueryData(queryKeys.accounts.current(sessionId), user);
       
       // Invalidate account queries
       queryClient.invalidateQueries({ queryKey: queryKeys.accounts.all });

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

@@ -17,7 +17,10 @@ export const queryKeys = {
     list: (sessionIds: string[]) => [...queryKeys.accounts.lists(), sessionIds] as const,
     details: () => [...queryKeys.accounts.all, 'detail'] as const,
     detail: (sessionId: string) => [...queryKeys.accounts.details(), sessionId] as const,
-    current: () => [...queryKeys.accounts.all, 'current'] as const,
+    current: (sessionId?: string | null) =>
+      sessionId
+        ? ([...queryKeys.accounts.all, 'current', sessionId] as const)
+        : ([...queryKeys.accounts.all, 'current'] as const),
     settings: () => [...queryKeys.accounts.all, 'settings'] as const,
   },
 
@@ -46,7 +49,7 @@ export const queryKeys = {
   devices: {
     all: ['devices'] as const,
     lists: () => [...queryKeys.devices.all, 'list'] as const,
-    list: (userId?: string) => [...queryKeys.devices.lists(), userId] as const,
+    list: (accountScope?: string) => [...queryKeys.devices.lists(), accountScope] as const,
     details: () => [...queryKeys.devices.all, 'detail'] as const,
     detail: (deviceId: string) => [...queryKeys.devices.details(), deviceId] as const,
   },
@@ -71,7 +74,7 @@ export const queryKeys = {
   // Storage usage queries
   storage: {
     all: ['storage'] as const,
-    usage: () => [...queryKeys.storage.all, 'usage'] as const,
+    usage: (accountScope?: string) => [...queryKeys.storage.all, 'usage', accountScope] as const,
   },
 
   // Connected apps (FedCM grants the user has authorized)

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

@@ -65,7 +65,7 @@ export const useCurrentUser = (options?: { enabled?: boolean }) => {
   const queryClient = useQueryClient();
 
   const query = useQuery({
-    queryKey: queryKeys.accounts.current(),
+    queryKey: queryKeys.accounts.current(activeSessionId),
     queryFn: async () => {
       if (!activeSessionId) {
         throw new Error('No active session');

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

@@ -34,10 +34,10 @@ import type {
  * API's `{ plan: 'basic' }` fallback when the user has never subscribed.
  */
 export const useUserSubscription = (options?: { enabled?: boolean }) => {
-  const { oxyServices, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, isAuthenticated, activeSessionId, user } = useOxy();
 
   return useQuery({
-    queryKey: queryKeys.payments.subscription(),
+    queryKey: queryKeys.payments.subscription(user?.id),
     queryFn: async () => {
       return authenticatedApiCall<Subscription>(
         oxyServices,
@@ -45,7 +45,7 @@ export const useUserSubscription = (options?: { enabled?: boolean }) => {
         () => oxyServices.getCurrentUserSubscription(),
       );
     },
-    enabled: (options?.enabled !== false) && isAuthenticated,
+    enabled: (options?.enabled !== false) && isAuthenticated && !!user?.id,
     // Subscription state changes rarely; tolerate a longer fresh window.
     staleTime: 5 * 60 * 1000, // 5 minutes
     gcTime: 30 * 60 * 1000, // 30 minutes
@@ -59,10 +59,10 @@ export const useUserSubscription = (options?: { enabled?: boolean }) => {
  * returns the user's `deposit` and `purchase` transactions newest-first.
  */
 export const useUserPayments = (options?: { enabled?: boolean }) => {
-  const { oxyServices, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, isAuthenticated, activeSessionId, user } = useOxy();
 
   return useQuery({
-    queryKey: queryKeys.payments.history(),
+    queryKey: queryKeys.payments.history(user?.id),
     queryFn: async () => {
       return authenticatedApiCall<Payment[]>(
         oxyServices,
@@ -70,7 +70,7 @@ export const useUserPayments = (options?: { enabled?: boolean }) => {
         () => oxyServices.getUserPayments(),
       );
     },
-    enabled: (options?.enabled !== false) && isAuthenticated,
+    enabled: (options?.enabled !== false) && isAuthenticated && !!user?.id,
     // Billing history is append-mostly; a short fresh window is fine.
     staleTime: 2 * 60 * 1000, // 2 minutes
     gcTime: 30 * 60 * 1000, // 30 minutes
@@ -84,10 +84,10 @@ export const useUserPayments = (options?: { enabled?: boolean }) => {
  * Balance changes frequently, so the fresh window is intentionally short.
  */
 export const useUserWallet = (options?: { enabled?: boolean }) => {
-  const { oxyServices, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, isAuthenticated, activeSessionId, user } = useOxy();
 
   return useQuery({
-    queryKey: queryKeys.payments.wallet(),
+    queryKey: queryKeys.payments.wallet(user?.id),
     queryFn: async () => {
       return authenticatedApiCall<Wallet>(
         oxyServices,
@@ -95,7 +95,7 @@ export const useUserWallet = (options?: { enabled?: boolean }) => {
         () => oxyServices.getCurrentUserWallet(),
       );
     },
-    enabled: (options?.enabled !== false) && isAuthenticated,
+    enabled: (options?.enabled !== false) && isAuthenticated && !!user?.id,
     staleTime: 60 * 1000, // 1 minute (balance moves often)
     gcTime: 10 * 60 * 1000, // 10 minutes
   });
@@ -116,12 +116,12 @@ export const useUserWalletTransactions = (
   params?: { limit?: number; offset?: number },
   options?: { enabled?: boolean },
 ) => {
-  const { oxyServices, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, isAuthenticated, activeSessionId, user } = useOxy();
   const limit = params?.limit;
   const offset = params?.offset;
 
   return useQuery({
-    queryKey: queryKeys.payments.walletTransactions(limit, offset),
+    queryKey: queryKeys.payments.walletTransactions(limit, offset, user?.id),
     queryFn: async () => {
       return authenticatedApiCall<WalletTransactionsResponse>(
         oxyServices,
@@ -129,7 +129,7 @@ export const useUserWalletTransactions = (
         () => oxyServices.getCurrentUserWalletTransactions({ limit, offset }),
       );
     },
-    enabled: (options?.enabled !== false) && isAuthenticated,
+    enabled: (options?.enabled !== false) && isAuthenticated && !!user?.id,
     staleTime: 60 * 1000, // 1 minute (ledger updates frequently)
     gcTime: 10 * 60 * 1000, // 10 minutes
   });

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

@@ -5,6 +5,9 @@ import { queryKeys } from './queryKeys';
 import { useOxy } from '../../context/OxyContext';
 import { fetchSessionsWithFallback, mapSessionsToClient } from '../../utils/sessionHelpers';
 
+const accountQueryScope = (activeSessionId: string | null, actingAs?: string | null): string =>
+  `${activeSessionId ?? 'no-session'}:${actingAs ?? 'self'}`;
+
 /**
  * Get all active sessions for the current user
  */
@@ -90,10 +93,10 @@ export const useDeviceSessions = (options?: { enabled?: boolean }) => {
  * Get user devices
  */
 export const useUserDevices = (options?: { enabled?: boolean }) => {
-  const { oxyServices, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, isAuthenticated, activeSessionId, actingAs } = useOxy();
 
   return useQuery({
-    queryKey: queryKeys.devices.list(),
+    queryKey: queryKeys.devices.list(accountQueryScope(activeSessionId, actingAs)),
     queryFn: async () => {
       return authenticatedApiCall(
         oxyServices,
@@ -101,7 +104,7 @@ export const useUserDevices = (options?: { enabled?: boolean }) => {
         () => oxyServices.getUserDevices()
       );
     },
-    enabled: (options?.enabled !== false) && isAuthenticated,
+    enabled: (options?.enabled !== false) && isAuthenticated && !!activeSessionId,
     staleTime: 5 * 60 * 1000,
     gcTime: 30 * 60 * 1000,
   });
@@ -132,10 +135,10 @@ export const useSecurityInfo = (options?: { enabled?: boolean }) => {
  * `useEffect` fetches.
  */
 export const useAccountStorageUsage = (options?: { enabled?: boolean }) => {
-  const { oxyServices, isAuthenticated, activeSessionId } = useOxy();
+  const { oxyServices, isAuthenticated, activeSessionId, actingAs } = useOxy();
 
   return useQuery<AccountStorageUsageResponse>({
-    queryKey: queryKeys.storage.usage(),
+    queryKey: queryKeys.storage.usage(accountQueryScope(activeSessionId, actingAs)),
     queryFn: async () => {
       return authenticatedApiCall(
         oxyServices,
@@ -143,7 +146,7 @@ export const useAccountStorageUsage = (options?: { enabled?: boolean }) => {
         () => oxyServices.getAccountStorageUsage()
       );
     },
-    enabled: (options?.enabled !== false) && isAuthenticated,
+    enabled: (options?.enabled !== false) && isAuthenticated && !!activeSessionId,
     staleTime: 5 * 60 * 1000,
     gcTime: 30 * 60 * 1000,
   });

package/src/ui/hooks/queryClient.ts

@@ -33,7 +33,7 @@ import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persi
 import { isDev } from '@oxyhq/core';
 import type { StorageInterface } from '../utils/storageHelpers';
 
-const QUERY_CACHE_KEY = 'oxy_query_cache_v2';
+const QUERY_CACHE_KEY = 'oxy_query_cache_v3';
 const QUERY_CACHE_MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days
 const QUERY_PERSIST_THROTTLE_MS = 1_000;
 
@@ -50,7 +50,6 @@ const PERSISTED_QUERY_PREFIXES: ReadonlyArray<string> = [
   'sessions',
   'devices',
   'privacy',
-  'payments',
 ];
 
 /**
@@ -209,9 +208,10 @@ export const attachQueryPersistence = (
   return { unsubscribe, restored };
 };
 
-// Legacy v1 cache key — kept so we can opportunistically purge stale blobs
-// written by older builds. Safe to drop after a few releases.
-const LEGACY_QUERY_CACHE_KEYS: ReadonlyArray<string> = ['oxy_query_cache'];
+// Legacy cache keys — kept so we can opportunistically purge stale blobs
+// written by older builds. v2 may contain persisted payments data, so the
+// active key is bumped to v3 and old blobs are only removed during explicit clears.
+const LEGACY_QUERY_CACHE_KEYS: ReadonlyArray<string> = ['oxy_query_cache_v2', 'oxy_query_cache'];
 
 /**
  * Remove the persisted query+mutation cache (used on full sign-out / data

package/src/ui/hooks/useOxyAuthSession.ts

@@ -53,6 +53,27 @@ export interface AuthSession {
   expiresAt: number;
 }
 
+/**
+ * Extended `POST /auth/session/create` response (the "Sign in with Oxy" handoff
+ * fields, Workstream C2). Both are optional so this hook degrades gracefully
+ * when the handoff backend is not yet deployed — the legacy `oxyauth://<token>`
+ * QR (`qrData`) remains the fallback.
+ */
+interface AuthSessionCreateResponse {
+  /**
+   * Public, single-use authorize code carried in the QR / deep-link. NEVER the
+   * secret `sessionToken` — the approver resolves the requesting app's identity
+   * from this code server-side.
+   */
+  authorizeCode?: string;
+  /** Ready-to-render deep-link / universal-link string (`oxycommons://approve?...`). */
+  qrPayload?: string;
+  /** Session lifecycle status (e.g. `'pending'`). */
+  status?: string;
+  /** Server-authoritative expiry (epoch ms); the client-proposed value is the fallback. */
+  expiresAt?: number;
+}
+
 /** Real-time auth-session socket payload (also matches the poll status shape). */
 interface AuthUpdatePayload {
   status: 'authorized' | 'cancelled' | 'expired';
@@ -76,6 +97,21 @@ export interface UseOxyAuthSessionResult {
   authSession: AuthSession | null;
   /** The QR payload string (`oxyauth://<token>`), or `''` when no session. */
   qrData: string;
+  /**
+   * The PUBLIC, single-use authorize code for the "Sign in with Oxy" handoff,
+   * or `null` when the handoff backend did not return one. The approver (the
+   * Oxy identity app) resolves the requesting app's identity from this code —
+   * it is safe to display; it is NOT the secret `sessionToken`.
+   */
+  authorizeCode: string | null;
+  /**
+   * The structured "Sign in with Oxy" deep-link payload
+   * (`oxycommons://approve?...`) to render in the cross-device QR and to open on
+   * the same device, or `null` when the handoff backend did not return one.
+   * Render this (preferred over `qrData`) in the QR and pass it to
+   * `Linking.openURL` for same-device approval.
+   */
+  qrPayload: string | null;
   /** `true` while the session is being created (initial spinner). */
   isLoading: boolean;
   /** A user-facing error message, or `null`. Drives the retry UI. */
@@ -89,6 +125,13 @@ export interface UseOxyAuthSessionResult {
    * This is the action behind the platform-primary "Continue with Oxy" button.
    */
   openAuthApproval: () => Promise<void>;
+  /**
+   * Same-device "Sign in with Oxy" handoff: deep-link to `qrPayload`
+   * (`oxycommons://approve?...`) so the native Oxy identity app opens directly
+   * to approve. No-op when no `qrPayload` was returned. The socket / poll still
+   * completes the sign-in once the approval lands.
+   */
+  openSameDeviceApproval: () => Promise<void>;
   /** Tear down the current session and create a fresh one (the retry action). */
   retry: () => void;
   /** Disconnect the socket and stop polling. Idempotent. */
@@ -198,6 +241,9 @@ export function useOxyAuthSession(
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [isWaiting, setIsWaiting] = useState(false);
+  // "Sign in with Oxy" handoff fields surfaced from the `create` response.
+  const [authorizeCode, setAuthorizeCode] = useState<string | null>(null);
+  const [qrPayload, setQrPayload] = useState<string | null>(null);
 
   const socketRef = useRef<Socket | null>(null);
   const pollingIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -376,6 +422,9 @@ export function useOxyAuthSession(
   const generateAuthSession = useCallback(async () => {
     setIsLoading(true);
     setError(null);
+    // Reset the handoff fields for the fresh session (also clears them on retry).
+    setAuthorizeCode(null);
+    setQrPayload(null);
     isProcessingRef.current = false;
 
     // The cross-app device sign-in flow identifies the requesting app by its
@@ -393,8 +442,11 @@ export function useOxyAuthSession(
       const sessionToken = generateSessionToken();
       const expiresAt = Date.now() + AUTH_SESSION_EXPIRY_MS;
 
-      // Register the auth session with the server.
-      await oxyServices.makeRequest(
+      // Register the auth session with the server. The response carries the
+      // "Sign in with Oxy" handoff fields (public `authorizeCode` + structured
+      // `qrPayload`) when the handoff backend is deployed; both are optional, so
+      // the legacy `oxyauth://<token>` QR path keeps working without them.
+      const createResponse = await oxyServices.makeRequest<AuthSessionCreateResponse>(
         'POST',
         '/auth/session/create',
         { sessionToken, expiresAt, clientId },
@@ -402,6 +454,8 @@ export function useOxyAuthSession(
       );
 
       setAuthSession({ sessionToken, expiresAt });
+      setAuthorizeCode(createResponse?.authorizeCode ?? null);
+      setQrPayload(createResponse?.qrPayload ?? null);
       setIsWaiting(true);
 
       // Socket is the fast path; the poll is a transport-independent backstop
@@ -461,6 +515,23 @@ export function useOxyAuthSession(
     }
   }, [authSession, oxyServices]);
 
+  // Same-device "Sign in with Oxy" handoff: deep-link to the `qrPayload`
+  // (`oxycommons://approve?...`) so the native Oxy identity app opens directly
+  // to approve. The socket / poll already resolves the flow once the approval
+  // lands, so this only needs to launch the deep link. No-op when the handoff
+  // backend returned no `qrPayload`.
+  const openSameDeviceApproval = useCallback(async () => {
+    if (!qrPayload) {
+      return;
+    }
+    try {
+      await Linking.openURL(qrPayload);
+    } catch (err) {
+      debug.error('Unable to open the Oxy app for approval:', err);
+      setError('Unable to open the Oxy app. Scan the QR code from another device instead.');
+    }
+  }, [qrPayload]);
+
   // Tear down and recreate the session (the retry action).
   const retry = useCallback(() => {
     cleanup();
@@ -546,10 +617,13 @@ export function useOxyAuthSession(
   return {
     authSession,
     qrData,
+    authorizeCode,
+    qrPayload,
     isLoading,
     error,
     isWaiting,
     openAuthApproval,
+    openSameDeviceApproval,
     retry,
     cleanup,
   };