@ethora/chat-component-rn 26.10.5 → 26.10.7

package/src/networking/xmpp/sendMediaMessage.xmpp.ts

@@ -1,5 +1,8 @@
 import { Client, xml } from '@xmpp/client';
 import { sendSealedMedia, shouldEncrypt } from '../../e2ee/send';
+import type { IAttachment, IMentionSpan } from '../../types/types';
+import { serializeAttachments } from '../../helpers/attachments';
+import { normalizeCaptionInput } from '../../helpers/caption';
 
 // Monotonic counter — see sendTextMessage for the rationale (avoids
 // Date.now() id collisions on <1ms-apart sends).
@@ -20,6 +23,18 @@ const toServiceXmlns = (devServer: string | undefined, client: Client): string =
   return `wss://${ds.replace(/^\/+|\/+$/g, '')}/ws`;
 };
 
+/**
+ * One media stanza for one or more files.
+ *
+ * `data` carries the flat fields that describe attachment #0, so a client
+ * that predates multi-attach still shows the first file. With more than one
+ * file the whole list rides on `<data attachments='JSON'>` (selection order).
+ *
+ * A typed caption rides on the message too: as `caption` / `captionMentions`
+ * attributes in a plain room, and inside the sealed <body> in an e2ee room
+ * (never as an attribute there). A message with one file and no caption is
+ * byte-identical to what this function produced before multi-attach.
+ */
 export function sendMediaMessage(
   client: Client,
   roomJID: string,
@@ -30,7 +45,7 @@ export function sendMediaMessage(
   const id =
     customId || `send-media-message-${Date.now()}-${(_sendMediaSeq = (_sendMediaSeq + 1) >>> 0)}`;
 
-  const dataToSend = {
+  const dataToSend: Record<string, unknown> = {
     xmlns: toServiceXmlns(devServer, client),
     senderJID: client.jid?.toString(),
     senderFirstName: data.firstName,
@@ -63,23 +78,65 @@ export function sendMediaMessage(
     push: 'true',
   };
 
+  // Only stamped when there is more than one file, so a single-file stanza
+  // keeps exactly the attributes it always had.
+  const files: IAttachment[] = Array.isArray(data?.attachments) ? data.attachments : [];
+  if (files.length > 1) {
+    // The flat fields describe attachment #0, whatever the caller passed, so
+    // an older client shows the first file of the message.
+    const head = files[0]!;
+    const flat: Array<keyof IAttachment> = [
+      'attachmentId',
+      'location',
+      'locationPreview',
+      'mimetype',
+      'originalName',
+      'fileName',
+      'size',
+      'duration',
+    ];
+    for (const key of flat) {
+      const value = head[key];
+      if (value !== undefined && value !== null && value !== '') {
+        dataToSend[key] = value;
+      }
+    }
+    dataToSend.attachments = serializeAttachments(files);
+  }
+
   const keys: string[] | undefined = data?.e2eeKeys;
   if (keys?.length) {
-    (dataToSend as Record<string, unknown>).clientEncrypted = 'true';
+    dataToSend.clientEncrypted = 'true';
   }
+
+  const caption = normalizeCaptionInput({
+    text: typeof data?.caption === 'string' ? data.caption : '',
+    mentions: data?.captionMentions as IMentionSpan[] | undefined,
+  });
   const hints = xml('store', { xmlns: 'urn:xmpp:hints' });
 
   if (keys?.length && shouldEncrypt(roomJID)) {
+    // The caption is sealed with the keys. It is never copied onto <data>.
+    const sealedBody = caption
+      ? { v: 1, keys, caption: caption.caption, ...(caption.mentions ? { captionMentions: caption.mentions } : {}) }
+      : { v: 1, keys };
     sendSealedMedia(
       client,
       roomJID,
       id,
-      xml('body', {}, JSON.stringify({ v: 1, keys })),
+      xml('body', {}, JSON.stringify(sealedBody)),
       [xml('data', dataToSend), hints]
     );
     return id;
   }
 
+  if (caption) {
+    dataToSend.caption = caption.caption;
+    if (caption.mentions) {
+      dataToSend.captionMentions = JSON.stringify(caption.mentions);
+    }
+  }
+
   const message = xml(
     'message',
     {

package/src/networking/xmpp/sendReceivedReceipt.xmpp.ts

@@ -0,0 +1,31 @@
+import { Client, xml } from '@xmpp/client';
+
+// XEP-0184 delivery receipt, broadcast to the room (mirrors
+// sendMessageReaction.xmpp.ts) so every occupant can render tick state.
+// The top-level stanza `from` gets rewritten to the room/nick by the MUC
+// server, so the real xmppUsername travels in the <received> `from` attr.
+export function sendReceivedReceipt(
+  client: Client,
+  messageId: string,
+  roomJid: string
+) {
+  const id = `message-received:${Date.now().toString()}`;
+
+  const message = xml(
+    'message',
+    {
+      id,
+      type: 'groupchat',
+      from: client.jid?.toString(),
+      to: roomJid,
+    },
+    xml('received', {
+      xmlns: 'urn:xmpp:receipts',
+      id: messageId,
+      from: client.jid?.toString(),
+    }),
+    xml('store', { xmlns: 'urn:xmpp:hints' })
+  );
+
+  client.send(message);
+}

package/src/networking/xmppClient.ts

@@ -17,6 +17,8 @@ import {
 } from './xmpp/getHistory.xmpp';
 import { sendTextMessage } from './xmpp/sendTextMessage.xmpp';
 import { sendMessageReaction } from './xmpp/sendMessageReaction.xmpp';
+import { sendReceivedReceipt } from './xmpp/sendReceivedReceipt.xmpp';
+import { sendDisplayedMarker } from './xmpp/sendDisplayedMarker.xmpp';
 import { sendTextMessageWithTranslateTag } from './xmpp/sendTextMessageWithTranslateTag.xmpp';
 import { deleteMessage } from './xmpp/deleteMessage.xmpp';
 import { RoomJoinManager } from './xmpp/roomJoinSweep';
@@ -48,6 +50,8 @@ import {
 
 // Canonical production XMPP WSS endpoint (standard wss/443, no port suffix).
 const DEFAULT_DEV_SERVER = 'xmpp.chat.ethora.com';
+// Upper bound on remembered XEP-0184 acks (oldest forgotten first).
+const RECEIPT_ACKED_CAP = 2000;
 
 // How long to wait for the old client's stop() during a reconnect before
 // giving up on it. Short on purpose: we are already tearing this client
@@ -279,6 +283,13 @@ export class XmppClient {
   }
   disableLastRead = false;
   private activeRoomJID: string | null = null;
+  // XEP-0184 acks already sent, as `room:messageId`. A message is acked once,
+  // whether it arrived live or again inside a MAM page. Oldest entries drop
+  // first once the set passes the cap.
+  private receiptAckedIds: Set<string> = new Set();
+  // XEP-0333: the last read watermark sent per room. A repeat flush for the
+  // same newest message sends nothing.
+  private lastWatermarkSentByRoom: Map<string, string> = new Map();
   private activeRoomBoostUntil = 0;
   private softPauseUntil = 0;
   private mamInFlightByRoom: Map<string, MamInFlightEntry> = new Map();
@@ -1594,6 +1605,43 @@ export class XmppClient {
     return typeof result === 'string' ? result : '';
   }
 
+  /**
+   * XEP-0184 delivery receipt for a message from someone else. Sent for live
+   * messages and for messages a MAM page brings in; a message already acked
+   * is skipped. When the stream is down (or `config.disableReadReceipts` is
+   * on) nothing is recorded, so a later page can still ack it.
+   */
+  sendReceivedReceiptStanza(messageId: string, roomJid: string) {
+    // Privacy switch: with read receipts off this client stays silent, so
+    // nobody learns that (or when) it received their message.
+    if (store.getState().chatSettingStore.config?.disableReadReceipts) {return;}
+    if (!messageId || !roomJid || !this.isStreamReady()) {return;}
+    const jid = normalizeRoomJid(roomJid, this.conference);
+    const key = `${jid}:${messageId}`;
+    if (this.receiptAckedIds.has(key)) {return;}
+    this.receiptAckedIds.add(key);
+    if (this.receiptAckedIds.size > RECEIPT_ACKED_CAP) {
+      const oldest = this.receiptAckedIds.values().next().value;
+      if (oldest !== undefined) {this.receiptAckedIds.delete(oldest);}
+    }
+    sendReceivedReceipt(this.client, messageId, jid);
+  }
+
+  /**
+   * XEP-0333 read watermark for a room: the newest message the user has
+   * displayed. Off with `disableLastRead` or `config.disableReadReceipts`.
+   * The caller decides when the room counts as read (see computeReadWatermark).
+   */
+  sendDisplayedMarkerStanza(messageId: string, roomJid: string) {
+    if (this.disableLastRead) {return;}
+    if (store.getState().chatSettingStore.config?.disableReadReceipts) {return;}
+    if (!messageId || !roomJid || !this.isStreamReady()) {return;}
+    const jid = normalizeRoomJid(roomJid, this.conference);
+    if (this.lastWatermarkSentByRoom.get(jid) === messageId) {return;}
+    this.lastWatermarkSentByRoom.set(jid, messageId);
+    sendDisplayedMarker(this.client, messageId, jid);
+  }
+
   sendMessageReactionStanza(
     messageId: string,
     roomJid: string,

package/src/push/pushKeyStore.ts

@@ -0,0 +1,163 @@
+import { fromBase64, toBase64 } from '../e2ee/crypto';
+import { loadSecureStore, type SecureStoreOptions } from '../helpers/secureStoreRuntime';
+import { pushLog } from '../utils/devLogger';
+import {
+  SEALED_BOX_PUBLIC_KEY_BYTES,
+  SEALED_BOX_SECRET_KEY_BYTES,
+  generateSealedBoxKeyPair,
+  sealedBoxKeyId,
+  sealedBoxPublicKeyOf,
+} from './sealedBox';
+import type { SealedPushKey } from './sealedPush';
+
+// The device key for encrypted pushes: one X25519 pair per install, in the
+// platform keychain / keystore through expo-secure-store. The public half
+// goes to the push service with the token (`pushKey`); the secret half
+// never leaves the device and is read by whoever renders a sealed push —
+// the Android background task (`sealedPushTask.ts`, same process, same
+// store) and the iOS notification service extension, which reads the
+// keychain item directly (plugins/notification-service), so the item's
+// attributes below are a contract with the Swift side:
+//   service   `ethora.push` (expo-secure-store stores it as `ethora.push:no-auth`)
+//   account   `ethora_push_secret_key`, UTF-8
+//   value     base64 of the 32-byte secret key, UTF-8
+//   group     the app's first keychain access group, which the config
+//             plugin shares with the extension
+// Readable after the first unlock so a push that arrives while the phone
+// is locked still decrypts; this device only, so an iCloud keychain copy
+// on another device is never a key for pushes that go to this one.
+
+export const PUSH_KEY_KEYCHAIN_SERVICE = 'ethora.push';
+export const PUSH_SECRET_KEY_ITEM = 'ethora_push_secret_key';
+export const PUSH_PUBLIC_KEY_ITEM = 'ethora_push_public_key';
+
+export interface PushKeyPair {
+  /** Base64 of the raw 32-byte X25519 public key — the `pushKey` of the registration. */
+  publicKey: string;
+  /** The `pushKeyId` the service derives for it, for logs and the kid check. */
+  keyId: string;
+}
+
+let warnedMissingStore = false;
+const warnMissingStoreOnce = () => {
+  if (warnedMissingStore) {return;}
+  warnedMissingStore = true;
+  pushLog(
+    'warn',
+    'push: expo-secure-store is not installed, so no device key for encrypted ' +
+      'pushes can be kept; pushes stay in the clear.'
+  );
+};
+
+const storeOptions = (): SecureStoreOptions | null => {
+  const store = loadSecureStore();
+  if (!store) {return null;}
+  const accessible = store.accessible.afterFirstUnlockThisDeviceOnly;
+  return {
+    keychainService: PUSH_KEY_KEYCHAIN_SERVICE,
+    ...(accessible !== undefined ? { keychainAccessible: accessible } : {}),
+  };
+};
+
+const readItem = async (item: string): Promise<string | null> => {
+  const store = loadSecureStore();
+  const options = storeOptions();
+  if (!store || !options) {return null;}
+  try {
+    return await store.getItemAsync(item, options);
+  } catch (e) {
+    pushLog('warn', `push: reading ${item} failed`, e);
+    return null;
+  }
+};
+
+const decodeKey = (raw: string | null, length: number): Uint8Array | null => {
+  if (!raw) {return null;}
+  try {
+    const bytes = fromBase64(raw);
+    return bytes.length === length ? bytes : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The stored pair, or null when there is none (or it is unreadable).
+ * The public key is re-derived from the secret, so the pair is consistent
+ * even if only the secret item survived.
+ */
+export async function loadPushSecretKey(): Promise<SealedPushKey | null> {
+  const secretKey = decodeKey(await readItem(PUSH_SECRET_KEY_ITEM), SEALED_BOX_SECRET_KEY_BYTES);
+  if (!secretKey) {return null;}
+  const stored = decodeKey(await readItem(PUSH_PUBLIC_KEY_ITEM), SEALED_BOX_PUBLIC_KEY_BYTES);
+  return { publicKey: stored ?? sealedBoxPublicKeyOf(secretKey), secretKey };
+}
+
+const describe = (publicKey: Uint8Array): PushKeyPair => ({
+  publicKey: toBase64(publicKey),
+  keyId: sealedBoxKeyId(publicKey),
+});
+
+/** The public half of the stored pair, null when the device has no key. */
+export async function getPushKeyPair(): Promise<PushKeyPair | null> {
+  const key = await loadPushSecretKey();
+  return key ? describe(key.publicKey) : null;
+}
+
+/**
+ * Generate and store a new pair, replacing any existing one. Pushes sealed
+ * for the old key stop opening at once, so re-register the token with the
+ * new `publicKey` right after. Null when expo-secure-store is missing or
+ * the keychain refused the write.
+ */
+export async function resetPushKeyPair(): Promise<PushKeyPair | null> {
+  const store = loadSecureStore();
+  const options = storeOptions();
+  if (!store || !options) {
+    warnMissingStoreOnce();
+    return null;
+  }
+  const pair = generateSealedBoxKeyPair();
+  try {
+    await store.setItemAsync(PUSH_SECRET_KEY_ITEM, toBase64(pair.secretKey), options);
+    await store.setItemAsync(PUSH_PUBLIC_KEY_ITEM, toBase64(pair.publicKey), options);
+  } catch (e) {
+    pushLog('warn', 'push: storing the device key failed', e);
+    return null;
+  }
+  const check = await loadPushSecretKey();
+  if (!check || toBase64(check.publicKey) !== toBase64(pair.publicKey)) {
+    pushLog('warn', 'push: the device key was not kept');
+    return null;
+  }
+  pushLog('rn', `push: new device key ${sealedBoxKeyId(pair.publicKey)}`);
+  return describe(pair.publicKey);
+}
+
+/**
+ * The device key for encrypted pushes, created on first call. Hand
+ * `publicKey` to `registerPushToken` (or send it as `pushKey` yourself).
+ */
+export async function ensurePushKeyPair(): Promise<PushKeyPair | null> {
+  const existing = await getPushKeyPair();
+  return existing ?? resetPushKeyPair();
+}
+
+/** Remove the pair; the next `ensurePushKeyPair` creates a new one. */
+export async function clearPushKeyPair(): Promise<void> {
+  const store = loadSecureStore();
+  const options = storeOptions();
+  if (!store || !options) {return;}
+  for (const item of [PUSH_SECRET_KEY_ITEM, PUSH_PUBLIC_KEY_ITEM]) {
+    try {
+      await store.deleteItemAsync(item, options);
+    } catch {
+      // Not there — nothing to remove.
+    }
+  }
+}
+
+/** Test seam only. */
+export const __resetPushKeyStoreForTests = (): void => {
+  warnedMissingStore = false;
+};

package/src/push/sealedBox.ts

@@ -0,0 +1,104 @@
+import { hsalsa, xsalsa20poly1305 } from '@noble/ciphers/salsa.js';
+import { clean, concatBytes, u32, u8, utf8ToBytes } from '@noble/ciphers/utils.js';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { blake2b } from '@noble/hashes/blake2.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+
+// libsodium's sealed box (`crypto_box_seal` / `crypto_box_seal_open`) on
+// the noble primitives the e2ee code already ships, so the JS side needs
+// no native libsodium. The push service seals every chat push for a
+// device that registered an X25519 public key (ethora-backend,
+// services/push/README.md, "Encrypted pushes"); this is the matching
+// receiver. The iOS notification service extension decrypts the same
+// boxes in Swift with libsodium (plugins/notification-service).
+//
+// Layout: ephemeral public key (32) || crypto_box(message, nonce,
+// recipient pk, ephemeral sk), with crypto_box = XSalsa20-Poly1305 under
+// HSalsa20(X25519 shared secret) and nonce = BLAKE2b-192(epk || rpk).
+// `__tests__/sealedBox.test.ts` pins this against libsodium itself.
+
+export const SEALED_BOX_PUBLIC_KEY_BYTES = 32;
+export const SEALED_BOX_SECRET_KEY_BYTES = 32;
+/** Ephemeral public key (32) + Poly1305 tag (16). */
+export const SEALED_BOX_OVERHEAD_BYTES = 48;
+
+const NONCE_BYTES = 24;
+const SIGMA = u32(utf8ToBytes('expand 32-byte k'));
+const ZERO_NONCE_PREFIX = new Uint32Array(4);
+
+export interface SealedBoxKeyPair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+export const generateSealedBoxKeyPair = (): SealedBoxKeyPair => {
+  const { secretKey, publicKey } = x25519.keygen();
+  return { publicKey, secretKey };
+};
+
+export const sealedBoxPublicKeyOf = (secretKey: Uint8Array): Uint8Array =>
+  x25519.getPublicKey(secretKey);
+
+/**
+ * The key id the push service derives when the registration carries none:
+ * the first 16 hex characters of SHA-256 over the raw public key. Sent back
+ * as `kid` in every sealed push.
+ */
+export const sealedBoxKeyId = (publicKey: Uint8Array): string =>
+  bytesToHex(sha256(publicKey)).slice(0, 16);
+
+// crypto_box_beforenm: HSalsa20 over the X25519 shared secret.
+const boxSharedKey = (theirPublicKey: Uint8Array, mySecretKey: Uint8Array): Uint8Array => {
+  const shared = x25519.getSharedSecret(mySecretKey, theirPublicKey);
+  const words = new Uint32Array(8);
+  hsalsa(SIGMA, u32(shared), ZERO_NONCE_PREFIX, words);
+  clean(shared);
+  return u8(words);
+};
+
+const sealNonce = (ephemeralPublicKey: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array =>
+  blake2b(concatBytes(ephemeralPublicKey, recipientPublicKey), { dkLen: NONCE_BYTES });
+
+/** `crypto_box_seal`: used by the tests and the key tool, not by the app. */
+export function sealedBoxSeal(message: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array {
+  if (recipientPublicKey.length !== SEALED_BOX_PUBLIC_KEY_BYTES) {
+    throw new Error('sealedBoxSeal: the public key must be 32 bytes');
+  }
+  const ephemeral = generateSealedBoxKeyPair();
+  const key = boxSharedKey(recipientPublicKey, ephemeral.secretKey);
+  const nonce = sealNonce(ephemeral.publicKey, recipientPublicKey);
+  const box = xsalsa20poly1305(key, nonce).encrypt(message);
+  clean(key, ephemeral.secretKey);
+  return concatBytes(ephemeral.publicKey, box);
+}
+
+/**
+ * `crypto_box_seal_open`. Returns null for anything that does not open:
+ * a wrong key, a box for another key, a damaged or truncated box.
+ */
+export function sealedBoxOpen(
+  sealed: Uint8Array,
+  publicKey: Uint8Array,
+  secretKey: Uint8Array
+): Uint8Array | null {
+  if (
+    sealed.length < SEALED_BOX_OVERHEAD_BYTES ||
+    publicKey.length !== SEALED_BOX_PUBLIC_KEY_BYTES ||
+    secretKey.length !== SEALED_BOX_SECRET_KEY_BYTES
+  ) {
+    return null;
+  }
+  const ephemeralPublicKey = sealed.subarray(0, SEALED_BOX_PUBLIC_KEY_BYTES);
+  const box = sealed.subarray(SEALED_BOX_PUBLIC_KEY_BYTES);
+  let key: Uint8Array | null = null;
+  try {
+    key = boxSharedKey(ephemeralPublicKey, secretKey);
+    const nonce = sealNonce(ephemeralPublicKey, publicKey);
+    return xsalsa20poly1305(key, nonce).decrypt(box);
+  } catch {
+    return null;
+  } finally {
+    if (key) {clean(key);}
+  }
+}

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 };
+}