@sendoracloud/sdk-react-native 1.35.0 → 1.38.0

package/dist/index.cjs

@@ -65,6 +65,12 @@ async function getAsyncStorage() {
   })();
   return asyncStoragePromise;
 }
+var warned = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
 var Storage = class {
   constructor(opts = {}) {
     this.cache = /* @__PURE__ */ new Map();
@@ -73,6 +79,12 @@ var Storage = class {
     this.secureKeys = new Set(opts.secureKeys ?? []);
     this.prefix = opts.prefix ?? DEFAULT_PREFIX;
     this.securePrefix = opts.prefix ?? "";
+    if (this.secure === null && this.secureKeys.size > 0) {
+      warnOnce(
+        "no-secure-adapter",
+        "[sendora] No `secureStorage` adapter supplied \u2014 auth tokens (refresh token, access token, cached user) will be stored in PLAIN AsyncStorage, which is included in iOS/Android device backups. Pass `secureStorage` in init() with a Keychain/Keystore-backed adapter (e.g. expo-secure-store). The session still persists either way; this is about where the token rests."
+      );
+    }
   }
   /** The adapter-facing name for a key. Bare by default; see `prefix`. */
   secureName(key) {
@@ -126,6 +138,10 @@ var Storage = class {
         }
       }
     } catch {
+      warnOnce(
+        "secure-read-degraded",
+        "[sendora] The `secureStorage` adapter failed on read; falling back to plain AsyncStorage for this session. Tokens are preserved but no longer encrypted at rest. Check your adapter."
+      );
       if (store) {
         try {
           const legacy = await store.getItem(this.prefix + k);
@@ -142,6 +158,10 @@ var Storage = class {
     this.cache.set(key, value);
     if (this.isSecure(key)) {
       void this.secure.setItem(this.secureName(key), value).catch(() => {
+        warnOnce(
+          "secure-write-degraded",
+          "[sendora] The `secureStorage` adapter failed on write; this value fell back to plain AsyncStorage. The session is preserved but this token is no longer encrypted at rest. Check your adapter."
+        );
         void getAsyncStorage().then((store) => {
           if (store) store.setItem(this.prefix + key, value).catch(() => {
           });
@@ -208,7 +228,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.35.0",
+  version: "1.38.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",
@@ -264,7 +284,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 && tsx test/token-expiry.test.ts && tsx test/unlink.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 && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -496,6 +516,12 @@ function classifyAuthErrorKind(code, status) {
       return "credential_in_use";
     case "LAST_CREDENTIAL":
       return "last_credential";
+    // ⚠ MUST be a code case, not a status one. The tail of this function is
+    // `if (status >= 400) return "invalid_credential"`, which would otherwise
+    // claim the 403 and report a step-up refusal as a bad credential —
+    // documented as "needs NEW input", which is the opposite of the truth.
+    case "RECENT_AUTH_REQUIRED":
+      return "recent_auth_required";
     case "NOT_ANONYMOUS":
     case "FORBIDDEN_NON_ANONYMOUS":
       return "already_identified";
@@ -1582,13 +1608,24 @@ var Auth = class {
     const data = await this.unwrap(res, "MFA_CONFIRM_FAILED");
     return Boolean(data.confirmed);
   }
+  /**
+   * Disable MFA.
+   *
+   * ⚠ STEP-UP gated (s58.319): a stale `auth_time` is refused with 403
+   * `RECENT_AUTH_REQUIRED` / kind `recent_auth_required`.
+   *
+   * ⚠ Discarded its response until s58.335, and `request()` never throws on a
+   * non-2xx (it warns and returns the Response), so the refusal had nowhere to
+   * surface — the app reported MFA as off while TOTP stayed enrolled.
+   */
   async disableMfa() {
-    await post(
+    const res = await post(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
       "/api/v1/auth-service/mfa/disable",
       {},
       this.bearerHeaders()
     );
+    await this.unwrap(res, "MFA_DISABLE_FAILED");
   }
   // ============================================================
   // DEVICE SESSIONS (Bearer-authenticated)
@@ -1603,19 +1640,28 @@ var Auth = class {
     const parsed = await res.json();
     return Array.isArray(parsed.data) ? parsed.data : [];
   }
+  /**
+   * Revoke one of the caller's own sessions ("sign out that device").
+   * ⚠ Discarded its response until s58.335 — a "sign out this device" button
+   * that reports success on a failure is the one place a user acts on the claim
+   * and then stops worrying.
+   */
   async revokeSession(sessionId) {
-    await del(
+    const res = await del(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
       `/api/v1/auth-service/sessions/me/${encodeURIComponent(sessionId)}`,
       this.bearerHeaders()
     );
+    await this.unwrap(res, "SESSION_REVOKE_FAILED");
   }
+  /** Revoke every session for the caller. Same reporting defect as `revokeSession`. */
   async revokeAllSessions() {
-    await del(
+    const res = await del(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
       "/api/v1/auth-service/sessions/me",
       this.bearerHeaders()
     );
+    await this.unwrap(res, "SESSION_REVOKE_ALL_FAILED");
   }
   /**
    * Delete the signed-in user's account (Apple App Store Guideline 5.1.1(v)).
@@ -1781,7 +1827,10 @@ var Auth = class {
     if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
     const parsed = await res.json().catch(() => ({}));
     if (!res.ok || !parsed.success) {
-      throw new AuthError(parsed.error?.code ?? errCode, parsed.error?.message ?? `HTTP ${res.status}`);
+      throw new AuthError(parsed.error?.code ?? errCode, parsed.error?.message ?? `HTTP ${res.status}`, {
+        status: res.status,
+        retryAfterSeconds: readRetryAfterSeconds(parsed)
+      });
     }
     return parsed.data;
   }
@@ -2107,7 +2156,7 @@ var Auth = class {
     this.hooks.storage.remove(TOKEN_EXPIRES_KEY);
     this.hooks.storage.remove(REFRESH_KEY);
     this.stopProactiveRefreshCron();
-    await this.hooks.onAnonymousWipe();
+    await this.hooks.onAnonymousWipe(reason);
     if (reason !== "replaced") {
       this.emitAuthState({ event: "signed_out", user: null, reason });
     }
@@ -2578,33 +2627,31 @@ var Links = class {
     }
   }
   /**
-   * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-   * `installReferrer` is supplied, the SDK auto-discovers:
-   *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-   *     accurate when present).
-   *   - Otherwise: computes the canonical device fingerprint hash.
+   * Cold-launch deferred deep-link match.
+   *
+   * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+   * fingerprint on iOS when you passed no signal; it no longer does — Apple
+   * prohibits deriving a device identifier from device signals for attribution
+   * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+   * exactly that. Signal resolution now:
+   *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+   *     preferred and compliant path.
+   *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+   *     With `allowProbabilisticMatch: true` the server matches on a coarse
+   *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+   *     returns `null` and you route the user through your normal onboarding UX —
+   *     which is the expected iOS cold-launch outcome, not an error.
    *
    * Fires `onLinkOpened` with `isDeferred: true` on success.
    */
   async matchDeferred(input = {}) {
-    let fingerprintHash = input.fingerprintHash;
+    const fingerprintHash = input.fingerprintHash;
     let installReferrer = input.installReferrer;
     if (!fingerprintHash && !installReferrer) {
       installReferrer = await getPlayInstallReferrer() ?? void 0;
-      if (!installReferrer) {
-        try {
-          fingerprintHash = await computeDeviceFingerprint();
-        } catch (err) {
-          if (this.deps.debug) console.warn("[sendoracloud] fingerprint compute failed:", err);
-        }
-      }
-    }
-    if (!fingerprintHash && !installReferrer) {
-      throw new LinkError(
-        "INVALID_INPUT",
-        "links.matchDeferred: install `react-native-play-install-referrer` for Android, or ensure web crypto / expo-crypto is available for iOS fingerprint compute."
-      );
     }
+    const canMatch = !!fingerprintHash || !!installReferrer || input.allowProbabilisticMatch === true;
+    if (!canMatch) return null;
     const body = {};
     if (fingerprintHash) body.fingerprintHash = fingerprintHash;
     if (installReferrer) body.installReferrer = installReferrer;
@@ -3052,9 +3099,11 @@ var SendoraSDK = class {
         if (userId) this.storage.set(USER_ID_KEY, userId);
         else this.storage.remove(USER_ID_KEY);
       },
-      onAnonymousWipe: async () => {
-        this.anonId = uuid();
-        this.storage.set(ANON_KEY, this.anonId);
+      onAnonymousWipe: async (reason) => {
+        if (reason === "user" || reason === "account_deleted") {
+          this.anonId = uuid();
+          this.storage.set(ANON_KEY, this.anonId);
+        }
         this.userId = null;
         this.storage.remove(USER_ID_KEY);
       }

package/dist/index.d.cts

@@ -464,7 +464,7 @@ type UnlinkResult = {
  * OTP, a dismissed Game Center sheet and a 429 all leave `getUserSync()` and
  * the stored refresh token exactly as they were.
  */
-type AuthErrorKind = "network" | "server" | "rate_limited" | "invalid_credential" | "account_locked" | "credential_in_use" | "last_credential" | "already_identified" | "cancelled" | "config" | "unknown";
+type AuthErrorKind = "network" | "server" | "rate_limited" | "invalid_credential" | "account_locked" | "credential_in_use" | "last_credential" | "recent_auth_required" | "already_identified" | "cancelled" | "config" | "unknown";
 declare class AuthError extends Error {
     code: string;
     /**
@@ -497,12 +497,15 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called when the SDK switches from one identity to another via
-     * signIn() or non-anonymous signUp(). The parent rotates anonId
-     * + drops any pending events so the new user can't carry over
-     * orphaned attribution.
+     * Called from `wipeLocalIdentity` whenever the local session is cleared. The
+     * `reason` lets the parent decide whether to rotate the anonymous analytics id:
+     * it rotates ONLY at a person-boundary ("user" = explicit signOut,
+     * "account_deleted"), never on a successful sign-in/upgrade ("replaced") or an
+     * involuntary session death ("session_expired") — those are the same person, and
+     * the anon id must survive so pre-auth analytics link to them (Firebase-FID
+     * semantics; the industry norm).
      */
-    onAnonymousWipe: () => Promise<void>;
+    onAnonymousWipe: (reason: WipeReason) => Promise<void>;
     apiUrl: string;
     publicKey: string;
     debug: boolean;
@@ -565,6 +568,12 @@ type AuthStateChange = {
     user: AuthUser | null;
 };
 type AuthStateListener = (change: AuthStateChange) => void;
+/**
+ * Internal marker for a wipe that is immediately followed by a `persist()` of
+ * a NEW session (the sign-in success path). Not a sign-out — emitting one
+ * would make every successful sign-in look like a logout to subscribers.
+ */
+type WipeReason = AuthSignedOutReason | "replaced";
 declare class Auth {
     private hooks;
     private user;
@@ -1109,6 +1118,16 @@ declare class Auth {
         recoveryCodes: string[];
     }>;
     confirmMfa(code: string): Promise<boolean>;
+    /**
+     * Disable MFA.
+     *
+     * ⚠ STEP-UP gated (s58.319): a stale `auth_time` is refused with 403
+     * `RECENT_AUTH_REQUIRED` / kind `recent_auth_required`.
+     *
+     * ⚠ Discarded its response until s58.335, and `request()` never throws on a
+     * non-2xx (it warns and returns the Response), so the refusal had nowhere to
+     * surface — the app reported MFA as off while TOTP stayed enrolled.
+     */
     disableMfa(): Promise<void>;
     listMySessions(): Promise<Array<{
         id: string;
@@ -1117,7 +1136,14 @@ declare class Auth {
         lastUsedAt: string | null;
         createdAt: string;
     }>>;
+    /**
+     * Revoke one of the caller's own sessions ("sign out that device").
+     * ⚠ Discarded its response until s58.335 — a "sign out this device" button
+     * that reports success on a failure is the one place a user acts on the claim
+     * and then stops worrying.
+     */
     revokeSession(sessionId: string): Promise<void>;
+    /** Revoke every session for the caller. Same reporting defect as `revokeSession`. */
     revokeAllSessions(): Promise<void>;
     /**
      * Delete the signed-in user's account (Apple App Store Guideline 5.1.1(v)).
@@ -1383,11 +1409,33 @@ interface LinkOpenedEvent<T extends LinkData = LinkData> {
 }
 type LinkOpenedHandler<T extends LinkData = LinkData> = (event: LinkOpenedEvent<T>) => void;
 interface LinkMatchInput {
-    /** Hex-encoded SHA-256 — pass output of `computeDeviceFingerprint()`. */
+    /**
+     * Hex-encoded SHA-256 device fingerprint.
+     *
+     * ⚠ **Do not supply this on iOS.** Apple prohibits deriving a device identifier
+     * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), and it
+     * does not care which side of the network computed it — passing a hash you built
+     * on-device is the same practice. The SDK no longer computes one for you (it used
+     * to, implicitly, on iOS). Left here for the rare Android/self-hosted caller that
+     * has a legitimate deterministic hash; on iOS, omit it.
+     */
     fingerprintHash?: string;
     /** Raw Play Install Referrer. Sendora probes
      *  `react-native-play-install-referrer` automatically when this is omitted. */
     installReferrer?: string;
+    /**
+     * Opt in to probabilistic matching on iOS.
+     *
+     * iOS has no deterministic deferred-install signal (no install referrer), and the
+     * SDK will not fingerprint the device. The only remaining matcher is the server's
+     * coarse IP + timestamp window — the same class of practice Apple scrutinises, and
+     * it collides across a shared NAT / iCloud Private Relay. So it is **off by
+     * default**: without this flag, `matchDeferred()` on iOS matches nothing and
+     * returns `null` (route the user through your normal onboarding UX). Set it only
+     * if you accept the accuracy and compliance trade-off. No effect on Android, where
+     * the Play Install Referrer is deterministic.
+     */
+    allowProbabilisticMatch?: boolean;
     iosBundleId?: string;
     androidPackageName?: string;
 }
@@ -1420,12 +1468,14 @@ interface LinkStats {
  */
 declare function extractShortcodeFromUrl(url: string, linkDomain?: string): string | null;
 /**
- * Canonical device-fingerprint recipe. Identical byte-for-byte across the
- * RN / iOS / Android SDKs so a click logged from one platform and an
- * install completing on another won't accidentally match.
+ * Canonical device-fingerprint recipe (`${platform}|${screenW}x${screenH}|${timezone}|${locale}`
+ * → lowercase hex SHA-256), identical across the RN / iOS / Android SDKs.
  *
- * Input: `${platform}|${screenW}x${screenH}|${timezone}|${locale}`
- * Output: lowercase hex SHA-256.
+ * @deprecated ⚠ Do not use on iOS. Apple prohibits deriving a device identifier
+ * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), regardless
+ * of ATT — and this is exactly that. `matchDeferred()` no longer calls it
+ * implicitly. It is retained only for an Android/self-hosted caller with a
+ * legitimate deterministic use, and is slated for removal in a future major.
  */
 declare function computeDeviceFingerprint(): Promise<string>;
 /** Probe optional `react-native-play-install-referrer` peer. Returns the
@@ -1494,11 +1544,20 @@ declare class Links {
      */
     handleUniversalLink(url: string): Promise<boolean>;
     /**
-     * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-     * `installReferrer` is supplied, the SDK auto-discovers:
-     *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-     *     accurate when present).
-     *   - Otherwise: computes the canonical device fingerprint hash.
+     * Cold-launch deferred deep-link match.
+     *
+     * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+     * fingerprint on iOS when you passed no signal; it no longer does — Apple
+     * prohibits deriving a device identifier from device signals for attribution
+     * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+     * exactly that. Signal resolution now:
+     *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+     *     preferred and compliant path.
+     *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+     *     With `allowProbabilisticMatch: true` the server matches on a coarse
+     *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+     *     returns `null` and you route the user through your normal onboarding UX —
+     *     which is the expected iOS cold-launch outcome, not an error.
      *
      * Fires `onLinkOpened` with `isDeferred: true` on success.
      */

package/dist/index.d.ts

@@ -464,7 +464,7 @@ type UnlinkResult = {
  * OTP, a dismissed Game Center sheet and a 429 all leave `getUserSync()` and
  * the stored refresh token exactly as they were.
  */
-type AuthErrorKind = "network" | "server" | "rate_limited" | "invalid_credential" | "account_locked" | "credential_in_use" | "last_credential" | "already_identified" | "cancelled" | "config" | "unknown";
+type AuthErrorKind = "network" | "server" | "rate_limited" | "invalid_credential" | "account_locked" | "credential_in_use" | "last_credential" | "recent_auth_required" | "already_identified" | "cancelled" | "config" | "unknown";
 declare class AuthError extends Error {
     code: string;
     /**
@@ -497,12 +497,15 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called when the SDK switches from one identity to another via
-     * signIn() or non-anonymous signUp(). The parent rotates anonId
-     * + drops any pending events so the new user can't carry over
-     * orphaned attribution.
+     * Called from `wipeLocalIdentity` whenever the local session is cleared. The
+     * `reason` lets the parent decide whether to rotate the anonymous analytics id:
+     * it rotates ONLY at a person-boundary ("user" = explicit signOut,
+     * "account_deleted"), never on a successful sign-in/upgrade ("replaced") or an
+     * involuntary session death ("session_expired") — those are the same person, and
+     * the anon id must survive so pre-auth analytics link to them (Firebase-FID
+     * semantics; the industry norm).
      */
-    onAnonymousWipe: () => Promise<void>;
+    onAnonymousWipe: (reason: WipeReason) => Promise<void>;
     apiUrl: string;
     publicKey: string;
     debug: boolean;
@@ -565,6 +568,12 @@ type AuthStateChange = {
     user: AuthUser | null;
 };
 type AuthStateListener = (change: AuthStateChange) => void;
+/**
+ * Internal marker for a wipe that is immediately followed by a `persist()` of
+ * a NEW session (the sign-in success path). Not a sign-out — emitting one
+ * would make every successful sign-in look like a logout to subscribers.
+ */
+type WipeReason = AuthSignedOutReason | "replaced";
 declare class Auth {
     private hooks;
     private user;
@@ -1109,6 +1118,16 @@ declare class Auth {
         recoveryCodes: string[];
     }>;
     confirmMfa(code: string): Promise<boolean>;
+    /**
+     * Disable MFA.
+     *
+     * ⚠ STEP-UP gated (s58.319): a stale `auth_time` is refused with 403
+     * `RECENT_AUTH_REQUIRED` / kind `recent_auth_required`.
+     *
+     * ⚠ Discarded its response until s58.335, and `request()` never throws on a
+     * non-2xx (it warns and returns the Response), so the refusal had nowhere to
+     * surface — the app reported MFA as off while TOTP stayed enrolled.
+     */
     disableMfa(): Promise<void>;
     listMySessions(): Promise<Array<{
         id: string;
@@ -1117,7 +1136,14 @@ declare class Auth {
         lastUsedAt: string | null;
         createdAt: string;
     }>>;
+    /**
+     * Revoke one of the caller's own sessions ("sign out that device").
+     * ⚠ Discarded its response until s58.335 — a "sign out this device" button
+     * that reports success on a failure is the one place a user acts on the claim
+     * and then stops worrying.
+     */
     revokeSession(sessionId: string): Promise<void>;
+    /** Revoke every session for the caller. Same reporting defect as `revokeSession`. */
     revokeAllSessions(): Promise<void>;
     /**
      * Delete the signed-in user's account (Apple App Store Guideline 5.1.1(v)).
@@ -1383,11 +1409,33 @@ interface LinkOpenedEvent<T extends LinkData = LinkData> {
 }
 type LinkOpenedHandler<T extends LinkData = LinkData> = (event: LinkOpenedEvent<T>) => void;
 interface LinkMatchInput {
-    /** Hex-encoded SHA-256 — pass output of `computeDeviceFingerprint()`. */
+    /**
+     * Hex-encoded SHA-256 device fingerprint.
+     *
+     * ⚠ **Do not supply this on iOS.** Apple prohibits deriving a device identifier
+     * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), and it
+     * does not care which side of the network computed it — passing a hash you built
+     * on-device is the same practice. The SDK no longer computes one for you (it used
+     * to, implicitly, on iOS). Left here for the rare Android/self-hosted caller that
+     * has a legitimate deterministic hash; on iOS, omit it.
+     */
     fingerprintHash?: string;
     /** Raw Play Install Referrer. Sendora probes
      *  `react-native-play-install-referrer` automatically when this is omitted. */
     installReferrer?: string;
+    /**
+     * Opt in to probabilistic matching on iOS.
+     *
+     * iOS has no deterministic deferred-install signal (no install referrer), and the
+     * SDK will not fingerprint the device. The only remaining matcher is the server's
+     * coarse IP + timestamp window — the same class of practice Apple scrutinises, and
+     * it collides across a shared NAT / iCloud Private Relay. So it is **off by
+     * default**: without this flag, `matchDeferred()` on iOS matches nothing and
+     * returns `null` (route the user through your normal onboarding UX). Set it only
+     * if you accept the accuracy and compliance trade-off. No effect on Android, where
+     * the Play Install Referrer is deterministic.
+     */
+    allowProbabilisticMatch?: boolean;
     iosBundleId?: string;
     androidPackageName?: string;
 }
@@ -1420,12 +1468,14 @@ interface LinkStats {
  */
 declare function extractShortcodeFromUrl(url: string, linkDomain?: string): string | null;
 /**
- * Canonical device-fingerprint recipe. Identical byte-for-byte across the
- * RN / iOS / Android SDKs so a click logged from one platform and an
- * install completing on another won't accidentally match.
+ * Canonical device-fingerprint recipe (`${platform}|${screenW}x${screenH}|${timezone}|${locale}`
+ * → lowercase hex SHA-256), identical across the RN / iOS / Android SDKs.
  *
- * Input: `${platform}|${screenW}x${screenH}|${timezone}|${locale}`
- * Output: lowercase hex SHA-256.
+ * @deprecated ⚠ Do not use on iOS. Apple prohibits deriving a device identifier
+ * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), regardless
+ * of ATT — and this is exactly that. `matchDeferred()` no longer calls it
+ * implicitly. It is retained only for an Android/self-hosted caller with a
+ * legitimate deterministic use, and is slated for removal in a future major.
  */
 declare function computeDeviceFingerprint(): Promise<string>;
 /** Probe optional `react-native-play-install-referrer` peer. Returns the
@@ -1494,11 +1544,20 @@ declare class Links {
      */
     handleUniversalLink(url: string): Promise<boolean>;
     /**
-     * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-     * `installReferrer` is supplied, the SDK auto-discovers:
-     *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-     *     accurate when present).
-     *   - Otherwise: computes the canonical device fingerprint hash.
+     * Cold-launch deferred deep-link match.
+     *
+     * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+     * fingerprint on iOS when you passed no signal; it no longer does — Apple
+     * prohibits deriving a device identifier from device signals for attribution
+     * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+     * exactly that. Signal resolution now:
+     *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+     *     preferred and compliant path.
+     *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+     *     With `allowProbabilisticMatch: true` the server matches on a coarse
+     *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+     *     returns `null` and you route the user through your normal onboarding UX —
+     *     which is the expected iOS cold-launch outcome, not an error.
      *
      * Fires `onLinkOpened` with `isDeferred: true` on success.
      */

package/dist/index.js

@@ -20,6 +20,12 @@ async function getAsyncStorage() {
   })();
   return asyncStoragePromise;
 }
+var warned = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
 var Storage = class {
   constructor(opts = {}) {
     this.cache = /* @__PURE__ */ new Map();
@@ -28,6 +34,12 @@ var Storage = class {
     this.secureKeys = new Set(opts.secureKeys ?? []);
     this.prefix = opts.prefix ?? DEFAULT_PREFIX;
     this.securePrefix = opts.prefix ?? "";
+    if (this.secure === null && this.secureKeys.size > 0) {
+      warnOnce(
+        "no-secure-adapter",
+        "[sendora] No `secureStorage` adapter supplied \u2014 auth tokens (refresh token, access token, cached user) will be stored in PLAIN AsyncStorage, which is included in iOS/Android device backups. Pass `secureStorage` in init() with a Keychain/Keystore-backed adapter (e.g. expo-secure-store). The session still persists either way; this is about where the token rests."
+      );
+    }
   }
   /** The adapter-facing name for a key. Bare by default; see `prefix`. */
   secureName(key) {
@@ -81,6 +93,10 @@ var Storage = class {
         }
       }
     } catch {
+      warnOnce(
+        "secure-read-degraded",
+        "[sendora] The `secureStorage` adapter failed on read; falling back to plain AsyncStorage for this session. Tokens are preserved but no longer encrypted at rest. Check your adapter."
+      );
       if (store) {
         try {
           const legacy = await store.getItem(this.prefix + k);
@@ -97,6 +113,10 @@ var Storage = class {
     this.cache.set(key, value);
     if (this.isSecure(key)) {
       void this.secure.setItem(this.secureName(key), value).catch(() => {
+        warnOnce(
+          "secure-write-degraded",
+          "[sendora] The `secureStorage` adapter failed on write; this value fell back to plain AsyncStorage. The session is preserved but this token is no longer encrypted at rest. Check your adapter."
+        );
         void getAsyncStorage().then((store) => {
           if (store) store.setItem(this.prefix + key, value).catch(() => {
           });
@@ -163,7 +183,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.35.0",
+  version: "1.38.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",
@@ -219,7 +239,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 && tsx test/token-expiry.test.ts && tsx test/unlink.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 && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -451,6 +471,12 @@ function classifyAuthErrorKind(code, status) {
       return "credential_in_use";
     case "LAST_CREDENTIAL":
       return "last_credential";
+    // ⚠ MUST be a code case, not a status one. The tail of this function is
+    // `if (status >= 400) return "invalid_credential"`, which would otherwise
+    // claim the 403 and report a step-up refusal as a bad credential —
+    // documented as "needs NEW input", which is the opposite of the truth.
+    case "RECENT_AUTH_REQUIRED":
+      return "recent_auth_required";
     case "NOT_ANONYMOUS":
     case "FORBIDDEN_NON_ANONYMOUS":
       return "already_identified";
@@ -1537,13 +1563,24 @@ var Auth = class {
     const data = await this.unwrap(res, "MFA_CONFIRM_FAILED");
     return Boolean(data.confirmed);
   }
+  /**
+   * Disable MFA.
+   *
+   * ⚠ STEP-UP gated (s58.319): a stale `auth_time` is refused with 403
+   * `RECENT_AUTH_REQUIRED` / kind `recent_auth_required`.
+   *
+   * ⚠ Discarded its response until s58.335, and `request()` never throws on a
+   * non-2xx (it warns and returns the Response), so the refusal had nowhere to
+   * surface — the app reported MFA as off while TOTP stayed enrolled.
+   */
   async disableMfa() {
-    await post(
+    const res = await post(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
       "/api/v1/auth-service/mfa/disable",
       {},
       this.bearerHeaders()
     );
+    await this.unwrap(res, "MFA_DISABLE_FAILED");
   }
   // ============================================================
   // DEVICE SESSIONS (Bearer-authenticated)
@@ -1558,19 +1595,28 @@ var Auth = class {
     const parsed = await res.json();
     return Array.isArray(parsed.data) ? parsed.data : [];
   }
+  /**
+   * Revoke one of the caller's own sessions ("sign out that device").
+   * ⚠ Discarded its response until s58.335 — a "sign out this device" button
+   * that reports success on a failure is the one place a user acts on the claim
+   * and then stops worrying.
+   */
   async revokeSession(sessionId) {
-    await del(
+    const res = await del(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
       `/api/v1/auth-service/sessions/me/${encodeURIComponent(sessionId)}`,
       this.bearerHeaders()
     );
+    await this.unwrap(res, "SESSION_REVOKE_FAILED");
   }
+  /** Revoke every session for the caller. Same reporting defect as `revokeSession`. */
   async revokeAllSessions() {
-    await del(
+    const res = await del(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
       "/api/v1/auth-service/sessions/me",
       this.bearerHeaders()
     );
+    await this.unwrap(res, "SESSION_REVOKE_ALL_FAILED");
   }
   /**
    * Delete the signed-in user's account (Apple App Store Guideline 5.1.1(v)).
@@ -1736,7 +1782,10 @@ var Auth = class {
     if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
     const parsed = await res.json().catch(() => ({}));
     if (!res.ok || !parsed.success) {
-      throw new AuthError(parsed.error?.code ?? errCode, parsed.error?.message ?? `HTTP ${res.status}`);
+      throw new AuthError(parsed.error?.code ?? errCode, parsed.error?.message ?? `HTTP ${res.status}`, {
+        status: res.status,
+        retryAfterSeconds: readRetryAfterSeconds(parsed)
+      });
     }
     return parsed.data;
   }
@@ -2062,7 +2111,7 @@ var Auth = class {
     this.hooks.storage.remove(TOKEN_EXPIRES_KEY);
     this.hooks.storage.remove(REFRESH_KEY);
     this.stopProactiveRefreshCron();
-    await this.hooks.onAnonymousWipe();
+    await this.hooks.onAnonymousWipe(reason);
     if (reason !== "replaced") {
       this.emitAuthState({ event: "signed_out", user: null, reason });
     }
@@ -2538,33 +2587,31 @@ var Links = class {
     }
   }
   /**
-   * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-   * `installReferrer` is supplied, the SDK auto-discovers:
-   *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-   *     accurate when present).
-   *   - Otherwise: computes the canonical device fingerprint hash.
+   * Cold-launch deferred deep-link match.
+   *
+   * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+   * fingerprint on iOS when you passed no signal; it no longer does — Apple
+   * prohibits deriving a device identifier from device signals for attribution
+   * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+   * exactly that. Signal resolution now:
+   *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+   *     preferred and compliant path.
+   *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+   *     With `allowProbabilisticMatch: true` the server matches on a coarse
+   *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+   *     returns `null` and you route the user through your normal onboarding UX —
+   *     which is the expected iOS cold-launch outcome, not an error.
    *
    * Fires `onLinkOpened` with `isDeferred: true` on success.
    */
   async matchDeferred(input = {}) {
-    let fingerprintHash = input.fingerprintHash;
+    const fingerprintHash = input.fingerprintHash;
     let installReferrer = input.installReferrer;
     if (!fingerprintHash && !installReferrer) {
       installReferrer = await getPlayInstallReferrer() ?? void 0;
-      if (!installReferrer) {
-        try {
-          fingerprintHash = await computeDeviceFingerprint();
-        } catch (err) {
-          if (this.deps.debug) console.warn("[sendoracloud] fingerprint compute failed:", err);
-        }
-      }
-    }
-    if (!fingerprintHash && !installReferrer) {
-      throw new LinkError(
-        "INVALID_INPUT",
-        "links.matchDeferred: install `react-native-play-install-referrer` for Android, or ensure web crypto / expo-crypto is available for iOS fingerprint compute."
-      );
     }
+    const canMatch = !!fingerprintHash || !!installReferrer || input.allowProbabilisticMatch === true;
+    if (!canMatch) return null;
     const body = {};
     if (fingerprintHash) body.fingerprintHash = fingerprintHash;
     if (installReferrer) body.installReferrer = installReferrer;
@@ -3012,9 +3059,11 @@ var SendoraSDK = class {
         if (userId) this.storage.set(USER_ID_KEY, userId);
         else this.storage.remove(USER_ID_KEY);
       },
-      onAnonymousWipe: async () => {
-        this.anonId = uuid();
-        this.storage.set(ANON_KEY, this.anonId);
+      onAnonymousWipe: async (reason) => {
+        if (reason === "user" || reason === "account_deleted") {
+          this.anonId = uuid();
+          this.storage.set(ANON_KEY, this.anonId);
+        }
         this.userId = null;
         this.storage.remove(USER_ID_KEY);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "1.35.0",
+  "version": "1.38.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 && tsx test/token-expiry.test.ts && tsx test/unlink.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 && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts"
   },
   "devDependencies": {
     "@types/react": "^19.2.16",