@ethora/chat-component-rn 26.10.6 → 26.10.7

package/plugins/withNotificationServiceExtension.js

@@ -1,15 +1,21 @@
 /**
- * Expo config plugin — adds an iOS Notification Service Extension that shows
- * the attachment thumbnail (photo / video preview) in chat pushes.
- *
- * The push service sends `previewUrl` with `mutable-content: 1`. Android
- * renders the picture by itself; iOS only does it through an extension
- * target inside the app, which downloads the file and attaches it
- * (plugins/notification-service/NotificationService.swift).
+ * Expo config plugin — adds an iOS Notification Service Extension for Ethora
+ * chat pushes. The extension (plugins/notification-service/NotificationService.swift)
+ *  - decrypts encrypted (sealed) pushes with the device key the app keeps in
+ *    the keychain and shows the real title and text in place of the
+ *    "New message" placeholder;
+ *  - shows the attachment thumbnail (photo / video preview) the push service
+ *    sends as `previewUrl`.
  *
  * An extension is a separate target signed with the app, so it cannot ship
  * inside the npm package as code: this plugin writes it into ios/ on every
  * `expo prebuild` (the generated ios/ folder is gitignored in Expo apps).
+ * For the key to be readable from the extension, the app and the extension
+ * share a keychain access group (`$(AppIdentifierPrefix)<bundle id>`, the
+ * app's own default group, listed first so items the app writes without a
+ * group — expo-secure-store's — land in it). The sealed box is opened in
+ * plain Swift (SealedBox.swift: CryptoKit for X25519, the rest ported from
+ * tweetnacl), so the extension needs no pod.
  *
  * Host app.json:
  *   "plugins": ["@ethora/chat-component-rn"]
@@ -23,25 +29,39 @@
 
 const fs = require('fs');
 const path = require('path');
-const { withDangerousMod, withXcodeProject } = require('expo/config-plugins');
+const { withDangerousMod, withEntitlementsPlist, withXcodeProject } = require('expo/config-plugins');
 
 const TARGET_NAME = 'EthoraNotificationService';
 const SOURCE_DIR = path.join(__dirname, 'notification-service');
-const FILES = ['NotificationService.swift', 'Info.plist'];
+const SOURCES = ['NotificationService.swift', 'SealedBox.swift'];
+const FILES = [...SOURCES, 'Info.plist'];
+const ENTITLEMENTS_FILE = `${TARGET_NAME}.entitlements`;
+const KEYCHAIN_GROUPS_KEY = 'keychain-access-groups';
 
-const extensionBundleId = (config) => {
-  const appBundleId = config.ios && config.ios.bundleIdentifier;
-  if (!appBundleId) {
+const appBundleId = (config) => {
+  const bundleId = config.ios && config.ios.bundleIdentifier;
+  if (!bundleId) {
     throw new Error(
       '[@ethora/chat-component-rn] ios.bundleIdentifier is required for the notification service extension'
     );
   }
-  return `${appBundleId}.${TARGET_NAME}`;
+  return bundleId;
+};
+
+const extensionBundleId = (config) => `${appBundleId(config)}.${TARGET_NAME}`;
+
+/** The keychain access group shared by the app and the extension. */
+const keychainGroup = (config) => `$(AppIdentifierPrefix)${appBundleId(config)}`;
+
+const withSharedGroupFirst = (groups, group) => {
+  const list = Array.isArray(groups) ? groups.filter((g) => g !== group) : [];
+  return [group, ...list];
 };
 
 // EAS Build creates signing credentials only for targets it knows about.
 const withEasAppExtension = (config) => {
   const bundleIdentifier = extensionBundleId(config);
+  const group = keychainGroup(config);
   config.extra = config.extra || {};
   config.extra.eas = config.extra.eas || {};
   config.extra.eas.build = config.extra.eas.build || {};
@@ -49,12 +69,42 @@ const withEasAppExtension = (config) => {
   const ios = (config.extra.eas.build.experimental.ios =
     config.extra.eas.build.experimental.ios || {});
   const extensions = (ios.appExtensions = ios.appExtensions || []);
-  if (!extensions.some((ext) => ext.targetName === TARGET_NAME)) {
-    extensions.push({ targetName: TARGET_NAME, bundleIdentifier, entitlements: {} });
+  let entry = extensions.find((ext) => ext.targetName === TARGET_NAME);
+  if (!entry) {
+    entry = { targetName: TARGET_NAME, bundleIdentifier, entitlements: {} };
+    extensions.push(entry);
   }
+  entry.entitlements = entry.entitlements || {};
+  entry.entitlements[KEYCHAIN_GROUPS_KEY] = withSharedGroupFirst(
+    entry.entitlements[KEYCHAIN_GROUPS_KEY],
+    group
+  );
   return config;
 };
 
+// The app's side of the shared keychain group (Keychain Sharing capability).
+const withAppKeychainGroup = (config) =>
+  withEntitlementsPlist(config, (cfg) => {
+    const group = keychainGroup(cfg);
+    cfg.modResults[KEYCHAIN_GROUPS_KEY] = withSharedGroupFirst(
+      cfg.modResults[KEYCHAIN_GROUPS_KEY],
+      group
+    );
+    return cfg;
+  });
+
+const entitlementsPlist = (group) => `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>${KEYCHAIN_GROUPS_KEY}</key>
+  <array>
+    <string>${group}</string>
+  </array>
+</dict>
+</plist>
+`;
+
 // Copied on every prebuild so an SDK update reaches the app.
 const withExtensionFiles = (config) =>
   withDangerousMod(config, [
@@ -65,6 +115,7 @@ const withExtensionFiles = (config) =>
       for (const file of FILES) {
         fs.copyFileSync(path.join(SOURCE_DIR, file), path.join(dest, file));
       }
+      fs.writeFileSync(path.join(dest, ENTITLEMENTS_FILE), entitlementsPlist(keychainGroup(cfg)));
       return cfg;
     },
   ]);
@@ -97,14 +148,14 @@ const withExtensionTarget = (config, { appleTeamId } = {}) =>
       objects.PBXTargetDependency = objects.PBXTargetDependency || {};
       objects.PBXContainerItemProxy = objects.PBXContainerItemProxy || {};
 
-      const group = project.addPbxGroup(FILES, TARGET_NAME, TARGET_NAME);
+      const group = project.addPbxGroup([...FILES, ENTITLEMENTS_FILE], TARGET_NAME, TARGET_NAME);
       const mainGroup = project.getFirstProject().firstProject.mainGroup;
       project.addToPbxGroup(group.uuid, mainGroup);
 
       // 'app_extension' also embeds the .appex into the app (Copy Files to
       // PlugIns) and makes the app depend on it.
       const target = project.addTarget(TARGET_NAME, 'app_extension', TARGET_NAME, bundleIdentifier);
-      project.addBuildPhase(['NotificationService.swift'], 'PBXSourcesBuildPhase', 'Sources', target.uuid);
+      project.addBuildPhase(SOURCES, 'PBXSourcesBuildPhase', 'Sources', target.uuid);
       project.addBuildPhase([], 'PBXResourcesBuildPhase', 'Resources', target.uuid);
       project.addBuildPhase([], 'PBXFrameworksBuildPhase', 'Frameworks', target.uuid);
       targetUuid = target.uuid;
@@ -116,6 +167,7 @@ const withExtensionTarget = (config, { appleTeamId } = {}) =>
         PRODUCT_BUNDLE_IDENTIFIER: `"${bundleIdentifier}"`,
         INFOPLIST_FILE: `"${TARGET_NAME}/Info.plist"`,
         GENERATE_INFOPLIST_FILE: 'NO',
+        CODE_SIGN_ENTITLEMENTS: `"${TARGET_NAME}/${ENTITLEMENTS_FILE}"`,
         SWIFT_VERSION: appSettings.SWIFT_VERSION || '5.0',
         IPHONEOS_DEPLOYMENT_TARGET: appSettings.IPHONEOS_DEPLOYMENT_TARGET || '15.1',
         TARGETED_DEVICE_FAMILY: appSettings.TARGETED_DEVICE_FAMILY || '"1,2"',
@@ -132,6 +184,6 @@ const withExtensionTarget = (config, { appleTeamId } = {}) =>
   });
 
 const withNotificationServiceExtension = (config, props = {}) =>
