@ethora/chat-component-rn 26.8.1 → 26.8.2

package/src/helpers/persistCrypto.ts

@@ -0,0 +1,127 @@
+import CryptoJS from 'crypto-js';
+import { secureGet, secureSet } from './secureKeyValue';
+
+// AES-256-CBC at rest for the bulk persisted state (message history +
+// room list) that `roomStore/persistence.ts` writes to AsyncStorage.
+// This is envelope encryption, not a SecureStore write of the payload
+// itself: expo-secure-store has historically capped a single value's
+// size on Android (chunking exists in newer releases, but the payload
+// here is unbounded — up to MESSAGE_LIMIT messages per room, times
+// every room), so only the small symmetric KEY goes through the
+// platform Keychain/Keystore (`secureKeyValue.ts`); the ciphertext
+// itself stays in plain AsyncStorage, unreadable without that key.
+const CIPHER_KEY_STORE_KEY = 'ethora_history_cipher_key';
+const ENVELOPE_VERSION = 1;
+const KEY_BYTES = 32; // AES-256
+const IV_BYTES = 16; // one AES block
+
+interface Envelope {
+  v: number;
+  iv: string; // base64
+  ct: string; // base64 ciphertext
+}
+
+/**
+ * `crypto-js`'s own `WordArray.random()` falls back to `Math.random()`
+ * when it can't detect a browser `window.crypto` — not safe for key/IV
+ * material. `react-native-get-random-values` (a REQUIRED peer
+ * dependency, imported at the top of `main.ts`/`index.js` before
+ * anything else in the SDK runs) polyfills the real thing onto
+ * `global.crypto.getRandomValues` instead; source bytes from that and
+ * hand them to crypto-js as a WordArray rather than trust its default.
+ */
+const randomWordArray = (byteLength: number): CryptoJS.lib.WordArray => {
+  const bytes = new Uint8Array(byteLength);
+  (global as any).crypto.getRandomValues(bytes);
+  const words: number[] = [];
+  for (let i = 0; i < bytes.length; i += 4) {
+    words.push(
+      ((bytes[i] || 0) << 24) |
+        ((bytes[i + 1] || 0) << 16) |
+        ((bytes[i + 2] || 0) << 8) |
+        (bytes[i + 3] || 0)
+    );
+  }
+  return CryptoJS.lib.WordArray.create(words, byteLength);
+};
+
+let cachedKeyPromise: Promise<CryptoJS.lib.WordArray> | null = null;
+
+/**
+ * One AES-256 key per install, generated on first use and persisted
+ * through the SecureStore/Keychain bridge. Reused across logins on
+ * purpose: the ciphertext it protects is deleted wholesale on logout
+ * (`clearPersistedState`), so there is no cross-account data for a
+ * stable key to expose — only the encrypted blob of whoever is
+ * currently logged in ever exists on disk at a given time.
+ */
+const loadOrCreateKey = (): Promise<CryptoJS.lib.WordArray> => {
+  if (cachedKeyPromise) {return cachedKeyPromise;}
+  cachedKeyPromise = (async () => {
+    const existing = await secureGet(CIPHER_KEY_STORE_KEY);
+    if (existing) {
+      return CryptoJS.enc.Base64.parse(existing);
+    }
+    const key = randomWordArray(KEY_BYTES);
+    await secureSet(CIPHER_KEY_STORE_KEY, CryptoJS.enc.Base64.stringify(key));
+    return key;
+  })();
+  return cachedKeyPromise;
+};
+
+/** Encrypt a JSON-serialisable payload for storage. Returns the string to persist. */
+export async function encryptForPersist(plaintext: string): Promise<string> {
+  const key = await loadOrCreateKey();
+  const iv = randomWordArray(IV_BYTES);
+  const encrypted = CryptoJS.AES.encrypt(plaintext, key, {
+    iv,
+    mode: CryptoJS.mode.CBC,
+    padding: CryptoJS.pad.Pkcs7,
+  });
+  const envelope: Envelope = {
+    v: ENVELOPE_VERSION,
+    iv: CryptoJS.enc.Base64.stringify(iv),
+    ct: encrypted.ciphertext.toString(CryptoJS.enc.Base64),
+  };
+  return JSON.stringify(envelope);
+}
+
+/**
+ * Decrypt a value previously written by `encryptForPersist`. Returns
+ * null (never throws) for anything that isn't a valid envelope for the
+ * current key — including a plaintext blob from a pre-encryption
+ * install: the app just re-hydrates that room/history from the server,
+ * same as any other empty-cache cold start.
+ */
+export async function decryptFromPersist(
+  stored: string
+): Promise<string | null> {
+  try {
+    const envelope = JSON.parse(stored) as Partial<Envelope>;
+    if (
+      !envelope ||
+      envelope.v !== ENVELOPE_VERSION ||
+      !envelope.iv ||
+      !envelope.ct
+    ) {
+      return null;
+    }
+    const key = await loadOrCreateKey();
+    const iv = CryptoJS.enc.Base64.parse(envelope.iv);
+    const ciphertext = CryptoJS.enc.Base64.parse(envelope.ct);
+    const decrypted = CryptoJS.AES.decrypt(
+      { ciphertext } as CryptoJS.lib.CipherParams,
+      key,
+      { iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 }
+    );
+    const plaintext = decrypted.toString(CryptoJS.enc.Utf8);
+    return plaintext || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Test seam only. */
+export const __resetPersistCryptoKeyForTests = (): void => {
+  cachedKeyPromise = null;
+};

package/src/helpers/pickImageAsset.ts

@@ -0,0 +1,68 @@
+import { Alert, Linking } from 'react-native';
+import * as ImagePicker from 'expo-image-picker';
+
+/**
+ * A picked image in the shape React Native's FormData understands.
+ *
+ * NOT a web `File`: RN streams a multipart part straight from a `file://`
+ * uri and has no usable Blob/File/atob path. Screens ported from the web
+ * client used to carry base64 -> Blob -> File helpers that could never
+ * have run here.
+ */
+export interface PickedImage {
+  uri: string;
+  type: string;
+  name: string;
+}
+
+/**
+ * Ask for library permission, open the picker, and normalise the result.
+ *
+ * Returns `null` for every non-error outcome — permission refused, user
+ * cancelled — so call sites can simply keep their current value.
+ *
+ * Exists because the avatar pickers are wired to `onPress`, which hands
+ * the callback a SyntheticEvent. Storing that event as "the image" (what
+ * two screens used to do) rendered a pooled event as an <Image source>
+ * and then crashed with "Property is not configurable" when React tried
+ * to release it — on top of never letting the user pick anything.
+ */
+export const pickImageAsset = async (): Promise<PickedImage | null> => {
+  try {
+    // expo-image-picker owns the permission prompt internally and
+    // returns a `granted` flag.
+    const perm = await ImagePicker.requestMediaLibraryPermissionsAsync();
+    if (!perm.granted) {
+      Alert.alert(
+        'Permission required',
+        'Photo library permission is needed to select images.',
+        [
+          { text: 'Cancel', style: 'cancel' },
+          { text: 'Open Settings', onPress: () => Linking.openSettings() },
+        ]
+      );
+      return null;
+    }
+
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ['images'],
+      allowsEditing: true,
+      aspect: [1, 1],
+      quality: 0.8,
+    });
+    if (result.canceled || !result.assets?.[0]) {
+      return null;
+    }
+
+    const asset = result.assets[0];
+    const originalName = asset.fileName || asset.uri.split('/').pop();
+    return {
+      uri: asset.uri,
+      type: asset.mimeType || 'image/jpeg',
+      name: originalName || `image_${Date.now()}.jpg`,
+    };
+  } catch (error) {
+    console.error('Failed to pick an image:', error);
+    return null;
+  }
+};

