fb-messenger-e2ee 0.1.0 → 0.1.2

package/src/e2ee/application/e2ee-client.ts

@@ -1,376 +0,0 @@
-/**
- * E2EE Client - Layer orchestrator
- *
- * Ties together all E2EE layers:
- *   - DeviceStore (key persistence)
- *   - Signal Manager (DM + Group encryption)
- *   - Message Builder (protobuf)
- *   - Media Crypto (AES-CBC + HMAC + HKDF)
- *   - Media Upload (HTTP)
- *   - Noise Handshake (transport) - used by connection layer
- *
- * This replaces the stub E2EEService for actual E2EE message handling.
- */
-
-import type { DeviceStore } from "../store/device-store.ts";
-import type { MediaTypeKey } from "../media/media-crypto.ts";
-import { encryptMedia, decryptMedia } from "../media/media-crypto.ts";
-import {
-  encryptDM,
-  decryptDM,
-  decryptDMPreKey,
-  encryptGroup,
-  decryptGroup,
-  createSenderKeyDistributionMessage,
-  processSKDM,
-  establishSession,
-  jidToAddress,
-  hasSession,
-} from "../signal/signal-manager.ts";
-import type {
-  E2EEDecryptMediaOptions,
-  E2EEEncryptMediaResult,
-  E2EESendTextOptions,
-  EncryptionResult,
-} from "../../models/e2ee.ts";
-export type {
-  E2EEDecryptMediaOptions,
-  E2EEEncryptMediaOptions,
-  E2EEEncryptMediaResult,
-  E2EESendTextOptions,
-  E2EESendTextResult,
-  EncryptionResult,
-  MediaFields,
-} from "../../models/e2ee.ts";
-import {
-  encodeMessageApplication,
-  encodeMessageTransport,
-  MessageBuilder,
-  encodeTextMessage,
-  encodeImageMessage,
-  encodeVideoMessage,
-  encodeAudioMessage,
-  encodeDocumentMessage,
-  encodeStickerMessage,
-  encodeReactionMessage,
-  encodeEditMessage,
-  encodeRevokeMessage,
-} from "../message/message-builder.ts";
-import type { RawPreKeyBundle } from "../../models/e2ee.ts";
-import type { MediaUploadConfig, MmsTypeStr } from "../../models/media.ts";
-import { uploadMedia } from "../media/media-upload.ts";
-import { MmsType } from "../media/media-crypto.ts";
-
-// Types
-
-export interface DMTextFanoutPayloads {
-  type: "dm";
-  messageApp: Buffer;
-  devicePayload: Buffer;
-  selfDevicePayload: Buffer;
-  frankingTag: Buffer;
-}
-
-// E2EEClient
-
-export class E2EEClient {
-  private store: DeviceStore;
-
-  constructor(store: DeviceStore) {
-    this.store = store;
-  }
-
-  // Session management
-
-  /** Establish a session with a contact using their prekey bundle (X3DH). */
-  async establishSession(recipientJid: string, bundle: RawPreKeyBundle): Promise<void> {
-    const addr = jidToAddress(recipientJid);
-    await establishSession(this.store, addr, bundle);
-  }
-
-  async processSenderKeyDistribution(
-    senderJid: string,
-    skdmBytes: Buffer,
-    groupJid?: string,
-  ): Promise<void> {
-    await processSKDM(this.store, senderJid, skdmBytes, groupJid);
-  }
-
-  // Message encrypt (DM)
-
-  /** Build DM text transports for V3 participant fanout. */
-  async buildDMTextFanoutPayloads(opts: E2EESendTextOptions): Promise<DMTextFanoutPayloads> {
-    const builder = new MessageBuilder().setText(opts.text);
-    if (opts.replyToId && opts.replyToSenderJid) {
-      builder.setReply(opts.replyToId, opts.replyToSenderJid);
-    }
-    const consumerApp = builder.build();
-    const { messageApp, frankingTag } = encodeMessageApplication(consumerApp, builder.getReply());
-
-    return {
-      type: "dm",
-      messageApp,
-      devicePayload: encodeMessageTransport({ messageApp }),
-      selfDevicePayload: encodeMessageTransport({
-        messageApp,
-        dsm: { destinationJid: opts.toJid, phash: "" },
-      }),
-      frankingTag,
-    };
-  }
-
-  /**
-   * Build and encrypt a DM text message for Signal transport.
-   * Kept for low-level callers; production send should fan out through participants.
-   */
-  async encryptDMText(opts: E2EESendTextOptions): Promise<Extract<EncryptionResult, { type: "dm" }>> {
-    const fanout = await this.buildDMTextFanoutPayloads(opts);
-    const recipientAddr = jidToAddress(opts.toJid);
-    const selfAddr = jidToAddress(opts.selfJid);
-    const encrypted = await encryptDM(this.store, recipientAddr, selfAddr, fanout.devicePayload);
-
-    return {
-      type: "dm",
-      encrypted: { type: encrypted.type, ciphertext: Buffer.from(encrypted.ciphertext) },
-      frankingTag: fanout.frankingTag,
-      messageApp: fanout.messageApp,
-    };
-  }
-
-  /** Build and encrypt a group text message. */
-  async encryptGroupText(
-    groupJid: string,
-    selfJid: string,
-    text: string,
-    messageId: string,
-    replyToId?: string,
-    replyToSenderJid?: string
-  ): Promise<Extract<EncryptionResult, { type: "group" }>> {
-    const builder = new MessageBuilder().setText(text);
-    if (replyToId && replyToSenderJid) {
-      builder.setReply(replyToId, replyToSenderJid);
-    }
-    const consumerApp = builder.build();
-    const { messageApp, frankingTag } = encodeMessageApplication(consumerApp, builder.getReply());
-
-    const { skdm, distributionId } = await createSenderKeyDistributionMessage(this.store, groupJid, selfJid);
-
-    const groupTransport = encodeMessageTransport({
-      messageApp,
-      backupDirective: { messageId, actionType: "UPSERT" },
-    });
-    // Per-device SKDM transport should not include application payload
-    const deviceTransport = encodeMessageTransport({
-      skdm: { groupId: groupJid, skdmBytes: Buffer.from(skdm.serialize()) },
-    });
-    // DSM is included only for sender's other devices (same user, different device)
-    const selfDeviceTransport = encodeMessageTransport({
-      skdm: { groupId: groupJid, skdmBytes: Buffer.from(skdm.serialize()) },
-      dsm: { destinationJid: groupJid, phash: "" },
-    });
-
-    const groupCiphertext = await encryptGroup(this.store, groupJid, selfJid, groupTransport, distributionId);
-
-    return {
-      type: "group",
-      messageApp,
-      groupCiphertext: Buffer.from(groupCiphertext),
-      devicePayload: Buffer.from(deviceTransport),
-      selfDevicePayload: Buffer.from(selfDeviceTransport),
-      skdmPayload: Buffer.from(groupTransport),
-      skdm: {
-        groupId: groupJid,
-        skdmBytes: Buffer.from(skdm.serialize()),
-        distributionId,
-      },
-      frankingTag,
-    };
-  }
-
-  /** Build and encrypt a pre-built MessageApplication for a group send. */
-  async encryptGroupMessageApplication(
-    groupJid: string,
-    selfJid: string,
-    messageApp: Buffer,
-    messageId: string,
-  ): Promise<Omit<Extract<EncryptionResult, { type: "group" }>, "frankingTag">> {
-    const { skdm, distributionId } = await createSenderKeyDistributionMessage(this.store, groupJid, selfJid);
-
-    const groupTransport = encodeMessageTransport({
-      messageApp,
-      backupDirective: { messageId, actionType: "UPSERT" },
-    });
-    const deviceTransport = encodeMessageTransport({
-      skdm: { groupId: groupJid, skdmBytes: Buffer.from(skdm.serialize()) },
-    });
-    const selfDeviceTransport = encodeMessageTransport({
-      skdm: { groupId: groupJid, skdmBytes: Buffer.from(skdm.serialize()) },
-      dsm: { destinationJid: groupJid, phash: "" },
-    });
-
-    const groupCiphertext = await encryptGroup(this.store, groupJid, selfJid, groupTransport, distributionId);
-
-    return {
-      type: "group",
-      messageApp,
-      groupCiphertext: Buffer.from(groupCiphertext),
-      devicePayload: Buffer.from(deviceTransport),
-      selfDevicePayload: Buffer.from(selfDeviceTransport),
-      skdmPayload: Buffer.from(groupTransport),
-      skdm: {
-        groupId: groupJid,
-        skdmBytes: Buffer.from(skdm.serialize()),
-        distributionId,
-      },
-    };
-  }
-
-  /** Create a sender-key distribution payload for targeted group retry responses. */
-  async createSenderKeyDistributionPayload(groupJid: string, selfJid: string): Promise<{ groupId: string; skdmBytes: Buffer; distributionId: string }> {
-    const { skdm, distributionId } = await createSenderKeyDistributionMessage(this.store, groupJid, selfJid);
-    return { groupId: groupJid, skdmBytes: Buffer.from(skdm.serialize()), distributionId };
-  }
-
-  /** Encrypt a MessageApplication payload directly to one device (used for retry responses). */
-  async encryptMessageAppForDevice(
-    recipientJid: string,
-    selfJid: string,
-    messageApp: Buffer,
-    opts: {
-      skdm?: { groupId: string; skdmBytes: Buffer };
-      dsm?: { destinationJid: string; phash: string };
-      backupDirective?: { messageId: string; actionType: "UPSERT" | "REMOVE" };
-    } = {},
-  ): Promise<{ type: "msg" | "pkmsg"; ciphertext: Buffer }> {
-    const transport = encodeMessageTransport({
-      messageApp,
-      skdm: opts.skdm,
-      dsm: opts.dsm,
-      backupDirective: opts.backupDirective,
-    });
-    return this.encryptDevicePayload(recipientJid, selfJid, transport);
-  }
-
-  /** Check if a session exists for a given device JID. */
-  async hasSession(jid: string): Promise<boolean> {
-    const addr = jidToAddress(jid);
-    return hasSession(this.store, addr);
-  }
-
-  /** Encrypt an SKDM for a specific device DM. */
-  async encryptSKDM(recipientJid: string, selfJid: string, skdm: { groupId: string; skdmBytes: Buffer }): Promise<{ type: "msg" | "pkmsg"; ciphertext: Buffer }> {
-    const transport = encodeMessageTransport({
-      skdm, // No application payload for SKDM-only DM
-    });
-
-    const recipientAddr = jidToAddress(recipientJid);
-    const selfAddr = jidToAddress(selfJid);
-    const encrypted = await encryptDM(this.store, recipientAddr, selfAddr, transport);
-
-    return {
-      type: encrypted.type,
-      ciphertext: Buffer.from(encrypted.ciphertext),
-    };
-  }
-
-  async encryptDevicePayload(recipientJid: string, selfJid: string, payload: Buffer): Promise<{ type: "msg" | "pkmsg"; ciphertext: Buffer }> {
-    const recipientAddr = jidToAddress(recipientJid);
-    const selfAddr = jidToAddress(selfJid);
-    const encrypted = await encryptDM(this.store, recipientAddr, selfAddr, payload);
-
-    return {
-      type: encrypted.type,
-      ciphertext: Buffer.from(encrypted.ciphertext),
-    };
-  }
-
-  // Message decrypt
-
-  /** Decrypt a DM Signal message (type = "msg"). Returns raw MessageTransport bytes. */
-  async decryptDMMessage(senderJid: string, ciphertext: Buffer): Promise<Buffer> {
-    const addr = jidToAddress(senderJid);
-    return decryptDM(this.store, addr, ciphertext);
-  }
-
-  /** Decrypt a DM PreKeySignalMessage (first message from sender). */
-  async decryptDMPreKeyMessage(senderJid: string, selfJid: string, ciphertext: Buffer): Promise<Buffer> {
-    const senderAddr = jidToAddress(senderJid);
-    const selfAddr = jidToAddress(selfJid);
-    return decryptDMPreKey(this.store, senderAddr, selfAddr, ciphertext);
-  }
-
-  async decryptGroupMessage(
-    senderJid: string,
-    ciphertext: Buffer,
-    groupJid?: string,
-  ): Promise<Buffer> {
-    return decryptGroup(this.store, senderJid, ciphertext, groupJid);
-  }
-
-  // Media
-
-  /** Encrypt media bytes for upload. Returns crypto fields + uploadable buffer. */
-  encryptMedia(data: Buffer, type: MediaTypeKey) {
-    return encryptMedia(data, type);
-  }
-
-  /** Decrypt downloaded E2EE media. */
-  decryptMedia(opts: E2EEDecryptMediaOptions): Buffer {
-    return decryptMedia(opts);
-  }
-
-  /**
-   * Encrypt + upload media in one step.
-   * Returns all fields needed to build a ConsumerApplication media message.
-   * @param refreshConfig Optional callback to refresh upload config on 401.
-   */
-  async encryptAndUploadMedia(
-    uploadConfig: MediaUploadConfig,
-    data: Buffer,
-    type: MediaTypeKey,
-    mimeType: string,
-    refreshConfig?: () => Promise<MediaUploadConfig>,
-  ): Promise<E2EEEncryptMediaResult> {
-    const mmsTypeStr = MmsType[type] as MmsTypeStr;
-    const encrypted = encryptMedia(data, type);
-    const uploaded = await uploadMedia(uploadConfig, encrypted.dataToUpload, encrypted.fileEncSHA256, mmsTypeStr, {
-      refreshConfig,
-    });
-
-    const mediaKeyTimestamp = Math.floor(Date.now() / 1000);
-
-    return {
-      mediaKey: encrypted.mediaKey,
-      fileSHA256: encrypted.fileSHA256,
-      fileEncSHA256: encrypted.fileEncSHA256,
-      fileLength: encrypted.fileLength,
-      directPath: uploaded.directPath,
-      handle: uploaded.handle,
-      objectId: uploaded.objectId,
-      mediaFields: {
-        mimeType,
-        fileSHA256: encrypted.fileSHA256,
-        fileLength: encrypted.fileLength,
-        mediaKey: encrypted.mediaKey,
-        fileEncSHA256: encrypted.fileEncSHA256,
-        directPath: uploaded.directPath,
-        objectId: uploaded.objectId,
-        mediaKeyTimestamp,
-      },
-    };
-  }
-
-  // Message builder helpers (passthrough)
-
-  buildTextMessage = encodeTextMessage;
-  buildImageMessage = encodeImageMessage;
-  buildVideoMessage = encodeVideoMessage;
-  buildAudioMessage = encodeAudioMessage;
-  buildDocumentMessage = encodeDocumentMessage;
-  buildStickerMessage = encodeStickerMessage;
-  buildReactionMessage = encodeReactionMessage;
-  buildEditMessage = encodeEditMessage;
-  buildRevokeMessage = encodeRevokeMessage;
-  buildMessageApplication = encodeMessageApplication;
-  buildMessageTransport = encodeMessageTransport;
-}

