@abloatai/ablo 0.7.0 → 0.9.0

package/dist/source/next.js

@@ -0,0 +1,26 @@
+/**
+ * Next.js App Router adapter for Data Source. The core `dataSource()` already
+ * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
+ * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
+ * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ *
+ *   // app/api/ablo/source/route.ts
+ *   import { dataSourceNext } from '@abloatai/ablo/source/next';
+ *   import { prismaDataSource } from '@abloatai/ablo/source';
+ *   import { schema } from '@/ablo/schema';
+ *   import { prisma } from '@/lib/prisma';
+ *
+ *   export const { POST } = dataSourceNext({
+ *     schema,
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     adapter: prismaDataSource(prisma, schema),
+ *   });
+ *
+ * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
+ * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
+ * — not pre-built.
+ */
+import { dataSource } from './index.js';
+export function dataSourceNext(options) {
+    return { POST: dataSource(options) };
+}

package/dist/sync/BootstrapHelper.d.ts

@@ -61,7 +61,13 @@ export interface BootstrapOptions {
      * old clients that don't send a models param).
      */
     instantModels?: string[];
+    /**
+     * Shared SDK credential getter. Preferred over `setAuthToken`; read at
+     * request time so token refreshes apply without recreating BootstrapHelper.
+     */
+    getAuthToken?: AuthTokenGetter;
 }
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
 export declare class BootstrapHelper {
     private options;
@@ -74,6 +80,10 @@ export declare class BootstrapHelper {
      */
     setCacheScope(cacheScope: string): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
+    /**
+     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     */
     setAuthToken(authToken: string | undefined): void;
     /**
      * Create a promise that rejects after a timeout

package/dist/sync/BootstrapHelper.js

@@ -3,7 +3,8 @@
  * Removed problematic caching that was serving stale data
  */
 import { getContext } from '../context.js';
-import { SyncSessionError, AbloConnectionError, translateHttpError } from '../errors.js';
+import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
 export class BootstrapHelper {
@@ -46,6 +47,10 @@ export class BootstrapHelper {
     setSyncGroups(syncGroups) {
         this.options.syncGroups = [...(syncGroups ?? [])];
     }
+    /**
+     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     */
     setAuthToken(authToken) {
         if (!authToken) {
             delete this.options.authToken;
@@ -60,7 +65,9 @@ export class BootstrapHelper {
     createTimeoutPromise(ms, operation) {
         return new Promise((_, reject) => {
             setTimeout(() => {
-                reject(new Error(`Bootstrap ${operation} timed out after ${ms}ms`));
+                reject(new AbloConnectionError(`Bootstrap ${operation} timed out after ${ms}ms`, {
+                    code: 'bootstrap_fetch_timeout',
+                }));
             }, ms);
         });
     }
@@ -138,6 +145,17 @@ export class BootstrapHelper {
                     });
                     throw error;
                 }
+                // Don't retry NON-retryable errors. A 401/403/4xx auth or client error
+                // (api_key_required, jwt_issuer_untrusted, …) will NOT succeed by
+                // repeating the same request with the same credential — retrying just
+                // hammers the server and floods the console with doomed requests. Only
+                // transient failures (5xx, 429, timeouts, network blips, or an
+                // unclassified error with no code) flow through to the retry/backoff.
+                const ablo = toAbloError(error);
+                if (ablo.code && !isRetryableCode(ablo.code)) {
+                    getContext().observability.breadcrumb('Bootstrap non-retryable error — failing fast', 'sync.bootstrap', 'warning', { code: ablo.code, httpStatus: ablo.httpStatus });
+                    throw ablo;
+                }
                 lastError = error;
                 getContext().observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
                     attempt: attempt + 1,
@@ -157,7 +175,11 @@ export class BootstrapHelper {
             });
             return cached;
         }
-        throw lastError || new Error('Failed to fetch bootstrap data');
+        throw lastError
+            ? toAbloError(lastError)
+            : new AbloConnectionError('Failed to fetch bootstrap data', {
+                code: 'bootstrap_fetch_timeout',
+            });
     }
     /**
      * Fetch bootstrap with ETag, returning 304 hints
@@ -180,15 +202,11 @@ export class BootstrapHelper {
         // conditional revalidation (If-None-Match) implement it at their own
         // level where they own the cache-key namespace. The 304 branch below
         // remains defensively in place for when a caller enables revalidation.
-        const headers = { 'Content-Type': 'application/json' };
-        if (this.options.authToken) {
-            headers.Authorization = `Bearer ${this.options.authToken}`;
-        }
+        const headers = withAuthHeaders(this.options.getAuthToken, { 'Content-Type': 'application/json' }, this.options.authToken);
         this.abortController = new AbortController();
         const res = await fetch(url, {
             method: 'GET',
             headers,
-            credentials: 'include',
             signal: this.abortController.signal,
         });
         const etag = res.headers.get('ETag');
@@ -198,17 +216,6 @@ export class BootstrapHelper {
             return { notModified: true, etag };
         }
         if (!res.ok) {
-            // Check for session/auth errors - these should redirect to login
-            if (SyncSessionError.isSessionErrorResponse(res.status)) {
-                let body = '';
-                try {
-                    body = await res.text();
-                }
-                catch {
-                    // Ignore body parsing errors
-                }
-                throw new SyncSessionError(body || `Session expired or invalid: ${res.status}`, res.status);
-            }
             const bodyText = await res.text().catch(() => '');
             let parsed = bodyText;
             if (bodyText) {
@@ -219,7 +226,21 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Translate the canonical envelope FIRST so the server's specific code +
+            // message survive (e.g. `api_key_required`, `jwt_issuer_untrusted`).
+            const translated = translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            // Only a genuine session/JWT EXPIRY — or a bare auth failure carrying no
+            // structured code — should drive the sign-in redirect. A specific auth
+            // code like `api_key_required` is NOT an expired session: re-logging-in
+            // mints the same credential and loops. Surface it as its real typed error
+            // instead of a `session_expired` wrapping the stringified body.
+            if (translated.code === 'session_expired' ||
+                translated.code === 'jwt_expired' ||
+                ((res.status === 401 || res.status === 403) &&
+                    translated.code === undefined)) {
+                throw new SyncSessionError(translated.message, res.status);
+            }
+            throw translated;
         }
         const rawJson = await res.json();
         const data = parseBootstrapResponse(rawJson);
@@ -252,15 +273,11 @@ export class BootstrapHelper {
         try {
             response = await fetch(url, {
                 method: 'GET',
-                headers: {
+                headers: withAuthHeaders(this.options.getAuthToken, {
                     'Content-Type': 'application/json',
                     'Cache-Control': 'no-cache, no-store, must-revalidate',
                     Pragma: 'no-cache',
-                    ...(this.options.authToken
-                        ? { Authorization: `Bearer ${this.options.authToken}` }
-                        : {}),
-                },
-                credentials: 'include',
+                }, this.options.authToken),
                 signal: this.abortController.signal,
                 cache: 'no-store', // Force browser to not cache
             });
@@ -275,17 +292,6 @@ export class BootstrapHelper {
         }
         clearTimeout(timeoutId);
         if (!response.ok) {
-            // Check for session/auth errors - these should redirect to login
-            if (SyncSessionError.isSessionErrorResponse(response.status)) {
-                let body = '';
-                try {
-                    body = await response.text();
-                }
-                catch {
-                    // Ignore body parsing errors
-                }
-                throw new SyncSessionError(body || `Session expired or invalid: ${response.status}`, response.status);
-            }
             const bodyText = await response.text().catch(() => '');
             let parsed = bodyText;
             if (bodyText) {
@@ -296,7 +302,17 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            // Same code-aware handling as the primary bootstrap fetch: preserve the
+            // server's specific code/message; only a genuine expiry (or a bare,
+            // code-less auth failure) drives the sign-in redirect.
+            const translated = translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            if (translated.code === 'session_expired' ||
+                translated.code === 'jwt_expired' ||
+                ((response.status === 401 || response.status === 403) &&
+                    translated.code === undefined)) {
+                throw new SyncSessionError(translated.message, response.status);
+            }
+            throw translated;
         }
         const rawJson = await response.json();
         const data = parseBootstrapResponse(rawJson);
@@ -318,10 +334,9 @@ export class BootstrapHelper {
         const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
         const response = await fetch(url, {
             method: 'GET',
-            headers: {
+            headers: withAuthHeaders(this.options.getAuthToken, {
                 'Content-Type': 'application/json',
-            },
-            credentials: 'include',
+            }, this.options.authToken),
         });
         if (response.status === 404) {
             return null;
@@ -417,7 +432,6 @@ export class BootstrapHelper {
         try {
             const response = await fetch(`${this.options.baseUrl}/health`, {
                 method: 'GET',
-                credentials: 'include',
                 signal: AbortSignal.timeout(5000),
                 cache: 'no-store',
             });

package/dist/sync/ConnectionManager.d.ts

@@ -34,7 +34,8 @@
  *      instead of hard-reloading an already-offline browser.
  */
 import { type ProbeResult } from './NetworkProbe.js';
-export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'session_expired';
+import type { AuthTokenGetter } from '../auth/credentialSource.js';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'refreshing_credential' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
 export type ConnectionEvent = {
     type: 'NETWORK_LOST';
 } | {
@@ -52,8 +53,20 @@ export type ConnectionEvent = {
 } | {
     type: 'PROBE_SUCCESS';
     sessionValid: boolean;
+} | {
+    type: 'PROBE_AUTH_BLOCKED';
+}
+/** The probe saw an expired ephemeral access key (`access_credential_expiry`).
+ *  Recoverable: re-mint a fresh `ek_`/`rk_` and re-probe — never a sign-out. */
+ | {
+    type: 'PROBE_CREDENTIAL_STALE';
 } | {
     type: 'PROBE_FAILED';
+}
+/** A fresh access credential is available (the re-mint succeeded, or one was
+ *  pushed in via `setAuthToken`). Re-probe so a parked connection picks it up. */
+ | {
+    type: 'CREDENTIAL_REFRESHED';
 } | {
     type: 'RECONNECT_SUCCESS';
 } | {
@@ -68,6 +81,20 @@ export type ConnectionEvent = {
 export interface ConnectionCallbacks {
     /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
     onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Re-mint the short-lived access credential (the Stripe-style `ek_`/`rk_`)
+     * and push it into the credential source, then report the outcome. Invoked
+     * on `refreshing_credential` — i.e. when a probe found the access key stale
+     * (`PROBE_CREDENTIAL_STALE`). Mirrors the `getToken` contract:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe & reconnect.
+     *   - `'session_error'` → the LONG-LIVED login is gone (mint returned null →
+     *                          401/403); terminal → sign out.
+     *   - `'network_error'` → couldn't reach the mint endpoint (offline/5xx/throw);
+     *                          transient → back off and retry, never sign out.
+     * Optional: a deployment with no re-mint path (e.g. a static `apiKey`) omits
+     * it, and the FSM falls back to a plain re-probe.
+     */
+    onRefreshCredential?: () => Promise<'refreshed' | 'session_error' | 'network_error'>;
     /** Called when the session is confirmed expired — route to signin. */
     onSessionExpired: () => void;
     /** Called to tear down the WebSocket when entering a dead state. */
@@ -88,6 +115,12 @@ export interface ConnectionManagerOptions {
      * default of `probeNetwork`.
      */
     baseUrl?: string;
+    /**
+     * Current bearer credential for authenticated probes. Read lazily so token
+     * refreshes pushed through `Ablo.setAuthToken()` are used by the next probe
+     * without recreating the manager.
+     */
+    getAuthToken?: AuthTokenGetter;
     /** Override retry ceilings / jitter. Production should leave defaults. */
     backoff?: Partial<typeof DEFAULT_BACKOFF>;
 }
@@ -107,8 +140,12 @@ export declare class ConnectionManager {
     private debounceTimer;
     private watchdogTimer;
     private stuckCycles;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    private credentialRefreshAttempts;
     private disposed;
     private readonly baseUrl?;
+    private readonly getAuthToken?;
     private readonly backoff;
     private handleBrowserOnline;
     private handleBrowserOffline;
@@ -120,6 +157,25 @@ export declare class ConnectionManager {
     private transition;
     private onEnterState;
     private runProbe;
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    private runRefreshCredential;
     private runReconnect;
     private scheduleBackoff;
     private setupBrowserListeners;

package/dist/sync/ConnectionManager.js

@@ -46,6 +46,10 @@ const DEFAULT_BACKOFF = {
 const ONLINE_DEBOUNCE_MS = 500;
 const WATCHDOG_INTERVAL_MS = 30_000;
 const MAX_STUCK_CYCLES_BEFORE_RELOAD = 6;
+/** Cap on consecutive access-key re-mints before giving up to `auth_blocked`.
+ *  Stops a hot loop if the server keeps reporting the key stale even after a
+ *  "successful" re-mint (clock skew, a mint returning an already-rejected key). */
+const MAX_CREDENTIAL_REFRESH_ATTEMPTS = 3;
 // ─── ConnectionManager ────────────────────────────────────────────────────
 export class ConnectionManager {
     // Observable state
@@ -59,14 +63,19 @@ export class ConnectionManager {
     debounceTimer = null;
     watchdogTimer = null;
     stuckCycles = 0;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    credentialRefreshAttempts = 0;
     disposed = false;
     baseUrl;
+    getAuthToken;
     backoff;
     handleBrowserOnline = null;
     handleBrowserOffline = null;
     handleVisibilityChange = null;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl;
+        this.getAuthToken = options.getAuthToken;
         this.backoff = { ...DEFAULT_BACKOFF, ...(options.backoff ?? {}) };
         makeAutoObservable(this, {}, { autoBind: true });
     }
@@ -151,6 +160,7 @@ export class ConnectionManager {
                     case 'MANUAL_RETRY':
                     case 'TAB_VISIBLE':
                     case 'WS_HANDSHAKE_FAILED':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
@@ -162,6 +172,11 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_CREDENTIAL_STALE':
+                        // Access key expired but the login is fine — re-mint, don't sign out.
+                        return 'refreshing_credential';
+                    case 'PROBE_AUTH_BLOCKED':
+                        return 'auth_blocked';
                     case 'PROBE_FAILED':
                         return 'waiting_for_network';
                     case 'NETWORK_LOST':
@@ -175,6 +190,7 @@ export class ConnectionManager {
                     case 'TAB_VISIBLE':
                     case 'MANUAL_RETRY':
                     case 'BACKOFF_ELAPSED':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -185,6 +201,35 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_CREDENTIAL_STALE':
+                        return 'refreshing_credential';
+                    case 'PROBE_AUTH_BLOCKED':
+                        return 'auth_blocked';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
+            case 'refreshing_credential':
+                // Re-minting the short-lived access key (the Stripe-style `ek_`/`rk_`).
+                // The login is presumed valid; this is NOT a sign-out state.
+                switch (event.type) {
+                    case 'CREDENTIAL_REFRESHED':
+                        // Fresh key in hand — re-probe so we reconnect with it.
+                        return 'probing_network';
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        // The re-mint hit a genuine 401/403: the long-lived login itself is
+                        // gone. THIS is the only path from here to sign-out.
+                        return 'session_expired';
+                    case 'RECONNECT_FAILED':
+                        // Couldn't reach the mint endpoint (offline/5xx/throw) — transient.
+                        // Back off and retry; never sign out for a network failure.
+                        return 'backoff';
+                    case 'PROBE_AUTH_BLOCKED':
+                        // Bounded-attempt fallback: the key keeps coming back stale even
+                        // after re-mint (see runRefreshCredential's attempt guard). Stop
+                        // looping without signing out.
+                        return 'auth_blocked';
                     case 'NETWORK_LOST':
                         return 'offline';
                     default:
@@ -214,10 +259,32 @@ export class ConnectionManager {
                         return 'probing_network';
                     case 'NETWORK_ONLINE':
                     case 'TAB_VISIBLE':
-                        // Network came back while we were waiting out a backoff
-                        // delay — jump straight to probing instead of waiting the
-                        // full exponential interval. Fixes the "doesn't retrigger
-                        // when internet comes back" bug.
+                    case 'CREDENTIAL_REFRESHED':
+                        // Network came back (or a fresh credential arrived) while we were
+                        // waiting out a backoff delay — jump straight to probing instead of
+                        // waiting the full exponential interval. Fixes the "doesn't
+                        // retrigger when internet comes back" bug.
+                        return 'probing_network';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    case 'WS_SESSION_ERROR':
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        return 'session_expired';
+                    default:
+                        return null;
+                }
+            case 'auth_blocked':
+                // Reachable, but the data-plane rejected the credential (non-retryable,
+                // non-expiry — e.g. api_key_required, jwt_issuer_untrusted). Don't
+                // auto-reconnect and don't sign out. Allow a manual retry or a
+                // tab-focus / network-return / fresh-credential re-probe (e.g. after a
+                // server deploy or an out-of-band re-mint); a network drop parks
+                // offline; a genuine session error still expires.
+                switch (event.type) {
+                    case 'MANUAL_RETRY':
+                    case 'TAB_VISIBLE':
+                    case 'NETWORK_ONLINE':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -238,6 +305,9 @@ export class ConnectionManager {
         switch (state) {
             case 'connected':
                 this.clearBackoffTimer();
+                runInAction(() => {
+                    this.credentialRefreshAttempts = 0;
+                });
                 break;
             case 'offline':
                 this.clearBackoffTimer();
@@ -252,9 +322,22 @@ export class ConnectionManager {
             case 'reconnecting':
                 this.runReconnect();
                 break;
+            case 'refreshing_credential':
+                this.runRefreshCredential();
+                break;
             case 'backoff':
                 this.scheduleBackoff();
                 break;
+            case 'auth_blocked':
+                // Stop — reachable but the credential was rejected (e.g.
+                // api_key_required / jwt_issuer_untrusted from the data plane). Neither
+                // reconnecting nor re-auth fixes it. Drop the socket and wait for a
+                // manual retry / re-probe. Crucially NOT onSessionExpired (no sign-out)
+                // and NOT a reconnect — that's the whole point of this state.
+                this.clearBackoffTimer();
+                this.callbacks?.onDisconnectWebSocket();
+                getContext().observability.breadcrumb('Auth blocked — reachable but credential rejected; not reconnecting or signing out', 'sync.offline', 'error');
+                break;
             case 'session_expired':
                 this.clearBackoffTimer();
                 this.callbacks?.onDisconnectWebSocket();
@@ -266,21 +349,108 @@ export class ConnectionManager {
     // ── Async operations ─────────────────────────────────────────────────
     async runProbe() {
         try {
-            const result = await probeNetwork(this.baseUrl);
+            const result = await probeNetwork({
+                baseUrl: this.baseUrl,
+                getAuthToken: this.getAuthToken,
+            });
             runInAction(() => {
                 this.lastProbeResult = result;
             });
-            if (result.reachable) {
-                this.send({ type: 'PROBE_SUCCESS', sessionValid: result.sessionValid ?? true });
-            }
-            else {
-                this.send({ type: 'PROBE_FAILED' });
+            // One probe outcome → one event. Exhaustive over ProbeOutcome so a new
+            // outcome can't be silently dropped.
+            switch (result.outcome) {
+                case 'reachable':
+                    this.send({ type: 'PROBE_SUCCESS', sessionValid: true });
+                    break;
+                case 'session_expired':
+                    // Genuine login expiry — terminal. (PROBE_SUCCESS with
+                    // sessionValid:false routes to session_expired in the FSM.)
+                    this.send({ type: 'PROBE_SUCCESS', sessionValid: false });
+                    break;
+                case 'credential_stale':
+                    // Access key expired but the login is fine — re-mint, don't sign out.
+                    this.send({ type: 'PROBE_CREDENTIAL_STALE' });
+                    break;
+                case 'auth_blocked':
+                    this.send({ type: 'PROBE_AUTH_BLOCKED' });
+                    break;
+                case 'unreachable':
+                    this.send({ type: 'PROBE_FAILED' });
+                    break;
+                default: {
+                    const _exhaustive = result.outcome;
+                    void _exhaustive;
+                    this.send({ type: 'PROBE_FAILED' });
+                }
             }
         }
         catch {
             this.send({ type: 'PROBE_FAILED' });
         }
     }
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    async runRefreshCredential() {
+        if (this.credentialRefreshAttempts >= MAX_CREDENTIAL_REFRESH_ATTEMPTS) {
+            getContext().logger.warn('[ConnectionManager] Access key still stale after repeated re-mints — stopping', { attempts: this.credentialRefreshAttempts });
+            runInAction(() => {
+                this.credentialRefreshAttempts = 0;
+            });
+            this.send({ type: 'PROBE_AUTH_BLOCKED' });
+            return;
+        }
+        runInAction(() => {
+            this.credentialRefreshAttempts += 1;
+        });
+        const refresher = this.callbacks?.onRefreshCredential;
+        if (!refresher) {
+            // No re-mint path wired — re-probe with whatever the credential source
+            // holds (a static-key deployment refreshes out-of-band, if at all).
+            this.send({ type: 'CREDENTIAL_REFRESHED' });
+            return;
+        }
+        try {
+            const result = await refresher();
+            switch (result) {
+                case 'refreshed':
+                    this.send({ type: 'CREDENTIAL_REFRESHED' });
+                    break;
+                case 'session_error':
+                    this.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
+                    break;
+                case 'network_error':
+                    this.send({ type: 'RECONNECT_FAILED' });
+                    break;
+                default: {
+                    const _exhaustive = result;
+                    void _exhaustive;
+                    this.send({ type: 'RECONNECT_FAILED' });
+                }
+            }
+        }
+        catch (error) {
+            // A thrown refresher is transient by contract (offline / mint endpoint
+            // unreachable) — back off and retry, never sign out.
+            getContext().logger.warn('[ConnectionManager] Credential re-mint threw (transient)', { error });
+            this.send({ type: 'RECONNECT_FAILED' });
+        }
+    }
     async runReconnect() {
         if (!this.callbacks)
             return;
@@ -395,6 +565,7 @@ export class ConnectionManager {
             const isStuck = this.state !== 'connected' &&
                 this.state !== 'session_expired' &&
                 this.state !== 'probing_network' &&
+                this.state !== 'refreshing_credential' &&
                 this.state !== 'reconnecting';
             if (isStuck) {
                 this.stuckCycles++;
@@ -431,7 +602,11 @@ export class ConnectionManager {
     get isConnected() { return this.state === 'connected'; }
     get isOffline() { return this.state === 'offline' || this.state === 'waiting_for_network'; }
     get isReconnecting() {
-        return this.state === 'probing_network' || this.state === 'reconnecting' || this.state === 'backoff';
+        return (this.state === 'probing_network' ||
+            this.state === 'validating_session' ||
+            this.state === 'refreshing_credential' ||
+            this.state === 'reconnecting' ||
+            this.state === 'backoff');
     }
     get isSessionExpired() { return this.state === 'session_expired'; }
     get offlineDuration() {