feat: unify /ai/v1 auth onto NativeAuth + Android session-expiry handling

Two OSS-side changes that unblock a NativeAuth (Quire Cloud) deployment
end-to-end, without the deprecated AI HMAC token mode.

Server — /ai/v1/* delegates to the primary AuthBackend under native auth:
- Add BackendAiAuthenticator, which maps the configured AuthBackend's
  AuthUser to an AiPrincipal (subject="native:<id>", tenant_id="local",
  auth_mode="native"). create_app() builds it when
  auth_backend=native + ai_auth_mode=basic.
- Remove the old crash guard that forbade that combination — it is now the
  supported native-AI path. ai_auth_mode=token is unchanged and remains for
  its X-2 deprecation window. CalibreWeb Basic default is byte-for-byte
  unchanged.
- Extend AiPrincipal.auth_mode with "native"; update README + docstrings.

Android — Bearer session expiry + re-auth signal (NativeAuth has no refresh
endpoint, so the client surfaces re-auth rather than silently refreshing):
- Persist expires_at end-to-end: AccountCredentials.Bearer.expiresAtEpochMs
  (+ isExpiredAt), stored in CalibreCredentialStore, parsed from the login
  response in ConnectServerViewModel.
- CalibreCredentialStore.needsReauth StateFlow, raised by notifyUnauthorized()
  (a 401 on a same-origin Bearer request, via AccountAuthInterceptor's new
  non-mutating onBearerUnauthorized callback) and checkSessionExpiry();
  reset on save/clear; pre-expired sessions start raised on cold launch.
- AppNavGraph routes to the connect screen when the signal flips. The
  interceptor stays a non-retrying Interceptor (no credential mutation from
  the network layer).

Tests: server suite green (added native-seam unit + integration coverage);
Android auth + opds unit tests and assembleDebug green.

Author: vitofico

app/src/main/java/io/theficos/ereader/ui/AppNavGraph.kt

@@ -59,6 +59,19 @@ fun AppNavGraph(container: AppContainer) {
         hasAccount = container.credentialStore.getAccount() != null,
         welcomeCompleted = container.welcomePreferencesStore.isCompleted(),
     )
+    // Re-auth gating for NativeAuth (Bearer) sessions. The store raises this
+    // when the session token expires or a request comes back 401 — there's no
+    // refresh token, so the only recovery is signing in again. We probe expiry
+    // once on entry, then route to the connect screen whenever the signal
+    // flips true mid-session. A successful re-login clears the signal (the
+    // store resets it on save) and the connect screen navigates onward.
+    LaunchedEffect(Unit) { container.credentialStore.checkSessionExpiry() }
+    val needsReauth by container.credentialStore.needsReauth.collectAsState()
+    LaunchedEffect(needsReauth) {
+        if (needsReauth) {
+            nav.navigate("connect-server") { launchSingleTop = true }
+        }
+    }
     NavHost(navController = nav, startDestination = startDestination) {
         composable("welcome") {
             WelcomeScreen(

app/src/main/java/io/theficos/ereader/ui/onboarding/ConnectServerViewModel.kt

@@ -25,6 +25,7 @@ import okhttp3.OkHttpClient
 import okhttp3.Request
 import okhttp3.RequestBody.Companion.toRequestBody
 import java.io.IOException
+import java.time.OffsetDateTime
 import java.util.Base64
 import java.util.concurrent.TimeUnit
 
@@ -112,7 +113,12 @@ class ConnectServerViewModel(
             }
             _state.value = when (result) {
                 is VerificationOutcome.OkBearer -> {
-                    credentialStore.saveBearerAccount(canonicalBaseUrl, email, result.token)
+                    credentialStore.saveBearerAccount(
+                        canonicalBaseUrl,
+                        email,
+                        result.token,
+                        result.expiresAtEpochMs,
+                    )
                     UiState.Completed
                 }
                 is VerificationOutcome.OkBasic -> error("unreachable in bearer flow")
@@ -181,13 +187,13 @@ class ConnectServerViewModel(
                 when (resp.code) {
                     200 -> {
                         val body = resp.body?.string().orEmpty()
-                        val token = parseLoginToken(body)
-                        if (token.isNullOrBlank()) {
+                        val parsed = parseLogin(body)
+                        if (parsed == null || parsed.token.isBlank()) {
                             VerificationOutcome.Failure(
                                 "Server returned 200 but the response didn't include a token.",
                             )
                         } else {
-                            VerificationOutcome.OkBearer(token)
+                            VerificationOutcome.OkBearer(parsed.token, parsed.expiresAtEpochMs)
                         }
                     }
                     401 -> VerificationOutcome.Failure("Email or password rejected by the server.")
@@ -204,9 +210,22 @@ class ConnectServerViewModel(
         }
     }
 
-    private fun parseLoginToken(body: String): String? = runCatching {
+    /** Token plus optional absolute expiry, parsed from a login response. */
+    private data class ParsedLogin(val token: String, val expiresAtEpochMs: Long?)
+
+    /**
+     * Parse `{"token": ..., "expires_at": ...}` from the login response.
+     * `expires_at` is an ISO-8601 instant (e.g. `2026-06-28T12:00:00+00:00`
+     * or `...Z`); an absent or unparseable value yields a null expiry, which
+     * the credential store treats as "expiry unknown" rather than failing the
+     * login. Returns null only when the body isn't a JSON object.
+     */
+    private fun parseLogin(body: String): ParsedLogin? = runCatching {
         val parsed = Json.parseToJsonElement(body) as? JsonObject ?: return null
-        (parsed["token"] as? JsonPrimitive)?.content
+        val token = (parsed["token"] as? JsonPrimitive)?.content ?: return null
+        val expiresAt = (parsed["expires_at"] as? JsonPrimitive)?.content
+            ?.let { raw -> runCatching { OffsetDateTime.parse(raw).toInstant().toEpochMilli() }.getOrNull() }
+        ParsedLogin(token, expiresAt)
     }.getOrNull()
 
     /** UI state. Sealed so the screen can `when`-exhaust render branches. */