package/src/e2ee/application/fanout-planner.ts

@@ -1,79 +0,0 @@
-import { createHash } from "node:crypto";
-
-export interface ParsedMessengerJid {
-  user: string;
-  device: number;
-  server: string;
-}
-
-export function parseMessengerJid(jid: string): ParsedMessengerJid {
-  const [userPart = jid, server = ""] = jid.split("@");
-  const colonIdx = userPart.indexOf(":");
-  const dotIdx = userPart.indexOf(".");
-  const userEnd = dotIdx !== -1 ? dotIdx : (colonIdx !== -1 ? colonIdx : userPart.length);
-  const user = userPart.slice(0, userEnd) || userPart;
-  const rawDevice = colonIdx !== -1
-    ? userPart.slice(colonIdx + 1)
-    : (dotIdx !== -1 ? userPart.slice(dotIdx + 1) : "0");
-  return { user, device: Number(rawDevice) || 0, server };
-}
-
-export function toBareMessengerJid(jid: string): string {
-  const parsed = parseMessengerJid(jid);
-  return parsed.server === "msgr" ? `${parsed.user}.0@msgr` : jid;
-}
-
-export function normalizeDMThreadToJid(threadId: string): string {
-  const jid = threadId.includes("@")
-    ? threadId
-    : (threadId.includes(".") || threadId.includes(":") ? `${threadId}@msgr` : `${threadId}.0@msgr`);
-  return toBareMessengerJid(jid);
-}
-
-export function sameMessengerUser(a: string, b: string): boolean {
-  const pa = parseMessengerJid(a);
-  const pb = parseMessengerJid(b);
-  return pa.server === "msgr" && pb.server === "msgr" && pa.user === pb.user;
-}
-
-export function sameMessengerDevice(a: string, b: string): boolean {
-  const pa = parseMessengerJid(a);
-  const pb = parseMessengerJid(b);
-  return pa.server === "msgr" && pb.server === "msgr" && pa.user === pb.user && pa.device === pb.device;
-}
-
-export function uniqueJids(jids: string[]): string[] {
-  const seen = new Set<string>();
-  const out: string[] = [];
-  for (const jid of jids) {
-    if (!jid) continue;
-    const parsed = parseMessengerJid(jid);
-    const key = parsed.server === "msgr" ? `${parsed.user}:${parsed.device}@${parsed.server}` : jid;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push(jid);
-  }
-  return out;
-}
-
-export function toADString(jid: string): string {
-  const [userPart = "", server = ""] = jid.split("@");
-  if (server === "msgr") {
-    const parsed = parseMessengerJid(jid);
-    if (!parsed.user) return jid;
-    return `${parsed.user}.0:${parsed.device}@${server}`;
-  }
-
-  const [userAndAgent = "", devicePart = ""] = userPart.split(":");
-  const [user = "", rawAgentPart = ""] = userAndAgent.split(".");
-  const rawAgent = rawAgentPart ? Number(rawAgentPart) : 0;
-  const device = devicePart ? Number(devicePart) : 0;
-  if (!user) return jid;
-  return `${user}.${rawAgent}:${device}@${server}`;
-}
-
-export function buildParticipantListHash(participants: string[]): string {
-  const sorted = [...participants].map((jid) => toADString(jid)).sort();
-  const hash = createHash("sha256").update(sorted.join("")).digest();
-  return `2:${hash.subarray(0, 6).toString("base64").replace(/=+$/, "")}`;
-}