package/src/helpers/pushPayload.ts

@@ -0,0 +1,62 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { store } from '../roomStore';
+import {
+  clearPendingNotificationJid,
+  setCurrentRoom,
+  setPendingNotificationJid,
+} from '../roomStore/roomsSlice';
+import { handleCallPush } from './incomingCallFromPush';
+import { normalizeRoomJid } from './normalizeRoomJid';
+
+export type PushPayloadOutcome = 'call' | 'room' | 'pending' | 'unknown';
+
+export const PENDING_NOTIFICATION_JID_KEY = 'ethora_pending_notification_jid';
+export const PENDING_NOTIFICATION_TTL_MS = 5 * 60 * 1000;
+
+export const readPendingJid = async (): Promise<string | null> => {
+  try {
+    const raw = await AsyncStorage.getItem(PENDING_NOTIFICATION_JID_KEY);
+    if (!raw) {return null;}
+    if (raw.startsWith('{')) {
+      const { jid, at } = JSON.parse(raw) as { jid?: string; at?: number };
+      if (!jid || !at || Date.now() - at > PENDING_NOTIFICATION_TTL_MS) {
+        await AsyncStorage.removeItem(PENDING_NOTIFICATION_JID_KEY);
+        return null;
+      }
+      return jid;
+    }
+    return raw;
+  } catch {
+    return null;
+  }
+};
+
+export const openRoomFromPush = (jid: string): 'room' | 'pending' => {
+  const state = store.getState();
+  const conference = state.chatSettingStore?.config?.xmppSettings?.conference;
+  const full = normalizeRoomJid(jid, conference);
+
+  AsyncStorage.setItem(
+    PENDING_NOTIFICATION_JID_KEY,
+    JSON.stringify({ jid: full, at: Date.now() })
+  ).catch(() => undefined);
+  if (state.rooms?.rooms?.[full]) {
+    store.dispatch(clearPendingNotificationJid());
+    store.dispatch(setCurrentRoom({ roomJID: full }));
+    return 'room';
+  }
+  store.dispatch(setPendingNotificationJid(full));
+  return 'pending';
+};
+
+export const handlePushPayload = (
+  data: Record<string, unknown> | null | undefined
+): PushPayloadOutcome => {
+  if (!data) {return 'unknown';}
+  if (handleCallPush(data as Record<string, any>)) {return 'call';}
+  const jid = data.jid ?? data.chatJid ?? data.roomJid ?? data.roomJID;
+  if (typeof jid === 'string' && jid) {
+    return openRoomFromPush(jid);
+  }
+  return 'unknown';
+};

