@sendoracloud/sdk-react-native 1.32.0 → 1.34.0

package/dist/index.cjs

@@ -48,7 +48,7 @@ var import_react_native_get_random_values = require("react-native-get-random-val
 var import_react_native5 = require("react-native");
 
 // src/storage.ts
-var PREFIX = "sendora_";
+var DEFAULT_PREFIX = "sendora_";
 var asyncStoragePromise = null;
 async function getAsyncStorage() {
   if (asyncStoragePromise) return asyncStoragePromise;
@@ -71,6 +71,12 @@ var Storage = class {
     this.hydrated = false;
     this.secure = opts.secureAdapter ?? null;
     this.secureKeys = new Set(opts.secureKeys ?? []);
+    this.prefix = opts.prefix ?? DEFAULT_PREFIX;
+    this.securePrefix = opts.prefix ?? "";
+  }
+  /** The adapter-facing name for a key. Bare by default; see `prefix`. */
+  secureName(key) {
+    return this.securePrefix + key;
   }
   isSecure(key) {
     return this.secure !== null && this.secureKeys.has(key);
@@ -91,7 +97,7 @@ var Storage = class {
         await this.hydrateSecureKey(k, store);
       } else if (store) {
         try {
-          const v = await store.getItem(PREFIX + k);
+          const v = await store.getItem(this.prefix + k);
           if (v !== null) this.cache.set(k, v);
         } catch {
         }
@@ -102,18 +108,18 @@ var Storage = class {
   /** Read a secure key: adapter first, else migrate legacy plaintext. Never throws. */
   async hydrateSecureKey(k, store) {
     try {
-      const secureVal = await this.secure.getItem(k);
+      const secureVal = await this.secure.getItem(this.secureName(k));
       if (secureVal !== null) {
         this.cache.set(k, secureVal);
         return;
       }
       if (store) {
-        const legacy = await store.getItem(PREFIX + k).catch(() => null);
+        const legacy = await store.getItem(this.prefix + k).catch(() => null);
         if (legacy !== null) {
           this.cache.set(k, legacy);
           try {
-            await this.secure.setItem(k, legacy);
-            await store.removeItem(PREFIX + k).catch(() => {
+            await this.secure.setItem(this.secureName(k), legacy);
+            await store.removeItem(this.prefix + k).catch(() => {
             });
           } catch {
           }
@@ -122,7 +128,7 @@ var Storage = class {
     } catch {
       if (store) {
         try {
-          const legacy = await store.getItem(PREFIX + k);
+          const legacy = await store.getItem(this.prefix + k);
           if (legacy !== null) this.cache.set(k, legacy);
         } catch {
         }
@@ -135,27 +141,27 @@ var Storage = class {
   set(key, value) {
     this.cache.set(key, value);
     if (this.isSecure(key)) {
-      void this.secure.setItem(key, value).catch(() => {
+      void this.secure.setItem(this.secureName(key), value).catch(() => {
         void getAsyncStorage().then((store) => {
-          if (store) store.setItem(PREFIX + key, value).catch(() => {
+          if (store) store.setItem(this.prefix + key, value).catch(() => {
           });
         });
       });
       return;
     }
     void getAsyncStorage().then((store) => {
-      if (store) store.setItem(PREFIX + key, value).catch(() => {
+      if (store) store.setItem(this.prefix + key, value).catch(() => {
       });
     });
   }
   remove(key) {
     this.cache.delete(key);
     if (this.isSecure(key)) {
-      void this.secure.removeItem(key).catch(() => {
+      void this.secure.removeItem(this.secureName(key)).catch(() => {
       });
     }
     void getAsyncStorage().then((store) => {
-      if (store) store.removeItem(PREFIX + key).catch(() => {
+      if (store) store.removeItem(this.prefix + key).catch(() => {
       });
     });
   }
@@ -171,7 +177,7 @@ var Storage = class {
     if (this.secure) {
       for (const k of this.secureKeys) {
         try {
-          await this.secure.removeItem(k);
+          await this.secure.removeItem(this.secureName(k));
         } catch {
         }
       }
@@ -182,13 +188,13 @@ var Storage = class {
     if (typeof store.getAllKeys === "function") {
       try {
         const all = await store.getAllKeys();
-        keys = all.filter((k) => k.startsWith(PREFIX));
+        keys = all.filter((k) => k.startsWith(this.prefix));
       } catch {
         keys = [];
       }
     }
     if (keys.length === 0) {
-      keys = Array.from(this.secureKeys).map((k) => PREFIX + k);
+      keys = Array.from(this.secureKeys).map((k) => this.prefix + k);
     }
     for (const k of keys) {
       try {
@@ -202,7 +208,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.32.0",
+  version: "1.34.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -258,7 +264,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -595,6 +601,27 @@ var Auth = class {
     this.user = null;
     this.accessToken = null;
     this.accessExpiresAt = 0;
+    /**
+     * Set once we have PROOF that this device's clock runs fast, which
+     * releases the `exp` guard in `canServeCachedToken`.
+     *
+     * The proof is specific and cannot be faked by a stale deadline: a token
+     * the server minted *seconds ago* reads as already past its own `exp`.
+     * A freshly-issued token is never genuinely expired, so the only
+     * explanation is the clock we measured it with.
+     *
+     * ⚠ NEVER PERSIST THIS. It is re-learned for the cost of one refresh per
+     * process, and a persisted "my clock is fast" belief would outlive the
+     * clock correction that made it false — which is precisely the stale-frame
+     * bug this whole guard exists to close, moved one level up.
+     *
+     * ⚠ Without this escape the `exp` guard alone is a REFRESH LOOP on any
+     * device whose clock is fast by more than the token TTL (default 60 min):
+     * every freshly-minted token would read as already expired, so every
+     * `getAccessToken()` would refresh, forever. That is why the fix is not
+     * simply "require `exp` too".
+     */
+    this.clockSkewConfirmed = false;
     this.inflight = Promise.resolve();
     this.refreshInflight = null;
     /**
@@ -614,6 +641,7 @@ var Auth = class {
     this.deletionCancelledListeners = /* @__PURE__ */ new Set();
     this.authStateListeners = /* @__PURE__ */ new Set();
     this.lastDeletionCancelled = null;
+    this.lastAnonRetirement = null;
     this.lastTakeover = null;
     /**
      * Anon refresh token captured at `signIn()` time, stashed keyed to the
@@ -685,6 +713,7 @@ var Auth = class {
       }
     }
     this.hydrated = true;
+    if (this.user && this.hooks.storage.get(REFRESH_KEY)) this.startProactiveRefreshCron();
     this.resolveReady();
   }
   getCurrentUser() {
@@ -807,6 +836,19 @@ var Auth = class {
   getLastDeletionCancelled() {
     return this.lastDeletionCancelled;
   }
+  /**
+   * What the last sign-in did with this device's guest account, or null if no
+   * sign-in has happened this session (s58.278).
+   *
+   * The one worth acting on is `"preserved"`: a guest account was presented,
+   * was NOT retired, and is therefore still alive server-side — so "recover
+   * your other account" is a real offer rather than a guess. `"retired"` means
+   * migrate from `onDeviceTakeover`'s id; `"none"` means there was nothing to
+   * reconcile. Cleared on signOut.
+   */
+  getLastAnonRetirement() {
+    return this.lastAnonRetirement;
+  }
   /** Internal — fan out deletion-cancelled to subscribers + cache the latest. */
   fireDeletionCancelled(userId) {
     const evt = { userId, at: /* @__PURE__ */ new Date() };
@@ -833,7 +875,11 @@ var Auth = class {
    *
    * Resolution order:
    *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
-   *     skew before exp) → return it. Fast path, no I/O.
+   *     before BOTH the tracked deadline and the token's own `exp`) →
+   *     return it. Fast path, no I/O. See `canServeCachedToken` for why
+   *     both are required and when the second is released.
+   *     Pass `{ forceRefresh: true }` to skip this step when the caller
+   *     knows the tracked deadline is wrong.
    *  2. No cached token AND no refresh token in storage → genuinely
    *     signed out → null.
    *  3. Expired/near-expiry but a refresh chain exists:
@@ -851,14 +897,85 @@ var Auth = class {
    *        the cooldown for an immediate retry on resume.
    *     c. Otherwise → fire the refresh and await it.
    */
-  async getAccessToken() {
-    if (this.accessToken && this.accessExpiresAt && Date.now() < this.accessExpiresAt - REFRESH_SAFETY_MS) {
+  /**
+   * The cached-token guard, and the single place the two deadlines are
+   * combined. Both must agree before a cached token is served:
+   *
+   *  1. the locally-tracked deadline (`Date.now() + expiresIn` at mint) —
+   *     immune to a constantly-wrong clock, blind to a clock that MOVES;
+   *  2. the token's own `exp` — immune to a clock that moves, wrong by the
+   *     full offset on a constantly-wrong clock.
+   *
+   * Guard 2 is released once `clockSkewConfirmed` proves the second failure
+   * mode is the one we are actually in.
+   *
+   * The gap this closes: `accessExpiresAt` is written in the device's clock
+   * frame at mint and PERSISTED. Step the clock backwards between mint and
+   * read — an iPhone acquiring automatic time after a long power-off, a
+   * restore, or a manual set — and the deadline is stale by the size of the
+   * correction, surviving relaunches. The SDK then serves a provably dead
+   * token, every request 401s, and because the fast path returns before
+   * reaching `persist()` or `wipeLocalIdentity()` nothing emits
+   * `signed_out`. Reported by Word Hurdle with a token 1929s past its `exp`.
+   */
+  canServeToken(token, expiresAt, nowMs) {
+    if (!token || !expiresAt) return false;
+    if (nowMs >= expiresAt - REFRESH_SAFETY_MS) return false;
+    if (this.clockSkewConfirmed) return true;
+    return accessTokenExpIsFuture(token, nowMs);
+  }
+  canServeCachedToken(nowMs) {
+    return this.canServeToken(this.accessToken, this.accessExpiresAt, nowMs);
+  }
+  /** Guard 1 alone: does the locally-tracked deadline still claim life? */
+  trackedDeadlineAlive(nowMs) {
+    return !!this.accessToken && !!this.accessExpiresAt && nowMs < this.accessExpiresAt - REFRESH_SAFETY_MS;
+  }
+  /**
+   * Refresh — and when the two deadlines disagree, let the token that comes
+   * back say which one was lying.
+   *
+   * ⚠ THE TIMING IS THE WHOLE MECHANISM, and the obvious placement is wrong.
+   * Learning at every mint site looks equivalent and is not: in the reported
+   * failure the token was MINTED while the clock was fast and only read after
+   * the correction, so a mint-time probe records "clock is fast", and the flag
+   * then waves through the very token the guard exists to refuse. Probing here
+   * — only on a refresh we performed BECAUSE `exp` contradicted a tracked
+   * deadline that still claimed life — separates the two cases, because by now
+   * the clock has either been corrected (fresh token reads live → stale
+   * deadline, guard holds) or is genuinely fast (fresh token still reads dead
+   * → release the guard, one probe, no loop).
+   */
+  async refreshAndReconcile(nowMs) {
+    const reconciling = this.deadlinesDisagree(nowMs);
+    const token = await this.refreshAccessToken();
+    if (reconciling && token) this.learnClockSkewFrom(token, Date.now());
+    return token;
+  }
+  /**
+   * Record whether a token the server issued MOMENTS AGO already reads as
+   * expired. It cannot genuinely be — so a `false` here is proof the device
+   * clock runs fast, and releases the `exp` guard for this process.
+   *
+   * Call this at every site that installs a server-issued token, and only
+   * with a token that just arrived. Handing it a cached token would let a
+   * stale deadline confirm itself.
+   */
+  learnClockSkewFrom(freshToken, nowMs) {
+    if (!accessTokenExpIsFuture(freshToken, nowMs)) this.clockSkewConfirmed = true;
+  }
+  /** True when a cached token is unusable ONLY because its `exp` contradicts a live tracked deadline. */
+  deadlinesDisagree(nowMs) {
+    return this.trackedDeadlineAlive(nowMs) && !this.canServeCachedToken(nowMs);
+  }
+  async getAccessToken(options) {
+    if (!options?.forceRefresh && this.canServeCachedToken(Date.now())) {
       return this.accessToken;
     }
     if (!this.hooks.storage.get(REFRESH_KEY)) return null;
     if (this.refreshInflight) return this.refreshInflight;
     if (Date.now() < this.refreshCooldownUntil) return null;
-    return this.refreshAccessToken();
+    return this.refreshAndReconcile(Date.now());
   }
   /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
   getAccessTokenSync() {
@@ -1675,7 +1792,7 @@ var Auth = class {
           const freshExpiresStr = this.hooks.storage.get(TOKEN_EXPIRES_KEY);
           if (freshAccess && freshExpiresStr) {
             const freshExpires = Number(freshExpiresStr);
-            if (Number.isFinite(freshExpires) && freshExpires > Date.now()) {
+            if (Number.isFinite(freshExpires) && this.canServeToken(freshAccess, freshExpires, Date.now())) {
               this.accessToken = freshAccess;
               this.accessExpiresAt = freshExpires;
               this.refreshFailureCount = 0;
@@ -1742,6 +1859,10 @@ var Auth = class {
     const tick = async () => {
       if (!this.accessToken || !this.accessExpiresAt) return;
       const now = Date.now();
+      if (!this.canServeCachedToken(now)) {
+        await this.refreshAndReconcile(now);
+        return;
+      }
       const lifetimeMs = this.accessExpiresAt - now;
       if (lifetimeMs <= 0) return;
       const guessOriginalMs = Math.max(lifetimeMs, 5 * 6e4);
@@ -1889,6 +2010,7 @@ var Auth = class {
         retiredAnonUserId: data.retiredAnonUserId
       });
     }
+    if (data.anonRetirement) this.lastAnonRetirement = data.anonRetirement;
     if (data.reactivatedFromDeletion) {
       this.fireDeletionCancelled(data.user.id);
       this.emitAuthState({ event: "deletion_cancelled", user: data.user });
@@ -1923,8 +2045,10 @@ var Auth = class {
     this.user = null;
     this.accessToken = null;
     this.accessExpiresAt = 0;
+    this.clockSkewConfirmed = false;
     this.lastTakeover = null;
     this.lastDeletionCancelled = null;
+    this.lastAnonRetirement = null;
     this.pendingAnonTakeover = null;
     this.hooks.storage.remove(USER_KEY);
     this.hooks.storage.remove(TOKEN_KEY);
@@ -1950,6 +2074,13 @@ function readRotatedTokens(data) {
   if (typeof t.expiresIn !== "number" || t.expiresIn <= 0) return null;
   return { accessToken: t.accessToken, refreshToken: t.refreshToken, expiresIn: t.expiresIn };
 }
+function accessTokenExpIsFuture(token, nowMs) {
+  const claims = decodeJwtPayload(token);
+  if (!claims) return true;
+  const exp = claims.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return true;
+  return nowMs < exp * 1e3;
+}
 function decodeJwtPayload(token) {
   try {
     const parts = token.split(".");
@@ -2639,6 +2770,16 @@ var AUTH_HYDRATE_KEYS = [
 ];
 var SECURE_KEYS = ["auth_refresh_token", "auth_access_token", "auth_user"];
 var PUBLIC_KEY_RE = /^pk_(prod|staging|dev|live|test)_[A-Za-z0-9]{16,}$/;
+var STORAGE_PREFIX_RE = /^[A-Za-z0-9_.-]{1,64}$/;
+function normalizeStoragePrefix(prefix) {
+  if (prefix === void 0) return void 0;
+  if (typeof prefix !== "string" || !STORAGE_PREFIX_RE.test(prefix)) {
+    throw new Error(
+      `[sendora] init: storagePrefix must be 1-64 chars of A-Z a-z 0-9 _ . - (got ${JSON.stringify(prefix)}). Changing it signs the device out, so it is validated rather than ignored.`
+    );
+  }
+  return prefix;
+}
 var MAX_PUSH_TOKEN_BYTES = 4096;
 var MAX_PUSH_METADATA_BYTES = 4096;
 var MAX_USER_ID_LEN = 256;
@@ -2812,8 +2953,13 @@ var SendoraSDK = class {
         `[sendoracloud] apiUrl override active: ${apiUrl} \u2014 confirm this is intentional. Tokens + events will be sent here.`
       );
     }
-    if (config.secureStorage) {
-      this.storage = new Storage({ secureAdapter: config.secureStorage, secureKeys: SECURE_KEYS });
+    if (config.secureStorage || config.storagePrefix !== void 0) {
+      const prefix = normalizeStoragePrefix(config.storagePrefix);
+      this.storage = new Storage({
+        secureAdapter: config.secureStorage,
+        secureKeys: SECURE_KEYS,
+        prefix
+      });
     }
     await this.storage.hydrate([
       ANON_KEY,

package/dist/index.d.cts

@@ -104,6 +104,29 @@ interface SendoraConfig {
      * threat model. It is opt-in: adding it never changes an app that doesn't pass it.
      */
     secureStorage?: SecureStorageAdapter;
+    /**
+     * Namespace every on-device key this SDK owns. Omit for the historical
+     * `sendora_` prefix — the default is byte-identical to prior releases.
+     *
+     * For apps that point one codebase at more than one Sendora project
+     * (staging vs production, a debug build beside a release build). Without
+     * it, both environments share `sendora_*` on the same device: whichever
+     * launched last owns the session, and a debug sign-in can evict the
+     * release build's. A custom `secureStorage` adapter only fixes the half
+     * that goes through the adapter — `auth_access_expires` and the anon id
+     * stay in AsyncStorage and still collide.
+     *
+     * ⚠ CHANGING THIS SIGNS THE DEVICE OUT. Keys are the session's only
+     * durable handle, and the SDK does not migrate between prefixes — a new
+     * prefix reads an empty store and mints a fresh anonymous user. Pick one
+     * per environment before shipping and never change it afterwards. This is
+     * the same frozen-key rule as ADR-023, delegated to you.
+     *
+     * ⚠ Applies to the `secureStorage` adapter too when set (adapter keys are
+     * bare by default). If you already namespace inside your own adapter,
+     * either drop that and use this, or expect `<yours><ours>key`.
+     */
+    storagePrefix?: string;
 }
 /**
  * Async key/value adapter for encrypted-at-rest auth storage. Compatible with a
@@ -178,13 +201,30 @@ type StorageOptions = {
     secureAdapter?: SecureStorageAdapter | null;
     /** Keys routed through `secureAdapter` when it is present. Everything else stays in AsyncStorage. */
     secureKeys?: Iterable<string>;
+    /**
+     * Namespace for every key this SDK owns. Omit for the default `sendora_`.
+     *
+     * ⚠ Asymmetric by necessity, and the asymmetry is what keeps upgrades
+     * safe. When omitted, AsyncStorage keys keep the historical `sendora_`
+     * prefix and secure-adapter keys stay BARE — exactly what shipped before
+     * this option existed, so no installed app loses its session on upgrade.
+     * When supplied, the prefix applies to BOTH stores, because the whole
+     * point is that two environments sharing one device share nothing.
+     */
+    prefix?: string;
 };
 declare class Storage {
     private cache;
     private hydrated;
     private readonly secure;
     private readonly secureKeys;
+    /** Applied to AsyncStorage keys. */
+    private readonly prefix;
+    /** Applied to secure-adapter keys — empty unless a custom prefix was set. */
+    private readonly securePrefix;
     constructor(opts?: StorageOptions);
+    /** The adapter-facing name for a key. Bare by default; see `prefix`. */
+    private secureName;
     private isSecure;
     /**
      * Populate the memory cache from persistent storage. Must be awaited
@@ -298,6 +338,8 @@ interface GameCenterPayload {
     teamPlayerId: string;
     bundleId: string;
 }
+/** @see AuthApiResponse.anonRetirement */
+type AnonRetirementOutcome = "retired" | "preserved" | "none";
 declare class EmailAlreadyTakenError extends Error {
     constructor(message?: string);
 }
@@ -515,6 +557,27 @@ declare class Auth {
     private user;
     private accessToken;
     private accessExpiresAt;
+    /**
+     * Set once we have PROOF that this device's clock runs fast, which
+     * releases the `exp` guard in `canServeCachedToken`.
+     *
+     * The proof is specific and cannot be faked by a stale deadline: a token
+     * the server minted *seconds ago* reads as already past its own `exp`.
+     * A freshly-issued token is never genuinely expired, so the only
+     * explanation is the clock we measured it with.
+     *
+     * ⚠ NEVER PERSIST THIS. It is re-learned for the cost of one refresh per
+     * process, and a persisted "my clock is fast" belief would outlive the
+     * clock correction that made it false — which is precisely the stale-frame
+     * bug this whole guard exists to close, moved one level up.
+     *
+     * ⚠ Without this escape the `exp` guard alone is a REFRESH LOOP on any
+     * device whose clock is fast by more than the token TTL (default 60 min):
+     * every freshly-minted token would read as already expired, so every
+     * `getAccessToken()` would refresh, forever. That is why the fix is not
+     * simply "require `exp` too".
+     */
+    private clockSkewConfirmed;
     private inflight;
     private refreshInflight;
     /**
@@ -534,6 +597,7 @@ declare class Auth {
     private deletionCancelledListeners;
     private authStateListeners;
     private lastDeletionCancelled;
+    private lastAnonRetirement;
     private lastTakeover;
     /**
      * Anon refresh token captured at `signIn()` time, stashed keyed to the
@@ -656,6 +720,17 @@ declare class Auth {
     onDeletionCancelled(listener: (evt: DeletionCancelledEvent) => void): () => void;
     /** The most recent deletion-cancelled event this session, or null. Cleared on signOut. */
     getLastDeletionCancelled(): DeletionCancelledEvent | null;
+    /**
+     * What the last sign-in did with this device's guest account, or null if no
+     * sign-in has happened this session (s58.278).
+     *
+     * The one worth acting on is `"preserved"`: a guest account was presented,
+     * was NOT retired, and is therefore still alive server-side — so "recover
+     * your other account" is a real offer rather than a guess. `"retired"` means
+     * migrate from `onDeviceTakeover`'s id; `"none"` means there was nothing to
+     * reconcile. Cleared on signOut.
+     */
+    getLastAnonRetirement(): AnonRetirementOutcome | null;
     /** Internal — fan out deletion-cancelled to subscribers + cache the latest. */
     private fireDeletionCancelled;
     /**
@@ -672,7 +747,11 @@ declare class Auth {
      *
      * Resolution order:
      *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
-     *     skew before exp) → return it. Fast path, no I/O.
+     *     before BOTH the tracked deadline and the token's own `exp`) →
+     *     return it. Fast path, no I/O. See `canServeCachedToken` for why
+     *     both are required and when the second is released.
+     *     Pass `{ forceRefresh: true }` to skip this step when the caller
+     *     knows the tracked deadline is wrong.
      *  2. No cached token AND no refresh token in storage → genuinely
      *     signed out → null.
      *  3. Expired/near-expiry but a refresh chain exists:
@@ -690,7 +769,62 @@ declare class Auth {
      *        the cooldown for an immediate retry on resume.
      *     c. Otherwise → fire the refresh and await it.
      */
-    getAccessToken(): Promise<string | null>;
+    /**
+     * The cached-token guard, and the single place the two deadlines are
+     * combined. Both must agree before a cached token is served:
+     *
+     *  1. the locally-tracked deadline (`Date.now() + expiresIn` at mint) —
+     *     immune to a constantly-wrong clock, blind to a clock that MOVES;
+     *  2. the token's own `exp` — immune to a clock that moves, wrong by the
+     *     full offset on a constantly-wrong clock.
+     *
+     * Guard 2 is released once `clockSkewConfirmed` proves the second failure
+     * mode is the one we are actually in.
+     *
+     * The gap this closes: `accessExpiresAt` is written in the device's clock
+     * frame at mint and PERSISTED. Step the clock backwards between mint and
+     * read — an iPhone acquiring automatic time after a long power-off, a
+     * restore, or a manual set — and the deadline is stale by the size of the
+     * correction, surviving relaunches. The SDK then serves a provably dead
+     * token, every request 401s, and because the fast path returns before
+     * reaching `persist()` or `wipeLocalIdentity()` nothing emits
+     * `signed_out`. Reported by Word Hurdle with a token 1929s past its `exp`.
+     */
+    private canServeToken;
+    private canServeCachedToken;
+    /** Guard 1 alone: does the locally-tracked deadline still claim life? */
+    private trackedDeadlineAlive;
+    /**
+     * Refresh — and when the two deadlines disagree, let the token that comes
+     * back say which one was lying.
+     *
+     * ⚠ THE TIMING IS THE WHOLE MECHANISM, and the obvious placement is wrong.
+     * Learning at every mint site looks equivalent and is not: in the reported
+     * failure the token was MINTED while the clock was fast and only read after
+     * the correction, so a mint-time probe records "clock is fast", and the flag
+     * then waves through the very token the guard exists to refuse. Probing here
+     * — only on a refresh we performed BECAUSE `exp` contradicted a tracked
+     * deadline that still claimed life — separates the two cases, because by now
+     * the clock has either been corrected (fresh token reads live → stale
+     * deadline, guard holds) or is genuinely fast (fresh token still reads dead
+     * → release the guard, one probe, no loop).
+     */
+    private refreshAndReconcile;
+    /**
+     * Record whether a token the server issued MOMENTS AGO already reads as
+     * expired. It cannot genuinely be — so a `false` here is proof the device
+     * clock runs fast, and releases the `exp` guard for this process.
+     *
+     * Call this at every site that installs a server-issued token, and only
+     * with a token that just arrived. Handing it a cached token would let a
+     * stale deadline confirm itself.
+     */
+    private learnClockSkewFrom;
+    /** True when a cached token is unusable ONLY because its `exp` contradicts a live tracked deadline. */
+    private deadlinesDisagree;
+    getAccessToken(options?: {
+        forceRefresh?: boolean;
+    }): Promise<string | null>;
     /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
     getAccessTokenSync(): string | null;
     /**
@@ -1904,4 +2038,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { AlreadyIdentifiedError, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameSignInOptions, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };
+export { AlreadyIdentifiedError, type AnonRetirementOutcome, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameSignInOptions, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };

package/dist/index.d.ts

@@ -104,6 +104,29 @@ interface SendoraConfig {
      * threat model. It is opt-in: adding it never changes an app that doesn't pass it.
      */
     secureStorage?: SecureStorageAdapter;
+    /**
+     * Namespace every on-device key this SDK owns. Omit for the historical
+     * `sendora_` prefix — the default is byte-identical to prior releases.
+     *
+     * For apps that point one codebase at more than one Sendora project
+     * (staging vs production, a debug build beside a release build). Without
+     * it, both environments share `sendora_*` on the same device: whichever
+     * launched last owns the session, and a debug sign-in can evict the
+     * release build's. A custom `secureStorage` adapter only fixes the half
+     * that goes through the adapter — `auth_access_expires` and the anon id
+     * stay in AsyncStorage and still collide.
+     *
+     * ⚠ CHANGING THIS SIGNS THE DEVICE OUT. Keys are the session's only
+     * durable handle, and the SDK does not migrate between prefixes — a new
+     * prefix reads an empty store and mints a fresh anonymous user. Pick one
+     * per environment before shipping and never change it afterwards. This is
+     * the same frozen-key rule as ADR-023, delegated to you.
+     *
+     * ⚠ Applies to the `secureStorage` adapter too when set (adapter keys are
+     * bare by default). If you already namespace inside your own adapter,
+     * either drop that and use this, or expect `<yours><ours>key`.
+     */
+    storagePrefix?: string;
 }
 /**
  * Async key/value adapter for encrypted-at-rest auth storage. Compatible with a
@@ -178,13 +201,30 @@ type StorageOptions = {
     secureAdapter?: SecureStorageAdapter | null;
     /** Keys routed through `secureAdapter` when it is present. Everything else stays in AsyncStorage. */
     secureKeys?: Iterable<string>;
+    /**
+     * Namespace for every key this SDK owns. Omit for the default `sendora_`.
+     *
+     * ⚠ Asymmetric by necessity, and the asymmetry is what keeps upgrades
+     * safe. When omitted, AsyncStorage keys keep the historical `sendora_`
+     * prefix and secure-adapter keys stay BARE — exactly what shipped before
+     * this option existed, so no installed app loses its session on upgrade.
+     * When supplied, the prefix applies to BOTH stores, because the whole
+     * point is that two environments sharing one device share nothing.
+     */
+    prefix?: string;
 };
 declare class Storage {
     private cache;
     private hydrated;
     private readonly secure;
     private readonly secureKeys;
+    /** Applied to AsyncStorage keys. */
+    private readonly prefix;
+    /** Applied to secure-adapter keys — empty unless a custom prefix was set. */
+    private readonly securePrefix;
     constructor(opts?: StorageOptions);
+    /** The adapter-facing name for a key. Bare by default; see `prefix`. */
+    private secureName;
     private isSecure;
     /**
      * Populate the memory cache from persistent storage. Must be awaited
@@ -298,6 +338,8 @@ interface GameCenterPayload {
     teamPlayerId: string;
     bundleId: string;
 }
+/** @see AuthApiResponse.anonRetirement */
+type AnonRetirementOutcome = "retired" | "preserved" | "none";
 declare class EmailAlreadyTakenError extends Error {
     constructor(message?: string);
 }
@@ -515,6 +557,27 @@ declare class Auth {
     private user;
     private accessToken;
     private accessExpiresAt;
+    /**
+     * Set once we have PROOF that this device's clock runs fast, which
+     * releases the `exp` guard in `canServeCachedToken`.
+     *
+     * The proof is specific and cannot be faked by a stale deadline: a token
+     * the server minted *seconds ago* reads as already past its own `exp`.
+     * A freshly-issued token is never genuinely expired, so the only
+     * explanation is the clock we measured it with.
+     *
+     * ⚠ NEVER PERSIST THIS. It is re-learned for the cost of one refresh per
+     * process, and a persisted "my clock is fast" belief would outlive the
+     * clock correction that made it false — which is precisely the stale-frame
+     * bug this whole guard exists to close, moved one level up.
+     *
+     * ⚠ Without this escape the `exp` guard alone is a REFRESH LOOP on any
+     * device whose clock is fast by more than the token TTL (default 60 min):
+     * every freshly-minted token would read as already expired, so every
+     * `getAccessToken()` would refresh, forever. That is why the fix is not
+     * simply "require `exp` too".
+     */
+    private clockSkewConfirmed;
     private inflight;
     private refreshInflight;
     /**
@@ -534,6 +597,7 @@ declare class Auth {
     private deletionCancelledListeners;
     private authStateListeners;
     private lastDeletionCancelled;
+    private lastAnonRetirement;
     private lastTakeover;
     /**
      * Anon refresh token captured at `signIn()` time, stashed keyed to the
@@ -656,6 +720,17 @@ declare class Auth {
     onDeletionCancelled(listener: (evt: DeletionCancelledEvent) => void): () => void;
     /** The most recent deletion-cancelled event this session, or null. Cleared on signOut. */
     getLastDeletionCancelled(): DeletionCancelledEvent | null;
+    /**
+     * What the last sign-in did with this device's guest account, or null if no
+     * sign-in has happened this session (s58.278).
+     *
+     * The one worth acting on is `"preserved"`: a guest account was presented,
+     * was NOT retired, and is therefore still alive server-side — so "recover
+     * your other account" is a real offer rather than a guess. `"retired"` means
+     * migrate from `onDeviceTakeover`'s id; `"none"` means there was nothing to
+     * reconcile. Cleared on signOut.
+     */
+    getLastAnonRetirement(): AnonRetirementOutcome | null;
     /** Internal — fan out deletion-cancelled to subscribers + cache the latest. */
     private fireDeletionCancelled;
     /**
@@ -672,7 +747,11 @@ declare class Auth {
      *
      * Resolution order:
      *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
-     *     skew before exp) → return it. Fast path, no I/O.
+     *     before BOTH the tracked deadline and the token's own `exp`) →
+     *     return it. Fast path, no I/O. See `canServeCachedToken` for why
+     *     both are required and when the second is released.
+     *     Pass `{ forceRefresh: true }` to skip this step when the caller
+     *     knows the tracked deadline is wrong.
      *  2. No cached token AND no refresh token in storage → genuinely
      *     signed out → null.
      *  3. Expired/near-expiry but a refresh chain exists:
@@ -690,7 +769,62 @@ declare class Auth {
      *        the cooldown for an immediate retry on resume.
      *     c. Otherwise → fire the refresh and await it.
      */
-    getAccessToken(): Promise<string | null>;
+    /**
+     * The cached-token guard, and the single place the two deadlines are
+     * combined. Both must agree before a cached token is served:
+     *
+     *  1. the locally-tracked deadline (`Date.now() + expiresIn` at mint) —
+     *     immune to a constantly-wrong clock, blind to a clock that MOVES;
+     *  2. the token's own `exp` — immune to a clock that moves, wrong by the
+     *     full offset on a constantly-wrong clock.
+     *
+     * Guard 2 is released once `clockSkewConfirmed` proves the second failure
+     * mode is the one we are actually in.
+     *
+     * The gap this closes: `accessExpiresAt` is written in the device's clock
+     * frame at mint and PERSISTED. Step the clock backwards between mint and
+     * read — an iPhone acquiring automatic time after a long power-off, a
+     * restore, or a manual set — and the deadline is stale by the size of the
+     * correction, surviving relaunches. The SDK then serves a provably dead
+     * token, every request 401s, and because the fast path returns before
+     * reaching `persist()` or `wipeLocalIdentity()` nothing emits
+     * `signed_out`. Reported by Word Hurdle with a token 1929s past its `exp`.
+     */
+    private canServeToken;
+    private canServeCachedToken;
+    /** Guard 1 alone: does the locally-tracked deadline still claim life? */
+    private trackedDeadlineAlive;
+    /**
+     * Refresh — and when the two deadlines disagree, let the token that comes
+     * back say which one was lying.
+     *
+     * ⚠ THE TIMING IS THE WHOLE MECHANISM, and the obvious placement is wrong.
+     * Learning at every mint site looks equivalent and is not: in the reported
+     * failure the token was MINTED while the clock was fast and only read after
+     * the correction, so a mint-time probe records "clock is fast", and the flag
+     * then waves through the very token the guard exists to refuse. Probing here
+     * — only on a refresh we performed BECAUSE `exp` contradicted a tracked
+     * deadline that still claimed life — separates the two cases, because by now
+     * the clock has either been corrected (fresh token reads live → stale
+     * deadline, guard holds) or is genuinely fast (fresh token still reads dead
+     * → release the guard, one probe, no loop).
+     */
+    private refreshAndReconcile;
+    /**
+     * Record whether a token the server issued MOMENTS AGO already reads as
+     * expired. It cannot genuinely be — so a `false` here is proof the device
+     * clock runs fast, and releases the `exp` guard for this process.
+     *
+     * Call this at every site that installs a server-issued token, and only
+     * with a token that just arrived. Handing it a cached token would let a
+     * stale deadline confirm itself.
+     */
+    private learnClockSkewFrom;
+    /** True when a cached token is unusable ONLY because its `exp` contradicts a live tracked deadline. */
+    private deadlinesDisagree;
+    getAccessToken(options?: {
+        forceRefresh?: boolean;
+    }): Promise<string | null>;
     /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
     getAccessTokenSync(): string | null;
     /**
@@ -1904,4 +2038,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { AlreadyIdentifiedError, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameSignInOptions, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };
+export { AlreadyIdentifiedError, type AnonRetirementOutcome, type AttachLinkingApiOptions, Auth, AuthError, type AuthErrorKind, type AuthSignedOutReason, type AuthStateChange, type AuthTokens, type AuthUser, type CredentialCollisionPolicy, CredentialInUseError, type DeletionCancelledEvent, type DeviceTakeoverEvent, EmailAlreadyTakenError, type GameSignInOptions, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, type LinkedIdentitiesResponse, type LinkedIdentity, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };

package/dist/index.js

@@ -3,7 +3,7 @@ import "react-native-get-random-values";
 import { Platform } from "react-native";
 
 // src/storage.ts
-var PREFIX = "sendora_";
+var DEFAULT_PREFIX = "sendora_";
 var asyncStoragePromise = null;
 async function getAsyncStorage() {
   if (asyncStoragePromise) return asyncStoragePromise;
@@ -26,6 +26,12 @@ var Storage = class {
     this.hydrated = false;
     this.secure = opts.secureAdapter ?? null;
     this.secureKeys = new Set(opts.secureKeys ?? []);
+    this.prefix = opts.prefix ?? DEFAULT_PREFIX;
+    this.securePrefix = opts.prefix ?? "";
+  }
+  /** The adapter-facing name for a key. Bare by default; see `prefix`. */
+  secureName(key) {
+    return this.securePrefix + key;
   }
   isSecure(key) {
     return this.secure !== null && this.secureKeys.has(key);
@@ -46,7 +52,7 @@ var Storage = class {
         await this.hydrateSecureKey(k, store);
       } else if (store) {
         try {
-          const v = await store.getItem(PREFIX + k);
+          const v = await store.getItem(this.prefix + k);
           if (v !== null) this.cache.set(k, v);
         } catch {
         }
@@ -57,18 +63,18 @@ var Storage = class {
   /** Read a secure key: adapter first, else migrate legacy plaintext. Never throws. */
   async hydrateSecureKey(k, store) {
     try {
-      const secureVal = await this.secure.getItem(k);
+      const secureVal = await this.secure.getItem(this.secureName(k));
       if (secureVal !== null) {
         this.cache.set(k, secureVal);
         return;
       }
       if (store) {
-        const legacy = await store.getItem(PREFIX + k).catch(() => null);
+        const legacy = await store.getItem(this.prefix + k).catch(() => null);
         if (legacy !== null) {
           this.cache.set(k, legacy);
           try {
-            await this.secure.setItem(k, legacy);
-            await store.removeItem(PREFIX + k).catch(() => {
+            await this.secure.setItem(this.secureName(k), legacy);
+            await store.removeItem(this.prefix + k).catch(() => {
             });
           } catch {
           }
@@ -77,7 +83,7 @@ var Storage = class {
     } catch {
       if (store) {
         try {
-          const legacy = await store.getItem(PREFIX + k);
+          const legacy = await store.getItem(this.prefix + k);
           if (legacy !== null) this.cache.set(k, legacy);
         } catch {
         }
@@ -90,27 +96,27 @@ var Storage = class {
   set(key, value) {
     this.cache.set(key, value);
     if (this.isSecure(key)) {
-      void this.secure.setItem(key, value).catch(() => {
+      void this.secure.setItem(this.secureName(key), value).catch(() => {
         void getAsyncStorage().then((store) => {
-          if (store) store.setItem(PREFIX + key, value).catch(() => {
+          if (store) store.setItem(this.prefix + key, value).catch(() => {
           });
         });
       });
       return;
     }
     void getAsyncStorage().then((store) => {
-      if (store) store.setItem(PREFIX + key, value).catch(() => {
+      if (store) store.setItem(this.prefix + key, value).catch(() => {
       });
     });
   }
   remove(key) {
     this.cache.delete(key);
     if (this.isSecure(key)) {
-      void this.secure.removeItem(key).catch(() => {
+      void this.secure.removeItem(this.secureName(key)).catch(() => {
       });
     }
     void getAsyncStorage().then((store) => {
-      if (store) store.removeItem(PREFIX + key).catch(() => {
+      if (store) store.removeItem(this.prefix + key).catch(() => {
       });
     });
   }
@@ -126,7 +132,7 @@ var Storage = class {
     if (this.secure) {
       for (const k of this.secureKeys) {
         try {
-          await this.secure.removeItem(k);
+          await this.secure.removeItem(this.secureName(k));
         } catch {
         }
       }
@@ -137,13 +143,13 @@ var Storage = class {
     if (typeof store.getAllKeys === "function") {
       try {
         const all = await store.getAllKeys();
-        keys = all.filter((k) => k.startsWith(PREFIX));
+        keys = all.filter((k) => k.startsWith(this.prefix));
       } catch {
         keys = [];
       }
     }
     if (keys.length === 0) {
-      keys = Array.from(this.secureKeys).map((k) => PREFIX + k);
+      keys = Array.from(this.secureKeys).map((k) => this.prefix + k);
     }
     for (const k of keys) {
       try {
@@ -157,7 +163,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.32.0",
+  version: "1.34.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -213,7 +219,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -550,6 +556,27 @@ var Auth = class {
     this.user = null;
     this.accessToken = null;
     this.accessExpiresAt = 0;
+    /**
+     * Set once we have PROOF that this device's clock runs fast, which
+     * releases the `exp` guard in `canServeCachedToken`.
+     *
+     * The proof is specific and cannot be faked by a stale deadline: a token
+     * the server minted *seconds ago* reads as already past its own `exp`.
+     * A freshly-issued token is never genuinely expired, so the only
+     * explanation is the clock we measured it with.
+     *
+     * ⚠ NEVER PERSIST THIS. It is re-learned for the cost of one refresh per
+     * process, and a persisted "my clock is fast" belief would outlive the
+     * clock correction that made it false — which is precisely the stale-frame
+     * bug this whole guard exists to close, moved one level up.
+     *
+     * ⚠ Without this escape the `exp` guard alone is a REFRESH LOOP on any
+     * device whose clock is fast by more than the token TTL (default 60 min):
+     * every freshly-minted token would read as already expired, so every
+     * `getAccessToken()` would refresh, forever. That is why the fix is not
+     * simply "require `exp` too".
+     */
+    this.clockSkewConfirmed = false;
     this.inflight = Promise.resolve();
     this.refreshInflight = null;
     /**
@@ -569,6 +596,7 @@ var Auth = class {
     this.deletionCancelledListeners = /* @__PURE__ */ new Set();
     this.authStateListeners = /* @__PURE__ */ new Set();
     this.lastDeletionCancelled = null;
+    this.lastAnonRetirement = null;
     this.lastTakeover = null;
     /**
      * Anon refresh token captured at `signIn()` time, stashed keyed to the
@@ -640,6 +668,7 @@ var Auth = class {
       }
     }
     this.hydrated = true;
+    if (this.user && this.hooks.storage.get(REFRESH_KEY)) this.startProactiveRefreshCron();
     this.resolveReady();
   }
   getCurrentUser() {
@@ -762,6 +791,19 @@ var Auth = class {
   getLastDeletionCancelled() {
     return this.lastDeletionCancelled;
   }
+  /**
+   * What the last sign-in did with this device's guest account, or null if no
+   * sign-in has happened this session (s58.278).
+   *
+   * The one worth acting on is `"preserved"`: a guest account was presented,
+   * was NOT retired, and is therefore still alive server-side — so "recover
+   * your other account" is a real offer rather than a guess. `"retired"` means
+   * migrate from `onDeviceTakeover`'s id; `"none"` means there was nothing to
+   * reconcile. Cleared on signOut.
+   */
+  getLastAnonRetirement() {
+    return this.lastAnonRetirement;
+  }
   /** Internal — fan out deletion-cancelled to subscribers + cache the latest. */
   fireDeletionCancelled(userId) {
     const evt = { userId, at: /* @__PURE__ */ new Date() };
@@ -788,7 +830,11 @@ var Auth = class {
    *
    * Resolution order:
    *  1. Cached token with comfortable life left (>= REFRESH_SAFETY_MS
-   *     skew before exp) → return it. Fast path, no I/O.
+   *     before BOTH the tracked deadline and the token's own `exp`) →
+   *     return it. Fast path, no I/O. See `canServeCachedToken` for why
+   *     both are required and when the second is released.
+   *     Pass `{ forceRefresh: true }` to skip this step when the caller
+   *     knows the tracked deadline is wrong.
    *  2. No cached token AND no refresh token in storage → genuinely
    *     signed out → null.
    *  3. Expired/near-expiry but a refresh chain exists:
@@ -806,14 +852,85 @@ var Auth = class {
    *        the cooldown for an immediate retry on resume.
    *     c. Otherwise → fire the refresh and await it.
    */
-  async getAccessToken() {
-    if (this.accessToken && this.accessExpiresAt && Date.now() < this.accessExpiresAt - REFRESH_SAFETY_MS) {
+  /**
+   * The cached-token guard, and the single place the two deadlines are
+   * combined. Both must agree before a cached token is served:
+   *
+   *  1. the locally-tracked deadline (`Date.now() + expiresIn` at mint) —
+   *     immune to a constantly-wrong clock, blind to a clock that MOVES;
+   *  2. the token's own `exp` — immune to a clock that moves, wrong by the
+   *     full offset on a constantly-wrong clock.
+   *
+   * Guard 2 is released once `clockSkewConfirmed` proves the second failure
+   * mode is the one we are actually in.
+   *
+   * The gap this closes: `accessExpiresAt` is written in the device's clock
+   * frame at mint and PERSISTED. Step the clock backwards between mint and
+   * read — an iPhone acquiring automatic time after a long power-off, a
+   * restore, or a manual set — and the deadline is stale by the size of the
+   * correction, surviving relaunches. The SDK then serves a provably dead
+   * token, every request 401s, and because the fast path returns before
+   * reaching `persist()` or `wipeLocalIdentity()` nothing emits
+   * `signed_out`. Reported by Word Hurdle with a token 1929s past its `exp`.
+   */
+  canServeToken(token, expiresAt, nowMs) {
+    if (!token || !expiresAt) return false;
+    if (nowMs >= expiresAt - REFRESH_SAFETY_MS) return false;
+    if (this.clockSkewConfirmed) return true;
+    return accessTokenExpIsFuture(token, nowMs);
+  }
+  canServeCachedToken(nowMs) {
+    return this.canServeToken(this.accessToken, this.accessExpiresAt, nowMs);
+  }
+  /** Guard 1 alone: does the locally-tracked deadline still claim life? */
+  trackedDeadlineAlive(nowMs) {
+    return !!this.accessToken && !!this.accessExpiresAt && nowMs < this.accessExpiresAt - REFRESH_SAFETY_MS;
+  }
+  /**
+   * Refresh — and when the two deadlines disagree, let the token that comes
+   * back say which one was lying.
+   *
+   * ⚠ THE TIMING IS THE WHOLE MECHANISM, and the obvious placement is wrong.
+   * Learning at every mint site looks equivalent and is not: in the reported
+   * failure the token was MINTED while the clock was fast and only read after
+   * the correction, so a mint-time probe records "clock is fast", and the flag
+   * then waves through the very token the guard exists to refuse. Probing here
+   * — only on a refresh we performed BECAUSE `exp` contradicted a tracked
+   * deadline that still claimed life — separates the two cases, because by now
+   * the clock has either been corrected (fresh token reads live → stale
+   * deadline, guard holds) or is genuinely fast (fresh token still reads dead
+   * → release the guard, one probe, no loop).
+   */
+  async refreshAndReconcile(nowMs) {
+    const reconciling = this.deadlinesDisagree(nowMs);
+    const token = await this.refreshAccessToken();
+    if (reconciling && token) this.learnClockSkewFrom(token, Date.now());
+    return token;
+  }
+  /**
+   * Record whether a token the server issued MOMENTS AGO already reads as
+   * expired. It cannot genuinely be — so a `false` here is proof the device
+   * clock runs fast, and releases the `exp` guard for this process.
+   *
+   * Call this at every site that installs a server-issued token, and only
+   * with a token that just arrived. Handing it a cached token would let a
+   * stale deadline confirm itself.
+   */
+  learnClockSkewFrom(freshToken, nowMs) {
+    if (!accessTokenExpIsFuture(freshToken, nowMs)) this.clockSkewConfirmed = true;
+  }
+  /** True when a cached token is unusable ONLY because its `exp` contradicts a live tracked deadline. */
+  deadlinesDisagree(nowMs) {
+    return this.trackedDeadlineAlive(nowMs) && !this.canServeCachedToken(nowMs);
+  }
+  async getAccessToken(options) {
+    if (!options?.forceRefresh && this.canServeCachedToken(Date.now())) {
       return this.accessToken;
     }
     if (!this.hooks.storage.get(REFRESH_KEY)) return null;
     if (this.refreshInflight) return this.refreshInflight;
     if (Date.now() < this.refreshCooldownUntil) return null;
-    return this.refreshAccessToken();
+    return this.refreshAndReconcile(Date.now());
   }
   /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
   getAccessTokenSync() {
@@ -1630,7 +1747,7 @@ var Auth = class {
           const freshExpiresStr = this.hooks.storage.get(TOKEN_EXPIRES_KEY);
           if (freshAccess && freshExpiresStr) {
             const freshExpires = Number(freshExpiresStr);
-            if (Number.isFinite(freshExpires) && freshExpires > Date.now()) {
+            if (Number.isFinite(freshExpires) && this.canServeToken(freshAccess, freshExpires, Date.now())) {
               this.accessToken = freshAccess;
               this.accessExpiresAt = freshExpires;
               this.refreshFailureCount = 0;
@@ -1697,6 +1814,10 @@ var Auth = class {
     const tick = async () => {
       if (!this.accessToken || !this.accessExpiresAt) return;
       const now = Date.now();
+      if (!this.canServeCachedToken(now)) {
+        await this.refreshAndReconcile(now);
+        return;
+      }
       const lifetimeMs = this.accessExpiresAt - now;
       if (lifetimeMs <= 0) return;
       const guessOriginalMs = Math.max(lifetimeMs, 5 * 6e4);
@@ -1844,6 +1965,7 @@ var Auth = class {
         retiredAnonUserId: data.retiredAnonUserId
       });
     }
+    if (data.anonRetirement) this.lastAnonRetirement = data.anonRetirement;
     if (data.reactivatedFromDeletion) {
       this.fireDeletionCancelled(data.user.id);
       this.emitAuthState({ event: "deletion_cancelled", user: data.user });
@@ -1878,8 +2000,10 @@ var Auth = class {
     this.user = null;
     this.accessToken = null;
     this.accessExpiresAt = 0;
+    this.clockSkewConfirmed = false;
     this.lastTakeover = null;
     this.lastDeletionCancelled = null;
+    this.lastAnonRetirement = null;
     this.pendingAnonTakeover = null;
     this.hooks.storage.remove(USER_KEY);
     this.hooks.storage.remove(TOKEN_KEY);
@@ -1905,6 +2029,13 @@ function readRotatedTokens(data) {
   if (typeof t.expiresIn !== "number" || t.expiresIn <= 0) return null;
   return { accessToken: t.accessToken, refreshToken: t.refreshToken, expiresIn: t.expiresIn };
 }
+function accessTokenExpIsFuture(token, nowMs) {
+  const claims = decodeJwtPayload(token);
+  if (!claims) return true;
+  const exp = claims.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return true;
+  return nowMs < exp * 1e3;
+}
 function decodeJwtPayload(token) {
   try {
     const parts = token.split(".");
@@ -2599,6 +2730,16 @@ var AUTH_HYDRATE_KEYS = [
 ];
 var SECURE_KEYS = ["auth_refresh_token", "auth_access_token", "auth_user"];
 var PUBLIC_KEY_RE = /^pk_(prod|staging|dev|live|test)_[A-Za-z0-9]{16,}$/;
+var STORAGE_PREFIX_RE = /^[A-Za-z0-9_.-]{1,64}$/;
+function normalizeStoragePrefix(prefix) {
+  if (prefix === void 0) return void 0;
+  if (typeof prefix !== "string" || !STORAGE_PREFIX_RE.test(prefix)) {
+    throw new Error(
+      `[sendora] init: storagePrefix must be 1-64 chars of A-Z a-z 0-9 _ . - (got ${JSON.stringify(prefix)}). Changing it signs the device out, so it is validated rather than ignored.`
+    );
+  }
+  return prefix;
+}
 var MAX_PUSH_TOKEN_BYTES = 4096;
 var MAX_PUSH_METADATA_BYTES = 4096;
 var MAX_USER_ID_LEN = 256;
@@ -2772,8 +2913,13 @@ var SendoraSDK = class {
         `[sendoracloud] apiUrl override active: ${apiUrl} \u2014 confirm this is intentional. Tokens + events will be sent here.`
       );
     }
-    if (config.secureStorage) {
-      this.storage = new Storage({ secureAdapter: config.secureStorage, secureKeys: SECURE_KEYS });
+    if (config.secureStorage || config.storagePrefix !== void 0) {
+      const prefix = normalizeStoragePrefix(config.storagePrefix);
+      this.storage = new Storage({
+        secureAdapter: config.secureStorage,
+        secureKeys: SECURE_KEYS,
+        prefix
+      });
     }
     await this.storage.hydrate([
       ANON_KEY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -56,7 +56,7 @@
   "scripts": {
     "build": "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     "typecheck": "tsc --noEmit",
-    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts"
+    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts"
   },
   "devDependencies": {
     "@types/react": "^19.2.16",