@ethora/chat-component-rn 26.10.6 → 26.10.7

package/src/push/sealedPush.ts

@@ -0,0 +1,127 @@
+import { fromBase64 } from '../e2ee/crypto';
+import { sealedBoxKeyId, sealedBoxOpen } from './sealedBox';
+
+// The envelope of an encrypted chat push (ethora-backend,
+// services/push/README.md, "Encrypted pushes"): the FCM `data` map on
+// Android, the custom keys next to `aps` on iOS. Only ids travel in the
+// clear; everything shown to the user is inside `enc`, a sealed box for
+// the key the device registered with its token.
+
+export const SEALED_PUSH_ALG = 'sealed-box-x25519';
+export const SEALED_PUSH_VERSION = '1';
+
+export interface SealedPushEnvelope {
+  v: string;
+  alg: string;
+  /** Id of the key the box was sealed for. */
+  kid: string;
+  /** Room JID. */
+  jid: string;
+  msgID: string;
+  /** Recipient. */
+  userJid: string;
+  /** Base64 of the sealed box; absent when the service could not seal. */
+  enc?: string;
+}
+
+/** What the box holds: the notification the service would have sent in the clear. */
+export interface SealedPushContent {
+  title: string;
+  body: string;
+  sender: string;
+  senderJid: string;
+  chat: string;
+  chatJid: string;
+  msgID: string;
+  /** Sender avatar URL, '' when none. */
+  image: string;
+}
+
+export type SealedPushFailure =
+  /** No key on this device (never generated, or the store is not readable). */
+  | 'no-key'
+  /** Sealed for another key — the app was reinstalled or the key rotated after registration. */
+  | 'key-mismatch'
+  /** The service sent ids only (it could not seal). */
+  | 'no-ciphertext'
+  /** Not a box for our key, or damaged. */
+  | 'bad-ciphertext'
+  /** Opened, but the plaintext is not the expected JSON. */
+  | 'bad-content';
+
+export type OpenSealedPushResult =
+  | { ok: true; content: SealedPushContent; envelope: SealedPushEnvelope }
+  | { ok: false; reason: SealedPushFailure; envelope: SealedPushEnvelope };
+
+const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+/** The envelope of `data` when it is a sealed chat push, else null. */
+export const sealedPushEnvelopeOf = (
+  data: Record<string, unknown> | null | undefined
+): SealedPushEnvelope | null => {
+  if (!data || data.alg !== SEALED_PUSH_ALG) {return null;}
+  const enc = str(data.enc);
+  return {
+    v: str(data.v) || SEALED_PUSH_VERSION,
+    alg: SEALED_PUSH_ALG,
+    kid: str(data.kid),
+    jid: str(data.jid),
+    msgID: str(data.msgID),
+    userJid: str(data.userJid),
+    ...(enc ? { enc } : {}),
+  };
+};
+
+export const isSealedPush = (data: Record<string, unknown> | null | undefined): boolean =>
+  sealedPushEnvelopeOf(data) !== null;
+
+const parseContent = (plaintext: Uint8Array): SealedPushContent | null => {
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(plaintext));
+    if (!parsed || typeof parsed !== 'object') {return null;}
+    return {
+      title: str(parsed.title),
+      body: str(parsed.body),
+      sender: str(parsed.sender),
+      senderJid: str(parsed.senderJid),
+      chat: str(parsed.chat),
+      chatJid: str(parsed.chatJid),
+      msgID: str(parsed.msgID),
+      image: str(parsed.image),
+    };
+  } catch {
+    return null;
+  }
+};
+
+export interface SealedPushKey {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+/**
+ * Open a sealed push with the device key. `key` null means there is no key
+ * on this device. Never throws: every failure names why, so the caller can
+ * show the placeholder and log the reason.
+ */
+export function openSealedPush(
+  envelope: SealedPushEnvelope,
+  key: SealedPushKey | null
+): OpenSealedPushResult {
+  if (!key) {return { ok: false, reason: 'no-key', envelope };}
+  if (envelope.kid && envelope.kid !== sealedBoxKeyId(key.publicKey)) {
+    return { ok: false, reason: 'key-mismatch', envelope };
+  }
+  if (!envelope.enc) {return { ok: false, reason: 'no-ciphertext', envelope };}
+  let sealed: Uint8Array;
+  try {
+    sealed = fromBase64(envelope.enc);
+  } catch {
+    return { ok: false, reason: 'bad-ciphertext', envelope };
+  }
+  const plaintext = sealedBoxOpen(sealed, key.publicKey, key.secretKey);
+  if (!plaintext) {return { ok: false, reason: 'bad-ciphertext', envelope };}
+  const content = parseContent(plaintext);
+  if (!content) {return { ok: false, reason: 'bad-content', envelope };}
+  return { ok: true, content, envelope };
+}

package/src/push/sealedPushTask.ts

@@ -0,0 +1,175 @@
+import { AppState, Platform } from 'react-native';
+import { pushLog } from '../utils/devLogger';
+import { loadPushSecretKey } from './pushKeyStore';
+import { openSealedPush, sealedPushEnvelopeOf, type OpenSealedPushResult } from './sealedPush';
+
+// Android half of encrypted pushes. A sealed push is data-only, so the OS
+// shows nothing by itself: expo-notifications hands it to a background
+// task (expo-task-manager, foreground, background and killed app alike)
+// and this task opens the box and posts the notification. iOS does the
+// same in the notification service extension; here `registerSealedPushTask`
+// is a no-op.
+//
+// Both packages are optional peers, required lazily: a host that does not
+// want encrypted pushes never pays for them.
+
+export const SEALED_PUSH_TASK = 'ETHORA_SEALED_PUSH';
+
+export interface SealedPushTaskOptions {
+  /** Android notification channel; the OS default channel when omitted. */
+  channelId?: string;
+  /** Shown when the box does not open (no key, another key, damaged). Default "New message". */
+  placeholderTitle?: string;
+  placeholderBody?: string;
+}
+
+const PLACEHOLDER_TITLE = 'New message';
+
+let registered = false;
+
+const loadTaskManager = (): any => {
+  try {
+    return require('expo-task-manager');
+  } catch {
+    return null;
+  }
+};
+
+const loadNotifications = (): any => {
+  try {
+    return require('expo-notifications');
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The FCM data map out of the task payload. expo-notifications passes the
+ * message as `{ notification, data }`; the data keys are on `data`
+ * itself, `data.dataString` carries the same as a JSON string on some
+ * versions, and a Firebase `RemoteMessage` keeps them under `data.data`.
+ */
+export const sealedPushDataOf = (payload: unknown): Record<string, unknown> | null => {
+  const root = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : null;
+  if (!root) {return null;}
+  const candidates: unknown[] = [root.data, root];
+  const data = root.data && typeof root.data === 'object' ? (root.data as Record<string, unknown>) : null;
+  if (data) {
+    if (typeof data.dataString === 'string') {
+      try {
+        candidates.unshift(JSON.parse(data.dataString));
+      } catch {
+        // not JSON — fall through to the map itself
+      }
+    }
+    candidates.push(data.data);
+  }
+  for (const candidate of candidates) {
+    if (sealedPushEnvelopeOf(candidate as Record<string, unknown>)) {
+      return candidate as Record<string, unknown>;
+    }
+  }
+  return null;
+};
+
+const notificationContent = (result: OpenSealedPushResult, options: SealedPushTaskOptions) => {
+  const { envelope } = result;
+  // What the tap handler (`handlePushPayload` through the host's response
+  // listener) needs: the same ids a plain push carries on `data`.
+  const data = {
+    jid: envelope.jid,
+    msgID: envelope.msgID,
+    userJid: envelope.userJid,
+    sealed: true,
+  };
+  if (!result.ok) {
+    return {
+      title: options.placeholderTitle || PLACEHOLDER_TITLE,
+      ...(options.placeholderBody ? { body: options.placeholderBody } : {}),
+      data,
+      sound: 'default',
+    };
+  }
+  const { content } = result;
+  return {
+    title: content.title || content.sender || content.chat || PLACEHOLDER_TITLE,
+    body: content.body,
+    data: { ...data, chatJid: content.chatJid, senderJid: content.senderJid },
+    sound: 'default',
+  };
+};
+
+/**
+ * Open a sealed push and show it. One notification per chat: the room JID
+ * is the identifier, so a newer message replaces the older one the way the
+ * service's collapse key does for plain pushes.
+ */
+export async function presentSealedPush(
+  data: Record<string, unknown>,
+  options: SealedPushTaskOptions = {}
+): Promise<OpenSealedPushResult | null> {
+  const envelope = sealedPushEnvelopeOf(data);
+  if (!envelope) {return null;}
+  const notifications = loadNotifications();
+  if (!notifications?.scheduleNotificationAsync) {return null;}
+
+  const result = openSealedPush(envelope, await loadPushSecretKey());
+  // console, not only pushLog: with the app killed this runs headless and
+  // `adb logcat -s ReactNativeJS` is the only place to see it.
+  if (result.ok) {
+    console.log(`[push] sealed push kid=${envelope.kid} opened for ${envelope.jid}`);
+  } else {
+    console.warn(`[push] sealed push kid=${envelope.kid} not opened (${result.reason}), showing the placeholder`);
+    pushLog('warn', `push: sealed push not opened (${result.reason}), showing the placeholder`);
+  }
+  await notifications.scheduleNotificationAsync({
+    identifier: envelope.jid || envelope.msgID || undefined,
+    content: notificationContent(result, options),
+    trigger: options.channelId ? { channelId: options.channelId } : null,
+  });
+  return result;
+}
+
+/**
+ * Define and register the background task that renders sealed pushes on
+ * Android. Call it at module scope of a file the app loads first (the
+ * entry file, or the root layout with expo-router): a killed app is
+ * started headless to run it, and the task must exist by then. No-op on
+ * iOS and when expo-task-manager / expo-notifications are not installed.
+ */
+export function registerSealedPushTask(options: SealedPushTaskOptions = {}): boolean {
+  if (Platform.OS !== 'android' || registered) {return registered;}
+  const taskManager = loadTaskManager();
+  const notifications = loadNotifications();
+  if (!taskManager?.defineTask || !notifications?.registerTaskAsync) {
+    pushLog(
+      'warn',
+      'push: expo-task-manager and expo-notifications are needed to show encrypted pushes on Android'
+    );
+    return false;
+  }
+  taskManager.defineTask(SEALED_PUSH_TASK, async ({ data, error }: { data: unknown; error: unknown }) => {
+    if (error) {return;}
+    const map = sealedPushDataOf(data);
+    if (!map) {return;}
+    // In the foreground the room is live over XMPP; the host's
+    // notification handler decides about plain pushes there too.
+    if (AppState.currentState === 'active') {return;}
+    try {
+      await presentSealedPush(map, options);
+    } catch (e) {
+      pushLog('warn', 'push: showing a sealed push failed', e);
+    }
+  });
+  registered = true;
+  notifications.registerTaskAsync(SEALED_PUSH_TASK).catch((e: unknown) => {
+    registered = false;
+    pushLog('warn', 'push: registering the sealed push task failed', e);
+  });
+  return true;
+}
+
+/** Test seam only. */
+export const __resetSealedPushTaskForTests = (): void => {
+  registered = false;
+};

package/src/services/pushRegistration.ts

@@ -11,6 +11,13 @@ import { pushLog } from '../utils/devLogger';
 
 export interface RegisterPushTokenOptions {
   tokenType?: PushTokenType;
+  /**
+   * Encrypted pushes: base64 of the device's X25519 public key
+   * (`ensurePushKeyPair().publicKey`). Sent with the token as `pushKey`;
+   * the service seals every chat push for it. A backend without the
+   * feature refuses the registration instead of delivering in the clear.
+   */
+  pushKey?: string;
 }
 
 export type RegisterPushTokenOutcome =
@@ -29,6 +36,7 @@ export type UnregisterPushTokenOutcome =
 export interface RegisteredPushToken {
   token: string;
   tokenType: PushTokenType;
+  pushKey?: string;
 }
 
 type Slot = 'chat' | 'voip';
@@ -93,6 +101,7 @@ const sameRegistration = (
   !!current &&
   current.token === token.token &&
   current.tokenType === token.tokenType &&
+  (current.pushKey || '') === (token.pushKey || '') &&
   current.gateway === isGateway(session) &&
   current.appId === session.appId &&
   current.xmppUsername === session.xmppUsername;
@@ -147,6 +156,7 @@ const registerOne = async (
       token: token.token,
       tokenType: token.tokenType,
       authToken: session.authToken,
+      pushKey: token.pushKey,
     });
   }
   registered.set(slotOf(token.tokenType), {
@@ -158,7 +168,8 @@ const registerOne = async (
   pushLog(
     'rn',
     `push: ${token.tokenType} token registered` +
-      (isGateway(session) ? ' (gateway)' : ` for app ${session.appId}`)
+      (isGateway(session) ? ' (gateway)' : ` for app ${session.appId}`) +
+      (token.pushKey && !isGateway(session) ? ' with a device key (encrypted pushes)' : '')
   );
 };
 
@@ -209,7 +220,7 @@ const runTokenHook = (session: Session): void => {
       if (typeof entry?.token !== 'string' || !entry.token.trim()) {
         continue;
       }
-      hold(entry.token.trim(), entry.tokenType);
+      hold(entry.token.trim(), entry.tokenType, entry.pushKey);
     }
     await registerNow();
   })().catch((error) => {
@@ -219,9 +230,18 @@ const runTokenHook = (session: Session): void => {
   });
 };
 
-const hold = (token: string, tokenType?: PushTokenType): RegisteredPushToken => {
+const hold = (
+  token: string,
+  tokenType?: PushTokenType,
+  pushKey?: string
+): RegisteredPushToken => {
   const resolved = tokenType ?? detectPushTokenType(token);
-  const entry: RegisteredPushToken = { token, tokenType: resolved };
+  const key = typeof pushKey === 'string' ? pushKey.trim() : '';
+  const entry: RegisteredPushToken = {
+    token,
+    tokenType: resolved,
+    ...(key ? { pushKey: key } : {}),
+  };
   held.set(slotOf(resolved), entry);
   return entry;
 };
@@ -274,7 +294,7 @@ export async function registerPushToken(
   if (typeof token !== 'string' || !token.trim()) {
     throw new TypeError('registerPushToken: token must be a non-empty string');
   }
-  hold(token.trim(), options?.tokenType);
+  hold(token.trim(), options?.tokenType, options?.pushKey);
   ensureWatching();
 
   const session = readSession();

package/src/types/types.ts

@@ -257,6 +257,12 @@ export type PushTokenType = 'apns' | 'apns-voip' | 'fcm' | 'expo';
 export interface PushTokenRegistration {
   token: string;
   tokenType?: PushTokenType;
+  /**
+   * Encrypted pushes: base64 of the device's X25519 public key
+   * (`ensurePushKeyPair().publicKey`). The service then seals every chat
+   * push for it; see README, "Encrypted pushes".
+   */
+  pushKey?: string;
 }
 
 export interface MessageBubble {

package/src/version.ts

@@ -1,3 +1,3 @@
 // Generated by scripts/sync-version.mjs on `npm version`.
 // Edit package.json's version instead of this file.
-export const ETHORA_CHAT_COMPONENT_VERSION = '26.10.6';
+export const ETHORA_CHAT_COMPONENT_VERSION = '26.10.7';