package/src/helpers/resolveInitBeforeLoadUser.ts

@@ -1,12 +1,12 @@
-import http, { setBaseURL } from '../networking/apiClient';
+import { setBaseURL } from '../networking/apiClient';
+import { refreshAuthTokens, isRefreshFatalError } from '../networking/authRefresh';
 import { loginViaJwt } from '../networking/api-requests/auth.api';
 import { getMyUser } from '../networking/api-requests/user.api';
 import { IConfig, User } from '../types/types';
 import { store } from '../roomStore';
 import { setUser } from '../roomStore/chatSettingsSlice';
 import { walletToUsername } from './walletUsername';
-import { asyncLocalStorage } from '../hooks/useLocalStorage';
-import { localStorageConstants } from './constants/LOCAL_STORAGE';
+import { secureUserStorage } from './secureUserStorage';
 
 interface ResolveInitBeforeLoadUserOptions {
   config?: IConfig;
@@ -46,15 +46,107 @@ const normalizeUserForXmpp = (user?: User | null): User | null => {
   return { ...user, xmppUsername: normalizedXmppUsername };
 };
 
+// Hermes has no atob/Buffer; hand-decode just enough base64url to read a
+// JWT's `iat`. Claims are ASCII so the byte-per-char string is fine.
+const B64_ALPHABET =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+const readJwtIat = (token?: string | null): number => {
+  if (!token || typeof token !== 'string') {return 0;}
+  const part = token.split('.')[1];
+  if (!part) {return 0;}
+  try {
+    const clean = part.replace(/-/g, '+').replace(/_/g, '/');
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (let i = 0; i < clean.length; i++) {
+      const idx = B64_ALPHABET.indexOf(clean[i]);
+      if (idx === -1) {continue;}
+      buffer = (buffer << 6) | idx;
+      bits += 6;
+      if (bits >= 8) {
+        bits -= 8;
+        out += String.fromCharCode((buffer >> bits) & 0xff);
+      }
+    }
+    const iat = JSON.parse(out)?.iat;
+    return typeof iat === 'number' ? iat : 0;
+  } catch {
+    return 0;
+  }
+};
+
+/**
+ * A `userLogin.user` is typically a snapshot the host captured at ITS
+ * login time and re-presents verbatim on every mount, while this SDK
+ * keeps rotating the session and persisting the newest pair to
+ * `ETHORA_USER`. Taking the snapshot as-is therefore discards the live
+ * session in favour of an ever-aging copy: media goes blank the moment
+ * the snapshot has no `fileToken` (secure-files URLs 401 without it),
+ * and once the snapshot's refresh token ages out entirely the account
+ * looks dead even though the SDK held a working session all along.
+ *
+ * So, for the SAME account only, prefer whichever refresh pair was
+ * minted later (JWT `iat` decides — a host that genuinely re-logged-in
+ * hands us newer tokens and wins), and fill in a missing `fileToken`
+ * from the persisted copy either way.
+ */
+const adoptFresherPersistedSession = async (candidate: User): Promise<User> => {
+  try {
+    const stored = await secureUserStorage().get();
+    if (!stored) {return candidate;}
+
+    const sameUser =
+      (candidate._id && stored._id && candidate._id === stored._id) ||
+      (candidate.xmppUsername &&
+        stored.xmppUsername &&
+        candidate.xmppUsername === stored.xmppUsername);
+    if (!sameUser) {return candidate;}
+
+    const merged = { ...candidate };
+
+    if (
+      stored.refreshToken &&
+      readJwtIat(stored.refreshToken) > readJwtIat(candidate.refreshToken)
+    ) {
+      merged.refreshToken = stored.refreshToken;
+      if (stored.token) {merged.token = stored.token;}
+      if (stored.fileToken) {merged.fileToken = stored.fileToken;}
+    }
+
+    if (!merged.fileToken && stored.fileToken) {
+      merged.fileToken = stored.fileToken;
+    }
+
+    return merged;
+  } catch {
+    return candidate;
+  }
+};
+
+/**
+ * Bootstrap rotation.
+ *
+ * Was a second, independent `/users/login/refresh` caller that bypassed
+ * every lock in the SDK — and, worse, only wrote the rotated token to
+ * the store on the happy path, so several of the early-return branches
+ * below used to drop it. Under the backend's reuse detection a dropped
+ * rotation means the next launch presents a burned token and the
+ * session is killed.
+ *
+ * `refreshAuthTokens` persists the new pair before it resolves, so by
+ * the time this returns the rotation is safe no matter which branch the
+ * caller takes afterwards. The explicit token is required here: during
+ * bootstrap the candidate session isn't in the store yet.
+ */
 const refreshWithToken = async (refreshToken: string) => {
-  const response = await http.post(
-    '/users/login/refresh',
-    {},
-    { headers: { Authorization: refreshToken } }
-  );
+  const result = await refreshAuthTokens({ refreshToken });
   return {
-    token: response?.data?.token || '',
-    refreshToken: response?.data?.refreshToken || refreshToken,
+    token: result.token,
+    refreshToken: result.refreshToken || refreshToken,
+    xmppPassword: result.xmppPassword || '',
+    fileToken: result.fileToken || '',
   };
 };
 
@@ -87,11 +179,15 @@ const tryHydrateViaMy = async (
 
   let workingToken = candidate?.token || '';
   let workingRefresh = candidate?.refreshToken || '';
+  let rotatedXmppPassword = '';
+  let workingFileToken = candidate?.fileToken || '';
 
   const candidateWithCurrentTokens = (): User => ({
     ...candidate,
     token: workingToken || candidate.token,
     refreshToken: workingRefresh || candidate.refreshToken,
+    xmppPassword: rotatedXmppPassword || candidate.xmppPassword,
+    fileToken: workingFileToken || candidate.fileToken,
   });
 
   const fallbackWithCreds = (): User | null => {
@@ -107,6 +203,8 @@ const tryHydrateViaMy = async (
       if (merged) {
         merged.token = workingToken || merged.token;
         merged.refreshToken = workingRefresh || merged.refreshToken;
+        merged.xmppPassword = rotatedXmppPassword || merged.xmppPassword;
+        merged.fileToken = workingFileToken || merged.fileToken;
       }
       return merged;
     } catch (error) {
@@ -127,6 +225,8 @@ const tryHydrateViaMy = async (
     const refreshed = await refreshWithToken(workingRefresh);
     workingToken = refreshed.token;
     workingRefresh = refreshed.refreshToken;
+    rotatedXmppPassword = refreshed.xmppPassword || rotatedXmppPassword;
+    workingFileToken = refreshed.fileToken || workingFileToken;
 
     try {
       const myUser = await getMyUser({ token: workingToken, endpoint: myEndpoint });
@@ -136,6 +236,8 @@ const tryHydrateViaMy = async (
       if (merged) {
         merged.token = workingToken || merged.token;
         merged.refreshToken = workingRefresh || merged.refreshToken;
+        merged.xmppPassword = rotatedXmppPassword || merged.xmppPassword;
+        merged.fileToken = workingFileToken || merged.fileToken;
       }
       return merged;
     } catch (myError) {
@@ -147,6 +249,11 @@ const tryHydrateViaMy = async (
     }
   } catch (error) {
     if (signal?.aborted || isAbortError(error)) {return null;}
+    // A fatal refresh verdict (reuse detected / token not found / stale
+    // with nothing newer around) carries no HTTP response, so it would
+    // otherwise fall through to `throw` — the session is simply dead,
+    // which for bootstrap means "nothing to restore".
+    if (isRefreshFatalError(error)) {return null;}
     if (isAuthError(error)) {return null;}
     throw error;
   }
@@ -162,13 +269,15 @@ export const resolveInitBeforeLoadUser = async (
     setBaseURL(config.baseUrl, config.customAppToken);
   }
 
-  const myEndpoint = config?.initBeforeLoadAuth?.myEndpoint || '/users/my';
+  const myEndpoint = config?.initBeforeLoadAuth?.myEndpoint || '/v1/users/my';
 
   // Priority 1: explicit userLogin
   const explicitUser = config?.userLogin?.enabled ? config?.userLogin?.user : null;
   if (explicitUser) {
     const candidate = normalizeUserForXmpp(explicitUser);
-    if (candidate && hasXmppCredentials(candidate)) {return candidate;}
+    if (candidate && hasXmppCredentials(candidate)) {
+      return await adoptFresherPersistedSession(candidate);
+    }
 
     const hydrated = await tryHydrateViaMy(explicitUser, myEndpoint, signal).catch(
       () => null
@@ -217,13 +326,13 @@ export const resolveInitBeforeLoadUser = async (
 
   // Priority 5: persisted user in AsyncStorage
   try {
-    const storedUser = await asyncLocalStorage<User>(localStorageConstants.ETHORA_USER).get();
+    const storedUser = await secureUserStorage().get();
     if (storedUser && (storedUser.token || storedUser.refreshToken || storedUser.xmppPassword)) {
       const hydrated = await tryHydrateViaMy(storedUser, myEndpoint, signal).catch(
         () => null
       );
       if (hydrated && hasXmppCredentials(hydrated)) {return hydrated;}
-      await asyncLocalStorage(localStorageConstants.ETHORA_USER).remove();
+      await secureUserStorage().remove();
     }
   } catch {
     // ignore storage errors
@@ -275,7 +384,7 @@ export const refreshUserCredentialsForXmpp = async (
     }
   }
 
-  const myEndpoint = config?.initBeforeLoadAuth?.myEndpoint || '/users/my';
+  const myEndpoint = config?.initBeforeLoadAuth?.myEndpoint || '/v1/users/my';
 
   // Priority 2: redux store user (covers userLogin + customLogin +
   // anything previously persisted into chatSettingStore.user). The
@@ -295,9 +404,7 @@ export const refreshUserCredentialsForXmpp = async (
   // should already mirror this, but if the redux state got cleared
   // mid-session (logout race) this gives us one last shot.
   try {
-    const storedUser = await asyncLocalStorage<User>(
-      localStorageConstants.ETHORA_USER
-    ).get();
+    const storedUser = await secureUserStorage().get();
     if (
       storedUser &&
       (storedUser.token || storedUser.refreshToken || storedUser.xmppPassword)

package/src/helpers/secureFileUrl.ts

@@ -0,0 +1,103 @@
+import { store } from '../roomStore';
+import { getCurrentBaseURL } from '../networking/apiClient';
+import { refreshAuthTokens } from '../networking/authRefresh';
+
+const SECURE_FILES_HOST_PREFIX = 'secure-files.';
+const SECURE_MEDIA_PATH_PREFIX = '/secure-media/';
+
+const FILE_TOKEN_PARAM = 'ft';
+
+export const resolveFileUrl = (url?: string | null): string => {
+  if (!url) {return '';}
+  // Any scheme at all — http(s), data, file, content, blob.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url)) {return url;}
+  if (!url.startsWith('/')) {return url;}
+
+  const base = getCurrentBaseURL().replace(/\/+$/, '');
+  return base ? `${base}${url}` : url;
+};
+
+export const isSecureFileUrl = (url?: string | null): boolean => {
+  if (!url) {return false;}
+
+  const path = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, '');
+  if (path.startsWith(SECURE_MEDIA_PATH_PREFIX)) {return true;}
+
+  const match = /^https?:\/\/(?:[^@/]+@)?([^:/?#]+)/i.exec(url);
+  if (!match) {return false;}
+  return match[1].toLowerCase().startsWith(SECURE_FILES_HOST_PREFIX);
+};
+
+export const appendFileToken = (
+  url: string | null | undefined,
+  fileToken: string | null | undefined
+): string => {
+  if (!url) {return '';}
+
+  const resolved = resolveFileUrl(url);
+  if (!fileToken || !isSecureFileUrl(resolved)) {return resolved;}
+  url = resolved;
+
+  const hashIndex = url.indexOf('#');
+  const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+  const withoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+
+  const queryIndex = withoutHash.indexOf('?');
+  const base = queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex);
+  const query = queryIndex === -1 ? '' : withoutHash.slice(queryIndex + 1);
+
+  const params = query
+    .split('&')
+    .filter(Boolean)
+    .filter((pair) => pair.split('=')[0] !== FILE_TOKEN_PARAM);
+
+  params.push(`${FILE_TOKEN_PARAM}=${encodeURIComponent(fileToken)}`);
+
+  return `${base}?${params.join('&')}${hash}`;
+};
+
+export const withFileToken = (url?: string | null): string =>
+  appendFileToken(
+    url,
+    store.getState().chatSettingStore?.user?.fileToken || ''
+  );
+
+const RECOVERY_COOLDOWN_MS = 30_000;
+let recoveryInFlight: Promise<boolean> | null = null;
+let lastRecoveryAt = 0;
+
+export const requestFileTokenRecovery = (): Promise<boolean> => {
+  if (recoveryInFlight) {return recoveryInFlight;}
+
+  const now = Date.now();
+  if (now - lastRecoveryAt < RECOVERY_COOLDOWN_MS) {
+    return Promise.resolve(false);
+  }
+  lastRecoveryAt = now;
+
+  const state = store.getState();
+  const refreshConfig = state.chatSettingStore?.config?.refreshTokens;
+  const user = state.chatSettingStore?.user;
+
+  if (!refreshConfig?.enabled) {return Promise.resolve(false);}
+
+  const run = async (): Promise<boolean> => {
+    if (!refreshConfig.refreshFunction && !user?.refreshToken) {return false;}
+
+    const tokens = await refreshAuthTokens();
+    return Boolean(tokens.fileToken);
+  };
+
+  recoveryInFlight = run()
+    .catch(() => false)
+    .finally(() => {
+      recoveryInFlight = null;
+    });
+
+  return recoveryInFlight;
+};
+
+export const __resetFileTokenRecoveryForTests = (): void => {
+  recoveryInFlight = null;
+  lastRecoveryAt = 0;
+};

package/src/helpers/secureKeyValue.ts

@@ -0,0 +1,80 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { loadSecureStore } from './secureStoreRuntime';
+import { pushLog } from '../utils/devLogger';
+
+// Fallback keys are prefixed and namespaced away from every other
+// AsyncStorage key this SDK writes, so a host that never installs
+// expo-secure-store can still be told apart from one that used to lack
+// it and has since added it (see `secureSet`'s stale-fallback cleanup).
+const FALLBACK_PREFIX = '@ethora/secure-fallback:';
+
+let warnedFallback = false;
+const warnFallbackOnce = () => {
+  if (warnedFallback) {return;}
+  warnedFallback = true;
+  pushLog(
+    'warn',
+    'expo-secure-store is not installed — auth tokens, the XMPP ' +
+      'password, and the message-history cipher key are falling back ' +
+      'to plain AsyncStorage instead of the platform Keychain/Keystore. ' +
+      'Add the optional peer dependency `expo-secure-store` to your app ' +
+      'to store them securely.'
+  );
+};
+
+/**
+ * Small-value secure KV store: platform Keychain/Keystore via
+ * expo-secure-store when the host has it installed, plain (but still
+ * namespaced) AsyncStorage otherwise. NOT for bulk data — see
+ * `persistCrypto.ts`'s size note on why message history goes through
+ * AES instead of straight into this store.
+ */
+export async function secureGet(key: string): Promise<string | null> {
+  const store = loadSecureStore();
+  if (store) {
+    try {
+      return await store.getItemAsync(key);
+    } catch (e) {
+      pushLog('warn', `secureStore: getItemAsync(${key}) failed`, e);
+      return null;
+    }
+  }
+  warnFallbackOnce();
+  return AsyncStorage.getItem(FALLBACK_PREFIX + key);
+}
+
+export async function secureSet(key: string, value: string): Promise<void> {
+  const store = loadSecureStore();
+  if (store) {
+    try {
+      await store.setItemAsync(key, value);
+      // Clean up a stale plaintext fallback copy from before this host
+      // added expo-secure-store — otherwise it sits on disk forever.
+      AsyncStorage.removeItem(FALLBACK_PREFIX + key).catch(() => undefined);
+      return;
+    } catch (e) {
+      pushLog('warn', `secureStore: setItemAsync(${key}) failed`, e);
+      return;
+    }
+  }
+  warnFallbackOnce();
+  await AsyncStorage.setItem(FALLBACK_PREFIX + key, value);
+}
+
+export async function secureRemove(key: string): Promise<void> {
+  const store = loadSecureStore();
+  if (store) {
+    try {
+      await store.deleteItemAsync(key);
+    } catch {
+      // Key may simply not exist — deleteItemAsync throwing here isn't
+      // actionable either way.
+    }
+  }
+  await AsyncStorage.removeItem(FALLBACK_PREFIX + key).catch(() => undefined);
+}
+
+/** Test seam only. */
+export const __resetSecureKeyValueWarningForTests = (): void => {
+  warnedFallback = false;
+};