package/src/e2ee/application/outbound-message-cache.ts

@@ -1,58 +0,0 @@
-import { now } from "../../utils/fca-utils.ts";
-
-export interface RecentE2EEOutgoing {
-  kind: "dm" | "group";
-  chatJid: string;
-  messageId: string;
-  messageType: string;
-  messageApp: Buffer;
-  frankingTag: Buffer;
-  createdAtMs: number;
-}
-
-export interface OutboundMessageCacheOptions {
-  ttlMs?: number;
-  maxEntries?: number;
-}
-
-/**
- * Short-lived cache of encrypted outbound message material used to answer
- * Messenger retry receipts without re-registering the device.
- */
-export class OutboundMessageCache {
-  private readonly records = new Map<string, RecentE2EEOutgoing>();
-  private readonly ttlMs: number;
-  private readonly maxEntries: number;
-
-  constructor(opts: OutboundMessageCacheOptions = {}) {
-    this.ttlMs = opts.ttlMs ?? 15 * 60 * 1000;
-    this.maxEntries = opts.maxEntries ?? 200;
-  }
-
-  remember(record: RecentE2EEOutgoing): void {
-    this.prune();
-    this.records.set(record.messageId, record);
-
-    while (this.records.size > this.maxEntries) {
-      const oldest = this.records.keys().next().value;
-      if (!oldest) break;
-      this.records.delete(oldest);
-    }
-  }
-
-  get(messageId: string): RecentE2EEOutgoing | undefined {
-    this.prune();
-    return this.records.get(messageId);
-  }
-
-  prune(nowMs: number = now()): void {
-    const cutoff = nowMs - this.ttlMs;
-    for (const [messageId, record] of this.records) {
-      if (record.createdAtMs < cutoff) this.records.delete(messageId);
-    }
-  }
-
-  clear(): void {
-    this.records.clear();
-  }
-}

