@oxyhq/services 23.2.0 → 24.0.1

package/android/src/main/java/so/oxy/identity/OxyIdentityStore.kt

@@ -2,12 +2,8 @@ package so.oxy.identity
 
 import android.content.Context
 import android.content.SharedPreferences
-import android.util.Log
-import androidx.security.crypto.EncryptedSharedPreferences
-import androidx.security.crypto.MasterKey
-import java.io.IOException
-import java.security.GeneralSecurityException
-import java.security.KeyStore
+import so.oxy.storage.OxyEncryptedPrefs
+import so.oxy.storage.RecoveryPolicy
 
 /**
  * Shared accessor for the hardware-backed EncryptedSharedPreferences that holds
@@ -15,137 +11,35 @@ import java.security.KeyStore
  *
  * Used by BOTH [OxyIdentityModule] (the JS bridge / local read + write) and
  * [OxyIdentityProvider] (the cross-process read surface) so the store name and
- * the AES256 encryption scheme can never drift between the two halves.
+ * the encryption scheme can never drift between the two halves.
  *
- * ## Single memoized instance (CRITICAL)
+ * Opening the file — the single-memoized-instance rule and the two-stage keyset
+ * self-heal, both load-bearing and non-obvious — lives in [OxyEncryptedPrefs],
+ * which is shared with the background-session store. Read its documentation
+ * before changing anything about how this file is opened.
  *
- * `EncryptedSharedPreferences.create()` must be called AT MOST ONCE per file per
- * process. It is NOT safe to re-instantiate: when a second instance is created
- * for the same file while another is live (e.g. the JS write thread and a Binder
- * thread serving [OxyIdentityProvider.call] concurrently), Tink's keyset load
- * races and the next decrypt throws `AEADBadTagException` — which silently turned
- * every cross-app read into "no shared identity". So the instance is created once,
- * lazily, under a lock, keyed on the process-global application context, and
- * reused for all reads/writes/provider calls.
- *
- * ## Keyset self-heal (CRITICAL)
- *
- * The androidx master key that wraps this file's Tink keyset lives under the
- * UID-scoped default alias [MasterKey.DEFAULT_MASTER_KEY_ALIAS] — one entry for
- * the whole `so.oxy.shared` UID. When a NEW package joins that shared UID, that
- * master key can be rotated/regenerated, leaving the keyset already written into
- * `oxy_shared_identity.xml` wrapped under the OLD key. `create()` then fails GCM
- * verification (`AEADBadTag` -> `GeneralSecurityException`, or an unreadable
- * keyset -> `IOException`) on EVERY read/write, and `EncryptedSharedPreferences`
- * never self-heals — the slot stays permanently dead and cross-app "Sign in with
- * Oxy" silently falls back to interactive import.
- *
- * [openOrHealPrefs] recovers ONCE, in two bounded stages (no retry loop):
- *   1. Delete ONLY this slot's prefs file (the stale wrapped keyset) and rebuild
- *      against the current master key — heals the common rotation case without
- *      touching the master key, so other shared-UID members keep their keysets.
- *   2. If a fresh keyset STILL can't be built, the master key itself is unusable:
- *      delete its keystore alias so a new one is generated, wipe the file again,
- *      and rebuild. If that final rebuild throws, the exception propagates and the
- *      existing `runCatching {}` at every call site degrades to null.
- *
- * This NEVER touches the primary self-custody identity: that lives in
- * expo-secure-store under a DISTINCT prefs file ("SecureStore") and DISTINCT
- * keystore aliases ("key_v1"/extended), not the androidx master key wiped here.
- * The shared slot is a derived copy that Commons re-populates from the primary on
- * the next boot (`migrateToSharedIdentity`), so wiping it is non-destructive.
+ * One consequence worth restating here: an open can legitimately return an EMPTY
+ * file (the self-heal wipes a keyset it cannot read). That is safe for this slot
+ * specifically because it is a DERIVED copy — Commons re-populates it from the
+ * primary self-custody identity on the next boot (`migrateToSharedIdentity`), and
+ * that primary lives in expo-secure-store under a different file and different
+ * keystore aliases, untouched by any recovery here.
  */
 internal object OxyIdentityStore {
   const val PREFS_NAME = "oxy_shared_identity"
   const val KEY_PRIVATE = "priv"
   const val KEY_PUBLIC = "pub"
 
-  private const val TAG = "OxyIdentityStore"
-  private const val ANDROID_KEYSTORE = "AndroidKeyStore"
-
-  @Volatile private var cachedPrefs: SharedPreferences? = null
-
-  private fun prefs(context: Context): SharedPreferences {
-    cachedPrefs?.let { return it }
-    return synchronized(this) {
-      cachedPrefs ?: openOrHealPrefs(context.applicationContext).also { cachedPrefs = it }
-    }
-  }
-
   /**
-   * Opens the EncryptedSharedPreferences, self-healing a corrupted/unreadable
-   * keyset once (see the "Keyset self-heal" note above). Both exception types the
-   * androidx `create()` declares — `GeneralSecurityException` (AEAD/GCM tag
-   * mismatch) and `IOException` (unparseable keyset) — route into recovery.
+   * [RecoveryPolicy.RegenerateSharedMasterKey] preserves this store's original
+   * behaviour: when its keyset cannot be rebuilt, the master key is regenerated.
+   * That is defensible HERE and nowhere else so far, because this slot going dead
+   * already breaks cross-app "Sign in with Oxy" for every Oxy app on the device —
+   * the collateral is not worse than the failure it recovers from — and because
+   * this slot is itself re-populated from the primary identity on the next boot.
    */
-  private fun openOrHealPrefs(appContext: Context): SharedPreferences {
-    return try {
-      buildEncryptedPrefs(appContext)
-    } catch (corrupt: GeneralSecurityException) {
-      healCorruptedKeyset(appContext, corrupt)
-    } catch (corrupt: IOException) {
-      healCorruptedKeyset(appContext, corrupt)
-    }
-  }
-
-  /**
-   * Stage 1: wipe ONLY this slot's prefs file (which holds the stale wrapped
-   * keyset) and rebuild against the current master key. Escalates to stage 2 if a
-   * fresh keyset still can't be built.
-   */
-  private fun healCorruptedKeyset(appContext: Context, cause: Exception): SharedPreferences {
-    Log.w(
-      TAG,
-      "shared-identity keyset unreadable (rotated master key); cleared and regenerated: ${cause.message}",
-      cause
-    )
-    appContext.deleteSharedPreferences(PREFS_NAME)
-    return try {
-      buildEncryptedPrefs(appContext)
-    } catch (stillCorrupt: GeneralSecurityException) {
-      regenerateMasterKeyAndRebuild(appContext, stillCorrupt)
-    } catch (stillCorrupt: IOException) {
-      regenerateMasterKeyAndRebuild(appContext, stillCorrupt)
-    }
-  }
-
-  /**
-   * Stage 2 (belt-and-suspenders): the androidx master key itself is unusable, so
-   * delete its keystore alias to force a fresh one, wipe the now-stale file again,
-   * and rebuild. The alias is used ONLY by androidx EncryptedSharedPreferences —
-   * expo-secure-store (the primary identity) uses its own distinct aliases — so
-   * this never touches the self-custody key. A throw here propagates to the
-   * call-site `runCatching {}`, which degrades to null.
-   */
-  private fun regenerateMasterKeyAndRebuild(appContext: Context, cause: Exception): SharedPreferences {
-    Log.w(
-      TAG,
-      "shared-identity keyset still unreadable after prefs reset; deleting master key " +
-        "'${MasterKey.DEFAULT_MASTER_KEY_ALIAS}' and regenerating: ${cause.message}",
-      cause
-    )
-    KeyStore.getInstance(ANDROID_KEYSTORE).apply {
-      load(null)
-      if (containsAlias(MasterKey.DEFAULT_MASTER_KEY_ALIAS)) {
-        deleteEntry(MasterKey.DEFAULT_MASTER_KEY_ALIAS)
-      }
-    }
-    appContext.deleteSharedPreferences(PREFS_NAME)
-    return buildEncryptedPrefs(appContext)
-  }
-
-  private fun buildEncryptedPrefs(appContext: Context): SharedPreferences {
-    val masterKey = MasterKey.Builder(appContext)
-      .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
-      .build()
-    return EncryptedSharedPreferences.create(
-      appContext,
-      PREFS_NAME,
-      masterKey,
-      EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
-      EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
-    )
-  }
+  private fun prefs(context: Context): SharedPreferences =
+    OxyEncryptedPrefs.open(context, PREFS_NAME, RecoveryPolicy.RegenerateSharedMasterKey)
 
   /** Read the stored keypair as (privateKey, publicKey), or null when absent/blank. */
   fun read(context: Context): Pair<String, String>? {

package/android/src/main/java/so/oxy/session/OxyBackgroundSession.kt

@@ -0,0 +1,184 @@
+package so.oxy.session
+
+import android.content.Context
+import android.util.Log
+import java.util.concurrent.TimeUnit
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+
+/**
+ * How native background code — a WorkManager worker refreshing a home-screen
+ * widget, a sync job — authenticates when there is no JS runtime in the process.
+ *
+ * ## What this is
+ *
+ * The app, while running, provisions a background credential and hands it to this
+ * store (see `OxyBackgroundSessionModule`). Background code then exchanges it for
+ * a short access token whenever it needs one. That is the whole surface:
+ *
+ * ```kotlin
+ * when (val token = OxyBackgroundSession.accessToken(applicationContext)) {
+ *   is OxyBackgroundToken.Available -> fetch(token.baseUrl, token.accessToken, token.accountId)
+ *   is OxyBackgroundToken.SignedOut -> renderSignedOut()          // final; Result.success()
+ *   is OxyBackgroundToken.Transient -> Result.retry()             // keep last content
+ *   is OxyBackgroundToken.Malformed -> Result.failure()           // wire contract moved
+ * }
+ * ```
+ *
+ * ## What it deliberately cannot do
+ *
+ * It cannot create a session. Only the app, holding a bearer, can provision a
+ * credential — so background code can EXTEND a session the user established
+ * in-app but can never bootstrap one from nothing.
+ *
+ * It cannot damage the app's session. It never reads or writes the device
+ * credential, and the credential it does use is not rotated by anyone, so a
+ * worker killed mid-mint loses nothing. That property is the reason this exists
+ * as a separate credential instead of background code simply reading the device
+ * secret.
+ *
+ * It does not narrow authority. The minted token is a FULL user access token:
+ * access tokens carry no scopes today, so this yields exactly what the device
+ * credential yields while it is valid. The gains are isolation, a bounded
+ * lifetime and independent revocability — NOT "read-only". Do not read
+ * "background" as a permission boundary.
+ *
+ * ## Account correctness
+ *
+ * Every mint is re-authorized server-side against the live device session, so a
+ * stale record cannot resurrect a signed-out account. [OxyBackgroundToken.Available.accountId]
+ * is the server's answer, not a local guess — key cached content by it and drop
+ * content belonging to another account.
+ */
+object OxyBackgroundSession {
+  private const val TAG = "OxyBackgroundSession"
+
+  /**
+   * Refuse to reuse a cached token this close to expiry, so it cannot die midway
+   * through the request it was fetched for.
+   */
+  private val TOKEN_REUSE_FLOOR_MS = TimeUnit.SECONDS.toMillis(60)
+
+  /**
+   * Serializes mints within a process so several widgets refreshing together make
+   * ONE network call and share its result, instead of one call each — which would
+   * also burn the server's per-device rate limit. Waiters re-check the cache after
+   * acquiring, so only the first actually mints.
+   */
+  private val mintMutex = Mutex()
+
+  /**
+   * A usable access token for the account this device's app last provisioned, or
+   * the reason there is not one. Never throws.
+   */
+  suspend fun accessToken(context: Context): OxyBackgroundToken {
+    val appContext = context.applicationContext
+    val credential = readCredential(appContext) ?: return OxyBackgroundToken.SignedOut
+
+    cachedToken(appContext, credential)?.let { return it }
+
+    return mintMutex.withLock {
+      // Another caller may have minted while this one waited for the lock.
+      cachedToken(appContext, credential)?.let { return@withLock it }
+      mintLocked(appContext, credential)
+    }
+  }
+
+  /**
+   * The account a background caller is currently provisioned for, without a
+   * network call — for keying cached content, or deciding whether cached content
+   * belongs to the current account at all. Null when there is no credential.
+   */
+  fun activeAccountId(context: Context): String? =
+    runCatching { OxyBackgroundSessionStore.readAccountId(context.applicationContext) }
+      .getOrNull()
+
+  /**
+   * Whether a credential is present, so a widget can draw its signed-out state
+   * without attempting a fetch. A `true` here is not a promise that the next mint
+   * succeeds — the server is still the authority.
+   */
+  fun hasCredential(context: Context): Boolean = activeAccountId(context) != null
+
+  /**
+   * Read the credential, degrading to null on a storage failure.
+   *
+   * The keystore can be transiently unavailable (direct-boot, a device being
+   * upgraded), and [so.oxy.storage.OxyEncryptedPrefs] can legitimately hand back
+   * an emptied file after healing an unreadable keyset. Both mean "no credential
+   * right now" rather than a crash in a background worker.
+   */
+  private fun readCredential(appContext: Context): OxyBackgroundSessionStore.Credential? =
+    runCatching { OxyBackgroundSessionStore.readCredential(appContext) }
+      .onFailure { Log.w(TAG, "background credential store unreadable", it) }
+      .getOrNull()
+
+  private fun cachedToken(
+    appContext: Context,
+    credential: OxyBackgroundSessionStore.Credential,
+  ): OxyBackgroundToken.Available? {
+    val cached = runCatching {
+      OxyBackgroundSessionStore.readToken(appContext, credential.accountId, TOKEN_REUSE_FLOOR_MS)
+    }.getOrNull() ?: return null
+    return OxyBackgroundToken.Available(
+      accessToken = cached.accessToken,
+      expiresAt = cached.expiresAt,
+      accountId = cached.accountId,
+      baseUrl = credential.baseUrl,
+    )
+  }
+
+  /**
+   * Mint and map the outcome. Called with [mintMutex] held.
+   *
+   * Only [OxyBackgroundSessionApi.MintOutcome.Revoked] — an explicit server
+   * verdict — clears the record. Transient and malformed outcomes KEEP it, so a
+   * deploy window or a contract change can never sign a user out of their
+   * widgets.
+   */
+  private suspend fun mintLocked(
+    appContext: Context,
+    credential: OxyBackgroundSessionStore.Credential,
+  ): OxyBackgroundToken =
+    when (val outcome = OxyBackgroundSessionApi.mint(credential)) {
+      is OxyBackgroundSessionApi.MintOutcome.Minted -> {
+        runCatching {
+          OxyBackgroundSessionStore.writeToken(
+            appContext,
+            OxyBackgroundSessionStore.CachedToken(
+              accessToken = outcome.accessToken,
+              expiresAt = outcome.expiresAt,
+              accountId = outcome.accountId,
+            ),
+          )
+        }.onFailure {
+          // Caching is an optimization; a failure to store costs one extra mint
+          // next time and must not fail the token the caller is waiting for.
+          Log.w(TAG, "could not cache the minted background token", it)
+        }
+        OxyBackgroundToken.Available(
+          accessToken = outcome.accessToken,
+          expiresAt = outcome.expiresAt,
+          accountId = outcome.accountId,
+          baseUrl = credential.baseUrl,
+        )
+      }
+
+      OxyBackgroundSessionApi.MintOutcome.Revoked -> {
+        Log.i(TAG, "background credential was revoked by the server; clearing it")
+        runCatching { OxyBackgroundSessionStore.clear(appContext) }
+          .onFailure { Log.w(TAG, "could not clear the revoked background credential", it) }
+        OxyBackgroundToken.SignedOut
+      }
+
+      is OxyBackgroundSessionApi.MintOutcome.Transient -> {
+        Log.w(TAG, "background token mint failed transiently; keeping the credential", outcome.cause)
+        OxyBackgroundToken.Transient(outcome.cause)
+      }
+
+      is OxyBackgroundSessionApi.MintOutcome.Malformed -> {
+        Log.e(TAG, "background token response could not be read; keeping the credential", outcome.cause)
+        OxyBackgroundToken.Malformed(outcome.cause)
+      }
+    }
+}

package/android/src/main/java/so/oxy/session/OxyBackgroundSessionApi.kt

@@ -0,0 +1,162 @@
+package so.oxy.session
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.json.JSONException
+import org.json.JSONObject
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import java.text.ParseException
+import java.text.SimpleDateFormat
+import java.util.Locale
+import java.util.TimeZone
+import java.util.concurrent.TimeUnit
+
+/**
+ * The one network call background code makes: `POST /session/device/background-token`.
+ *
+ * Bearer-less and cookie-less — possession of the provisioned secret IS the
+ * proof. Unlike `POST /session/device/token` this NEVER rotates: the presented
+ * secret stays valid until it expires or is revoked, which is what makes it safe
+ * to call from a process the OS may kill at any moment.
+ *
+ * `HttpURLConnection` rather than an HTTP client library, for the same reason
+ * Mention's widget uses it: this is one small POST, and adding an HTTP stack to
+ * every consuming app's release APK would cost more than it saves.
+ */
+internal object OxyBackgroundSessionApi {
+  private val CONNECT_TIMEOUT_MS = TimeUnit.SECONDS.toMillis(10).toInt()
+  private val READ_TIMEOUT_MS = TimeUnit.SECONDS.toMillis(15).toInt()
+
+  /**
+   * The two server verdicts that PROVE the credential is finished, and the only
+   * two that may delete it.
+   *
+   * This mirrors `@oxyhq/core`'s `refresh.ts` rule deliberately, and for the same
+   * hard-won reason: ANY other 401 — a proxy or middleware 401, an ALB answering
+   * for a starting instance, an HTML error page during a deploy — is NOT proof
+   * that a credential is bad. Treating an ambiguous 401 as revocation is what
+   * logged users out ecosystem-wide once already. Here the blast radius is
+   * smaller (a widget going blank rather than a session dying) but the rule is
+   * the same, so the failure mode reads identically to anyone debugging it.
+   *
+   * These strings are wire contract with oxy-api, not log text.
+   */
+  private const val ERROR_CREDENTIAL_INVALID = "background_credential_invalid"
+  private const val ERROR_ACCOUNT_NOT_ON_DEVICE = "account_not_on_device"
+
+  internal sealed interface MintOutcome {
+    data class Minted(val accessToken: String, val expiresAt: Long, val accountId: String) : MintOutcome
+    /** An explicit server verdict: this credential is finished. Delete it. */
+    data object Revoked : MintOutcome
+    data class Transient(val cause: Exception) : MintOutcome
+    data class Malformed(val cause: Exception) : MintOutcome
+  }
+
+  suspend fun mint(credential: OxyBackgroundSessionStore.Credential): MintOutcome =
+    withContext(Dispatchers.IO) {
+      val endpoint = "${credential.baseUrl.trimEnd('/')}/session/device/background-token"
+      val body = JSONObject()
+        .put("deviceId", credential.deviceId)
+        .put("secret", credential.secret)
+        .toString()
+
+      val connection: HttpURLConnection = try {
+        (URL(endpoint).openConnection() as HttpURLConnection).apply {
+          requestMethod = "POST"
+          connectTimeout = CONNECT_TIMEOUT_MS
+          readTimeout = READ_TIMEOUT_MS
+          doOutput = true
+          // No Authorization header and no cookies, by design.
+          setRequestProperty("Content-Type", "application/json")
+          setRequestProperty("Accept", "application/json")
+        }
+      } catch (cause: IOException) {
+        return@withContext MintOutcome.Transient(cause)
+      }
+
+      try {
+        connection.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+        val status = connection.responseCode
+        if (status != HttpURLConnection.HTTP_OK) {
+          return@withContext classifyFailure(status, readErrorBody(connection))
+        }
+        val payload = connection.inputStream.bufferedReader().use { it.readText() }
+        parseMintResponse(payload)
+      } catch (cause: IOException) {
+        // Connect/read failure, DNS, TLS, a dropped socket mid-body.
+        MintOutcome.Transient(cause)
+      } finally {
+        connection.disconnect()
+      }
+    }
+
+  /**
+   * Read the error body, tolerating its absence — `errorStream` is null for some
+   * statuses, and a failure to read the explanation of a failure must not become
+   * a different failure.
+   */
+  private fun readErrorBody(connection: HttpURLConnection): String =
+    try {
+      connection.errorStream?.bufferedReader()?.use { it.readText() } ?: ""
+    } catch (cause: IOException) {
+      ""
+    }
+
+  /**
+   * A non-200 becomes [MintOutcome.Revoked] ONLY on an explicit verdict; every
+   * other status and every unrecognised 401 is [MintOutcome.Transient] so the
+   * credential is kept. Substring matching on the raw body (rather than parsing
+   * it) is deliberate: it is what core does, and it survives the body being an
+   * error page rather than the JSON envelope.
+   */
+  private fun classifyFailure(status: Int, body: String): MintOutcome {
+    if (status == HttpURLConnection.HTTP_UNAUTHORIZED &&
+      (body.contains(ERROR_CREDENTIAL_INVALID) || body.contains(ERROR_ACCOUNT_NOT_ON_DEVICE))
+    ) {
+      return MintOutcome.Revoked
+    }
+    return MintOutcome.Transient(IOException("POST /session/device/background-token responded $status"))
+  }
+
+  private fun parseMintResponse(payload: String): MintOutcome =
+    try {
+      val data = JSONObject(payload).getJSONObject("data")
+      val accessToken = data.getString("accessToken")
+      val accountId = data.getString("accountId")
+      val expiresAt = parseIsoInstant(data.getString("expiresAt"))
+      if (accessToken.isEmpty() || accountId.isEmpty()) {
+        MintOutcome.Malformed(JSONException("background-token response had an empty accessToken or accountId"))
+      } else {
+        MintOutcome.Minted(accessToken, expiresAt, accountId)
+      }
+    } catch (cause: JSONException) {
+      MintOutcome.Malformed(cause)
+    } catch (cause: ParseException) {
+      MintOutcome.Malformed(cause)
+    }
+
+  /**
+   * Parse the server's `expiresAt` into epoch millis.
+   *
+   * The shape is fixed rather than guessed: oxy-api emits it with JavaScript's
+   * `Date.toISOString()`, which is specified to produce exactly
+   * `yyyy-MM-ddTHH:mm:ss.sssZ`. `SimpleDateFormat` (rather than `java.time`)
+   * because `Instant.parse` needs API 26 or core-library desugaring, and this
+   * module must compile for every consuming app's minSdk without imposing a
+   * build-config requirement on them.
+   *
+   * Anything else throws [ParseException], which the caller classifies as
+   * `Malformed` — never a silent fallback to a made-up expiry, which would either
+   * throw away a valid token or keep using a dead one.
+   */
+  private fun parseIsoInstant(value: String): Long {
+    val format = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSXXX", Locale.US).apply {
+      timeZone = TimeZone.getTimeZone("UTC")
+      isLenient = false
+    }
+    val parsed = format.parse(value) ?: throw ParseException("unparseable expiresAt: $value", 0)
+    return parsed.time
+  }
+}

package/android/src/main/java/so/oxy/session/OxyBackgroundSessionModule.kt

@@ -0,0 +1,101 @@
+package so.oxy.session
+
+import android.content.Context
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+
+/**
+ * JS side of the background session credential.
+ *
+ * JS is the only writer of the credential and native background code is the only
+ * consumer, so this bridge is deliberately one-way: put, clear, and a read of the
+ * account id (which JS needs to notice that the stored credential belongs to a
+ * different account than the one now signed in). There is no `get` — JS has no
+ * use for the secret it just wrote, and not exposing it keeps the secret's only
+ * reader native.
+ *
+ * Every function is a no-op-or-null on failure rather than throwing: the app must
+ * work identically whether or not background credentials are available, and a
+ * keystore hiccup must never break sign-in.
+ */
+class OxyBackgroundSessionModule : Module() {
+  private val context: Context
+    get() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+
+  /**
+   * The provisioned credential as it crosses the bridge.
+   *
+   * `expiresAt` is epoch MILLIS, already parsed from the server's ISO-8601 string
+   * on the JS side — JS has a `Date`, so there is no reason to hand native a
+   * string to re-parse.
+   */
+  data class CredentialInput(
+    @Field val baseUrl: String = "",
+    @Field val deviceId: String = "",
+    @Field val secret: String = "",
+    @Field val accountId: String = "",
+    @Field val expiresAt: Double = 0.0,
+  ) : Record
+
+  override fun definition() = ModuleDefinition {
+    Name("OxyBackgroundSession")
+
+    /**
+     * Store (replacing) the credential. Rejects an incomplete or already-expired
+     * one rather than persisting something no mint could ever use.
+     */
+    AsyncFunction("put") { credential: CredentialInput ->
+      val expiresAt = credential.expiresAt.toLong()
+      if (
+        credential.baseUrl.isEmpty() ||
+        credential.deviceId.isEmpty() ||
+        credential.secret.isEmpty() ||
+        credential.accountId.isEmpty() ||
+        expiresAt <= System.currentTimeMillis()
+      ) {
+        return@AsyncFunction false
+      }
+      runCatching {
+        OxyBackgroundSessionStore.writeCredential(
+          context,
+          OxyBackgroundSessionStore.Credential(
+            baseUrl = credential.baseUrl,
+            deviceId = credential.deviceId,
+            secret = credential.secret,
+            accountId = credential.accountId,
+            expiresAt = expiresAt,
+          ),
+        )
+      }.isSuccess
+    }
+
+    /**
+     * Drop the credential and any cached token. Called on sign-out and BEFORE an
+     * account switch, so the window in which background code could serve the
+     * previous account's data is as short as a local write.
+     */
+    AsyncFunction("clear") {
+      runCatching { OxyBackgroundSessionStore.clear(context) }.isSuccess
+    }
+
+    /**
+     * What is currently stored — the account it belongs to and when it expires
+     * (epoch millis) — or null when there is no usable credential.
+     *
+     * This is what lets JS decide whether to provision at all: a credential for
+     * the signed-in account with plenty of life left needs no network call. It
+     * deliberately does NOT return the secret; native is its only reader.
+     */
+    AsyncFunction("peek") {
+      val stored = runCatching { OxyBackgroundSessionStore.readCredential(context) }.getOrNull()
+        ?: return@AsyncFunction null
+      mapOf(
+        "accountId" to stored.accountId,
+        "expiresAt" to stored.expiresAt.toDouble(),
+      )
+    }
+  }
+}