@oxyhq/services 27.1.3 → 29.0.0

package/lib/typescript/module/ui/types/navigation.d.ts

@@ -123,5 +123,31 @@ export interface OxyProviderProps {
      * @default false
      */
     backgroundSession?: boolean;
+    /**
+     * Whether this origin/app may persist the durable device credential
+     * (`deviceId` + `deviceSecret`) at all.
+     *
+     * `'persistent'` (the default, and every app's behaviour) stores it — web
+     * localStorage per origin, SecureStore per app on native — so the SDK can
+     * re-mint an access token on the next cold boot.
+     *
+     * `'ephemeral'` stores NOTHING durable: the session lives in memory for the
+     * lifetime of the page and is gone on reload. It exists for ONE caller,
+     * `auth.oxy.so` with the browser hub enabled (issue #937 Phase 5, ADR 0003),
+     * where the durable credential for the browser profile is the server-side
+     * DeviceSession behind the `__Host-oxy-device` handle. Two durable
+     * credentials for one origin is the dual authority that phase exists to
+     * remove — revoking the hub while a localStorage secret still mints would
+     * make a sign-out look like it worked — so the way to let the hub be
+     * authoritative is to stop persisting the other one, not to consult it
+     * second.
+     *
+     * Do NOT reach for this to make an app "more private". A relying-party
+     * origin set to `'ephemeral'` simply signs the user out on every reload,
+     * because nothing else on that origin remembers the device.
+     *
+     * @default 'persistent'
+     */
+    deviceCredentialStorage?: 'persistent' | 'ephemeral';
 }
 //# sourceMappingURL=navigation.d.ts.map

package/lib/typescript/module/ui/types/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAElD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAE5B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGrC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAGlC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAGjE,aAAa,CAAC,EAAE,SAAS,CAAC;IAG1B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAElD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAE5B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGrC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAGlC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAGjE,aAAa,CAAC,EAAE,SAAS,CAAC;IAG1B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,uBAAuB,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;CACxD"}

package/lib/typescript/module/ui/utils/avatarUtils.d.ts

