@oxyhq/services 22.12.4 → 22.13.0

package/src/ui/session/authStore.ts

@@ -5,105 +5,21 @@
  * (`deviceId` + `deviceSecret`) per origin (web) / per device (native), and the
  * SDK re-mints the access token from that credential on cold boot. `@oxyhq/core`
  * owns the store shape + logic (`createWebAuthStateStore` /
- * `createNativeAuthStateStore`); this module only supplies the platform storage
+ * `createNativeAuthStateStore`); this module only selects the platform storage
  * seam:
  *
  *  - web  → `createWebAuthStateStore()` (localStorage, in-memory fallback).
  *  - native → `createNativeAuthStateStore(secureKV)` for the SESSION blob over
- *    `expo-secure-store` (AsyncStorage fallback).
- *
- * `expo-secure-store` is loaded via a runtime-computed dynamic import (the same
- * optional-native-module pattern `OxyProvider` uses for netinfo / keyboard
- * controller), so the web bundle never pulls it and a device without it falls
- * back to AsyncStorage rather than crashing.
+ *    the shared `createNativeSecureKeyValueStorage()` adapter
+ *    (`expo-secure-store`, AsyncStorage fallback).
  */
 import {
   createWebAuthStateStore,
   createNativeAuthStateStore,
   type AuthStateStore,
-  type NativeKeyValueStorage,
 } from '@oxyhq/core';
-import { createPlatformStorage, isReactNative } from '../utils/storageHelpers';
-
-// Variable indirection so Metro's static analyzer never traces expo-secure-store
-// into the web bundle; the module is native-only and optional.
-const SECURE_STORE_MODULE = 'expo-secure-store';
-
-interface SecureStoreLike {
-  getItemAsync(key: string): Promise<string | null>;
-  setItemAsync(key: string, value: string): Promise<void>;
-  deleteItemAsync(key: string): Promise<void>;
-}
-
-let secureStorePromise: Promise<SecureStoreLike | null> | null = null;
-
-/**
- * Resolve the `expo-secure-store` module once (memoised), or `null` when it is
- * unavailable — callers then fall back to AsyncStorage. Never throws.
- */
-function loadSecureStore(): Promise<SecureStoreLike | null> {
-  if (!secureStorePromise) {
-    const moduleName = SECURE_STORE_MODULE;
-    secureStorePromise = import(moduleName)
-      .then((mod: Partial<SecureStoreLike>) => {
-        if (
-          typeof mod.getItemAsync === 'function' &&
-          typeof mod.setItemAsync === 'function' &&
-          typeof mod.deleteItemAsync === 'function'
-        ) {
-          return {
-            getItemAsync: mod.getItemAsync.bind(mod),
-            setItemAsync: mod.setItemAsync.bind(mod),
-            deleteItemAsync: mod.deleteItemAsync.bind(mod),
-          } satisfies SecureStoreLike;
-        }
-        return null;
-      })
-      .catch(() => null);
-  }
-  return secureStorePromise;
-}
-
-/**
- * A native `NativeKeyValueStorage` that prefers `expo-secure-store` (encrypted
- * at rest) and falls back to AsyncStorage when SecureStore is not installed.
- * The SecureStore module is resolved lazily on first access so construction
- * stays synchronous.
- */
-function createNativeSecureKeyValueStorage(): NativeKeyValueStorage {
-  let asyncStorage: Awaited<ReturnType<typeof createPlatformStorage>> | null = null;
-  const getAsyncStorage = async () => {
-    if (!asyncStorage) {
-      asyncStorage = await createPlatformStorage();
-    }
-    return asyncStorage;
-  };
-  return {
-    getItem: async (key) => {
-      const secure = await loadSecureStore();
-      if (secure) {
-        return secure.getItemAsync(key);
-      }
-      return (await getAsyncStorage()).getItem(key);
-    },
-    setItem: async (key, value) => {
-      const secure = await loadSecureStore();
-      if (secure) {
-        await secure.setItemAsync(key, value);
-        return;
-      }
-      await (await getAsyncStorage()).setItem(key, value);
-    },
-    removeItem: async (key) => {
-      const secure = await loadSecureStore();
-      if (secure) {
-        await secure.deleteItemAsync(key);
-        return;
-      }
-      await (await getAsyncStorage()).removeItem(key);
-    },
-  };
-}
+import { isReactNative } from '../utils/storageHelpers';
+import { createNativeSecureKeyValueStorage } from './nativeSecureStorage';
 
 /**
  * Build the platform {@link AuthStateStore} for this runtime.

package/src/ui/session/createSessionClient.ts

@@ -33,16 +33,29 @@ import { createTokenTransport } from './tokenTransport';
  *
  * The realtime socket uses bearer when authenticated, or deviceId+deviceSecret
  * when signed out (after the one-shot join redirect).
+ *
+ * `getPinnedAccountId` reports the account an IDENTITY-BOUND provider
+ * (`sessionMode: 'identity'`) is pinned to, and `null` for every account-mode
+ * provider — which is exactly the value `SessionClient` and the transport read
+ * when the option is absent, so account mode is unchanged. While it reports an
+ * account, the client tracks device state truthfully but never re-binds its
+ * bearer to the device's mutable active account.
  */
 export function createSessionClient(
   oxyServices: OxyServices,
   onUnauthenticated?: (origin: SessionStateOrigin) => void,
+  getPinnedAccountId?: () => string | null,
 ): {
   client: SessionClient;
   host: ReturnType<typeof createSessionClientHost>;
 } {
   const host = createSessionClientHost(oxyServices);
-  const transport = createTokenTransport(oxyServices);
-  const client = new SessionClient(host, { transport, socketFactory: io, onUnauthenticated });
+  const transport = createTokenTransport(oxyServices, getPinnedAccountId);
+  const client = new SessionClient(host, {
+    transport,
+    socketFactory: io,
+    onUnauthenticated,
+    getPinnedAccountId,
+  });
   return { client, host };
 }

