@rakomi/react-native 0.5.0 → 0.7.0

package/README.md

@@ -211,6 +211,7 @@ have to branch:
 | What happened | Code your UI handles |
 |---|---|
 | The user dismissed the sheet | `PASSKEY_CEREMONY_CANCELLED` |
+| Nobody finished the sheet in time | `PASSKEY_CEREMONY_TIMED_OUT` — retryable; the SDK asked your module to cancel the request |
 | The device cannot do passkeys, or no adapter is wired | `PASSKEY_NOT_SUPPORTED` |
 | The credential is already registered for this user | `PASSKEY_ALREADY_REGISTERED` |
 | The action needs a fresh re-authentication first | `PASSKEY_STEP_UP_REQUIRED` |

package/THIRD-PARTY-NOTICES

@@ -1,6 +1,6 @@
 THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
 
-For the npm package: @rakomi/react-native@0.5.0
+For the npm package: @rakomi/react-native@0.7.0
 
 This package's published bundle (`dist/`) INLINES the third-party components listed below.
 Their copyright and permission notices are reproduced verbatim, as required by their licenses

package/dist/index.cjs

@@ -212,8 +212,8 @@ function createRnHttpClient(options = {}) {
     }
   };
 }
-function err(cls, message) {
-  return { ok: false, error: { class: cls, code: `auth/${cls}`, message } };
+function err(cls, message, cause) {
+  return { ok: false, error: { class: cls, code: `auth/${cls}`, message, ...cause && { cause } } };
 }
 function proverUnavailable(message = "DPoP prover unavailable") {
   return err("dpop_prover_unavailable", message);
@@ -271,32 +271,30 @@ async function refreshWithDpop(input) {
   return mapFailure(result, true);
 }
 function mapFailure(result, attachedProof) {
-  const message = result.error.message ?? "refresh failed";
+  const message = "message" in result.error ? result.error.message : "refresh failed";
   if (attachedProof && (result.dpopProofRejected || result.dpopNonce !== void 0)) {
-    return err("invalid_dpop_proof", message);
+    return err("invalid_dpop_proof", message, result.error);
   }
-  if (result.error.code === "REFRESH_FAILED" && result.error.reason === "network") {
-    return err("network", message);
+  if (result.error.code === "REFRESH_FAILED" && (result.error.reason === "revoked" || result.error.reason === "expired")) {
+    return err("invalid_refresh_token", message, result.error);
   }
-  return err("invalid_refresh_token", message);
+  return err("network", message, result.error);
 }
 
 // src/internal/token-runtime.ts
-var RETRY_DELAYS_MS = [2e3, 8e3, 3e4];
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return void 0;
+  }
+}
 function bytesToBase64Url(bytes) {
   let binary = "";
   for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
   const std = btoa(binary);
   return std.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function deriveDefaultJwksUri(tokenEndpoint) {
-  try {
-    const url = new URL(tokenEndpoint);
-    return `${url.origin}/.well-known/jwks.json`;
-  } catch {
-    return tokenEndpoint.replace(/\/[^/]*$/, "") + "/.well-known/jwks.json";
-  }
-}
 var RAKOMI_PLATFORM_ISSUER_DEFAULT = "https://api.rakomi.com";
 var RAKOMI_PLATFORM_AUDIENCE_DEFAULT = "https://api.rakomi.com";
 function deriveDefaultIssuer(options) {
@@ -335,7 +333,9 @@ var TokenRuntime = class _TokenRuntime {
   storageKeyResolved = null;
   jwksKeyResolved = null;
   jwksCache = null;
-  jwksUri;
+  explicitJwksUri;
+  deploymentBaseUrl;
+  jwksUriResolver;
   jwksTtlMs;
   expectedIssuer;
   expectedAudience;
@@ -347,8 +347,8 @@ var TokenRuntime = class _TokenRuntime {
   refreshAttempts = 0;
   retryTimer = null;
   destroyed = false;
-  offlineStaleCycles = 0;
-  static MAX_OFFLINE_STALE_CYCLES = 3;
+  lastRefreshError = null;
+  restorePending = false;
   submitNonces = /* @__PURE__ */ new Map();
   static NONCE_TTL_MS = 5 * 60 * 1e3;
   static MAX_PENDING_NONCES = 100;
@@ -369,7 +369,18 @@ var TokenRuntime = class _TokenRuntime {
     this.now = options.now ?? Date.now;
     this.setTimeoutFn = options.setTimeout ?? globalThis.setTimeout.bind(globalThis);
     this.clearTimeoutFn = options.clearTimeout ?? globalThis.clearTimeout.bind(globalThis);
-    this.jwksUri = options.jwksUri ?? deriveDefaultJwksUri(options.tokenEndpoint);
+    this.explicitJwksUri = options.jwksUri;
+    this.deploymentBaseUrl = options.baseUrl ?? originOf(options.tokenEndpoint);
+    this.jwksUriResolver = sdkCore.createIssuerJwksUriResolver({
+      fetchDiscoveryDocument: async (url) => {
+        const response = await this.http.fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+        if (response.status === 404) return null;
+        if (!response.ok) {
+          throw new Error(`discovery fetch failed: HTTP ${response.status}`);
+        }
+        return response.json();
+      }
+    });
     this.jwksTtlMs = options.jwksTtlMs ?? 24 * 60 * 60 * 1e3;
     this.expectedIssuer = options.expectedIssuer ?? deriveDefaultIssuer({ baseUrl: options.baseUrl, tokenEndpoint: options.tokenEndpoint });
     this.expectedAudience = options.expectedAudience ?? RAKOMI_PLATFORM_AUDIENCE_DEFAULT;
@@ -468,7 +479,10 @@ var TokenRuntime = class _TokenRuntime {
     }
     const success = await this.performRefresh();
     if (!success || !this.accessToken || this.expiresAtMs === null) {
-      return { ok: false, error: { code: "REFRESH_FAILED", reason: "expired", message: "No valid token available" } };
+      return {
+        ok: false,
+        error: this.lastRefreshError ?? { code: "REFRESH_FAILED", reason: "expired", message: "No valid token available" }
+      };
     }
     const expiresIn = Math.max(0, Math.floor((this.expiresAtMs - this.now()) / 1e3));
     return { ok: true, token: this.accessToken, tokenType: "Bearer", headers: {}, expiresIn };
@@ -492,6 +506,10 @@ var TokenRuntime = class _TokenRuntime {
    */
   async refreshOnForeground() {
     if (this.refreshInFlight) return;
+    if (this.restorePending) {
+      await this.performRefresh({ duringRestore: true });
+      return;
+    }
     if (!this.currentUser) return;
     this.dispatch({ type: "REFRESH_START" });
     await this.performRefresh();
@@ -506,6 +524,8 @@ var TokenRuntime = class _TokenRuntime {
     this.currentSession = null;
     this.refreshInFlight = null;
     this.refreshAttempts = 0;
+    this.lastRefreshError = null;
+    this.restorePending = false;
     if (this.retryTimer) {
       this.clearTimeoutFn(this.retryTimer);
       this.retryTimer = null;
@@ -526,18 +546,20 @@ var TokenRuntime = class _TokenRuntime {
   *
   * uses `jose.createLocalJWKSet` so verification is purely local once
   * the JWKS document has been fetched and cached. The cache is preloaded from `KeyValueStore`
-  * on cold-start (slot `jwks_cache`) and refreshed on TTL miss; on persistent network failure
+  * on cold-start (slot `jwks_cache`) and refreshed on TTL miss, or once when the token's `kid` is not in
+  * the cached set (a rotated key; rate-limited by a cooldown); on persistent network failure
   * the stale-while-error fallback keeps verification working until the cached doc itself expires.
   */
   async verifyAccessToken(token) {
     try {
       const cache = await this.getOrCreateJwksCache();
-      const keySet = await cache.getKeySet();
-      const result = await jose.jwtVerify(token, keySet, {
-        issuer: this.expectedIssuer,
-        audience: this.expectedAudience,
-        algorithms: ["RS256"]
-      });
+      const result = await cache.withKeyRotationRetry(
+        (keySet) => jose.jwtVerify(token, keySet, {
+          issuer: this.expectedIssuer,
+          audience: this.expectedAudience,
+          algorithms: [...sdkCore.ALLOWED_SIGNING_ALGORITHMS]
+        })
+      );
       return { ok: true, payload: result.payload };
     } catch (err2) {
       return { ok: false, reason: err2 instanceof Error ? err2.message : "verify failed" };
@@ -565,7 +587,7 @@ var TokenRuntime = class _TokenRuntime {
    * simply a dev pointed at a different host between builds), a slot keyed by tenant alone would
    * silently reuse a PREVIOUS host's persisted document as this instance's "fresh" cache on cold
    * start — cross-host reuse this offline-verification path must never do. The host segment is not
-   * secret (it is the caller's own `jwksUri` configuration), so a plain suffix is enough; this only
+   * secret (it is the caller's own `jwksUri` or expected-issuer configuration), so a plain suffix is enough; this only
    * needs to be a stable, DIFFERENT key per host, not a cryptographically-opaque one.
    */
   async resolveJwksKey() {
@@ -577,11 +599,25 @@ var TokenRuntime = class _TokenRuntime {
   }
   jwksHost() {
     try {
-      return new URL(this.jwksUri).hostname;
+      if (this.explicitJwksUri !== void 0) return new URL(this.explicitJwksUri).hostname;
+      const issuer = this.expectedIssuer === void 0 ? "" : encodeURIComponent(this.expectedIssuer);
+      const origin = this.deploymentBaseUrl === void 0 ? "" : new URL(this.deploymentBaseUrl).hostname;
+      return `${origin}.i.${issuer}`;
     } catch {
       return null;
     }
   }
+  /** The JWKS document URL: the explicit override, or the expected issuer's discovered `jwks_uri`. */
+  async currentJwksUri() {
+    if (this.explicitJwksUri !== void 0) return this.explicitJwksUri;
+    if (this.expectedIssuer === void 0) {
+      throw new Error("no expected issuer to discover signing keys from");
+    }
+    return this.jwksUriResolver.resolve(
+      this.expectedIssuer,
+      sdkCore.discoveryOriginFor(this.expectedIssuer, this.deploymentBaseUrl)
+    );
+  }
   async getOrCreateJwksCache() {
     if (this.jwksCache) return this.jwksCache;
     const key = await this.resolveJwksKey();
@@ -599,7 +635,10 @@ var TokenRuntime = class _TokenRuntime {
     this.jwksCache = sdkCore.createJwksCache({
       ttlMs: this.jwksTtlMs,
       fetchJwks: async () => {
-        const response = await this.http.fetch(this.jwksUri, { method: "GET", headers: { Accept: "application/json" } });
+        const response = await this.http.fetch(await this.currentJwksUri(), {
+          method: "GET",
+          headers: { Accept: "application/json" }
+        });
         if (!response.ok) {
           throw new Error(`JWKS fetch failed: HTTP ${response.status}`);
         }
@@ -678,10 +717,7 @@ var TokenRuntime = class _TokenRuntime {
       if (!dResult.ok) {
         return this.handleDpopRefreshFailure(dResult.error, opts.duringRestore ?? false);
       }
-      this.emitEvent?.({ type: "refresh_succeeded" });
-      this.refreshAttempts = 0;
-      this.offlineStaleCycles = 0;
-      await this.setTokens(dResult.tokens, opts.duringRestore ? "restore" : "refresh");
+      await this.completeRefresh(dResult.tokens, opts.duringRestore ?? false);
       return true;
     }
     const result = await sdkCore.refreshAccessToken({
@@ -698,12 +734,26 @@ var TokenRuntime = class _TokenRuntime {
       }
       return this.scheduleRetry(result.error, opts.duringRestore ?? false);
     }
-    this.emitEvent?.({ type: "refresh_succeeded" });
-    this.refreshAttempts = 0;
-    this.offlineStaleCycles = 0;
-    await this.setTokens(result.tokens, opts.duringRestore ? "restore" : "refresh");
+    await this.completeRefresh(result.tokens, opts.duringRestore ?? false);
     return true;
   }
+  /**
+   * Commit a successful refresh. A restore that only succeeded on a later retry (the first
+   * attempt at cold start hit a transient failure and `restore()` already returned) is completed
+   * here: the tokens are applied as a restore and RESTORE_SUCCESS loads the user, instead of a
+   * REFRESH_SUCCESS that would mark the machine authenticated with no user.
+   */
+  async completeRefresh(tokens, duringRestore) {
+    const resumedRestore = this.restorePending;
+    this.restorePending = false;
+    this.refreshAttempts = 0;
+    this.lastRefreshError = null;
+    this.emitEvent?.({ type: "refresh_succeeded" });
+    await this.setTokens(tokens, duringRestore || resumedRestore ? "restore" : "refresh");
+    if (resumedRestore && this.currentUser && this.currentSession) {
+      this.dispatch({ type: "RESTORE_SUCCESS", user: this.currentUser, session: this.currentSession });
+    }
+  }
   isAuthError(error) {
     return error.code === "REFRESH_FAILED" && (error.reason === "expired" || error.reason === "revoked");
   }
@@ -716,7 +766,7 @@ var TokenRuntime = class _TokenRuntime {
   async handleDpopRefreshFailure(error, duringRestore) {
     this.emitEvent?.({ type: "dpop_refresh_failed", metadata: { code: error.code } });
     if (error.class === "network") {
-      return this.scheduleRetry({ code: "REFRESH_FAILED", reason: "network", message: error.message }, duringRestore);
+      return this.scheduleRetry(error.cause ?? { code: "REFRESH_FAILED", reason: "network", message: error.message }, duringRestore);
     }
     if (error.class === "dpop_prover_unavailable") {
       this.emitEvent?.({ type: "refresh_failed", metadata: { reason: "dpop_prover_unavailable" } });
@@ -725,36 +775,53 @@ var TokenRuntime = class _TokenRuntime {
     await this.clear({ code: "REFRESH_FAILED", reason: "revoked", message: error.message });
     return false;
   }
+  /**
+   * Back off and retry a transient refresh failure. The session is never cleared here: when the
+   * budget is spent the typed transient error is surfaced (state `offline_stale` when signed in)
+   * and the stored refresh token waits for the next foreground / reconnect / `getToken()`.
+   */
   scheduleRetry(error, duringRestore) {
-    if (this.refreshAttempts >= RETRY_DELAYS_MS.length) {
-      if (!duringRestore && this.accessToken && this.expiresAtMs !== null && this.now() < this.expiresAtMs) {
-        this.refreshAttempts = 0;
-        this.offlineStaleCycles += 1;
-        if (this.offlineStaleCycles >= _TokenRuntime.MAX_OFFLINE_STALE_CYCLES) {
-          this.offlineStaleCycles = 0;
-          void this.clear({ code: "REFRESH_FAILED", reason: "revoked", message: "Refresh chronically failing \u2014 session lost" });
-          return false;
-        }
+    const transient = toTransientError(error);
+    this.lastRefreshError = transient;
+    if (duringRestore) this.restorePending = true;
+    const restoring = this.restorePending;
+    const delay = sdkCore.refreshRetryDelayMs(this.refreshAttempts, transient.code === "REFRESH_FAILED" ? transient.retryAfterMs : void 0);
+    if (delay === void 0) {
+      this.refreshAttempts = 0;
+      this.emitEvent?.({
+        type: "refresh_failed",
+        metadata: { reason: "retries_exhausted", ...transient.code === "REFRESH_FAILED" && transient.status !== void 0 && { status: transient.status } }
+      });
+      if (!restoring) {
+        this.dispatch({ type: "REFRESH_NETWORK_ERROR", error: transient });
         this.dispatch({ type: "OFFLINE_STALE" });
-        return false;
       }
-      void this.clear({ code: "REFRESH_FAILED", reason: "network", message: "Refresh exhausted retries" });
       return false;
     }
-    const delay = RETRY_DELAYS_MS[this.refreshAttempts];
     this.refreshAttempts++;
     this.emitEvent?.({ type: "network_retry", metadata: { delayMs: delay, attempt: this.refreshAttempts } });
-    if (!duringRestore) {
-      this.dispatch({ type: "REFRESH_NETWORK_ERROR", error });
+    if (!restoring) {
+      this.dispatch({ type: "REFRESH_NETWORK_ERROR", error: transient });
     }
     if (this.retryTimer) this.clearTimeoutFn(this.retryTimer);
     this.retryTimer = this.setTimeoutFn(() => {
       this.retryTimer = null;
-      void this.performRefresh();
+      void this.performRefresh({ duringRestore: this.restorePending });
     }, delay);
     return false;
   }
 };
+function toTransientError(error) {
+  if (error.code === "REFRESH_FAILED" && error.reason === "network") return error;
+  return {
+    code: "REFRESH_FAILED",
+    reason: "network",
+    message: sdkCore.getErrorMessage(error),
+    ..."status" in error && error.status !== void 0 && { status: error.status },
+    ..."oauthError" in error && typeof error.oauthError === "string" && { oauthError: error.oauthError },
+    ...error.requestId !== void 0 && { requestId: error.requestId }
+  };
+}
 
 // src/native/expo-adapter.ts
 function createDefaultExpoAdapter(options = {}) {

package/dist/index.d.cts

@@ -455,7 +455,13 @@ interface UserProfileProps {
 }
 declare function UserProfile(props: UserProfileProps): ReactNode;
 
-/** RFC 9449 / three-class client-side refresh failure taxonomy (+ network). */
+/**
+ * RFC 9449 / three-class client-side refresh failure taxonomy (+ network).
+ *
+ * `network` is every transient failure — no connection, a 5xx, 429 or 408, an unreadable
+ * response — and also any rejection that is not definitive. The session is kept and retried;
+ * only `invalid_refresh_token` and `invalid_dpop_proof` end it.
+ */
 type DpopRefreshErrorClass = 'dpop_prover_unavailable' | 'invalid_dpop_proof' | 'invalid_refresh_token' | 'network';
 interface DpopRefreshError {
     /** Stable machine token for the failure class. */
@@ -463,6 +469,8 @@ interface DpopRefreshError {
     /** Full `auth/<class>` code string — parity with `@rakomi/node`'s surfacing. */
     code: `auth/${DpopRefreshErrorClass}`;
     message: string;
+    /** The underlying token-endpoint failure (HTTP status, OAuth `error`, `Retry-After`), when there was one. */
+    cause?: AuthError;
 }
 type DpopRefreshResult = {
     ok: true;

package/dist/index.d.ts

@@ -455,7 +455,13 @@ interface UserProfileProps {
 }
 declare function UserProfile(props: UserProfileProps): ReactNode;
 
-/** RFC 9449 / three-class client-side refresh failure taxonomy (+ network). */
+/**
+ * RFC 9449 / three-class client-side refresh failure taxonomy (+ network).
+ *
+ * `network` is every transient failure — no connection, a 5xx, 429 or 408, an unreadable
+ * response — and also any rejection that is not definitive. The session is kept and retried;
+ * only `invalid_refresh_token` and `invalid_dpop_proof` end it.
+ */
 type DpopRefreshErrorClass = 'dpop_prover_unavailable' | 'invalid_dpop_proof' | 'invalid_refresh_token' | 'network';
 interface DpopRefreshError {
     /** Stable machine token for the failure class. */
@@ -463,6 +469,8 @@ interface DpopRefreshError {
     /** Full `auth/<class>` code string — parity with `@rakomi/node`'s surfacing. */
     code: `auth/${DpopRefreshErrorClass}`;
     message: string;
+    /** The underlying token-endpoint failure (HTTP status, OAuth `error`, `Retry-After`), when there was one. */
+    cause?: AuthError;
 }
 type DpopRefreshResult = {
     ok: true;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, useMemo, useReducer, useRef, useEffect, useState, useCallback, useContext } from 'react';
-import { createAuthorizationEndpointCache, EventLog, reduce, INITIAL_SNAPSHOT, createTranslator, isSignedIn, hasPermission, hasRole, extractOrgClaims, parseAuthConfigResponse, generatePkce, issueState, buildAuthorizationUrl, consumeState, exchangeAuthCode, parseOAuthCallbackError, scorePassword, isSafeUrl, passkeyError, decodeUser, assertPasskey, stepUpWithPasskey, registerPasskey, listPasskeys, renamePasskey, deletePasskey, verifyMagicLink, requestMagicLink, verifyEmailOtp, requestEmailOtp, register, verifyTotp, MfaStepUpUnavailableError, extractRequestId, decodeSession, deriveTenantStorageKey, createJwksCache, refreshAccessToken, decodeJwtPayload, PasskeyCeremonyError, resolveExpectedIssuer } from '@rakomi/sdk-core';
+import { createAuthorizationEndpointCache, EventLog, reduce, INITIAL_SNAPSHOT, createTranslator, isSignedIn, hasPermission, hasRole, extractOrgClaims, parseAuthConfigResponse, generatePkce, issueState, buildAuthorizationUrl, consumeState, exchangeAuthCode, parseOAuthCallbackError, scorePassword, isSafeUrl, passkeyError, decodeUser, assertPasskey, stepUpWithPasskey, registerPasskey, listPasskeys, renamePasskey, deletePasskey, verifyMagicLink, requestMagicLink, verifyEmailOtp, requestEmailOtp, register, verifyTotp, MfaStepUpUnavailableError, extractRequestId, createIssuerJwksUriResolver, decodeSession, ALLOWED_SIGNING_ALGORITHMS, deriveTenantStorageKey, discoveryOriginFor, createJwksCache, refreshAccessToken, refreshRetryDelayMs, decodeJwtPayload, PasskeyCeremonyError, resolveExpectedIssuer, getErrorMessage } from '@rakomi/sdk-core';
 export { MfaStepUpRequiredError, MfaStepUpUnavailableError, base64url, createAuthorizationEndpointCache, createTranslator, decodeJwtPayload, decodeSession, decodeUser, deriveAuthorizationEndpointFallback, generatePkce, getErrorMessage, hasPermission, hasRole, isSafeUrl, networkError, parseOAuthCallbackError, parseTokenEndpointError, scorePassword, selectPluralForm } from '@rakomi/sdk-core';
 import { jwtVerify } from 'jose';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
@@ -211,8 +211,8 @@ function createRnHttpClient(options = {}) {
     }
   };
 }
-function err(cls, message) {
-  return { ok: false, error: { class: cls, code: `auth/${cls}`, message } };
+function err(cls, message, cause) {
+  return { ok: false, error: { class: cls, code: `auth/${cls}`, message, ...cause && { cause } } };
 }
 function proverUnavailable(message = "DPoP prover unavailable") {
   return err("dpop_prover_unavailable", message);
@@ -270,32 +270,30 @@ async function refreshWithDpop(input) {
   return mapFailure(result, true);
 }
 function mapFailure(result, attachedProof) {
-  const message = result.error.message ?? "refresh failed";
+  const message = "message" in result.error ? result.error.message : "refresh failed";
   if (attachedProof && (result.dpopProofRejected || result.dpopNonce !== void 0)) {
-    return err("invalid_dpop_proof", message);
+    return err("invalid_dpop_proof", message, result.error);
   }
-  if (result.error.code === "REFRESH_FAILED" && result.error.reason === "network") {
-    return err("network", message);
+  if (result.error.code === "REFRESH_FAILED" && (result.error.reason === "revoked" || result.error.reason === "expired")) {
+    return err("invalid_refresh_token", message, result.error);
   }
-  return err("invalid_refresh_token", message);
+  return err("network", message, result.error);
 }
 
 // src/internal/token-runtime.ts
-var RETRY_DELAYS_MS = [2e3, 8e3, 3e4];
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return void 0;
+  }
+}
 function bytesToBase64Url(bytes) {
   let binary = "";
   for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
   const std = btoa(binary);
   return std.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function deriveDefaultJwksUri(tokenEndpoint) {
-  try {
-    const url = new URL(tokenEndpoint);
-    return `${url.origin}/.well-known/jwks.json`;
-  } catch {
-    return tokenEndpoint.replace(/\/[^/]*$/, "") + "/.well-known/jwks.json";
-  }
-}
 var RAKOMI_PLATFORM_ISSUER_DEFAULT = "https://api.rakomi.com";
 var RAKOMI_PLATFORM_AUDIENCE_DEFAULT = "https://api.rakomi.com";
 function deriveDefaultIssuer(options) {
@@ -334,7 +332,9 @@ var TokenRuntime = class _TokenRuntime {
   storageKeyResolved = null;
   jwksKeyResolved = null;
   jwksCache = null;
-  jwksUri;
+  explicitJwksUri;
+  deploymentBaseUrl;
+  jwksUriResolver;
   jwksTtlMs;
   expectedIssuer;
   expectedAudience;
@@ -346,8 +346,8 @@ var TokenRuntime = class _TokenRuntime {
   refreshAttempts = 0;
   retryTimer = null;
   destroyed = false;
-  offlineStaleCycles = 0;
-  static MAX_OFFLINE_STALE_CYCLES = 3;
+  lastRefreshError = null;
+  restorePending = false;
   submitNonces = /* @__PURE__ */ new Map();
   static NONCE_TTL_MS = 5 * 60 * 1e3;
   static MAX_PENDING_NONCES = 100;
@@ -368,7 +368,18 @@ var TokenRuntime = class _TokenRuntime {
     this.now = options.now ?? Date.now;
     this.setTimeoutFn = options.setTimeout ?? globalThis.setTimeout.bind(globalThis);
     this.clearTimeoutFn = options.clearTimeout ?? globalThis.clearTimeout.bind(globalThis);
-    this.jwksUri = options.jwksUri ?? deriveDefaultJwksUri(options.tokenEndpoint);
+    this.explicitJwksUri = options.jwksUri;
+    this.deploymentBaseUrl = options.baseUrl ?? originOf(options.tokenEndpoint);
+    this.jwksUriResolver = createIssuerJwksUriResolver({
+      fetchDiscoveryDocument: async (url) => {
+        const response = await this.http.fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+        if (response.status === 404) return null;
+        if (!response.ok) {
+          throw new Error(`discovery fetch failed: HTTP ${response.status}`);
+        }
+        return response.json();
+      }
+    });
     this.jwksTtlMs = options.jwksTtlMs ?? 24 * 60 * 60 * 1e3;
     this.expectedIssuer = options.expectedIssuer ?? deriveDefaultIssuer({ baseUrl: options.baseUrl, tokenEndpoint: options.tokenEndpoint });
     this.expectedAudience = options.expectedAudience ?? RAKOMI_PLATFORM_AUDIENCE_DEFAULT;
@@ -467,7 +478,10 @@ var TokenRuntime = class _TokenRuntime {
     }
     const success = await this.performRefresh();
     if (!success || !this.accessToken || this.expiresAtMs === null) {
-      return { ok: false, error: { code: "REFRESH_FAILED", reason: "expired", message: "No valid token available" } };
+      return {
+        ok: false,
+        error: this.lastRefreshError ?? { code: "REFRESH_FAILED", reason: "expired", message: "No valid token available" }
+      };
     }
     const expiresIn = Math.max(0, Math.floor((this.expiresAtMs - this.now()) / 1e3));
     return { ok: true, token: this.accessToken, tokenType: "Bearer", headers: {}, expiresIn };
@@ -491,6 +505,10 @@ var TokenRuntime = class _TokenRuntime {
    */
   async refreshOnForeground() {
     if (this.refreshInFlight) return;
+    if (this.restorePending) {
+      await this.performRefresh({ duringRestore: true });
+      return;
+    }
     if (!this.currentUser) return;
     this.dispatch({ type: "REFRESH_START" });
     await this.performRefresh();
@@ -505,6 +523,8 @@ var TokenRuntime = class _TokenRuntime {
     this.currentSession = null;
     this.refreshInFlight = null;
     this.refreshAttempts = 0;
+    this.lastRefreshError = null;
+    this.restorePending = false;
     if (this.retryTimer) {
       this.clearTimeoutFn(this.retryTimer);
       this.retryTimer = null;
@@ -525,18 +545,20 @@ var TokenRuntime = class _TokenRuntime {
   *
   * uses `jose.createLocalJWKSet` so verification is purely local once
   * the JWKS document has been fetched and cached. The cache is preloaded from `KeyValueStore`
-  * on cold-start (slot `jwks_cache`) and refreshed on TTL miss; on persistent network failure
+  * on cold-start (slot `jwks_cache`) and refreshed on TTL miss, or once when the token's `kid` is not in
+  * the cached set (a rotated key; rate-limited by a cooldown); on persistent network failure
   * the stale-while-error fallback keeps verification working until the cached doc itself expires.
   */
   async verifyAccessToken(token) {
     try {
       const cache = await this.getOrCreateJwksCache();
-      const keySet = await cache.getKeySet();
-      const result = await jwtVerify(token, keySet, {
-        issuer: this.expectedIssuer,
-        audience: this.expectedAudience,
-        algorithms: ["RS256"]
-      });
+      const result = await cache.withKeyRotationRetry(
+        (keySet) => jwtVerify(token, keySet, {
+          issuer: this.expectedIssuer,
+          audience: this.expectedAudience,
+          algorithms: [...ALLOWED_SIGNING_ALGORITHMS]
+        })
+      );
       return { ok: true, payload: result.payload };
     } catch (err2) {
       return { ok: false, reason: err2 instanceof Error ? err2.message : "verify failed" };
@@ -564,7 +586,7 @@ var TokenRuntime = class _TokenRuntime {
    * simply a dev pointed at a different host between builds), a slot keyed by tenant alone would
    * silently reuse a PREVIOUS host's persisted document as this instance's "fresh" cache on cold
    * start — cross-host reuse this offline-verification path must never do. The host segment is not
-   * secret (it is the caller's own `jwksUri` configuration), so a plain suffix is enough; this only
+   * secret (it is the caller's own `jwksUri` or expected-issuer configuration), so a plain suffix is enough; this only
    * needs to be a stable, DIFFERENT key per host, not a cryptographically-opaque one.
    */
   async resolveJwksKey() {
@@ -576,11 +598,25 @@ var TokenRuntime = class _TokenRuntime {
   }
   jwksHost() {
     try {
-      return new URL(this.jwksUri).hostname;
+      if (this.explicitJwksUri !== void 0) return new URL(this.explicitJwksUri).hostname;
+      const issuer = this.expectedIssuer === void 0 ? "" : encodeURIComponent(this.expectedIssuer);
+      const origin = this.deploymentBaseUrl === void 0 ? "" : new URL(this.deploymentBaseUrl).hostname;
+      return `${origin}.i.${issuer}`;
     } catch {
       return null;
     }
   }
+  /** The JWKS document URL: the explicit override, or the expected issuer's discovered `jwks_uri`. */
+  async currentJwksUri() {
+    if (this.explicitJwksUri !== void 0) return this.explicitJwksUri;
+    if (this.expectedIssuer === void 0) {
+      throw new Error("no expected issuer to discover signing keys from");
+    }
+    return this.jwksUriResolver.resolve(
+      this.expectedIssuer,
+      discoveryOriginFor(this.expectedIssuer, this.deploymentBaseUrl)
+    );
+  }
   async getOrCreateJwksCache() {
     if (this.jwksCache) return this.jwksCache;
     const key = await this.resolveJwksKey();
@@ -598,7 +634,10 @@ var TokenRuntime = class _TokenRuntime {
     this.jwksCache = createJwksCache({
       ttlMs: this.jwksTtlMs,
       fetchJwks: async () => {
-        const response = await this.http.fetch(this.jwksUri, { method: "GET", headers: { Accept: "application/json" } });
+        const response = await this.http.fetch(await this.currentJwksUri(), {
+          method: "GET",
+          headers: { Accept: "application/json" }
+        });
         if (!response.ok) {
           throw new Error(`JWKS fetch failed: HTTP ${response.status}`);
         }
@@ -677,10 +716,7 @@ var TokenRuntime = class _TokenRuntime {
       if (!dResult.ok) {
         return this.handleDpopRefreshFailure(dResult.error, opts.duringRestore ?? false);
       }
-      this.emitEvent?.({ type: "refresh_succeeded" });
-      this.refreshAttempts = 0;
-      this.offlineStaleCycles = 0;
-      await this.setTokens(dResult.tokens, opts.duringRestore ? "restore" : "refresh");
+      await this.completeRefresh(dResult.tokens, opts.duringRestore ?? false);
       return true;
     }
     const result = await refreshAccessToken({
@@ -697,12 +733,26 @@ var TokenRuntime = class _TokenRuntime {
       }
       return this.scheduleRetry(result.error, opts.duringRestore ?? false);
     }
-    this.emitEvent?.({ type: "refresh_succeeded" });
-    this.refreshAttempts = 0;
-    this.offlineStaleCycles = 0;
-    await this.setTokens(result.tokens, opts.duringRestore ? "restore" : "refresh");
+    await this.completeRefresh(result.tokens, opts.duringRestore ?? false);
     return true;
   }
+  /**
+   * Commit a successful refresh. A restore that only succeeded on a later retry (the first
+   * attempt at cold start hit a transient failure and `restore()` already returned) is completed
+   * here: the tokens are applied as a restore and RESTORE_SUCCESS loads the user, instead of a
+   * REFRESH_SUCCESS that would mark the machine authenticated with no user.
+   */
+  async completeRefresh(tokens, duringRestore) {
+    const resumedRestore = this.restorePending;
+    this.restorePending = false;
+    this.refreshAttempts = 0;
+    this.lastRefreshError = null;
+    this.emitEvent?.({ type: "refresh_succeeded" });
+    await this.setTokens(tokens, duringRestore || resumedRestore ? "restore" : "refresh");
+    if (resumedRestore && this.currentUser && this.currentSession) {
+      this.dispatch({ type: "RESTORE_SUCCESS", user: this.currentUser, session: this.currentSession });
+    }
+  }
   isAuthError(error) {
     return error.code === "REFRESH_FAILED" && (error.reason === "expired" || error.reason === "revoked");
   }
@@ -715,7 +765,7 @@ var TokenRuntime = class _TokenRuntime {
   async handleDpopRefreshFailure(error, duringRestore) {
     this.emitEvent?.({ type: "dpop_refresh_failed", metadata: { code: error.code } });
     if (error.class === "network") {
-      return this.scheduleRetry({ code: "REFRESH_FAILED", reason: "network", message: error.message }, duringRestore);
+      return this.scheduleRetry(error.cause ?? { code: "REFRESH_FAILED", reason: "network", message: error.message }, duringRestore);
     }
     if (error.class === "dpop_prover_unavailable") {
       this.emitEvent?.({ type: "refresh_failed", metadata: { reason: "dpop_prover_unavailable" } });
@@ -724,36 +774,53 @@ var TokenRuntime = class _TokenRuntime {
     await this.clear({ code: "REFRESH_FAILED", reason: "revoked", message: error.message });
     return false;
   }
+  /**
+   * Back off and retry a transient refresh failure. The session is never cleared here: when the
+   * budget is spent the typed transient error is surfaced (state `offline_stale` when signed in)
+   * and the stored refresh token waits for the next foreground / reconnect / `getToken()`.
+   */
   scheduleRetry(error, duringRestore) {
-    if (this.refreshAttempts >= RETRY_DELAYS_MS.length) {
-      if (!duringRestore && this.accessToken && this.expiresAtMs !== null && this.now() < this.expiresAtMs) {
-        this.refreshAttempts = 0;
-        this.offlineStaleCycles += 1;
-        if (this.offlineStaleCycles >= _TokenRuntime.MAX_OFFLINE_STALE_CYCLES) {
-          this.offlineStaleCycles = 0;
-          void this.clear({ code: "REFRESH_FAILED", reason: "revoked", message: "Refresh chronically failing \u2014 session lost" });
-          return false;
-        }
+    const transient = toTransientError(error);
+    this.lastRefreshError = transient;
+    if (duringRestore) this.restorePending = true;
+    const restoring = this.restorePending;
+    const delay = refreshRetryDelayMs(this.refreshAttempts, transient.code === "REFRESH_FAILED" ? transient.retryAfterMs : void 0);
+    if (delay === void 0) {
+      this.refreshAttempts = 0;
+      this.emitEvent?.({
+        type: "refresh_failed",
+        metadata: { reason: "retries_exhausted", ...transient.code === "REFRESH_FAILED" && transient.status !== void 0 && { status: transient.status } }
+      });
+      if (!restoring) {
+        this.dispatch({ type: "REFRESH_NETWORK_ERROR", error: transient });
         this.dispatch({ type: "OFFLINE_STALE" });
-        return false;
       }
-      void this.clear({ code: "REFRESH_FAILED", reason: "network", message: "Refresh exhausted retries" });
       return false;
     }
-    const delay = RETRY_DELAYS_MS[this.refreshAttempts];
     this.refreshAttempts++;
     this.emitEvent?.({ type: "network_retry", metadata: { delayMs: delay, attempt: this.refreshAttempts } });
-    if (!duringRestore) {
-      this.dispatch({ type: "REFRESH_NETWORK_ERROR", error });
+    if (!restoring) {
+      this.dispatch({ type: "REFRESH_NETWORK_ERROR", error: transient });
     }
     if (this.retryTimer) this.clearTimeoutFn(this.retryTimer);
     this.retryTimer = this.setTimeoutFn(() => {
       this.retryTimer = null;
-      void this.performRefresh();
+      void this.performRefresh({ duringRestore: this.restorePending });
     }, delay);
     return false;
   }
 };
+function toTransientError(error) {
+  if (error.code === "REFRESH_FAILED" && error.reason === "network") return error;
+  return {
+    code: "REFRESH_FAILED",
+    reason: "network",
+    message: getErrorMessage(error),
+    ..."status" in error && error.status !== void 0 && { status: error.status },
+    ..."oauthError" in error && typeof error.oauthError === "string" && { oauthError: error.oauthError },
+    ...error.requestId !== void 0 && { requestId: error.requestId }
+  };
+}
 
 // src/native/expo-adapter.ts
 function createDefaultExpoAdapter(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rakomi/react-native",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "React Native / Expo SDK for Rakomi authentication.",
   "keywords": [
     "rakomi",
@@ -83,11 +83,11 @@
     }
   },
   "devDependencies": {
-    "@rakomi/react": "0.5.0"
+    "@rakomi/react": "0.7.0"
   },
   "dependencies": {
     "jose": "^6.2.3",
-    "@rakomi/sdk-core": "^0.5.0"
+    "@rakomi/sdk-core": "^0.7.0"
   },
   "scripts": {
     "build": "NODE_OPTIONS=--max-old-space-size=4096 tsup",

package/sbom.cdx.json

@@ -26,10 +26,10 @@
     },
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/%40rakomi%2Freact-native@0.5.0",
+      "bom-ref": "pkg:npm/%40rakomi%2Freact-native@0.7.0",
       "name": "@rakomi/react-native",
-      "version": "0.5.0",
-      "purl": "pkg:npm/%40rakomi%2Freact-native@0.5.0",
+      "version": "0.7.0",
+      "purl": "pkg:npm/%40rakomi%2Freact-native@0.7.0",
       "licenses": [
         {
           "license": {
@@ -42,10 +42,10 @@
   "components": [
     {
       "type": "library",
-      "bom-ref": "pkg:npm/@rakomi/sdk-core@0.5.0",
+      "bom-ref": "pkg:npm/@rakomi/sdk-core@0.7.0",
       "name": "@rakomi/sdk-core",
-      "version": "0.5.0",
-      "purl": "pkg:npm/@rakomi/sdk-core@0.5.0",
+      "version": "0.7.0",
+      "purl": "pkg:npm/@rakomi/sdk-core@0.7.0",
       "licenses": [
         {
           "license": {