@oxyhq/services 28.0.0 → 29.0.0

package/plugins/withSharedDeviceSessionReader.js

@@ -0,0 +1,57 @@
+/**
+ * Config plugin: withSharedDeviceSessionReader (every other official Oxy app).
+ *
+ * A reader app JOINS the device's existing session — it adopts the shared
+ * `deviceId` + `deviceSecret` a hub app published, so it lands signed in with no
+ * QR and, crucially, without ever asking for Commons's private identity key.
+ * This plugin wires the minimal Android side of `@oxyhq/services`:
+ *
+ *  - Requests the `signature`-level permission
+ *    `so.oxy.shared.permission.READ_DEVICE_SESSION` (defined by the hub apps).
+ *    Because it is `signature`, it is granted only when this app is signed with
+ *    the SAME certificate as the hub — that is the entire trust boundary, and it
+ *    is what makes an incorrectly-signed app unable to read the slot.
+ *  - Adds `<queries>` entries for the hub authorities so package-visibility
+ *    filtering (Android 11+) never hides them from `ContentResolver.call`.
+ *
+ * The provider itself is declared only by the hub apps
+ * (`withSharedDeviceSessionProvider`) — see the note there about why hosting is
+ * restricted to apps inside the `so.oxy.shared` UID.
+ *
+ * Keep this list identical to `PROVIDER_AUTHORITIES` in
+ * `android/src/main/java/so/oxy/devicesession/OxyDeviceSessionModule.kt`.
+ */
+const { withAndroidManifest } = require('@expo/config-plugins');
+
+const READ_DEVICE_SESSION_PERMISSION = 'so.oxy.shared.permission.READ_DEVICE_SESSION';
+const PROVIDER_AUTHORITIES = [
+  'so.oxy.accounts.devicesession',
+  'so.oxy.accounts.dev.devicesession',
+  'so.oxy.commons.devicesession',
+  'so.oxy.commons.dev.devicesession',
+];
+
+module.exports = function withSharedDeviceSessionReader(config) {
+  return withAndroidManifest(config, (modConfig) => {
+    const manifest = modConfig.modResults.manifest;
+
+    manifest['uses-permission'] = manifest['uses-permission'] ?? [];
+    if (!manifest['uses-permission'].some((p) => p.$['android:name'] === READ_DEVICE_SESSION_PERMISSION)) {
+      manifest['uses-permission'].push({ $: { 'android:name': READ_DEVICE_SESSION_PERMISSION } });
+    }
+
+    manifest['queries'] = manifest['queries'] ?? [];
+    if (manifest['queries'].length === 0) {
+      manifest['queries'].push({});
+    }
+    const queries = manifest['queries'][0];
+    queries.provider = queries.provider ?? [];
+    for (const authority of PROVIDER_AUTHORITIES) {
+      if (!queries.provider.some((p) => p.$['android:authorities'] === authority)) {
+        queries.provider.push({ $: { 'android:authorities': authority } });
+      }
+    }
+
+    return modConfig;
+  });
+};

package/src/__tests__/esmSourcePurity.test.ts