-  withExtensionTarget(withExtensionFiles(withEasAppExtension(config)), props);
+  withExtensionTarget(withExtensionFiles(withAppKeychainGroup(withEasAppExtension(config))), props);
 
 module.exports = withNotificationServiceExtension;

package/src/helpers/secureStoreRuntime.ts

@@ -12,10 +12,25 @@
  * AsyncStorage rather than crash (see `secureKeyValue.ts`).
  */
 
+/**
+ * The subset of expo-secure-store's options the SDK uses. `keychainService`
+ * must be repeated on every read of an item written with it; the
+ * accessibility constants come from `SecureStoreRuntime.accessible`.
+ */
+export interface SecureStoreOptions {
+  keychainService?: string;
+  /** iOS only: one of `accessible`; ignored on Android. */
+  keychainAccessible?: unknown;
+}
+
 export interface SecureStoreRuntime {
-  getItemAsync: (key: string) => Promise<string | null>;
-  setItemAsync: (key: string, value: string) => Promise<void>;
-  deleteItemAsync: (key: string) => Promise<void>;
+  getItemAsync: (key: string, options?: SecureStoreOptions) => Promise<string | null>;
+  setItemAsync: (key: string, value: string, options?: SecureStoreOptions) => Promise<void>;
+  deleteItemAsync: (key: string, options?: SecureStoreOptions) => Promise<void>;
+  /** expo-secure-store's iOS keychain accessibility constants (undefined on older versions). */
+  accessible: {
+    afterFirstUnlockThisDeviceOnly?: unknown;
+  };
 }
 
 let cached: SecureStoreRuntime | null | undefined;