@@ -221,7 +240,7 @@ class ConnectServerViewModel(
 
     private sealed class VerificationOutcome {
         object OkBasic : VerificationOutcome()
-        data class OkBearer(val token: String) : VerificationOutcome()
+        data class OkBearer(val token: String, val expiresAtEpochMs: Long?) : VerificationOutcome()
         data class Failure(val message: String) : VerificationOutcome()
     }
 

auth/src/main/java/io/theficos/ereader/auth/AccountCredentials.kt

@@ -53,14 +53,44 @@ sealed class AccountCredentials {
             "AccountCredentials.Basic(baseUrl=$baseUrl, username=$username, password=***, quireServerUrl=$quireServerUrl)"
     }
 
+    /**
+     * NativeAuth (`quire_server` / Quire Cloud) bearer-token credentials.
+     *
+     * [expiresAtEpochMs] is the absolute expiry of the session token, in
+     * Unix epoch milliseconds, as reported by the server's
+     * `POST /auth/v1/login` response (`expires_at`). It is **nullable** to
+     * cover two cases: legacy records persisted before expiry tracking
+     * existed, and login responses whose `expires_at` we could not parse.
+     * `null` means "expiry unknown" — callers must treat that as a
+     * still-usable token (fail-open) rather than as already-expired, since
+     * NativeAuth has no refresh endpoint and a spurious logout would be worse
+     * than letting the next request surface a real 401.
+     *
+     * NativeAuth issues opaque, non-refreshable session tokens, so when this
+     * instant passes the only recovery is a fresh interactive login. See
+     * [isExpiredAt].
+     */
     data class Bearer(
         override val baseUrl: String,
         val email: String,
         val token: String,
+        val expiresAtEpochMs: Long? = null,
     ) : AccountCredentials() {
         override val scheme: AuthScheme = AuthScheme.BEARER
         override val subject: String get() = email.lowercase()
+
+        /**
+         * True when this session's [expiresAtEpochMs] is known and is at or
+         * before [nowEpochMs]. Returns false when expiry is unknown
+         * (fail-open — see the [expiresAtEpochMs] doc).
+         */
+        fun isExpiredAt(nowEpochMs: Long): Boolean {
+            val exp = expiresAtEpochMs ?: return false
+            return nowEpochMs >= exp
+        }
+
         override fun toString(): String =
-            "AccountCredentials.Bearer(baseUrl=$baseUrl, email=$email, token=***)"
+            "AccountCredentials.Bearer(baseUrl=$baseUrl, email=$email, token=***, " +
+                "expiresAtEpochMs=$expiresAtEpochMs)"
     }
 }