@@ -0,0 +1,61 @@
+/**
+ * `@oxyhq/services` ships an ESM build, and ESM has no `require`.
+ *
+ * This is not a style rule: a surviving `require()` puts web bundlers into
+ * CommonJS interop, which hands consumers `undefined` bindings with no build
+ * error and no warning. It blanked auth.oxy.so/authorize once — see the note on
+ * `screenComponents` in `../ui/navigation/routes` for the mechanism, and
+ * `README.md` for the incident.
+ *
+ * Deferring is still legitimate: a thunk over a static import defers a READ,
+ * `import()` defers a LOAD. Neither needs `require()`.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const SRC_ROOT = join(__dirname, '..');
+
+/** Source extensions that end up in the published ESM build. */
+const SOURCE_EXTENSIONS = ['.ts', '.tsx'];
+
+/** Tests are compiled to CommonJS by ts-jest and never ship, so they are exempt. */
+const EXEMPT_SEGMENTS = ['__tests__'];
+
+function collectSourceFiles(dir: string): string[] {
+  const found: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      if (EXEMPT_SEGMENTS.includes(entry)) continue;
+      found.push(...collectSourceFiles(path));
+      continue;
+    }
+    if (SOURCE_EXTENSIONS.some((ext) => path.endsWith(ext)) && !path.endsWith('.d.ts')) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/**
+ * Drop comments and string/template literals so prose about `require()` — such
+ * as the notes explaining this very rule — is not mistaken for a call.
+ */
+function stripCommentsAndStrings(code: string): string {
+  return code
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1')
+    .replace(/'(?:[^'\\\n]|\\.)*'/g, "''")
+    .replace(/"(?:[^"\\\n]|\\.)*"/g, '""')
+    .replace(/`(?:[^`\\]|\\.)*`/g, '``');
+}
+
+describe('ESM source purity', () => {
+  it('never calls require() anywhere in the shipped source', () => {
+    const offenders = collectSourceFiles(SRC_ROOT)
+      .filter((file) => /\brequire\s*\(/.test(stripCommentsAndStrings(readFileSync(file, 'utf8'))))
+      .map((file) => relative(SRC_ROOT, file));
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/index.ts

@@ -33,6 +33,29 @@ setPlatformOS(Platform.OS as PlatformOS);
 // ---------------------------------------------------------------------------
 export { default as OxyProvider } from './ui/components/OxyProvider';
 export { useOxy } from './ui/context/OxyContext';
+// `useOxy()` THROWS when no provider is mounted. `useOptionalOxy()` returns
+// `null` instead, for the rare component that renders on both sides of the
+// provider boundary; there is no fabricated forever-loading runtime.
+export { useOptionalOxy, OxyProviderMissingError } from './ui/context/OxyContext';
+
+// The runtime surface (ADR 0004). These subscribe to the ONE runtime with a
+// selector, so — unlike `useOxy()`, whose value is rebuilt by any of its fifty
+// members moving — a locale change or a dialog opening does not re-render them.
+export {
+  useOxyRuntime,
+  useOxySnapshot,
+  useActiveAccount,
+  useDeviceDirectory,
+  OxyRuntimeMissingError,
+} from './ui/runtime';
+export type {
+  ActiveAccount,
+  OxyRuntime,
+  OxyRuntimeError,
+  OxyRuntimeSnapshot,
+  OxyRuntimeStatus,
+  OxyTokenStatus,
+} from './ui/runtime';
 export type { OxyContextState } from './ui/context/OxyContext';
 export { useAuth } from './ui/hooks/useAuth';
 export type { AuthState, AuthActions, UseAuthReturn } from './ui/hooks/useAuth';
@@ -45,7 +68,6 @@ export { IdentityBoundSessionError } from './ui/session/identityBinding';
 // Zustand stores
 // ---------------------------------------------------------------------------
 export { useAuthStore } from './ui/stores/authStore';
-export { useAccountStore } from './ui/stores/accountStore';
 export {
     useAssetStore,
     useAssets as useAssetsStore,
@@ -343,14 +365,14 @@ export { OxySignInRequestSurface } from './ui/components/OxySignInRequestSurface
 export type { OxySignInRequestSurfaceProps } from './ui/components/OxySignInRequestSurface';
 export type { OxySignInSurfaceAction } from './ui/components/authChooser/types';
 
-// Unified switchable-accounts hook — the single source of everything the user
-// can switch into: device sign-ins AND linked graph accounts (owned orgs +
-// shared-with-you), deduped by account id and hydrated with real
-// name/email/avatar/color. Backed by the shared `AccountDialogController` in
-// `@oxyhq/core`. Every switch routes through `useOxy().switchToAccount`.
-// The `SwitchableAccount` type lives in `@oxyhq/core` — import it from there.
-export { useSwitchableAccounts } from './ui/hooks/useSwitchableAccounts';
-export type { UseSwitchableAccountsResult } from './ui/hooks/useSwitchableAccounts';
+// The device switcher — the server's own directory (ADR 0002) of who is signed
+// in here and what each of them may act as, grouped by PERSON, with the two
+// removals an account id cannot name. Backed by the shared
+// `AccountDialogController` in `@oxyhq/core`; selecting a row activates a
+// `contextId`. `DevicePrincipalGroup` and `DeviceContext` live in `@oxyhq/core`
+// — import them from there.
+export { useDeviceSwitcher } from './ui/hooks/useDeviceSwitcher';
+export type { UseDeviceSwitcherResult } from './ui/hooks/useDeviceSwitcher';
 
 // Unified "Manage your Oxy Account" screen (the caller's own personal account)
 export { default as ProfileScreen } from './ui/screens/ProfileScreen';

package/src/ui/boot/runProviderColdBoot.ts

@@ -8,6 +8,7 @@ import {
 } from '@oxyhq/core';
 import type { SessionClient } from '@oxyhq/core';
 import { loadPersistedDeviceCredential } from '../utils/deviceCredential';
+import { createPlatformSharedDeviceCredentialStore } from '../session/sharedDeviceCredentialStore';
 import { tryCompleteOAuthReturn } from '../utils/oauthReturn';
 import { isWebBrowser } from '../utils/isWebBrowser';
 import { isNetConnectivityExplicitlyOffline } from '../utils/netConnectivity';
@@ -161,6 +162,12 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
       platform: { isWeb: isWebBrowser(), isNative: !isWebBrowser() },
       sessionMode,
       identity,
+      // The device-wide shared credential slot, enabling the `shared-device-adopt`
+      // lane: a newly installed official app joins this device's existing session
+      // instead of falling back to signing a challenge with the Commons identity
+      // key. `null` on web, where each origin is its own device by design; the
+      // core lane is also skipped outright in `sessionMode: 'identity'`.
+      sharedDeviceCredential: createPlatformSharedDeviceCredentialStore() ?? undefined,
       overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE_MS,
       isOffline: () => offline,
       onStepDeadline: (stepId) => {

package/src/ui/client.ts

@@ -19,7 +19,7 @@ export { default as FollowButton } from './components/FollowButton';
 export { default as OxyPayButton } from './components/OxyPayButton';
 
 // Context
-export { useOxy } from './context/OxyContext';
+export { useOxy, useOptionalOxy, OxyProviderMissingError } from './context/OxyContext';
 
 // Hooks
 export { useAuth } from './hooks/useAuth';
@@ -34,7 +34,6 @@ export { default as ManageAccountScreen } from './screens/ManageAccountScreen';
 
 // Stores
 export { useAuthStore } from './stores/authStore';
-export { useAccountStore } from './stores/accountStore';
 
 // Error handler utilities
 export {

package/src/ui/components/OxyAccountDialogScreen.tsx

@@ -31,6 +31,7 @@ import { useSurfaceHeader } from '../hooks/useSurfaceHeader';
 import type { BaseScreenProps } from '../types/navigation';
 import LogoText from './logo/LogoText';
 import OxyAuthChooser from './OxyAuthChooser';
+import { EMPTY_ACCOUNT_DIALOG_SNAPSHOT } from '../hooks/accountDialogSnapshot';
 
 type Translate = ReturnType<typeof useI18n>['t'];
 
@@ -61,20 +62,22 @@ const OxyAccountDialogScreen: React.FC<BaseScreenProps> = ({ canGoBack }) => {
 
   // A lightweight, header-only binding to the same controller `OxyAuthChooser`
   // binds independently — cheap, and the established pattern here (
-  // `useSwitchableAccounts` also binds to this controller on its own).
+  // `useDeviceSwitcher` also binds to this controller on its own).
   const subscribe = useCallback(
     (listener: () => void) => (controller ? controller.subscribe(listener) : () => undefined),
     [controller],
   );
   const getSnapshot = useCallback(
-    () => (controller ? controller.getSnapshot() : EMPTY_SNAPSHOT),
+    () => (controller ? controller.getSnapshot() : EMPTY_ACCOUNT_DIALOG_SNAPSHOT),
     [controller],
   );
   const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
   const { view } = snapshot;
-  const showBack =
-    view === 'qr' || view === 'signup' || (view === 'add' && snapshot.accounts.length > 0);
+  // "Add another account" only makes sense as a back destination when there IS
+  // another — i.e. somebody is already signed in on this device.
+  const hasSignedInAccounts = (snapshot.directory?.principals.length ?? 0) > 0;
+  const showBack = view === 'qr' || view === 'signup' || (view === 'add' && hasSignedInAccounts);
   const goToAccounts = useCallback(() => {
     if (!controller) return;
     const { view: currentView, signIn } = controller.getSnapshot();
@@ -100,7 +103,7 @@ const OxyAccountDialogScreen: React.FC<BaseScreenProps> = ({ canGoBack }) => {
   // by the bar. Every OTHER view keeps the SHARED Dialog nav header the rest of
   // the SDK uses — a large in-content title/subtitle that collapses into the bar
   // on scroll — because their copy is informative.
-  const copy = view === 'accounts' ? null : headerCopy(view, snapshot.accounts.length, t);
+  const copy = view === 'accounts' ? null : headerCopy(view, hasSignedInAccounts, t);
 
   useSurfaceHeader({
     titleContent: copy ? undefined : NAV_LOGO,
@@ -126,7 +129,7 @@ const OxyAccountDialogScreen: React.FC<BaseScreenProps> = ({ canGoBack }) => {
 
 function headerCopy(
   view: Exclude<AccountDialogSnapshot['view'], 'accounts'>,
-  accountCount: number,
+  hasSignedInAccounts: boolean,
   t: Translate,
 ): { title: string; subtitle: string | null } {
   switch (view) {
@@ -147,7 +150,7 @@ function headerCopy(
         subtitle: t('signup.subtitle') || 'One identity for the whole ecosystem.',
       };
     default:
-      return accountCount > 0
+      return hasSignedInAccounts
         ? {
             title: t('signin.addAccountTitle') || 'Add another account',
             subtitle: t('signin.addAccountSubtitle') || 'Sign in with another account.',
@@ -159,28 +162,6 @@ function headerCopy(
   }
 }
 
-const EMPTY_SNAPSHOT: AccountDialogSnapshot = {
-  view: 'accounts',
-  accounts: [],
-  activeAccountId: null,
-  loading: false,
-  error: null,
-  switchingAccountId: null,
-  signIn: {
-    phase: 'idle',
-    authorizeCode: null,
-    qrPayload: null,
-    expiresAt: null,
-    error: null,
-    route: null,
-    routeFailed: false,
-    pushSentAt: null,
-    openedAt: null,
-    progress: 'idle',
-  },
-  commonsAvailability: 'unknown',
-};
-
 /**
  * The screen gutter. In the Dialog's nav-header mode the surface adds NO content
  * padding of its own — the large title and each screen own theirs — so this must

package/src/ui/components/OxyAuthChooser.tsx

@@ -37,11 +37,12 @@ import type React from 'react';
 import { useCallback, useMemo, useState, useSyncExternalStore } from 'react';
 import { Linking, Platform } from 'react-native';
 import { toast } from '@oxyhq/bloom/toast';
+import { surfaces } from '@oxyhq/bloom/surfaces';
 import { useTheme } from '@oxyhq/bloom/theme';
-import type { AccountDialogSnapshot } from '@oxyhq/core';
-import { isOxyRpOrigin } from '@oxyhq/core';
+import { getNormalizedUserHandle, isOxyRpOrigin, type User } from '@oxyhq/core';
 import { useQueryClient } from '@tanstack/react-query';
 import { useOxy } from '../context/OxyContext';
+import { useDeviceSwitcher } from '../hooks/useDeviceSwitcher';
 import { useI18n } from '../hooks/useI18n';
 import {
   getAccountDialogConsumerHooks,
@@ -54,13 +55,16 @@ import AccountsMenuView from './authChooser/AccountsMenuView';
 import SignInEntryView from './authChooser/SignInEntryView';
 import SignInRequestView from './authChooser/SignInRequestView';
 import SignUpView from './authChooser/SignUpView';
-import type {
-  AccountStorageModel,
-  AccountsMenuActions,
-  OxyAuthChooserHandlers,
-  PasskeyMode,
-  SignInAlternatives,
+import {
+  resolveAccentHex,
+  type AccountHeroModel,
+  type AccountStorageModel,
+  type AccountsMenuActions,
+  type OxyAuthChooserHandlers,
+  type PasskeyMode,
+  type SignInAlternatives,
 } from './authChooser/types';
+import { EMPTY_ACCOUNT_DIALOG_SNAPSHOT } from '../hooks/accountDialogSnapshot';
 
 /** Commons' own identity-creation deep link (mirrors the `approve`/`attest`/`card` intents). */
 const COMMONS_CREATE_IDENTITY_URL = 'oxycommons://create-identity';
@@ -96,16 +100,20 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
   const {
     accountDialogController: controller,
     showBottomSheet,
-    refreshAccounts,
     signInWithPasskey,
     registerWithPasskey,
     oxyServices,
     logout,
     openAvatarPicker,
+    user,
   } = useOxy();
   const theme = useTheme();
   const { t } = useI18n();
   const queryClient = useQueryClient();
+  // The device's people and what each may act as, resolved for rendering — the
+  // SAME hook (and the same one builder) the auth.oxy.so chooser renders from,
+  // so the two switchers cannot drift.
+  const { principals } = useDeviceSwitcher();
 
   // A credential minted for `oxy.so` can only be ASSERTED there (or a loopback
   // dev host) — a hard WebAuthn RP-ID boundary the browser enforces, not
@@ -217,7 +225,7 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
     [controller, autoStartSignIn],
   );
   const getSnapshot = useCallback(
-    () => (controller ? controller.getSnapshot() : EMPTY_SNAPSHOT),
+    () => (controller ? controller.getSnapshot() : EMPTY_ACCOUNT_DIALOG_SNAPSHOT),
     [controller],
   );
   const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
@@ -228,31 +236,97 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
     () => null,
   );
 
-  const handleSwitch = useCallback(
-    async (accountId: string) => {
+  const handleActivate = useCallback(
+    async (contextId: string) => {
       if (!controller) return;
-      if (controller.getSnapshot().switchingAccountId) return;
-      if (accountId === controller.getSnapshot().activeAccountId) {
+      if (controller.getSnapshot().activatingContextId) return;
+      // Already live: activating it again bumps nothing server-side, so treat
+      // the press as "yes, this one" and close.
+      if (contextId === controller.getSnapshot().activeContext?.contextId) {
         onComplete?.();
         return;
       }
       try {
-        await controller.switchTo(accountId);
-        // `switchTo` records failures on the controller snapshot. Read that
-        // state after the operation so the same path works with both the real
-        // controller and framework test doubles that return void.
+        await controller.activateContext(contextId);
+        // Failures are recorded on the controller snapshot rather than thrown,
+        // so the same path works with the real controller and with test doubles
+        // that resolve void.
         if (controller.getSnapshot().error) {
-          toast.error(t('accountSwitcher.toasts.switchFailed'));
+          toast.error(t('accountSwitcher.toasts.activateFailed'));
           return;
         }
-        void refreshAccounts();
+        // The subject changed, so every account-scoped query is now about
+        // somebody else. The runtime resets its own caches between the bearer
+        // commit and the notify; this drops the Query cache the same way the
+        // account switch did.
         queryClient.invalidateQueries();
         onComplete?.();
       } catch {
-        toast.error(t('accountSwitcher.toasts.switchFailed'));
+        toast.error(t('accountSwitcher.toasts.activateFailed'));
+      }
+    },
+    [controller, onComplete, queryClient, t],
+  );
+
+  /**
+   * Remove ONE `principal → account` pair.
+   *
+   * Confirmed, and the confirmation says whose route is going: on a shared
+   * device the same organization is reachable through somebody else, and their
+   * access is untouched. That is the fact a single "remove account" control
+   * would get wrong.
+   */
+  const handleRemoveContext = useCallback(
+    async (contextId: string) => {
+      if (!controller) return;
+      const group = principals.find((principal) =>
+        principal.contexts.some((context) => context.contextId === contextId),
+      );
+      const context = group?.contexts.find((row) => row.contextId === contextId);
+      if (!group || !context) return;
+      const confirmed = await surfaces.confirm({
+        title: t('accountSwitcher.confirms.removeContextTitle'),
+        message: t('accountSwitcher.confirms.removeContext', {
+          person: group.displayName,
+          account: context.displayName,
+        }),
+        confirmLabel: t('common.remove'),
+        cancelLabel: t('common.cancel'),
+        destructive: true,
+      });
+      if (!confirmed) return;
+      const removed = await controller.signOutContext(contextId);
+      if (!removed) {
+        toast.error(t('accountSwitcher.toasts.contextRemoveFailed'));
+        return;
+      }
+      toast.success(t('accountSwitcher.toasts.contextRemoved', { account: context.displayName }));
+    },
+    [controller, principals, t],
+  );
+
+  /** Remove ONE PERSON and every account they reach here, and nobody else's. */
+  const handleRemovePrincipal = useCallback(
+    async (principalId: string) => {
+      if (!controller) return;
+      const group = principals.find((principal) => principal.principalId === principalId);
+      if (!group) return;
+      const confirmed = await surfaces.confirm({
+        title: t('accountSwitcher.confirms.removePrincipalTitle'),
+        message: t('accountSwitcher.confirms.removePrincipal', { name: group.displayName }),
+        confirmLabel: t('common.actions.signOut'),
+        cancelLabel: t('common.cancel'),
+        destructive: true,
+      });
+      if (!confirmed) return;
+      const removed = await controller.signOutPrincipal(principalId);
+      if (!removed) {
+        toast.error(t('accountSwitcher.toasts.principalRemoveFailed'));
+        return;
       }
+      toast.success(t('accountSwitcher.toasts.principalRemoved', { name: group.displayName }));
     },
-    [controller, onComplete, refreshAccounts, queryClient, t],
+    [controller, principals, t],
   );
 
   const handleManage = useCallback(() => {
@@ -278,8 +352,14 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
 
   const handlers = useMemo<OxyAuthChooserHandlers>(
     () => ({
-      onSwitch: (accountId) => {
-        void handleSwitch(accountId);
+      onActivate: (contextId) => {
+        void handleActivate(contextId);
+      },
+      onRemoveContext: (contextId) => {
+        void handleRemoveContext(contextId);
+      },
+      onRemovePrincipal: (principalId) => {
+        void handleRemovePrincipal(principalId);
       },
       onAdd: handleAdd,
       onManage: handleManage,
@@ -287,7 +367,21 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
       // uploads / clears the picked photo — the single shared avatar write path.
       onEditAvatar: () => openAvatarPicker(),
     }),
-    [handleSwitch, handleAdd, handleManage, openAvatarPicker],
+    [handleActivate, handleRemoveContext, handleRemovePrincipal, handleAdd, handleManage, openAvatarPicker],
+  );
+
+  /**
+   * The hero block — the account this client is signed in as, from its FULL
+   * profile rather than from a directory row.
+   *
+   * The directory carries the minimum that renders a row for every person on
+   * the device; this is the one account we legitimately hold everything for, so
+   * the hero keeps its real EMAIL, which the rows below do not pretend to have.
+   * The accent is not in that category — every row is drawn in its own account's
+   * (issue #961), this one included, from the same field.
+   */
+  const hero = useMemo<AccountHeroModel | null>(() => (user ? buildHero(user, theme.colors.primary, oxyServices) : null),
+    [user, theme.colors.primary, oxyServices],
   );
 
   // Everything that is NOT the surface's one primary action. Wired once here;
@@ -373,6 +467,8 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
     return (
       <AccountsMenuView
         snapshot={snapshot}
+        principals={principals}
+        hero={hero}
         theme={theme}
         t={t}
         handlers={handlers}
@@ -417,6 +513,7 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
   return (
     <SignInEntryView
       snapshot={snapshot}
+      principals={principals}
       theme={theme}
       t={t}
       handlers={handlers}
@@ -426,30 +523,32 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({
   );
 };
 
-// ---------------------------------------------------------------------------
-// Empty snapshot (no-provider loading state)
-// ---------------------------------------------------------------------------
-
-const EMPTY_SNAPSHOT: AccountDialogSnapshot = {
-  view: 'accounts',
-  accounts: [],
-  activeAccountId: null,
-  loading: false,
-  error: null,
-  switchingAccountId: null,
-  signIn: {
-    phase: 'idle',
-    authorizeCode: null,
-    qrPayload: null,
-    expiresAt: null,
-    error: null,
-    route: null,
-    routeFailed: false,
-    pushSentAt: null,
-    openedAt: null,
-    progress: 'idle',
-  },
-  commonsAvailability: 'unknown',
-};
+/**
+ * The hero model for the signed-in account.
+ *
+ * The address line is the account's canonical `@oxy.so` email when it has one,
+ * else its normalized `@handle`. It never synthesizes a `username@oxy.so`
+ * address — the identity contract forbids it, and a non-Oxy or missing email
+ * falls through to the handle.
+ */
+function buildHero(
+  user: User,
+  fallbackAccent: string,
+  oxyServices: ReturnType<typeof useOxy>['oxyServices'],
+): AccountHeroModel {
+  const handle = getNormalizedUserHandle(user);
+  const displayName = user.name?.displayName?.trim() || handle || '';
+  const addressLine = user.email?.toLowerCase().endsWith('@oxy.so')
+    ? user.email
+    : handle
+      ? `@${handle}`
+      : null;
+  return {
+    displayName,
+    addressLine,
+    avatarUrl: user.avatar ? oxyServices.getFileDownloadUrl(user.avatar, 'thumb') : undefined,
+    accentHex: resolveAccentHex(user.color ?? null, fallbackAccent),
+  };
+}
 
 export default OxyAuthChooser;

package/src/ui/components/OxyProvider.tsx

@@ -3,7 +3,7 @@ import { AppState, Platform, StyleSheet, View } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
 import type { OxyProviderProps } from '../types/navigation';
-import { OxyContextProvider, type OxyContextProviderProps } from '../context/OxyContext';
+import { OxyRuntimeProvider, type OxyRuntimeProviderProps } from '../context/OxyContext';
 import { QueryClientProvider, focusManager, onlineManager } from '@tanstack/react-query';
 import { BloomDialogProvider } from '@oxyhq/bloom/dialog';
 import { SurfaceProvider } from '@oxyhq/bloom/surfaces';
@@ -97,6 +97,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
     queryClient: providedQueryClient,
     requireAuth = 'off',
     backgroundSession = false,
+    deviceCredentialStorage = 'persistent',
 }) => {
 
     // Dynamic KeyboardProvider for native. Uses variable indirection
@@ -284,8 +285,8 @@ const OxyProvider: FC<OxyProviderProps> = ({
     const coreContent = (
         <QueryClientProvider client={queryClient}>
             <BloomDialogProvider>
-                <OxyContextProvider
-                    oxyServices={oxyServices as OxyContextProviderProps['oxyServices']}
+                <OxyRuntimeProvider
+                    oxyServices={oxyServices as OxyRuntimeProviderProps['oxyServices']}
                     baseURL={baseURL}
                     authWebUrl={authWebUrl}
                     authRedirectUri={authRedirectUri}
@@ -295,7 +296,8 @@ const OxyProvider: FC<OxyProviderProps> = ({
                     sessionMode={sessionMode}
                     webAuthMode={webAuthMode}
                     backgroundSession={backgroundSession}
-                    onAuthStateChange={onAuthStateChange as OxyContextProviderProps['onAuthStateChange']}
+                    deviceCredentialStorage={deviceCredentialStorage}
+                    onAuthStateChange={onAuthStateChange as OxyRuntimeProviderProps['onAuthStateChange']}
                 >
                     <SurfaceProvider>
                         {requireAuth === 'off' ? (
@@ -305,7 +307,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
                         )}
                     </SurfaceProvider>
                     <ToastOutlet />
-                </OxyContextProvider>
+                </OxyRuntimeProvider>
             </BloomDialogProvider>
         </QueryClientProvider>
     );