@@ -2,16 +2,8 @@ import type { OxyServices, User } from '@oxyhq/core';
 import type { UserProfileUpdate } from '@oxyhq/contracts';
 import type { QueryClient } from '@tanstack/react-query';
 /**
- * Refreshes avatar in accountStore with cache-busted URL to force image reload.
- *
- * @param sessionId - The session ID for the account to update
- * @param avatarFileId - The new avatar file ID
- * @param oxyServices - OxyServices instance to generate download URL
- */
-export declare function refreshAvatarInStore(sessionId: string, avatarFileId: string, oxyServices: OxyServices): void;
-/**
- * Updates user profile with avatar and handles all side effects (query invalidation, accountStore update).
- * This function can be used from within OxyContext provider without requiring useOxy hook.
+ * Updates user profile with avatar and handles all side effects (cache writes,
+ * query invalidation). Usable from inside the provider without `useOxy`.
  *
  * @param updates - Profile updates including avatar
  * @param oxyServices - OxyServices instance

package/lib/typescript/module/ui/utils/avatarUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"avatarUtils.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/avatarUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,WAAW,GACvB,IAAI,CAON;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,WAAW,EAAE,WAAW,EACxB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAyCf"}
+{"version":3,"file":"avatarUtils.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/avatarUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,WAAW,EAAE,WAAW,EACxB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@oxyhq/services",
-  "version": "27.1.3",
+  "version": "29.0.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "types": "lib/typescript/commonjs/index.d.ts",
   "react-native": "src/index.ts",
   "source": "src/index.ts",
-  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
@@ -77,6 +76,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "NOTICE",
     "src",
     "lib",
     "assets",
@@ -103,7 +103,7 @@
     "directory": "packages/services"
   },
   "author": "OxyHQ",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "engines": {
     "node": ">=18.0.0"
   },
@@ -138,7 +138,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "0.24.0",
+    "@oxyhq/contracts": "0.26.0",
     "@simplewebauthn/browser": "^13.3.0",
     "color": "^4.2.3"
   },
@@ -147,10 +147,10 @@
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@expo/vector-icons": "^15.0.3",
-    "@oxyhq/core": "19.1.2",
+    "@oxyhq/core": "21.0.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^11.4.1",
-    "@react-native/babel-preset": "^0.86.0",
+    "@react-native/babel-preset": "^0.86.2",
     "@release-it/conventional-changelog": "^10.0.6",
     "@tanstack/query-async-storage-persister": "^5.101",
     "@tanstack/query-sync-storage-persister": "^5.101",
@@ -183,14 +183,14 @@
     "react-native-svg": "15.15.5",
     "release-it": "^19.0.6",
     "socket.io-client": "^4.8.1",
-    "ts-jest": "^29.4.0",
+    "ts-jest": "^29.4.12",
     "typescript": "^5.9.2",
     "zustand": "^5.0.14"
   },
   "peerDependencies": {
     "@expo/vector-icons": "^15.0.3",
     "@oxyhq/bloom": ">=0.59.0",
-    "@oxyhq/core": "^19.0.0",
+    "@oxyhq/core": "^21.0.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": ">=11.4.1",
     "@tanstack/query-async-storage-persister": "^5.101",

package/plugins/withSharedDeviceSessionProvider.js

@@ -0,0 +1,102 @@
+/**
+ * Config plugin: withSharedDeviceSessionProvider (UID-member hub apps).
+ *
+ * The shared DeviceSession credential is how several official Oxy apps end up on
+ * ONE `DeviceSession` — and therefore one globally active account context —
+ * WITHOUT any of them reading Commons's private identity key. This plugin wires
+ * the Android side of `@oxyhq/services`:
+ *
+ *  - Defines a `signature`-level permission
+ *    `so.oxy.shared.permission.READ_DEVICE_SESSION`. `signature` means only apps
+ *    signed with the SAME certificate (the shared Oxy release keystore) can hold
+ *    it — the trust boundary is the signing key, not the deprecated `sharedUserId`.
+ *  - Requests that same permission so this app can also read cross-authority.
+ *  - Declares `OxyDeviceSessionProvider` at authority
+ *    `${applicationId}.devicesession` (AGP substitutes `${applicationId}` at
+ *    build), guarded by that permission. The provider is READ-only across the
+ *    process boundary: a sibling may join the device session, never overwrite it.
+ *  - Adds `<queries>` entries so Android 11+ package-visibility filtering never
+ *    hides the sibling providers from the resolver.
+ *
+ * WHICH APPS USE THIS PLUGIN: exactly the apps listed in `PROVIDER_AUTHORITIES`
+ * below, which must be apps inside the `so.oxy.shared` UID. UID members share one
+ * data directory, so they all serve the SAME file and the sweep in
+ * `OxyDeviceSessionModule` is deterministic whichever one answers. An app that is
+ * same-signature but outside that UID must use `withSharedDeviceSessionReader`
+ * instead — hosting from there would publish a second, independent copy of "the
+ * shared credential" and make the winner depend on list order.
+ *
+ * Keep this list identical to `PROVIDER_AUTHORITIES` in
+ * `android/src/main/java/so/oxy/devicesession/OxyDeviceSessionModule.kt`.
+ *
+ * This is deliberately a SEPARATE permission and a SEPARATE provider from
+ * `withSharedIdentityProvider`. Two secrets with different blast radii: the
+ * identity key is self-custody and irreplaceable, the device credential is
+ * server-revocable and re-publishable. An app that only needs a session gets only
+ * the second one.
+ */
+const { withAndroidManifest } = require('@expo/config-plugins');
+
+const READ_DEVICE_SESSION_PERMISSION = 'so.oxy.shared.permission.READ_DEVICE_SESSION';
+const PROVIDER_CLASS = 'so.oxy.devicesession.OxyDeviceSessionProvider';
+const PROVIDER_AUTHORITIES = [
+  'so.oxy.accounts.devicesession',
+  'so.oxy.accounts.dev.devicesession',
+  'so.oxy.commons.devicesession',
+  'so.oxy.commons.dev.devicesession',
+];
+
+module.exports = function withSharedDeviceSessionProvider(config) {
+  return withAndroidManifest(config, (modConfig) => {
+    const manifest = modConfig.modResults.manifest;
+
+    // 1. Define the signature-level permission.
+    manifest['permission'] = manifest['permission'] ?? [];
+    if (!manifest['permission'].some((p) => p.$['android:name'] === READ_DEVICE_SESSION_PERMISSION)) {
+      manifest['permission'].push({
+        $: {
+          'android:name': READ_DEVICE_SESSION_PERMISSION,
+          'android:protectionLevel': 'signature',
+        },
+      });
+    }
+
+    // 2. Request it (a hub app reads its siblings too — prod ⇆ dev variant).
+    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 } });
+    }
+
+    // 3. Make the sibling provider authorities visible under package filtering.
+    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 } });
+      }
+    }
+
+    // 4. Host the provider.
+    const app = manifest.application?.[0];
+    if (!app) {
+      throw new Error('withSharedDeviceSessionProvider: AndroidManifest has no <application>');
+    }
+    app.provider = app.provider ?? [];
+    if (!app.provider.some((p) => p.$['android:name'] === PROVIDER_CLASS)) {
+      app.provider.push({
+        $: {
+          'android:name': PROVIDER_CLASS,
+          'android:authorities': '${applicationId}.devicesession',
+          'android:exported': 'true',
+          'android:permission': READ_DEVICE_SESSION_PERMISSION,
+        },
+      });
+    }
+
+    return modConfig;
+  });
+};

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,
@@ -306,6 +328,11 @@ export {
   // guide most likely to be reached for did not resolve.
   isFollowedGlobally,
   withApplicationMode,
+  // Whether a cached status is safe to act on without a round trip — list rows
+  // often carry globalState without relationshipId.
+  isCompleteFollowStatus,
+  followRecordToStatus,
+  followRecordsToStatusMap,
 } from './ui/stores/followTargetStore';
 export { default as OxyPayButton } from './ui/components/OxyPayButton';
 export { LogoIcon } from './ui/components/logo/LogoIcon';
@@ -338,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