auth/src/main/java/io/theficos/ereader/auth/CalibreCredentialStore.kt

@@ -47,13 +47,37 @@ class CalibreCredentialStore(context: Context) {
 
     private val _accountFlow: MutableStateFlow<AccountCredentials?>
     private val _flow: MutableStateFlow<CalibreCredentials?>
+    private val _needsReauth: MutableStateFlow<Boolean>
 
     init {
         val initial = loadAccount()
         _accountFlow = MutableStateFlow(initial)
         _flow = MutableStateFlow(initial.asLegacyBasicOrNull())
+        // A stored Bearer session whose expiry has already passed on cold
+        // launch starts in the re-auth state, so the UI can route the user
+        // straight to sign-in instead of letting the first request 401.
+        _needsReauth = MutableStateFlow(
+            (initial as? AccountCredentials.Bearer)?.isExpiredAt(System.currentTimeMillis()) == true
+        )
     }
 
+    /**
+     * Re-auth signal for the configured Bearer (NativeAuth) account.
+     *
+     * Emits `true` when the current session can no longer authenticate and
+     * the user must sign in again — either because its `expires_at` has
+     * passed ([checkSessionExpiry]) or because a request came back `401`
+     * ([notifyUnauthorized]). NativeAuth has no refresh endpoint, so there is
+     * nothing to silently retry; the only recovery is a fresh interactive
+     * login, which the onboarding flow drives.
+     *
+     * This is a read-only *signal*: it never mutates or clears the stored
+     * credential. Saving a new account (a successful re-login) or clearing
+     * the store resets it to `false`. Basic accounts never set it — a 401
+     * there is a wrong-password condition handled by the onboarding verifier.
+     */
+    val needsReauth: StateFlow<Boolean> = _needsReauth.asStateFlow()
+
     /**
      * Scheme-aware account observable. New callers (sync, library, AI,
      * catalog) should prefer this over [flow] so BEARER accounts surface a
@@ -119,8 +143,20 @@ class CalibreCredentialStore(context: Context) {
      * Save a `quire_server` / Quire Cloud bearer-token account. The token is
      * stored as-is; callers must pass the raw token (no leading "Bearer ").
      * Blank values and tokens containing whitespace are rejected.
+     *
+     * [expiresAtEpochMs] is the session expiry from the login response's
+     * `expires_at`, in Unix epoch milliseconds; pass null when unknown (the
+     * session is then treated as non-expiring locally — see
+     * [AccountCredentials.Bearer.expiresAtEpochMs]). A successful save clears
+     * any pending [needsReauth] signal, since persisting a token is exactly
+     * what a re-login does.
      */
-    fun saveBearerAccount(baseUrl: String, email: String, token: String) {
+    fun saveBearerAccount(
+        baseUrl: String,
+        email: String,
+        token: String,
+        expiresAtEpochMs: Long? = null,
+    ) {
         require(baseUrl.isNotBlank()) { "baseUrl must not be blank" }
         require(email.isNotBlank()) { "email must not be blank" }
         require(token.isNotBlank()) { "token must not be blank" }
@@ -131,10 +167,46 @@ class CalibreCredentialStore(context: Context) {
             baseUrl = baseUrl.trim().trimEnd('/'),
             email = email,
             token = token,
+            expiresAtEpochMs = expiresAtEpochMs,
         )
         persistAccount(account)
     }
 
+    /**
+     * Record that an authenticated request to the configured account's origin
+     * came back `401`. Flips [needsReauth] to `true` **only** when the current
+     * account is Bearer (NativeAuth) — there is no token to refresh, so the
+     * user must sign in again. Never mutates or clears the stored credential
+     * (the network layer must not silently swap or drop credentials); it only
+     * raises the signal the UI observes. No-op for Basic accounts and when no
+     * account is configured.
+     */
+    fun notifyUnauthorized() {
+        synchronized(mutationLock) {
+            if (_accountFlow.value is AccountCredentials.Bearer) {
+                _needsReauth.value = true
+            }
+        }
+    }
+
+    /**
+     * Proactively evaluate the configured Bearer session's expiry against
+     * [nowEpochMs] and raise [needsReauth] if it has lapsed. Callers (e.g. the
+     * UI on resume / cold launch) invoke this so an already-expired session
+     * routes to sign-in without first firing a doomed network request.
+     * Returns the resulting [needsReauth] value. No-op effect for non-Bearer
+     * accounts or sessions with unknown expiry.
+     */
+    fun checkSessionExpiry(nowEpochMs: Long = System.currentTimeMillis()): Boolean {
+        synchronized(mutationLock) {
+            val account = _accountFlow.value
+            if (account is AccountCredentials.Bearer && account.isExpiredAt(nowEpochMs)) {
+                _needsReauth.value = true
+            }
+            return _needsReauth.value
+        }
+    }
+
     /** Clear all stored credentials. */
     fun clear() {
         synchronized(mutationLock) {
@@ -144,6 +216,7 @@ class CalibreCredentialStore(context: Context) {
             }
             _accountFlow.value = null
             _flow.value = null
+            _needsReauth.value = false
         }
     }
 
@@ -162,6 +235,7 @@ class CalibreCredentialStore(context: Context) {
                         .putString(KEY_PASS, account.password)
                         .remove(KEY_EMAIL)
                         .remove(KEY_TOKEN)
+                        .remove(KEY_EXPIRES_AT)
                     if (account.quireServerUrl != null) {
                         editor.putString(KEY_QUIRE_SERVER_URL, account.quireServerUrl)
                     } else {
@@ -175,6 +249,11 @@ class CalibreCredentialStore(context: Context) {
                         .remove(KEY_USER)
                         .remove(KEY_PASS)
                         .remove(KEY_QUIRE_SERVER_URL)
+                    if (account.expiresAtEpochMs != null) {
+                        editor.putLong(KEY_EXPIRES_AT, account.expiresAtEpochMs)
+                    } else {
+                        editor.remove(KEY_EXPIRES_AT)
+                    }
                 }
             }
             val committed = editor.commit()
@@ -187,6 +266,9 @@ class CalibreCredentialStore(context: Context) {
             }
             _accountFlow.value = account
             _flow.value = account.asLegacyBasicOrNull()
+            // A fresh save is a (re-)authentication: any pending re-auth
+            // signal is now satisfied.
+            _needsReauth.value = false
         }
     }
 
@@ -227,7 +309,14 @@ class CalibreCredentialStore(context: Context) {
             AuthScheme.BEARER -> {
                 val email = prefs.getString(KEY_EMAIL, null) ?: return null
                 val token = prefs.getString(KEY_TOKEN, null) ?: return null
-                AccountCredentials.Bearer(baseUrl, email, token)
+                // Absent key → unknown expiry (legacy record or unparseable
+                // login response). Stored as a plain Long when known.
+                val expiresAt = if (prefs.contains(KEY_EXPIRES_AT)) {
+                    prefs.getLong(KEY_EXPIRES_AT, 0L)
+                } else {
+                    null
+                }
+                AccountCredentials.Bearer(baseUrl, email, token, expiresAt)
             }
         }
     }
@@ -245,6 +334,7 @@ class CalibreCredentialStore(context: Context) {
         const val KEY_PASS = "password"
         const val KEY_EMAIL = "email"
         const val KEY_TOKEN = "token"
+        const val KEY_EXPIRES_AT = "expires_at_epoch_ms"
         const val KEY_QUIRE_SERVER_URL = "quire_server_url"
     }
 }