@oxyhq/services 27.1.3 → 29.0.0

package/NOTICE

@@ -0,0 +1,16 @@
+============================================================================
+ NOTICE
+ @oxyhq/services
+ Copyright (c) 2025-present The Oxy Collective, Inc.
+============================================================================
+
+This product is licensed under the Apache License, Version 2.0. See the
+LICENSE file in this directory.
+
+----------------------------------------------------------------------------
+ THIRD PARTY COMPONENTS
+----------------------------------------------------------------------------
+
+This package contains no third party source. Its dependencies are resolved
+and installed by the package manager and remain governed by their own
+licenses.

package/README.md

@@ -50,6 +50,69 @@ This package (`@oxyhq/services`) is the **single UI SDK** for every React surfac
 
 See [PLATFORM_GUIDE.md](./PLATFORM_GUIDE.md) for the complete architecture guide.
 
+### This package does not declare `sideEffects: false`
+
+It used to, and the declaration was **wrong**. Three modules in the build have
+top-level side effects, one of them the entry itself:
+
+| Module | Effect |
+|---|---|
+| `lib/module/index.js` | `setPlatformOS(Platform.OS)` — configures `@oxyhq/core` |
+| `lib/module/ui/navigation/surfaceBackBridge.js` | `installEscapeHandler()` — installs a global key handler |
+| `lib/module/ui/components/SettingsIcon.js` | assigns `displayName` |
+
+Removing a false declaration would be worth doing on its own. It also fixed a
+production outage, and that is the part worth remembering, because the symptom
+looked nothing like a `package.json` field.
+
+`auth.oxy.so/authorize` rendered a blank page with React error #130 ("element
+type is undefined") for every request that reached `OxySignInRequestSurface`,
+which blocked every OIDC login into Allo ([#784]). Source and dev server were
+fine; only the production bundle was broken. Two facts combined:
+
+1. **The UI graph was one large import cycle.** `ui/context/OxyContext` reaches
+   `ui/navigation/bottomSheetManager` → `navigation/routes`, `routes` reached
+   every screen (through `require()` calls it made for Metro's benefit), and
+   every screen reaches back into the context — a 67-module strongly connected
+   component that included `OxySignInRequestSurface`. A bundler cannot
+   concatenate a cycle, so it emits each member as a lazily-initialized wrapper
+   whose exported bindings are `undefined` until the initializer runs. Modules
+   outside the cycle, `OxyConsentScreen` among them, are emitted inline and were
+   never affected — which is exactly why only some screens broke.
+2. **`sideEffects: false` told the bundler that running those initializers was
+   unobservable**, so rolldown-vite omitted the initializer call at the
+   consuming import site in `packages/auth` while still emitting the reference.
+   The binding was therefore never assigned, and React was handed `undefined`.
+
+That cycle was the deeper defect, and it has since been cut down. `routes.ts`
+registers screens as `lazy(() => import(...))` rather than `require()`, so the
+registry no longer drags all 40 screens into the context's component; the two
+remaining `require()` sites became static imports read at call time. Measured on
+the built ESM output, the largest strongly connected component went from **67
+modules to 2**, and `OxySignInRequestSurface` is no longer inside any cycle.
+What is left is two mutual pairs — `surfaces` ↔ `SurfaceScreen` and
+`OxyContext` ↔ `useFollow` — each of which only ever reads the other at call or
+render time.
+
+Cycles still exist, so do not re-add `sideEffects` in any form. A narrowed,
+truthful list would leave every component still in a cycle exactly as exposed,
+because none of *them* has a top-level side effect either. The cost of not
+declaring it was measured at the time on the IdP's own production bundle, which
+is the heaviest consumer of this package on the web: **5,483.86 kB → 5,489.99 kB
+raw (+0.11%)** and **1,457.31 kB → 1,458.66 kB gzip (+0.09%)**.
+
+**No module in this package's source may call `require()`.** The build is ESM,
+and a surviving `require()` puts bundlers back into CommonJS interop — the same
+lazily-initialized wrappers, reachable the same silent way. To defer a read, use
+a thunk over a static import; to defer a *load*, use `import()`.
+`src/__tests__/esmSourcePurity.test.ts` enforces this.
+
+`packages/auth/lib/__tests__/authorize-surface-bundle.test.ts` builds the IdP's
+real production bundle and renders the surface out of it, so a regression fails
+in CI with React's own message instead of on auth.oxy.so.
+
+[#784]: https://github.com/OxyHQ/OxyHQServices/issues/784
+
 ## Installation
 
 ```bash
@@ -618,7 +681,7 @@ const metadata = getLanguageMetadata('es-ES');
 
 ### Common Issues
 
-#### 1. "useOxy must be used within an OxyContextProvider"
+#### 1. "useOxy() was called outside <OxyProvider>"
 
 **Solution**: Wrap your app with `OxyProvider`
 
@@ -785,4 +848,6 @@ Comprehensive documentation is available in the `/docs` directory:
 
 ## License
 
-This project is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only), (c) The Oxy Foundation, Inc. See the [LICENSE](LICENSE) file for details.
+This package is licensed under the Apache License, Version 2.0, (c) The Oxy Collective, Inc. See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.
+
+Versions published before `28.0.0` were AGPL-3.0-only and stay that way; a licence change binds future versions only.

package/android/src/main/java/so/oxy/devicesession/OxyDeviceSessionModule.kt

@@ -0,0 +1,178 @@
+package so.oxy.devicesession
+
+import android.content.Context
+import android.net.Uri
+import android.os.Bundle
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * JS bridge for the shared DeviceSession credential.
+ *
+ * - `read` resolves the credential this DEVICE holds, from the sibling providers
+ *   first and this app's own store second (see [readShared] for why that order).
+ * - `write` publishes into this app's own store only, and reports whether a
+ *   read-back confirmed it.
+ * - `clear` drops this app's copy.
+ *
+ * ## `read` returns a STATUS, not a nullable value
+ *
+ * The three answers "here it is", "there is none" and "I could not tell" are
+ * genuinely different, and only the second one authorises the JS side to seed the
+ * slot. A nullable return would merge the last two, and the merged value reads as
+ * "fresh device" — which is exactly how a locked or broken keystore ends up
+ * overwriting a live session. So every path here reports its status explicitly,
+ * and never degrades a failure into an absence.
+ *
+ * Return shapes:
+ * ```
+ * { "status": "present", "deviceId": "...", "deviceSecret": "..." }
+ * { "status": "absent" }
+ * { "status": "unavailable", "reason": "<ExceptionClassName>" }
+ * ```
+ *
+ * Plain scalars in, a plain `Map` out — never an Expo `Record`. This package
+ * ships as SOURCE that each consuming app compiles, so the annotation processing
+ * a `Record` needs to become introspectable does not necessarily run in the
+ * consumer's build; the one `Record` this package ever had failed to convert on a
+ * real device and stored nothing, silently. See the long note in
+ * `so.oxy.session.OxyBackgroundSessionModule` before reaching for one here.
+ */
+class OxyDeviceSessionModule : Module() {
+  private val context: Context
+    get() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+
+  override fun definition() = ModuleDefinition {
+    Name("OxyDeviceSession")
+
+    AsyncFunction("read") {
+      readShared()
+    }
+
+    AsyncFunction("write") { deviceId: String, deviceSecret: String ->
+      if (deviceId.isEmpty() || deviceSecret.isEmpty()) {
+        return@AsyncFunction false
+      }
+      OxyDeviceSessionStore.write(context, deviceId, deviceSecret)
+    }
+
+    AsyncFunction("clear") {
+      OxyDeviceSessionStore.clear(context)
+    }
+  }
+
+  /**
+   * Providers FIRST, this app's own store second.
+   *
+   * Under `android:sharedUserId="so.oxy.shared"` every Oxy app sees one data
+   * directory, so for a UID member the local file IS the group's file and the
+   * order changes nothing. It matters for a same-signature app OUTSIDE the UID:
+   * there the local file is a private mirror of whatever that app itself last
+   * wrote, so reading it first would shadow the group's real credential forever.
+   *
+   * `unavailable` is sticky across the whole sweep: if ANY source could not be
+   * read and none produced a credential, the answer is `unavailable`, not
+   * `absent`. The pessimistic merge is the point — the optimistic one authorises
+   * a write.
+   */
+  private fun readShared(): Map<String, String> {
+    var unavailableReason: String? = null
+
+    for (authority in PROVIDER_AUTHORITIES) {
+      when (val read = callProvider(authority)) {
+        is DeviceSessionRead.Present -> return present(read)
+        is DeviceSessionRead.Unavailable -> unavailableReason = unavailableReason ?: read.reason
+        // Absent, or no provider there at all (not installed, refused, threw) —
+        // neither is evidence about the other sources, so keep looking.
+        else -> Unit
+      }
+    }
+
+    when (val local = OxyDeviceSessionStore.read(context)) {
+      is DeviceSessionRead.Present -> return present(local)
+      is DeviceSessionRead.Unavailable -> unavailableReason = unavailableReason ?: local.reason
+      is DeviceSessionRead.Absent -> Unit
+    }
+
+    val reason = unavailableReason
+    return if (reason != null) {
+      mapOf(
+        OxyDeviceSessionProvider.KEY_STATUS to OxyDeviceSessionProvider.STATUS_UNAVAILABLE,
+        OxyDeviceSessionProvider.KEY_REASON to reason,
+      )
+    } else {
+      mapOf(OxyDeviceSessionProvider.KEY_STATUS to OxyDeviceSessionProvider.STATUS_ABSENT)
+    }
+  }
+
+  private fun present(read: DeviceSessionRead.Present): Map<String, String> = mapOf(
+    OxyDeviceSessionProvider.KEY_STATUS to OxyDeviceSessionProvider.STATUS_PRESENT,
+    OxyDeviceSessionStore.KEY_DEVICE_ID to read.deviceId,
+    OxyDeviceSessionStore.KEY_DEVICE_SECRET to read.deviceSecret,
+  )
+
+  /**
+   * Call one sibling provider. `null` means "nothing to learn from this one" —
+   * the app is not installed, package visibility hid it, the permission was
+   * refused, or the call threw. A provider that answered but could not read its
+   * own store returns [DeviceSessionRead.Unavailable], which the sweep keeps.
+   */
+  private fun callProvider(authority: String): DeviceSessionRead? = runCatching {
+    val uri = Uri.parse("content://$authority")
+    val bundle: Bundle = context.contentResolver.call(
+      uri,
+      OxyDeviceSessionProvider.METHOD_READ,
+      null,
+      null,
+    ) ?: return@runCatching null
+
+    when (bundle.getString(OxyDeviceSessionProvider.KEY_STATUS)) {
+      OxyDeviceSessionProvider.STATUS_PRESENT -> {
+        val deviceId = bundle.getString(OxyDeviceSessionStore.KEY_DEVICE_ID)
+        val deviceSecret = bundle.getString(OxyDeviceSessionStore.KEY_DEVICE_SECRET)
+        if (deviceId.isNullOrEmpty() || deviceSecret.isNullOrEmpty()) {
+          // A `present` verdict with an incomplete payload is a broken peer, not
+          // an empty device.
+          DeviceSessionRead.Unavailable("IncompleteProviderPayload")
+        } else {
+          DeviceSessionRead.Present(deviceId, deviceSecret)
+        }
+      }
+      OxyDeviceSessionProvider.STATUS_ABSENT -> DeviceSessionRead.Absent
+      OxyDeviceSessionProvider.STATUS_UNAVAILABLE ->
+        DeviceSessionRead.Unavailable(
+          bundle.getString(OxyDeviceSessionProvider.KEY_REASON) ?: "PeerUnavailable",
+        )
+      // An older sibling that predates this protocol. It said something we do not
+      // understand, so we have learned nothing — never read that as "absent".
+      else -> DeviceSessionRead.Unavailable("UnrecognisedProviderStatus")
+    }
+  }.getOrNull()
+
+  companion object {
+    /**
+     * Sibling authorities to sweep, in order. Each official Oxy Android app hosts
+     * the provider at `${applicationId}.devicesession` via the
+     * `withSharedDeviceSession` config plugin, and both the prod and `.dev`
+     * variants are listed so a developer build can join a device too.
+     *
+     * MAINTAINED LIST, and the constraint on it is specific: every entry must be
+     * an app inside the `so.oxy.shared` UID. UID members all serve ONE file, so
+     * the sweep is deterministic no matter which of them answers first. Adding an
+     * app that is same-signature but NOT in the UID would put a second,
+     * independent copy of "the shared credential" into the sweep and make the
+     * winner depend on list order.
+     *
+     * The same authorities must also be added to the `<queries>` block in
+     * `withSharedDeviceSession.js`, or Android 11+ package-visibility filtering
+     * hides them from `ContentResolver.call` and the sweep silently finds nothing.
+     */
+    private val PROVIDER_AUTHORITIES = listOf(
+      "so.oxy.accounts.devicesession",
+      "so.oxy.accounts.dev.devicesession",
+      "so.oxy.commons.devicesession",
+      "so.oxy.commons.dev.devicesession",
+    )
+  }
+}

package/android/src/main/java/so/oxy/devicesession/OxyDeviceSessionProvider.kt

@@ -0,0 +1,99 @@
+package so.oxy.devicesession
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.content.Context
+import android.content.pm.PackageManager
+import android.database.Cursor
+import android.net.Uri
+import android.os.Bundle
+
+/**
+ * Cross-process READ surface for the shared DeviceSession credential, declared
+ * per-app by the `withSharedDeviceSession` config plugin at authority
+ * `${applicationId}.devicesession` behind a `signature`-level permission.
+ *
+ * The signature check below is belt-and-suspenders on top of that permission:
+ * even if the manifest gate were ever misconfigured, a differently-signed caller
+ * still gets nothing. Same-signature is the whole trust boundary — an
+ * incorrectly-signed app cannot read this slot, and there is no other way in.
+ *
+ * READ-ONLY across the process boundary, deliberately. A caller may join the
+ * device's session; it may not seed or overwrite another app's. Writes happen
+ * only in-process via [OxyDeviceSessionModule], against this app's own store.
+ *
+ * What crosses the boundary is a session credential — never the identity
+ * keypair, which lives behind `so.oxy.identity.OxyIdentityProvider` under a
+ * different permission. That separation is the point.
+ *
+ * All standard CRUD operations are no-ops; this provider exists solely for the
+ * `call()` channel.
+ */
+class OxyDeviceSessionProvider : ContentProvider() {
+  override fun onCreate(): Boolean = true
+
+  override fun call(method: String, arg: String?, extras: Bundle?): Bundle? {
+    if (method != METHOD_READ) return null
+    val ctx = context ?: return null
+    if (!callerSignatureMatches(ctx)) return null
+
+    return when (val read = OxyDeviceSessionStore.read(ctx)) {
+      is DeviceSessionRead.Present -> Bundle().apply {
+        putString(KEY_STATUS, STATUS_PRESENT)
+        putString(OxyDeviceSessionStore.KEY_DEVICE_ID, read.deviceId)
+        putString(OxyDeviceSessionStore.KEY_DEVICE_SECRET, read.deviceSecret)
+      }
+      is DeviceSessionRead.Absent -> Bundle().apply { putString(KEY_STATUS, STATUS_ABSENT) }
+      // Reported, not swallowed. A null here would be indistinguishable from
+      // "this app has no credential", and the caller would go on to treat the
+      // device as fresh.
+      is DeviceSessionRead.Unavailable -> Bundle().apply {
+        putString(KEY_STATUS, STATUS_UNAVAILABLE)
+        putString(KEY_REASON, read.reason)
+      }
+    }
+  }
+
+  /**
+   * True when the calling package shares this app's signing certificate. Uses
+   * `checkSignatures` (deprecated but still the simplest correct cross-package
+   * signature comparison; returns SIGNATURE_MATCH only for same-cert apps).
+   */
+  private fun callerSignatureMatches(ctx: Context): Boolean {
+    val caller = callingPackage ?: return false
+    return runCatching {
+      @Suppress("DEPRECATION")
+      ctx.packageManager.checkSignatures(caller, ctx.packageName) == PackageManager.SIGNATURE_MATCH
+    }.getOrDefault(false)
+  }
+
+  override fun query(
+    uri: Uri,
+    projection: Array<out String>?,
+    selection: String?,
+    selectionArgs: Array<out String>?,
+    sortOrder: String?
+  ): Cursor? = null
+
+  override fun getType(uri: Uri): String? = null
+
+  override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+  override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0
+
+  override fun update(
+    uri: Uri,
+    values: ContentValues?,
+    selection: String?,
+    selectionArgs: Array<out String>?
+  ): Int = 0
+
+  companion object {
+    const val METHOD_READ = "read"
+    const val KEY_STATUS = "status"
+    const val KEY_REASON = "reason"
+    const val STATUS_PRESENT = "present"
+    const val STATUS_ABSENT = "absent"
+    const val STATUS_UNAVAILABLE = "unavailable"
+  }
+}

package/android/src/main/java/so/oxy/devicesession/OxyDeviceSessionStore.kt

@@ -0,0 +1,115 @@
+package so.oxy.devicesession
+
+import android.content.Context
+import android.content.SharedPreferences
+import so.oxy.storage.OxyEncryptedPrefs
+import so.oxy.storage.RecoveryPolicy
+
+/**
+ * What a read of the shared slot found.
+ *
+ * THREE outcomes, and the difference between the last two is the entire safety
+ * property of this file. An EMPTY slot authorises a write (seed the device
+ * session); a slot that could not be READ must authorise nothing, because it may
+ * hold a live session belonging to someone still signed in. Collapsing them —
+ * which a plain nullable return would do — is how a locked or broken keystore
+ * gets mistaken for a fresh device.
+ */
+internal sealed interface DeviceSessionRead {
+  data class Present(val deviceId: String, val deviceSecret: String) : DeviceSessionRead
+  object Absent : DeviceSessionRead
+  /** [reason] is an exception CLASS NAME only — never a message, never a value. */
+  data class Unavailable(val reason: String) : DeviceSessionRead
+}
+
+/**
+ * The cross-app DeviceSession credential — `deviceId` + `deviceSecret`, and
+ * nothing else.
+ *
+ * This is NOT the identity keypair. `so.oxy.identity.OxyIdentityStore` holds the
+ * self-custody private key that signs identity approvals and cannot be
+ * re-created; this file holds an ordinary session credential the server can
+ * revoke and any signed-in app can re-publish. They are separate files behind
+ * separate providers with separate permissions precisely so an app that only
+ * needs a session is never handed the key.
+ *
+ * Under `android:sharedUserId="so.oxy.shared"` every Oxy app sees ONE data
+ * directory, so this file is literally shared between them — that is the primary
+ * transport, and [OxyDeviceSessionProvider] extends the same bytes to a
+ * same-signature app outside the UID.
+ */
+internal object OxyDeviceSessionStore {
+  /**
+   * Global (not package-suffixed) on purpose — the opposite choice from
+   * `oxy_background_session`, and for the opposite reason. That store is
+   * per-app precisely so one app cannot touch another's widget credential. This
+   * one EXISTS to be one value shared by every app in the UID; scoping it per
+   * package would give each app its own copy and defeat the whole point.
+   */
+  const val PREFS_NAME = "oxy_shared_device_session"
+  const val KEY_DEVICE_ID = "deviceId"
+  const val KEY_DEVICE_SECRET = "deviceSecret"
+
+  /**
+   * [RecoveryPolicy.RebuildFileOnly] — this store must NEVER escalate to a
+   * UID-shared master-key reset.
+   *
+   * What it holds is DERIVED: every signed-in app re-publishes the credential
+   * from its own durable copy, so losing this file costs at most one interactive
+   * sign-in on a device that has no other Oxy app installed. A master-key reset
+   * would wipe every other Oxy store sharing the alias — including the
+   * self-custody identity keypair, which is IRREPLACEABLE. Trading someone's
+   * unrecoverable identity to save a credential we can simply re-publish is never
+   * the right trade, so the escalation is not merely discouraged here, it is
+   * unreachable.
+   *
+   * Consequence worth stating: a stage-1 heal WIPES this file. That surfaces as
+   * `Absent`, which is honest — after the wipe the slot really is empty, and the
+   * next successful mint in any app re-seeds it.
+   */
+  private fun prefs(context: Context): SharedPreferences =
+    OxyEncryptedPrefs.open(context, PREFS_NAME, RecoveryPolicy.RebuildFileOnly)
+
+  /**
+   * Read the credential. A thrown open (the keyset is unreadable and the policy
+   * above refuses to escalate) is reported as [DeviceSessionRead.Unavailable] —
+   * never as absent.
+   */
+  fun read(context: Context): DeviceSessionRead =
+    runCatching {
+      val p = prefs(context)
+      val deviceId = p.getString(KEY_DEVICE_ID, null)
+      val deviceSecret = p.getString(KEY_DEVICE_SECRET, null)
+      if (deviceId.isNullOrEmpty() || deviceSecret.isNullOrEmpty()) {
+        DeviceSessionRead.Absent
+      } else {
+        DeviceSessionRead.Present(deviceId, deviceSecret)
+      }
+    }.getOrElse { DeviceSessionRead.Unavailable(it.javaClass.simpleName) }
+
+  /**
+   * Replace the credential, returning whether a read-back confirmed it landed.
+   *
+   * The read-back is the contract JS relies on: a fresh install adopts whatever
+   * is in this slot, so publishing a value that did not actually persist would
+   * send it into a mint that can never succeed.
+   *
+   * `commit()` (synchronous) so a cross-process reader firing immediately after
+   * the write sees the flushed value.
+   */
+  fun write(context: Context, deviceId: String, deviceSecret: String): Boolean =
+    runCatching {
+      val p = prefs(context)
+      p.edit()
+        .putString(KEY_DEVICE_ID, deviceId)
+        .putString(KEY_DEVICE_SECRET, deviceSecret)
+        .commit()
+      p.getString(KEY_DEVICE_ID, null) == deviceId &&
+        p.getString(KEY_DEVICE_SECRET, null) == deviceSecret
+    }.getOrDefault(false)
+
+  /** Drop the shared credential. Best-effort; safe to call when already empty. */
+  fun clear(context: Context) {
+    runCatching { prefs(context).edit().clear().commit() }
+  }
+}

package/expo-module.config.json

@@ -6,6 +6,7 @@
   "android": {
     "modules": [
       "so.oxy.identity.OxyIdentityModule",
+      "so.oxy.devicesession.OxyDeviceSessionModule",
       "so.oxy.session.OxyBackgroundSessionModule"
     ]
   }