@oxyhq/services 26.0.0 → 26.0.1

package/src/ui/utils/oauthReturn.ts

@@ -3,7 +3,7 @@ import {
   clearOAuthHandshake,
   consumeOAuthReturnPath,
   logger,
-  canonicalizeOAuthRedirectUri,
+  normalizeOAuthRedirectUri,
   readOAuthHandshake,
 } from '@oxyhq/core';
 import { completeOAuthCode } from '../oauth/completeOAuthCode';
@@ -14,21 +14,12 @@ import { isWebBrowser } from './isWebBrowser';
  * When the RP lands with `?code=` after signing in at auth.oxy.so, exchange the
  * code for a device-first session before cold boot runs.
  *
- * This is the REDIRECT transport's return leg. The SDK never starts a full-page
- * authorize navigation on its own any more (#691 phase 7b), but this lane is
- * still load-bearing: a browser-BLOCKED sign-in popup falls back to a full-page
- * redirect (`startWebOAuthSignIn`), and that redirect comes back here.
- *
- * It owns only what is specific to a full-page round trip — reading the code off
- * the URL, recovering the handshake `sessionStorage` carried across the
- * navigation, and cleaning both up afterwards — and delegates state validation,
- * the PKCE exchange, and the session commit to `completeOAuthCode`, the same
- * function the popup transport runs.
- *
- * It is also the SINGLE cleanup path for an OAuth `error` landing on the URL:
- * any `?error=…` (including an `error=login_required` left over from the
- * now-deleted silent restore) is stripped along with `state` /
- * `error_description`, and the stale PKCE handshake is cleared.
+ * This is the REDIRECT transport's return leg. It owns only what is specific to
+ * a full-page round trip — reading the code off the URL, recovering the
+ * handshake `sessionStorage` carried across the navigation, and cleaning both up
+ * afterwards — and delegates state validation, the PKCE exchange, and the
+ * session commit to `completeOAuthCode`, the same function the popup transport
+ * runs.
  */
 export async function tryCompleteOAuthReturn(opts: {
   oxyServices: OxyServices;
@@ -58,18 +49,13 @@ export async function tryCompleteOAuthReturn(opts: {
     return false;
   }
 
-  const handshake = readOAuthHandshake();
-  const redirectUri = canonicalizeOAuthRedirectUri(
-    handshake?.redirectUri ?? opts.authRedirectUri ?? location.origin,
-  );
-
   const result = await completeOAuthCode({
     oxyServices: opts.oxyServices,
     clientId,
     code,
     returnedState: params.get('state'),
-    handshake,
-    redirectUri,
+    handshake: readOAuthHandshake(),
+    redirectUri: normalizeOAuthRedirectUri(opts.authRedirectUri ?? location.origin),
     commitSession: opts.commitSession,
     // Strip the params before the commit so a stale `?code=` cannot re-enter the
     // exchange loop, and read the return path FIRST — clearOAuthHandshake drops
@@ -134,5 +120,29 @@ function stripOAuthParamsFromUrl(): void {
   url.searchParams.delete('state');
   url.searchParams.delete('error');
   url.searchParams.delete('error_description');
+  url.searchParams.delete('hub_sync');
+  replaceUrlAfterOAuthReturn(`${url.pathname}${url.search}${url.hash}`);
+}
+
+/**
+ * When auth.oxy.so hub-sync redeem fails, the IdP redirects back with
+ * `?hub_sync=failed`. Strip the param and log so cold boot can continue
+ * without leaving a stale query string.
+ */
+export function consumeHubSyncFailure(): boolean {
+  if (!isWebBrowser()) return false;
+  const location = (globalThis as { location?: Location }).location;
+  if (!location) return false;
+
+  const params = new URLSearchParams(location.search);
+  if (params.get('hub_sync') !== 'failed') return false;
+
+  logger.warn('Hub sync failed — IdP device session may be out of sync', {
+    component: 'hubSync',
+  });
+
+  const url = new URL(location.href);
+  url.searchParams.delete('hub_sync');
   replaceUrlAfterOAuthReturn(`${url.pathname}${url.search}${url.hash}`);
+  return true;
 }

package/src/ui/utils/userUtils.ts

@@ -1,12 +1,15 @@
 /**
  * User display name and date formatting utilities.
  *
- * Display-name helpers follow the API contract: prefer `name.displayName` when
- * present, otherwise fall back to the normalized handle via
- * `getNormalizedUserHandle`.
+ * The display-name helpers are thin wrappers around the canonical
+ * `getAccountDisplayName` in `@oxyhq/core`, which handles all the edge cases
+ * (missing username, missing name, fallback to truncated `publicKey`, i18n).
  */
 
-import { getNormalizedUserHandle, type DisplayNameUserShape } from '@oxyhq/core';
+import {
+  getAccountDisplayName as coreGetAccountDisplayName,
+  type DisplayNameUserShape,
+} from '@oxyhq/core';
 
 /**
  * Formats a date string to a readable format (e.g., "Feb 21, 2025")
@@ -28,42 +31,44 @@ export const formatDate = (dateString: string | undefined | null | Date): string
   }
 };
 
-function readDisplayName(user: DisplayNameUserShape | null | undefined): string {
-  const name = user?.name;
-  if (!name || typeof name !== 'object') return '';
-  return typeof name.displayName === 'string' ? name.displayName.trim() : '';
-}
-
 /**
  * Gets a display name from user data.
  *
- * Prefers API `name.displayName`, then the normalized handle.
+ * Prefers full name → composed first+last → username → `Account 0x12345678…`
+ * (derived from publicKey) → translated "Unnamed".
+ *
+ * @param user - User-like object with optional name/username/publicKey
+ * @param locale - Optional locale for the final fallback label
  */
 export const getDisplayName = (
   user: DisplayNameUserShape | null | undefined,
-): string => {
-  const displayName = readDisplayName(user);
-  if (displayName) return displayName;
-  return getNormalizedUserHandle(user) ?? '';
-};
+  locale?: string,
+): string => coreGetAccountDisplayName(user, locale);
 
 /**
- * Gets a short display name (first token) for compact UI.
+ * Gets a short display name (first name or username).
+ *
+ * Used for compact UI (e.g. greetings). Falls back to the full display name
+ * helper, which also handles publicKey-only accounts.
  */
 export const getShortDisplayName = (
   user: DisplayNameUserShape | null | undefined,
+  locale?: string,
 ): string => {
-  const displayName = readDisplayName(user);
-  if (displayName) {
-    const firstToken = displayName.split(/\s+/).find(Boolean);
-    if (firstToken) return firstToken;
-  }
+  if (!user) return coreGetAccountDisplayName(user, locale);
 
-  const handle = getNormalizedUserHandle(user);
-  if (handle) {
-    const firstToken = handle.split(/\s+/).find(Boolean);
-    return firstToken ?? handle;
+  const name = user.name;
+  if (name && typeof name === 'object') {
+    const first = typeof name.first === 'string' ? name.first.trim() : '';
+    if (first) return first;
+    const full = typeof name.full === 'string' ? name.full.trim() : '';
+    if (full) return full.split(' ')[0];
+  } else if (typeof name === 'string' && name.trim()) {
+    return name.trim().split(' ')[0];
   }
 
-  return '';
+  if (typeof user.username === 'string' && user.username.trim()) return user.username.trim();
+
+  // Defer to the canonical helper for publicKey/unnamed fallbacks.
+  return coreGetAccountDisplayName(user, locale);
 };

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

@@ -1,184 +0,0 @@
-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

@@ -1,162 +0,0 @@
-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

@@ -1,116 +0,0 @@
-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
-
-/**
- * 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()
-
-  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.
-     *
-     * ## Five scalars, not a `Record`, and that is not a style choice
-     *
-     * This took a `Record` and it did not work on a device: every call was rejected
-     * with `The 1st argument cannot be cast to type CredentialInput (received class
-     * ReadableNativeMap)`, preceded by `Introspectable data is missing for class
-     * CredentialInput. Falling back to reflection-based conversion`. The fallback
-     * then failed too, so nothing was ever stored — the provision succeeded, the
-     * server issued a credential, and the widget stayed signed out forever with only
-     * a warning in the log to show for it.
-     *
-     * The reason is where this package's Kotlin lives: it ships as SOURCE that each
-     * consuming app compiles, so the annotation processing that generates a `Record`'s
-     * introspection metadata does not necessarily run in the consumer's build. The
-     * sibling module in this same library, `OxyIdentityModule`, has always passed
-     * plain scalars (`putShared(privateKey, publicKey)`) and has always worked — so
-     * scalars are the proven shape here and `CredentialInput` was the only `Record`
-     * in the package, i.e. the one untested path.
-     *
-     * Do not "tidy" these five parameters back into a `Record` without first proving
-     * on a real device that a `Record` converts at all in a consumer build. The
-     * failure is silent from JS's side: it surfaces as a widget that never signs in.
-     *
-     * `expiresAt` is epoch MILLIS as a `Double`, 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. `Double` because that is what a JS number crosses
-     * the bridge as; a `Long` parameter would fail to convert for the same family of
-     * reason this comment exists.
-     */
-    AsyncFunction("put") { baseUrl: String,
-      deviceId: String,
-      secret: String,
-      accountId: String,
-      expiresAtMs: Double ->
-      val expiresAt = expiresAtMs.toLong()
-      if (
-        baseUrl.isEmpty() ||
-        deviceId.isEmpty() ||
-        secret.isEmpty() ||
-        accountId.isEmpty() ||
-        expiresAt <= System.currentTimeMillis()
-      ) {
-        return@AsyncFunction false
-      }
-      runCatching {
-        OxyBackgroundSessionStore.writeCredential(
-          context,
-          OxyBackgroundSessionStore.Credential(
-            baseUrl = baseUrl,
-            deviceId = deviceId,
-            secret = secret,
-            accountId = 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(),
-      )
-    }
-  }
-}