@oxy.so/services 1.0.0

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 `@oxy.so/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,116 @@
+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(),
+      )
+    }
+  }
+}

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

@@ -0,0 +1,179 @@
+package so.oxy.session
+
+import android.content.Context
+import android.content.SharedPreferences
+import so.oxy.storage.OxyEncryptedPrefs
+import so.oxy.storage.RecoveryPolicy
+
+/**
+ * On-device storage for the background session credential and the short access
+ * token minted from it.
+ *
+ * Its own EncryptedSharedPreferences file — it never reads or writes the app's
+ * device credential (`oxy.auth.v1` in expo-secure-store). That separation is the
+ * whole point of the design: `POST /session/device/token` rotates the device
+ * secret on every mint and the presented secret dies 60 seconds later, so
+ * background code that touched it would be a second writer to a value the JS
+ * runtime depends on, and a worker killed between the mint and the local write
+ * would sign the user out of the app. Nothing here can do that.
+ *
+ * WRITERS: JS (via [OxyBackgroundSessionModule], while the app runs) owns the
+ * credential; native (via [OxyBackgroundSession]) owns only the cached token.
+ * Neither ever rotates the credential — the server does not rotate it either.
+ */
+internal object OxyBackgroundSessionStore {
+  /**
+   * Suffix is the hosting app's package name. Oxy apps share the `so.oxy.shared`
+   * Android UID (and therefore one data directory), so a single global prefs name
+   * would let one app that leaves `backgroundSession` off wipe another app's
+   * live credential on launch. Scoping by package keeps each app's widget/sync
+   * store independent.
+   */
+  private const val PREFS_NAME_PREFIX = "oxy_background_session_"
+
+  private fun prefsName(context: Context): String = PREFS_NAME_PREFIX + context.packageName
+
+  private const val KEY_BASE_URL = "baseUrl"
+  private const val KEY_DEVICE_ID = "deviceId"
+  private const val KEY_SECRET = "secret"
+  private const val KEY_ACCOUNT_ID = "accountId"
+  private const val KEY_EXPIRES_AT = "expiresAt"
+
+  private const val KEY_TOKEN = "token"
+  private const val KEY_TOKEN_EXPIRES_AT = "tokenExpiresAt"
+  private const val KEY_TOKEN_ACCOUNT_ID = "tokenAccountId"
+
+  /** The provisioned credential. [expiresAt] is epoch millis. */
+  internal data class Credential(
+    val baseUrl: String,
+    val deviceId: String,
+    val secret: String,
+    val accountId: String,
+    val expiresAt: Long,
+  )
+
+  /** A previously minted access token. [expiresAt] is epoch millis. */
+  internal data class CachedToken(
+    val accessToken: String,
+    val expiresAt: Long,
+    val accountId: String,
+  )
+
+  /**
+   * [RecoveryPolicy.RebuildFileOnly] — this store must NEVER escalate to a
+   * UID-shared master-key reset.
+   *
+   * What it holds is disposable: the app re-provisions the credential on its next
+   * foreground, so "no credential" is a complete recovery that costs the user
+   * nothing (background refreshes render signed out until then). A master-key reset
+   * would wipe every other Oxy store sharing the alias — including the self-custody
+   * identity keypair, which is IRREPLACEABLE. Trading someone else's unrecoverable
+   * data to save data we can simply ask for again is never the right trade, so the
+   * escalation is not merely discouraged here, it is unreachable.
+   */
+  private fun prefs(context: Context): SharedPreferences =
+    OxyEncryptedPrefs.open(context, prefsName(context), RecoveryPolicy.RebuildFileOnly)
+
+  /**
+   * The stored credential, or null when absent, incomplete, or expired.
+   *
+   * An expired credential is DELETED on the way out rather than merely ignored:
+   * it can never become valid again (only JS can provision, and it will write a
+   * fresh one), so leaving it on disk would keep a dead secret at rest for as
+   * long as the app went unopened.
+   */
+  fun readCredential(context: Context): Credential? {
+    val p = prefs(context)
+    val baseUrl = p.getString(KEY_BASE_URL, null)
+    val deviceId = p.getString(KEY_DEVICE_ID, null)
+    val secret = p.getString(KEY_SECRET, null)
+    val accountId = p.getString(KEY_ACCOUNT_ID, null)
+    val expiresAt = p.getLong(KEY_EXPIRES_AT, 0L)
+    if (
+      baseUrl.isNullOrEmpty() ||
+      deviceId.isNullOrEmpty() ||
+      secret.isNullOrEmpty() ||
+      accountId.isNullOrEmpty() ||
+      expiresAt <= 0L
+    ) {
+      return null
+    }
+    if (expiresAt <= System.currentTimeMillis()) {
+      clear(context)
+      return null
+    }
+    return Credential(baseUrl, deviceId, secret, accountId, expiresAt)
+  }
+
+  /**
+   * Replace the credential.
+   *
+   * Clears any cached token in the SAME commit: a token minted for the previous
+   * credential must never survive alongside a new one, or a switch could serve
+   * the previous account's bearer for up to its remaining lifetime.
+   *
+   * `commit()` (synchronous) because the very next thing that reads this may be a
+   * WorkManager worker on another thread.
+   */
+  fun writeCredential(context: Context, credential: Credential) {
+    prefs(context).edit()
+      .putString(KEY_BASE_URL, credential.baseUrl)
+      .putString(KEY_DEVICE_ID, credential.deviceId)
+      .putString(KEY_SECRET, credential.secret)
+      .putString(KEY_ACCOUNT_ID, credential.accountId)
+      .putLong(KEY_EXPIRES_AT, credential.expiresAt)
+      .remove(KEY_TOKEN)
+      .remove(KEY_TOKEN_EXPIRES_AT)
+      .remove(KEY_TOKEN_ACCOUNT_ID)
+      .commit()
+  }
+
+  /** The account the stored credential belongs to, without touching the network. */
+  fun readAccountId(context: Context): String? = readCredential(context)?.accountId
+
+  /** Drop the credential AND any cached token. Safe to call when already empty. */
+  fun clear(context: Context) {
+    prefs(context).edit().clear().commit()
+  }
+
+  /**
+   * A cached token still worth reusing for [accountId], or null.
+   *
+   * Rejects a token minted for a DIFFERENT account (defence in depth — writing a
+   * credential already clears the cache) and one inside [reuseFloorMs] of its
+   * expiry, so a token cannot expire midway through the request it was fetched
+   * for.
+   */
+  fun readToken(context: Context, accountId: String, reuseFloorMs: Long): CachedToken? {
+    val p = prefs(context)
+    val token = p.getString(KEY_TOKEN, null)
+    val tokenAccountId = p.getString(KEY_TOKEN_ACCOUNT_ID, null)
+    val expiresAt = p.getLong(KEY_TOKEN_EXPIRES_AT, 0L)
+    if (token.isNullOrEmpty() || tokenAccountId.isNullOrEmpty() || expiresAt <= 0L) {
+      return null
+    }
+    if (tokenAccountId != accountId) {
+      return null
+    }
+    if (expiresAt - reuseFloorMs <= System.currentTimeMillis()) {
+      return null
+    }
+    return CachedToken(token, expiresAt, tokenAccountId)
+  }
+
+  /**
+   * Cache a freshly minted token so sibling workers in the same refresh cycle
+   * share one mint instead of one each (which would also burn the per-device rate
+   * limit).
+   *
+   * `apply()` rather than `commit()`: unlike the credential this is a pure
+   * optimization, and a lost write only costs one extra mint.
+   */
+  fun writeToken(context: Context, token: CachedToken) {
+    prefs(context).edit()
+      .putString(KEY_TOKEN, token.accessToken)
+      .putLong(KEY_TOKEN_EXPIRES_AT, token.expiresAt)
+      .putString(KEY_TOKEN_ACCOUNT_ID, token.accountId)
+      .apply()
+  }
+}