package/src/ui/session/identityBinding.ts

@@ -0,0 +1,116 @@
+/**
+ * Identity-bound sessions — the PLATFORM half of `sessionMode: 'identity'`.
+ *
+ * `@oxyhq/core` owns everything platform-agnostic about an identity-bound
+ * session: the pin store shapes, `resolveIdentityPin`,
+ * `establishIdentitySession`, and the pinned cold-boot / re-mint lanes. What it
+ * deliberately leaves out is WHICH pin store a given runtime should use, so this
+ * module supplies it — web `localStorage` vs the same native SecureStore adapter
+ * the device credential already persists through — and adds the one piece of
+ * state the provider needs on top: a memoised, SYNCHRONOUSLY readable pinned
+ * account id.
+ *
+ * Why the memo matters: `SessionClient.getPinnedAccountId` is a synchronous read
+ * on the socket/apply path, while resolving the pin is asynchronous (a storage
+ * read plus a keychain read, through `resolveIdentityPin`). The provider
+ * resolves it before the cold boot and after every (re-)established identity
+ * session; every read after that is free.
+ */
+import {
+  createNativeIdentityPinStore,
+  createWebIdentityPinStore,
+  resolveIdentityPin,
+  type IdentityBinding,
+} from '@oxyhq/core';
+import { isReactNative } from '../utils/storageHelpers';
+import { createNativeSecureKeyValueStorage } from './nativeSecureStorage';
+
+/**
+ * The provider-scoped identity binding: the core {@link IdentityBinding} handed
+ * to the cold boot and the re-mint handler, plus the resolved pin the projection
+ * and `SessionClient` bind to.
+ */
+export interface IdentitySessionBinding {
+  /** Handed to `runSessionColdBoot` and `installAuthRefreshHandler`. */
+  readonly binding: IdentityBinding;
+  /**
+   * The last resolved pinned account id, read synchronously. `null` until the
+   * first resolve lands, and after a resolve that found no usable pin.
+   */
+  getPinnedAccountId(): string | null;
+  /**
+   * Resolve the pin, reusing the memo once a pinned account is known.
+   * Concurrent callers share one in-flight resolve.
+   */
+  ensurePinnedAccountId(): Promise<string | null>;
+  /**
+   * Drop the memo and re-resolve. Used after a lane that may have rewritten or
+   * cleared the pin (the cold boot, or a re-established identity session).
+   */
+  refreshPinnedAccountId(): Promise<string | null>;
+}
+
+/**
+ * Thrown by every account-graph mutation while the provider runs in
+ * `sessionMode: 'identity'`.
+ *
+ * An identity-bound app's user is the owner of the local identity key — fixed,
+ * for the lifetime of that key. Switching it is not a temporarily-unavailable
+ * operation that could be retried, it is not part of this mode's contract at
+ * all, so the surfaces reject loudly rather than resolving to a no-op that would
+ * read to the caller as a successful switch.
+ */
+export class IdentityBoundSessionError extends Error {
+  override readonly name = 'IdentityBoundSessionError';
+  readonly code = 'identity_bound_session';
+  constructor(readonly operation: string) {
+    super(
+      `"${operation}" is unavailable while the session is identity-bound (sessionMode: "identity"): this app authenticates as the owner of the local identity key and cannot switch accounts.`,
+    );
+  }
+}
+
+/**
+ * Build the identity binding for this runtime. Called ONCE per provider mount,
+ * and ONLY when `sessionMode: 'identity'` — account-mode providers never
+ * construct a pin store.
+ */
+export function createIdentitySessionBinding(): IdentitySessionBinding {
+  const pinStore = isReactNative()
+    ? createNativeIdentityPinStore(createNativeSecureKeyValueStorage())
+    : createWebIdentityPinStore();
+  const binding: IdentityBinding = { pinStore };
+
+  // Only a RESOLVED (non-null) pin is memoised. A `null` outcome is either "not
+  // pinned yet" or an indeterminate key read (locked keychain), and caching
+  // either one would leave this client permanently unpinned for the rest of the
+  // process — the exact state in which it would start following the device's
+  // mutable active account.
+  let pinnedAccountId: string | null = null;
+  let inFlight: Promise<string | null> | null = null;
+
+  const resolve = (): Promise<string | null> => {
+    if (!inFlight) {
+      inFlight = resolveIdentityPin(binding)
+        .then((pin) => {
+          pinnedAccountId = pin?.accountId ?? null;
+          return pinnedAccountId;
+        })
+        .finally(() => {
+          inFlight = null;
+        });
+    }
+    return inFlight;
+  };
+
+  return {
+    binding,
+    getPinnedAccountId: () => pinnedAccountId,
+    ensurePinnedAccountId: () =>
+      pinnedAccountId !== null ? Promise.resolve(pinnedAccountId) : resolve(),
+    refreshPinnedAccountId: () => {
+      pinnedAccountId = null;
+      return resolve();
+    },
+  };
+}