@@ -45,6 +60,9 @@ export const loadSecureStore = (): SecureStoreRuntime | null => {
         getItemAsync: mod.getItemAsync,
         setItemAsync: mod.setItemAsync,
         deleteItemAsync: mod.deleteItemAsync,
+        accessible: {
+          afterFirstUnlockThisDeviceOnly: mod.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY,
+        },
       };
     }
   } catch {

package/src/main.ts

@@ -56,6 +56,36 @@ export type {
   PushSubscriptionPayload,
 } from './networking/api-requests/push.api';
 export type { PushTokenType, PushTokenRegistration } from './types/types';
+// Encrypted (sealed) pushes: the device key and the Android renderer.
+// iOS renders them in the notification service extension the config
+// plugin adds. See README, "Encrypted pushes".
+export {
+  ensurePushKeyPair,
+  getPushKeyPair,
+  resetPushKeyPair,
+  clearPushKeyPair,
+  PUSH_KEY_KEYCHAIN_SERVICE,
+  PUSH_SECRET_KEY_ITEM,
+} from './push/pushKeyStore';
+export type { PushKeyPair } from './push/pushKeyStore';
+export {
+  registerSealedPushTask,
+  presentSealedPush,
+  SEALED_PUSH_TASK,
+} from './push/sealedPushTask';
+export type { SealedPushTaskOptions } from './push/sealedPushTask';
+export {
+  openSealedPush,
+  isSealedPush,
+  sealedPushEnvelopeOf,
+  SEALED_PUSH_ALG,
+} from './push/sealedPush';
+export type {
+  SealedPushEnvelope,
+  SealedPushContent,
+  SealedPushFailure,
+  OpenSealedPushResult,
+} from './push/sealedPush';
 export { useChatRoomFocus } from './hooks/useChatRoomFocus';
 export { logoutService, useLogout } from './hooks/useLogout';
 export { useQRCodeChat, handleQRChatId } from './hooks/useQRCodeChatHandler';

package/src/networking/api-requests/push.api.ts

@@ -67,10 +67,20 @@ const isUnknownFieldError = (error: any): boolean =>
   error?.response?.status === 422 &&
   /not allowed/i.test(String(error?.response?.data?.error ?? ''));
 
+/** The only sealing scheme the push service knows (README, "Encrypted pushes"). */
+export const PUSH_KEY_ALG = 'sealed-box-x25519';
+
 export interface PushSubscriptionPayload {
   registrationToken: string;
   deviceType: PushDeviceType;
   tokenType?: PushTokenType;
+  /**
+   * Encrypted pushes: base64 of the device's 32-byte X25519 public key.
+   * Absent keeps whatever key the service holds for this token.
+   */
+  pushKey?: string;
+  pushKeyAlg?: typeof PUSH_KEY_ALG;
+  pushKeyId?: string;
 }
 
 export interface RegisterPushSubscriptionArgs {
@@ -78,15 +88,23 @@ export interface RegisterPushSubscriptionArgs {
   token: string;
   tokenType: PushTokenType;
   authToken: string;
+  /** Base64 public key for encrypted pushes (`ensurePushKeyPair().publicKey`). */
+  pushKey?: string;
+  pushKeyId?: string;
 }
 
 export const buildPushSubscriptionPayload = (
   token: string,
-  tokenType: PushTokenType
+  tokenType: PushTokenType,
+  pushKey?: string,
+  pushKeyId?: string
 ): PushSubscriptionPayload => ({
   registrationToken: token,
   deviceType: resolvePushDeviceType(),
   tokenType,
+  ...(pushKey
+    ? { pushKey, pushKeyAlg: PUSH_KEY_ALG, ...(pushKeyId ? { pushKeyId } : {}) }
+    : {}),
 });
 
 export async function registerPushSubscription({
@@ -94,22 +112,29 @@ export async function registerPushSubscription({
   token,
   tokenType,
   authToken,
+  pushKey,
+  pushKeyId,
 }: RegisterPushSubscriptionArgs): Promise<void> {
   const path = `/v1/push/subscription/${encodeURIComponent(appId)}`;
   const headers = { Authorization: authToken };
-  const payload = buildPushSubscriptionPayload(token, tokenType);
+  const payload = buildPushSubscriptionPayload(token, tokenType, pushKey, pushKeyId);
 
   try {
     await http.post(path, payload, { headers });
     return;
   } catch (error: any) {
-    const canDowngrade = tokenType === 'apns' || tokenType === 'fcm';
+    // A backend that predates `tokenType` still delivers to apns / fcm
+    // tokens. One that predates `pushKey` would deliver in the clear: the
+    // host asked for encryption, so that is an error, never a quiet fallback.
+    const canDowngrade = (tokenType === 'apns' || tokenType === 'fcm') && !pushKey;
     if (!(canDowngrade && isUnknownFieldError(error))) {
       throw toRegistrationError(
         error,
         tokenType === 'expo'
           ? 'Push registration (the backend does not accept Expo push tokens yet)'
-          : 'Push registration'
+          : pushKey && isUnknownFieldError(error)
+            ? 'Push registration (the backend does not support encrypted pushes)'
+            : 'Push registration'
       );
     }
   }

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