@ethora/chat-component-rn 26.8.1 → 26.8.2

package/src/context/xmppProvider.tsx

@@ -14,7 +14,7 @@ import { VideoCallOverlay } from '../components/VideoCalls/VideoCallOverlay';
 import XmppClient, {
   XmppCredentialsProvider,
 } from '../networking/xmppClient';
-import { refreshTokens } from '../roomStore/chatSettingsSlice';
+import { refreshAuthTokensQuietly } from '../networking/authRefresh';
 import {
   IConfig,
   ProviderBootstrapStatus,
@@ -37,6 +37,7 @@ import {
 import { ensureScopedChatCache } from '../helpers/ensureScopedChatCache';
 import { getRooms as prefetchRoomsViaRest } from '../networking/api-requests/rooms.api';
 import { allRoomPresences } from '../networking/xmpp/allRoomPresences.xmpp';
+import { pushSubscriptionService } from '../services/pushSubscriptionService';
 import { store } from '../roomStore';
 import { logout, setStoreClient, setConfig } from '../roomStore/chatSettingsSlice';
 import {
@@ -45,12 +46,15 @@ import {
   clearVisibleRoom,
   setLastViewedTimestamp,
   deleteRoomMessage,
-  msgSortableMs,
   setUnreadSyncing,
 } from '../roomStore/roomsSlice';
+import {
+  getFlushBoundaryTs,
+  getReadMarkerTimestamp,
+} from '../helpers/getServerReadTimestamp';
 import { runHistoryPreloadScheduler } from '../helpers/historyPreloadScheduler';
-import { asyncLocalStorage } from '../hooks/useLocalStorage';
-import { localStorageConstants } from '../helpers/constants/LOCAL_STORAGE';
+import { updateMessagesTillLast } from '../helpers/updateMessagesTillLast';
+import { secureUserStorage } from '../helpers/secureUserStorage';
 import { clearPersistedState } from '../roomStore/persistence';
 import { pushLog as devPushLog } from '../utils/devLogger';
 
@@ -83,6 +87,16 @@ interface XmppProviderProps {
 
 const LOGOUT_EVENT = 'ethora-xmpp-logout';
 
+const subscribeAllRoomsForPush = (client: any, reason: string) => {
+  const rooms = Object.keys(store.getState().rooms.rooms || {});
+  if (!client || !rooms.length) {return;}
+  const nick = client.jid?.getLocal();
+  pushSubscriptionService
+    .subscribeToRooms(client, rooms, nick)
+    .then(() => devPushLog('xmpp', `${reason}: mucsub ok for ${rooms.length} rooms`))
+    .catch((e) => devPushLog('warn', `${reason}: mucsub subscribe failed`, e));
+};
+
 export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, isVisible }) => {
   const [client, setClient] = useState<XmppClient | null>(null);
   const [providerBootstrapStatus, setProviderBootstrapStatus] =
@@ -107,23 +121,25 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
   // the XmppClient at least doesn't crash on `undefined.password`.
   const credentialsProvider = useMemo<XmppCredentialsProvider>(() => {
     return async () => {
-      // 1. Consumer-supplied REST refresh (when wired). This runs
-      //    before the SDK's own refresh chain so non-Ethora backends
-      //    can keep auth state in sync with their own token endpoint.
-      const customRefresh = config?.refreshTokens?.refreshFunction;
-      if (customRefresh) {
-        try {
-          const result = await customRefresh();
-          if (result?.accessToken) {
-            store.dispatch(
-              refreshTokens({
-                token: result.accessToken,
-                refreshToken: result.refreshToken || '',
-              })
-            );
-          }
-        } catch (err) {
-          devPushLog('warn', 'XMPP creds refresh: customRefresh failed', err);
+      // 1. Make sure the REST tokens are fresh before re-minting XMPP
+      //    creds. This used to call `config.refreshTokens.refreshFunction`
+      //    directly and then fall into step 2, which refreshes again —
+      //    two rotations back to back, which the new backend scheme
+      //    reads as a race at best and token reuse at worst. One call to
+      //    the shared rotation point covers both the consumer-supplied
+      //    function and the built-in endpoint.
+      if (config?.refreshTokens?.enabled) {
+        const rotated = await refreshAuthTokensQuietly({ force: true });
+
+        if (rotated?.xmppPassword) {
+          const rotatedUser = store.getState().chatSettingStore.user;
+          return {
+            username:
+              rotatedUser?.xmppUsername ||
+              rotatedUser?.defaultWallet?.walletAddress ||
+              '',
+            password: rotated.xmppPassword,
+          };
         }
       }
 
@@ -163,7 +179,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
   }, [
     config?.jwtLogin?.enabled,
     config?.jwtLogin?.token,
-    config?.refreshTokens?.refreshFunction,
+    config?.refreshTokens?.enabled,
     config?.userLogin?.enabled,
     config?.customLogin?.enabled,
     config?.initBeforeLoadAuth?.myEndpoint,
@@ -227,9 +243,11 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       created.setOnOnline(() => {
         const underlying = (created as any).client;
         if (!underlying) {return;}
-        allRoomPresences(underlying).catch((e) =>
-          devPushLog('warn', 'reconnect: allRoomPresences re-join failed', e)
-        );
+        allRoomPresences(underlying)
+          .catch((e) =>
+            devPushLog('warn', 'reconnect: allRoomPresences re-join failed', e)
+          )
+          .finally(() => subscribeAllRoomsForPush(underlying, 'reconnect'));
         // Also refresh the private store so unread / lastViewed markers
         // are accurate after a long reconnect — the MUC re-join above only
         // restores delivery, not unread state. Idempotent on first connect.
@@ -238,6 +256,19 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
           .catch((e: unknown) =>
             devPushLog('warn', 'reconnect: privateStore refresh failed', e)
           );
+        // Pull whatever landed in each room's archive while the stream was
+        // down. MUC presence re-join above only restores delivery for
+        // messages sent AFTER this reconnect — anything sent during the
+        // offline window has no live stanza to catch, and previously only
+        // came back on a full app restart (fresh useChatWrapperInit mount
+        // re-running its own one-shot boot sync). Safe on the very first
+        // connect too: rooms have no `lastMessageTimestamp` yet at that
+        // point, so this is a no-op until the bootstrap's own history load
+        // populates it. Customer-reported #32.
+        const rooms = store.getState().rooms?.rooms || {};
+        updateMessagesTillLast(rooms, created).catch((e: unknown) =>
+          devPushLog('warn', 'reconnect: offline catch-up sync failed', e)
+        );
       });
 
       setClient(created);
@@ -299,6 +330,13 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
 
       if (completedBootstrapKeyRef.current === key) {
         devPushLog('rn', 'initBeforeLoad: already completed (same key) — skip');
+        // This run does no work, so it must not leave the budget it armed
+        // above running: 45 s later it would flip an already-'ready'
+        // provider to 'failed' and surface "Could not authenticate" over a
+        // healthy connection. Any dep change that leaves the key intact
+        // triggers this - e.g. a rotated `userLogin.user.token`.
+        reachedReady = true;
+        clearBudget();
         return;
       }
       if (inflightBootstrapKeyRef.current === key) {
@@ -322,7 +360,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
           devPushLog('rn', 'initBeforeLoad: clearStoreBeforeInit');
           store.dispatch(setLogoutState());
           store.dispatch(logout());
-          await asyncLocalStorage(localStorageConstants.ETHORA_USER).remove().catch(() => undefined);
+          await secureUserStorage().remove().catch(() => undefined);
         }
 
         await ensureScopedChatCache(config);
@@ -353,6 +391,29 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
           store.dispatch(setConfig(config));
         }
 
+        // Rotate BEFORE the first XMPP connect. On the rotating backend
+        // the xmpp password is a short-lived JWT that only the newest
+        // rotation knows, and each rotation invalidates its predecessors
+        // — so a snapshot's password (a host's cached `userLogin.user`,
+        // a persisted session) is usually already dead at boot. Without
+        // this, the first SASL attempt fails `not-authorized`, all three
+        // bootstrap retries re-present the same dead password, and the
+        // user dead-ends on the Connection error modal even though one
+        // rotation away a perfectly good session existed. The rotation
+        // also lands the fileToken pre-render, so secure media never
+        // paints blank first. Quiet + deduped; when it can't rotate
+        // (no refresh material, non-rotating backend) we just connect
+        // with what the snapshot has, exactly as before.
+        // jwtLogin is skipped: /users/client just minted fresh creds.
+        let connectPassword = resolved.xmppPassword;
+        if (config?.refreshTokens?.enabled && !config?.jwtLogin?.enabled) {
+          const rotated = await refreshAuthTokensQuietly({ force: true });
+          if (cancelled) {return;}
+          if (rotated?.xmppPassword) {
+            connectPassword = rotated.xmppPassword;
+          }
+        }
+
         // Kick off REST /chats/my; allRoomPresences below needs the
         // room list to be in redux, otherwise it joins 0 MUCs and the
         // user receives zero realtime messages until they manually tap
@@ -362,7 +423,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
 
         const c = await initializeClient(
           resolved.xmppUsername!,
-          resolved.xmppPassword,
+          connectPassword,
           config?.xmppSettings
         );
         if (cancelled) {return;}
@@ -398,6 +459,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
         } catch (e) {
           devPushLog('warn', 'initBeforeLoad: allRoomPresences failed', e);
         }
+        subscribeAllRoomsForPush((c as any).client, 'initBeforeLoad');
 
         store.dispatch(setStoreClient(c));
         completedBootstrapKeyRef.current = key;
@@ -542,9 +604,14 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
     // be re-marked visible on return. Lives in the effect closure (one per
     // client) — persists across the listener's many invocations.
     let visibleBeforeBackground: string | null = null;
+    const suspendInBackground = !config?.xmppSettings?.keepAliveInBackground;
     const sub = AppState.addEventListener('change', (next) => {
       const c = client;
       if (next === 'active') {
+        if (c?.isSuspended) {
+          devPushLog('rn', 'AppState active: resuming suspended XMPP client');
+          c.resume();
+        }
         // Returned to foreground. If the socket died while backgrounded
         // (iOS suspends the WebSocket; long background kills it), the
         // status may still read 'online' until xmpp.js notices the dead
@@ -572,22 +639,52 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       }
       // Going to background/inactive (sleep / app switcher / tray):
       if (!c) {return;}
+      if (next === 'background' && suspendInBackground) {
+        c.suspend().catch(() => undefined);
+      }
       const state = store.getState();
       const rooms = state.rooms?.rooms;
       const visibleRoomJID = state.rooms?.visibleRoomJID || null;
       // Mark the open room "not visible" while backgrounded so messages
       // that arrive (or MAM-replay on reconnect) count as unread instead
       // of being silently treated as read — the "mounted == visible ==
-      // read" gap. Stamp lastViewed=now as the read baseline, clear
-      // visibility, then flush that marker to the server private store.
-      // Restored on the next 'active' transition above. Handled here in
-      // the provider so consumers using the component as a package get
-      // correct unread without reaching into the chat store themselves.
+      // read" gap. Stamp lastViewed=<the read boundary, if the user left
+      // scrolled up, else the newest server-acked message>, not
+      // Date.now(), as the read baseline: a device clock running ahead
+      // would otherwise write a future marker that the forward-only
+      // private-store merge can never correct again (bug #38). Then
+      // clear visibility and flush that marker to the server private
+      // store. Restored on the next 'active' transition above. Handled
+      // here in the provider so consumers using the component as a
+      // package get correct unread without reaching into the chat store
+      // themselves.
+      //
+      // The read boundary (rooms.readBoundaries) is deliberately left
+      // untouched here - MessageList normally stays mounted through a
+      // simple background/foreground cycle, so its own scroll-tracking
+      // ref (the only thing that could re-derive this value) is still
+      // intact, and clearing the redux copy would desync the two. It's
+      // only USED here for the one-shot stamp+flush, matching customer
+      // #42: leaving (or backgrounding) a room while scrolled up must not
+      // mark messages the user never reached as read.
       visibleBeforeBackground = visibleRoomJID;
+      let boundaryTs: number | null = null;
       if (visibleRoomJID) {
-        store.dispatch(
-          setLastViewedTimestamp({ chatJID: visibleRoomJID, timestamp: Date.now() })
+        boundaryTs = state.rooms?.readBoundaries?.[visibleRoomJID] ?? null;
+        const readTs = getReadMarkerTimestamp(
+          rooms?.[visibleRoomJID],
+          state.roomHeapSlice,
+          boundaryTs
         );
+        // Nothing to anchor to yet (no known messages, no prior marker)
+        // - skip the local stamp rather than fall back to the device
+        // clock. The flush below still runs so the visibility clear
+        // isn't blocked on this.
+        if (readTs > 0) {
+          store.dispatch(
+            setLastViewedTimestamp({ chatJID: visibleRoomJID, timestamp: readTs })
+          );
+        }
         // Drop the "New messages" divider for the room we're leaving so it
         // doesn't linger when the user comes back (mirrors ChatRoom's
         // unmount cleanup, which never runs while the pane stays mounted).
@@ -597,13 +694,24 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
         store.dispatch(clearVisibleRoom());
       }
       // Fire-and-forget — we're going to the background and don't
-      // care about the resolution path.
-      c.flushLastViewedToPrivateStoreStanza(rooms, { visibleRoomJID }).catch(
-        () => {}
-      );
+      // care about the resolution path. `visibleRoomTs` carries the same
+      // boundary to the SERVER marker - without it the flush defaults to
+      // "everything" for the visible room, overriding a correct smaller
+      // local count.
+      c.flushLastViewedToPrivateStoreStanza(rooms, {
+        visibleRoomJID,
+        // Clamped through the same helper as the local stamp above.
+        visibleRoomTs: visibleRoomJID
+          ? getFlushBoundaryTs(
+              rooms?.[visibleRoomJID],
+              state.roomHeapSlice,
+              boundaryTs
+            )
+          : undefined,
+      }).catch(() => {});
     });
     return () => sub.remove();
-  }, [client]);
+  }, [client, config?.xmppSettings?.keepAliveInBackground]);
 
   // -----------------------------------------------------------
   // Consumer visibility signal (`isVisible` prop). For hosts that keep
@@ -612,11 +720,11 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
   // "shown" from "hidden", so the unread middleware would keep the open
   // room's badge at 0 and messages arriving while you're elsewhere look
   // already-read. When the host passes `isVisible`, mirror the AppState
-  // background/foreground handling: hidden → stamp lastViewed=now + clear
-  // room visibility (so later messages count) + flush; shown → restore
-  // visibility for the open room. Doing it here means consumers never
-  // touch the chat store themselves. (Undefined = host unmounts on hide,
-  // nothing to do.)
+  // background/foreground handling: hidden → stamp lastViewed=<newest
+  // server-acked message> + clear room visibility (so later messages
+  // count) + flush; shown → restore visibility for the open room. Doing
+  // it here means consumers never touch the chat store themselves.
+  // (Undefined = host unmounts on hide, nothing to do.)
   // -----------------------------------------------------------
   const chatWasVisibleRef = useRef(false);
   useEffect(() => {
@@ -631,10 +739,30 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
         store.dispatch(setVisibleRoom({ roomJID: activeRoomJID }));
       }
     } else {
+      // The read boundary (rooms.readBoundaries) is USED for the stamp
+      // and flush below but deliberately left in place - a host using
+      // `isVisible` keeps <Chat> mounted while hidden, so MessageList's
+      // own scroll-tracking ref is still intact and the redux copy must
+      // stay in sync with it. Only consumed, never Date.now(): a fast
+      // device clock would write a future marker that the forward-only
+      // private-store merge could then never correct (bug #38). And
+      // never "the newest acked message" unconditionally either - that
+      // silently marks messages the user scrolled past and never reached
+      // as read (bug #42, a regression of #33).
+      const boundaryTs = activeRoomJID
+        ? state.rooms?.readBoundaries?.[activeRoomJID] ?? null
+        : null;
       if (wasVisible && activeRoomJID) {
-        store.dispatch(
-          setLastViewedTimestamp({ chatJID: activeRoomJID, timestamp: Date.now() })
+        const readTs = getReadMarkerTimestamp(
+          rooms?.[activeRoomJID],
+          state.roomHeapSlice,
+          boundaryTs
         );
+        if (readTs > 0) {
+          store.dispatch(
+            setLastViewedTimestamp({ chatJID: activeRoomJID, timestamp: readTs })
+          );
+        }
         // Drop the "New messages" divider so it's gone when the user
         // returns to the chat (mirrors ChatRoom's unmount cleanup).
         store.dispatch(
@@ -645,7 +773,19 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       store.dispatch(clearVisibleRoom());
       if (wasVisible && client?.flushLastViewedToPrivateStoreStanza) {
         client
-          .flushLastViewedToPrivateStoreStanza(rooms, { visibleRoomJID: activeRoomJID })
+          .flushLastViewedToPrivateStoreStanza(rooms, {
+            visibleRoomJID: activeRoomJID,
+            // Carry the same boundary to the SERVER marker - without it
+            // the flush defaults to "everything" for the visible room.
+            // Clamped exactly like the local stamp above.
+            visibleRoomTs: activeRoomJID
+              ? getFlushBoundaryTs(
+                  rooms?.[activeRoomJID],
+                  state.roomHeapSlice,
+                  boundaryTs
+                )
+              : undefined,
+          })
           .catch(() => {});
       }
     }
@@ -666,26 +806,45 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       if (room.messages === lastMessagesRef) {return;}
       lastMessagesRef = room.messages;
 
-      let newest = 0;
-      const list = room.messages || [];
-      for (const m of list) {
-        if (!m || m.id === 'delimiter-new') {continue;}
-        const ms = msgSortableMs(m);
-        if (ms > newest) {newest = ms;}
-      }
-      if (newest <= lastStampedMs) {return;}
+      // getReadMarkerTimestamp (not a hand-rolled scan + Date.now()):
+      // it excludes pending/optimistic messages, which carry the DEVICE
+      // send time via `date` until the server echoes them back - a
+      // manual scan without that exclusion could pick up a pending
+      // message's device timestamp here and write a future marker the
+      // same way a raw Date.now() would (bug #38). And when the user has
+      // scrolled up (a boundary is set for this room), it clamps to that
+      // boundary instead of the newest message - without this, every
+      // incoming message while scrolled up advanced the marker to
+      // "newest" regardless of scroll position, and the later, smaller
+      // boundary write on leave was rejected by the forward-only
+      // private-store merge, leaving 0 unread even after a restart
+      // (customer #42, a regression of #33 reintroduced by #38).
+      const boundaryTs = s.rooms?.readBoundaries?.[jid] ?? null;
+      const newest = getReadMarkerTimestamp(room, s.roomHeapSlice, boundaryTs);
+      if (!newest || newest <= lastStampedMs) {return;}
       lastStampedMs = newest;
 
       store.dispatch(
-        setLastViewedTimestamp({ chatJID: jid, timestamp: Date.now() })
+        setLastViewedTimestamp({ chatJID: jid, timestamp: newest })
       );
 
       if (flushTimer) {clearTimeout(flushTimer);}
       if (client?.flushLastViewedToPrivateStoreStanza) {
         flushTimer = setTimeout(() => {
+          // Re-read fresh state rather than closing over `boundaryTs`:
+          // the user may have scrolled back to the bottom (clearing the
+          // boundary) in the 2s between the stamp and this flush, and
+          // the flush should reflect that.
+          const freshState = store.getState();
+          const freshBoundaryTs = freshState.rooms?.readBoundaries?.[jid] ?? null;
           client
-            .flushLastViewedToPrivateStoreStanza(store.getState().rooms?.rooms, {
+            .flushLastViewedToPrivateStoreStanza(freshState.rooms?.rooms, {
               visibleRoomJID: jid,
+              visibleRoomTs: getFlushBoundaryTs(
+                freshState.rooms?.rooms?.[jid],
+                freshState.roomHeapSlice,
+                freshBoundaryTs
+              ),
             })
             .catch(() => {});
         }, 2000);

package/src/helpers/createMessageFromXml.ts

@@ -93,6 +93,25 @@ export const createMessageFromXml = async (
   const senderLocal = senderJID.includes('@')
     ? senderJID.split('@')[0]
     : senderJID;
+
+  // Bug #41 root cause: the resource of the MUC `from` (room@conference/
+  // occupant-id) is the SAME field getDataFromXml uses to derive
+  // `user.id` for live messages and for the wrapped MAM convention
+  // (getHistory.xmpp.ts) - it's stamped by the server itself when the
+  // sender joined the room, so it's always present and always correct.
+  // The positional convention (onMessageHistory's MAM catch-up path)
+  // never called getDataFromXml, so it fell back to splitting the
+  // sender-supplied `<data senderJID>` attr on '@' instead - usually the
+  // same value, but WRONG (picks up the room's own id, not the
+  // sender's) whenever senderJID is absent from the stanza, and simply a
+  // different derivation than the live path even when it happens to
+  // agree. Prefer the resource-of-`from` here too so every path that
+  // reaches this function resolves the same sender identity the same
+  // way, instead of MAM catch-up rows needing a later correction once
+  // the "official" fetch lands.
+  const xmppFrom = (merged.xmppFrom || '').toString();
+  const fromResource = xmppFrom.includes('/') ? xmppFrom.split('/')[1] : '';
+
   const composed = [firstName, lastName].filter(Boolean).join(' ').trim();
   const existingName = String(merged?.user?.name || '').trim();
   const resolvedName =
@@ -107,7 +126,7 @@ export const createMessageFromXml = async (
     ...merged,
     user: {
       ...(merged.user || {}),
-      id: merged?.user?.id || senderLocal,
+      id: merged?.user?.id || fromResource || senderLocal,
       name: resolvedName,
       firstName: firstName || merged?.user?.firstName,
       lastName: lastName || merged?.user?.lastName,

package/src/helpers/ensureScopedChatCache.ts

@@ -3,7 +3,7 @@ import { store } from '../roomStore';
 import { logout } from '../roomStore/chatSettingsSlice';
 import { setLogoutState } from '../roomStore/roomsSlice';
 import { asyncLocalStorage } from '../hooks/useLocalStorage';
-import { localStorageConstants } from './constants/LOCAL_STORAGE';
+import { secureUserStorage } from './secureUserStorage';
 import { clearRoomsRestCache } from '../networking/api-requests/rooms.api';
 import { clearPersistedState } from '../roomStore/persistence';
 import {
@@ -53,7 +53,7 @@ export async function ensureScopedChatCache(config?: IConfig): Promise<void> {
     clearRoomsRestCache();
     store.dispatch(setLogoutState());
     store.dispatch(logout());
-    await asyncLocalStorage(localStorageConstants.ETHORA_USER).remove();
+    await secureUserStorage().remove();
     await clearPersistedState();
   }
 

package/src/helpers/getChatBackground.ts

@@ -0,0 +1,18 @@
+/** @format */
+
+import type { IConfig } from '../types/types';
+
+/** Ground behind the conversation, and behind the rounded corners of the
+ * header and the composer that sit over it. */
+export const DEFAULT_CHAT_BACKGROUND = '#F3F6FC';
+
+/**
+ * One place for the conversation's background colour.
+ *
+ * The message list has always painted it; the chat container behind it was
+ * plain white, which is what made the header's rounded bottom corners and
+ * the composer's rounded top corners invisible — the corners revealed the
+ * white parent, not the conversation.
+ */
+export const getChatBackgroundColor = (config?: IConfig): string =>
+  config?.backgroundChat?.color || DEFAULT_CHAT_BACKGROUND;

package/src/helpers/getDisplayFileName.ts

@@ -0,0 +1,87 @@
+import { ensureFilenameHasExtension, filenameFromUrl } from './mimeToExtension';
+
+export interface DisplayFileNameOptions {
+  originalName?: string | null;
+  fileName?: string | null;
+  location?: string | null;
+  mimetype?: string | null;
+}
+
+/**
+ * Picks the best human-readable filename for a chat attachment - the
+ * single source of truth for every place a file name is rendered in the
+ * UI, saved to disk, shared, or downloaded.
+ *
+ * Priority: `originalName` (the sender's own file name, e.g. "test1.pdf")
+ * beats `fileName` (the server's stored/hashed name, e.g.
+ * "3f9a1c...c2.pdf") beats the last path segment of `location`. The
+ * stored hash name is only a fallback of last resort.
+ *
+ * Bug #40: display and save/share/download logic used to prefer the
+ * stored hash name over the original one, so an attachment sent as
+ * "test1.pdf" showed up (and got saved to the phone) as something like
+ * "3f9a1c...c2.pdf" - both directions (web -> RN and RN -> RN).
+ *
+ * Always returns a non-empty string with a valid extension: if the
+ * chosen candidate has no extension (a hash name can be `<hex>` with no
+ * extension at all, or `<hex>.<ext>`), one is appended from `mimetype`
+ * (or `.bin` as a last resort when the mime is unknown/missing too).
+ */
+export function getDisplayFileName(options: DisplayFileNameOptions): string {
+  const candidate =
+    (options.originalName && options.originalName.trim()) ||
+    (options.fileName && options.fileName.trim()) ||
+    filenameFromUrl(options.location) ||
+    '';
+  return ensureFilenameHasExtension(candidate, options.mimetype);
+}
+
+/**
+ * Makes a display name safe to use as an actual path segment when
+ * saving/sharing a file to the device: strips path separators (so an
+ * odd/hostile server-provided name can't escape the target directory)
+ * and control characters. Keeps the rest of the name - including the
+ * extension - intact.
+ */
+export function sanitizeFileNameForPath(name: string): string {
+  const cleaned = (name || '')
+    .replace(/[\/\\]/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, '')
+    .trim();
+  return cleaned || 'file';
+}
+
+/**
+ * Resolves a filename that is safe to write into a target directory:
+ * sanitizes it, then - if `exists` reports a collision - inserts
+ * " (1)", " (2)", ... before the extension until a free name is found,
+ * so saving two different attachments that share a display name never
+ * silently overwrites the first one.
+ *
+ * `exists` is injected so callers can back it with whatever existence
+ * check makes sense for their storage API (expo-file-system,
+ * StorageAccessFramework directory listing, ...) - this function stays
+ * pure and easy to unit test.
+ */
+export async function getUniqueFileName(
+  name: string,
+  exists: (candidateName: string) => Promise<boolean>
+): Promise<string> {
+  const safeName = sanitizeFileNameForPath(name);
+  if (!(await exists(safeName))) {
+    return safeName;
+  }
+  const dotIndex = safeName.lastIndexOf('.');
+  const base = dotIndex > 0 ? safeName.slice(0, dotIndex) : safeName;
+  const ext = dotIndex > 0 ? safeName.slice(dotIndex) : '';
+  // 999 collisions is already a pathological case; fall back to a
+  // timestamp suffix rather than looping forever.
+  for (let i = 1; i < 1000; i += 1) {
+    const candidate = `${base} (${i})${ext}`;
+    if (!(await exists(candidate))) {
+      return candidate;
+    }
+  }
+  return `${base} (${Date.now()})${ext}`;
+}