package/src/ui/session/index.ts

@@ -4,13 +4,17 @@
  * `@oxyhq/core` owns the platform-agnostic `SessionClient`, its host adapter,
  * and the pure `DeviceSessionState → services` projection helpers; those are
  * re-exported straight from core here so `OxyContext` has one import site.
- * `@oxyhq/services` supplies only the two platform pieces: the thin
+ * `@oxyhq/services` supplies only the platform pieces: the thin
  * `createSessionClient` factory (injects socket.io-client `io` + the
- * device-first token transport) and the `AuthStateStore` factory.
+ * device-first token transport), the `AuthStateStore` factory, and — for
+ * `sessionMode: 'identity'` — the identity binding (platform pin store + the
+ * memoised pinned account id).
  */
 export { createSessionClient } from './createSessionClient';
 export { createTokenTransport } from './tokenTransport';
 export { createPlatformAuthStateStore } from './authStore';
+export { createIdentitySessionBinding, IdentityBoundSessionError } from './identityBinding';
+export type { IdentitySessionBinding } from './identityBinding';
 export {
   createSessionClientHost,
   accountIdsOf,

package/src/ui/session/nativeSecureStorage.ts

@@ -0,0 +1,98 @@
+/**
+ * The native secure key/value seam every durable `@oxyhq/core` store in this
+ * package is built on.
+ *
+ * `@oxyhq/core` owns the store LOGIC (`createNativeAuthStateStore` for the
+ * zero-cookie device credential, `createNativeIdentityPinStore` for the identity
+ * pin) and takes its persistence as an injected `NativeKeyValueStorage`. This
+ * module supplies that injection ONCE, so those stores can never drift onto
+ * different backings — a device credential in SecureStore and a pin in
+ * AsyncStorage would resolve differently after a keystore reset.
+ *
+ * `expo-secure-store` is loaded via a runtime-computed dynamic import (the same
+ * optional-native-module pattern `OxyProvider` uses for netinfo / keyboard
+ * controller), so the web bundle never pulls it and a device without it falls
+ * back to AsyncStorage rather than crashing.
+ */
+import type { NativeKeyValueStorage } from '@oxyhq/core';
+import { createPlatformStorage } from '../utils/storageHelpers';
+
+// Variable indirection so Metro's static analyzer never traces expo-secure-store
+// into the web bundle; the module is native-only and optional.
+const SECURE_STORE_MODULE = 'expo-secure-store';
+
+interface SecureStoreLike {
+  getItemAsync(key: string): Promise<string | null>;
+  setItemAsync(key: string, value: string): Promise<void>;
+  deleteItemAsync(key: string): Promise<void>;
+}
+
+let secureStorePromise: Promise<SecureStoreLike | null> | null = null;
+
+/**
+ * Resolve the `expo-secure-store` module once (memoised), or `null` when it is
+ * unavailable — callers then fall back to AsyncStorage. Never throws.
+ */
+function loadSecureStore(): Promise<SecureStoreLike | null> {
+  if (!secureStorePromise) {
+    const moduleName = SECURE_STORE_MODULE;
+    secureStorePromise = import(moduleName)
+      .then((mod: Partial<SecureStoreLike>) => {
+        if (
+          typeof mod.getItemAsync === 'function' &&
+          typeof mod.setItemAsync === 'function' &&
+          typeof mod.deleteItemAsync === 'function'
+        ) {
+          return {
+            getItemAsync: mod.getItemAsync.bind(mod),
+            setItemAsync: mod.setItemAsync.bind(mod),
+            deleteItemAsync: mod.deleteItemAsync.bind(mod),
+          } satisfies SecureStoreLike;
+        }
+        return null;
+      })
+      .catch(() => null);
+  }
+  return secureStorePromise;
+}
+
+/**
+ * A native `NativeKeyValueStorage` that prefers `expo-secure-store` (encrypted
+ * at rest) and falls back to AsyncStorage when SecureStore is not installed.
+ * The SecureStore module is resolved lazily on first access so construction
+ * stays synchronous.
+ */
+export function createNativeSecureKeyValueStorage(): NativeKeyValueStorage {
+  let asyncStorage: Awaited<ReturnType<typeof createPlatformStorage>> | null = null;
+  const getAsyncStorage = async () => {
+    if (!asyncStorage) {
+      asyncStorage = await createPlatformStorage();
+    }
+    return asyncStorage;
+  };
+  return {
+    getItem: async (key) => {
+      const secure = await loadSecureStore();
+      if (secure) {
+        return secure.getItemAsync(key);
+      }
+      return (await getAsyncStorage()).getItem(key);
+    },
+    setItem: async (key, value) => {
+      const secure = await loadSecureStore();
+      if (secure) {
+        await secure.setItemAsync(key, value);
+        return;
+      }
+      await (await getAsyncStorage()).setItem(key, value);
+    },
+    removeItem: async (key) => {
+      const secure = await loadSecureStore();
+      if (secure) {
+        await secure.deleteItemAsync(key);
+        return;
+      }
+      await (await getAsyncStorage()).removeItem(key);
+    },
+  };
+}

package/src/ui/session/tokenTransport.ts

@@ -23,10 +23,23 @@ import type { DeviceSessionState } from '@oxyhq/contracts';
  *
  * A failure is logged and swallowed: this method must never throw out (it runs
  * inside the socket state handler).
+ *
+ * `getPinnedAccountId` is the identity-bound escape hatch. Converging the bearer
+ * on `state.activeAccountId` is precisely what an identity-bound client must
+ * never do — its token is minted for the PINNED account by the cold boot /
+ * re-mint lane. `SessionClient` already bypasses the transport entirely while
+ * pinned; this guard is the services-side half of that contract, so no future
+ * wiring can reintroduce the convergence from this end.
  */
-export function createTokenTransport(oxyServices: OxyServices): TokenTransport {
+export function createTokenTransport(
+  oxyServices: OxyServices,
+  getPinnedAccountId?: () => string | null,
+): TokenTransport {
   return {
     async ensureActiveToken(state: DeviceSessionState): Promise<void> {
+      if ((getPinnedAccountId?.() ?? null) !== null) {
+        return;
+      }
       try {
         // Skip the mint ONLY when the planted bearer already identifies the
         // active account. `getCurrentUserId()` decodes the bearer's `userId`/`id`

package/src/ui/types/navigation.ts

@@ -2,7 +2,8 @@ import type { ReactNode, RefObject } from 'react';
 import type { QueryClient } from '@tanstack/react-query';
 import type { RouteName } from '../navigation/routes';
 import type { User } from '@oxyhq/core';
-import type { ClientSession } from '@oxyhq/core';
+import type { ClientSession, SessionMode } from '@oxyhq/core';
+import type { WebAuthMode } from '../oauth/types';
 
 export interface StepController {
     canGoBack: () => boolean;
@@ -80,6 +81,48 @@ export interface OxyProviderProps {
      * so a local/staging deployment targets its own IdP instead of production.
      */
     authorizeBaseUrl?: string;
+    /**
+     * Who owns this app's session.
+     *
+     * - `'account'` (default) — the device's ACTIVE account. Every ordinary Oxy
+     *   app: any app sharing the device's `DeviceSession` can switch the active
+     *   account and this one follows, sign-in surfaces and the account switcher
+     *   are available, and `accounts` lists the account graph.
+     * - `'identity'` — the owner of this device's PRIMARY identity key, for as
+     *   long as that key exists. The provider pins its authenticated user AND
+     *   its bearer to the account that key authenticates as, so an account
+     *   switch made by any sibling app changes the shared device state but never
+     *   this app's user or token. Built for the identity vault (Commons).
+     *
+     * In `'identity'` mode the account-graph surfaces are disabled at the source
+     * rather than hidden in the UI: `accounts` stays empty and is never fetched,
+     * `switchToAccount` / `switchSession` reject with `IdentityBoundSessionError`,
+     * `accountDialogController` is `null` and `openAccountDialog()` does nothing,
+     * and the two web OAuth cold-boot lanes (authorization-code return + silent
+     * cross-origin restore) are skipped — all of them commit whichever account
+     * the IdP resolves, which is not necessarily the local key's owner.
+     *
+     * Read once at mount, like `baseURL` / `oxyServices`: changing it on a
+     * mounted provider does not re-bind the session.
+     * @default 'account'
+     */
+    sessionMode?: SessionMode;
+    /**
+     * How a WEB third-party "Sign in with Oxy" hands the user to the IdP.
+     *
+     * - `'redirect'` (default) — a full-page navigation to `auth.oxy.so`, which
+     *   returns to the registered `redirect_uri` with `?code=`. The tab unmounts
+     *   and remounts, so route and unsaved state are lost.
+     * - `'popup'` — a small `auth.oxy.so` window opened from the user's click.
+     *   The app stays MOUNTED and becomes authenticated without a reload; the
+     *   IdP delivers only the authorization code + `state` back to the opener
+     *   via `postMessage` (never a token, device secret, or PKCE verifier). A
+     *   blocked popup falls back to the redirect automatically.
+     *
+     * Native is unaffected — it always uses an in-app auth session.
+     * @default 'redirect'
+     */
+    webAuthMode?: WebAuthMode;
     queryClient?: QueryClient;
     /** Sync device credentials to auth.oxy.so after interactive sign-in. @default true */
     hubSync?: boolean;

package/src/ui/utils/__tests__/crossOriginRestore.test.ts

@@ -25,6 +25,7 @@ import {
   isLoopbackOrigin,
   isOfficialWebOrigin,
   isIdpHubOrigin,
+  OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
 } from '@oxyhq/core';
 import { redirectToAuthorize } from '../../components/oauthNavigation';
 import {
@@ -139,5 +140,21 @@ describe('crossOriginRestore', () => {
       expect(params.get('client_id')).toBe('oxy_dk_test');
       expect(params.get('prompt')).toBe('none');
     });
+
+    it('persists the path-qualified redirect_uri in the handshake for token exchange', async () => {
+      makeOriginEligible();
+      const redirectUri = 'https://app.example/oauth/callback';
+      const redirected = await maybeStartSilentOAuthRestore({
+        oxyServices: OXY_SERVICES_STUB,
+        clientId: 'oxy_dk_test',
+        redirectUri,
+      });
+      expect(redirected).toBe(true);
+      expect(globalThis.sessionStorage?.getItem(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY)).toBe(
+        redirectUri,
+      );
+      const url = mockRedirect.mock.calls[0][0] as string;
+      expect(new URL(url).searchParams.get('redirect_uri')).toBe(redirectUri);
+    });
   });
 });

package/src/ui/utils/crossOriginRestore.ts

@@ -8,12 +8,13 @@ import {
   isOfficialWebOrigin,
   OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
   OXY_SILENT_OAUTH_ATTEMPTED_KEY,
+  clearOAuthHandshake,
   persistOAuthHandshake,
-  consumeOAuthReturnPath,
-  normalizeOAuthRedirectUri,
+  canonicalizeOAuthRedirectUri,
   logger,
 } from '@oxyhq/core';
 import { isWebBrowser } from './isWebBrowser';
+import { replaceUrlAfterOAuthReturn } from './oauthReturn';
 import { redirectToAuthorize } from '../components/oauthNavigation';
 
 function sessionStore(): Storage | undefined {
@@ -108,13 +109,12 @@ export async function maybeStartSilentOAuthRestore(
   try {
     const { codeVerifier, codeChallenge } = await generatePkcePair();
     const state = await generateOAuthState();
-    if (!persistOAuthHandshake(state, codeVerifier)) {
-      return false;
-    }
-
-    const redirectUri = normalizeOAuthRedirectUri(
+    const redirectUri = canonicalizeOAuthRedirectUri(
       opts.redirectUri ?? location.origin,
     );
+    if (!persistOAuthHandshake(state, codeVerifier, redirectUri)) {
+      return false;
+    }
 
     const authorizeUrl = buildOAuthAuthorizeUrl({
       authorizeBaseUrl: opts.authorizeBaseUrl,
@@ -161,12 +161,8 @@ export function consumeSilentOAuthError(): 'login_required' | 'consent_required'
     // Silent restore failed, but the visitor still asked for a specific page.
     // Put them back on it rather than leaving them on the bare origin the IdP
     // redirected to.
-    const returnPath = consumeOAuthReturnPath();
-    history.replaceState(
-      history.state,
-      '',
-      returnPath ?? `${url.pathname}${url.search}${url.hash}`,
-    );
+    replaceUrlAfterOAuthReturn(`${url.pathname}${url.search}${url.hash}`);
   }
+  clearOAuthHandshake();
   return error;
 }

package/src/ui/utils/deliveryPlatform.ts

@@ -0,0 +1,65 @@
+/**
+ * Classify the surface a "Sign in with Oxy" request is initiated from, for
+ * `AccountDialogController`'s `platform` option (issue #691, Phase 4/5).
+ *
+ * `@oxyhq/core` deliberately refuses to do this itself — it never touches a
+ * platform global — so the consumer that OWNS the environment classifies it and
+ * hands the verdict in. The verdict feeds `selectCommonsDelivery`, where it
+ * decides one thing only: whether this device may take the `'open-commons'`
+ * deep-link route. Getting it wrong in the "mobile" direction is the costly
+ * error (a custom-scheme navigation that does not resolve is a dead end with no
+ * automatic way back), so every ambiguous signal resolves AWAY from `'mobile'`.
+ *
+ * No user-agent string is parsed. The two signals used are declarative and
+ * standardized:
+ *   1. `navigator.userAgentData.mobile` — the User-Agent Client Hints boolean.
+ *      Authoritative where implemented (Chromium), in both directions.
+ *   2. The PRIMARY pointer (`(pointer: coarse)`) plus a touch digitizer.
+ *      A phone/tablet reports a coarse primary pointer; a touchscreen laptop
+ *      still reports its mouse as primary, so it is not misclassified.
+ */
+
+import type { CommonsDeliveryPlatform } from '@oxyhq/core';
+import { isWebBrowser } from './isWebBrowser';
+
+/**
+ * The `navigator.userAgentData` slice this module reads. Declared locally
+ * because `NavigatorUAData` is not in TypeScript's DOM lib yet; only the one
+ * field consumed here is modelled, and it stays optional so an implementation
+ * without it is simply "no answer" rather than a type lie.
+ */
+interface NavigatorUserAgentData {
+  readonly mobile?: boolean;
+}
+
+type NavigatorWithUserAgentData = Navigator & {
+  readonly userAgentData?: NavigatorUserAgentData;
+};
+
+/**
+ * Which surface this app is running on, as `selectCommonsDelivery` models it.
+ *
+ *  - Native (Expo/RN) is always `'mobile'`: it is an Oxy app installed on a
+ *    phone/tablet, exactly the case where a verified Commons link can resolve
+ *    on this very device.
+ *  - A web browser is classified from the signals above.
+ *  - Anything else — a browser-like environment with neither signal — is
+ *    `'unknown'`, a first-class value that never opts into the deep link.
+ */
+export function resolveDeliveryPlatform(): CommonsDeliveryPlatform {
+  if (!isWebBrowser()) return 'mobile';
+
+  const nav: NavigatorWithUserAgentData | undefined =
+    typeof navigator === 'undefined' ? undefined : navigator;
+
+  const uaMobile = nav?.userAgentData?.mobile;
+  if (typeof uaMobile === 'boolean') return uaMobile ? 'mobile' : 'desktop';
+
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    const coarsePrimaryPointer = window.matchMedia('(pointer: coarse)').matches;
+    const hasTouchDigitizer = (nav?.maxTouchPoints ?? 0) > 0;
+    return coarsePrimaryPointer && hasTouchDigitizer ? 'mobile' : 'desktop';
+  }
+
+  return 'unknown';
+}