package/src/e2ee/application/prekey-maintenance.ts

@@ -1,55 +0,0 @@
-import { now } from "../../utils/fca-utils.ts";
-import { logger } from "../../utils/logger.ts";
-import { MIN_PREKEY_COUNT, WANTED_PREKEY_COUNT } from "../signal/prekey-manager.ts";
-
-export interface PreKeyMaintenanceOptions {
-  getSocket: () => unknown | null;
-  getStore: () => unknown | null;
-  getServerPreKeyCount: () => Promise<number>;
-  uploadPreKeys: (count: number) => Promise<void>;
-}
-
-/** Periodically tops up one-time prekeys without rotating the registered device. */
-export class PreKeyMaintenance {
-  private interval?: ReturnType<typeof setInterval>;
-
-  constructor(private readonly opts: PreKeyMaintenanceOptions) {}
-
-  start(): void {
-    this.stop();
-    const intervalMs = Number(process.env.FB_E2EE_PREKEY_SYNC_INTERVAL_MS ?? "1800000");
-    if (!Number.isFinite(intervalMs) || intervalMs <= 0) return;
-
-    this.interval = setInterval(() => {
-      void this.sync("periodic").catch((err) => {
-        logger.error("PreKeyMaintenance", "Periodic prekey sync failed:", err);
-      });
-    }, intervalMs);
-  }
-
-  stop(): void {
-    if (this.interval) {
-      clearInterval(this.interval);
-      this.interval = undefined;
-    }
-  }
-
-  async sync(reason: string): Promise<void> {
-    if (!this.opts.getSocket() || !this.opts.getStore()) return;
-
-    const minCount = Number(process.env.FB_E2EE_PREKEY_MIN_COUNT ?? String(MIN_PREKEY_COUNT));
-    const uploadCount = Number(process.env.FB_E2EE_PREKEY_UPLOAD_COUNT ?? String(WANTED_PREKEY_COUNT));
-
-    try {
-      const serverCount = await this.opts.getServerPreKeyCount();
-      logger.info("PreKeyMaintenance", `E2EE prekey sync (${reason}): server has ${serverCount} prekeys`);
-
-      if (serverCount < minCount) {
-        await this.opts.uploadPreKeys(uploadCount);
-        logger.info("PreKeyMaintenance", `Uploaded ${uploadCount} E2EE prekeys without changing registered device`);
-      }
-    } catch (err) {
-      logger.error("PreKeyMaintenance", `Prekey sync failed (${reason}) at ${now()}:`, err);
-    }
-  }
-}