fb-messenger-e2ee 0.1.0

package/src/models/messaging.ts

@@ -0,0 +1,88 @@
+export interface SendMessageInput {
+  threadId: string;
+  text: string;
+  replyToMessageId?: string;
+}
+
+export interface SendMediaInput {
+  threadId: string;
+  data: Buffer;
+  fileName: string;
+  /** Optional; inferred from fileName extension when omitted. */
+  mimeType?: string;
+  caption?: string;
+  replyToMessageId?: string;
+  /** Optional media width in pixels for E2EE image/video/sticker payloads. */
+  width?: number;
+  /** Optional media height in pixels for E2EE image/video/sticker payloads. */
+  height?: number;
+  /** Optional media duration in whole seconds for E2EE video/audio payloads. */
+  seconds?: number;
+  /** Alias for seconds, kept for callers that use media-style naming. */
+  duration?: number;
+  /** Whether E2EE audio should be sent as push-to-talk/voice. Defaults to true for sendAudio. */
+  ptt?: boolean;
+}
+
+export interface SendStickerInput {
+  threadId: string;
+  stickerId: number;
+  replyToMessageId?: string;
+}
+
+export interface TypingInput {
+  threadId: string;
+  isTyping: boolean;
+}
+
+export interface MarkReadInput {
+  threadId: string;
+}
+
+export interface SendReactionInput {
+  messageId: string;
+  reaction: string;
+  /** Thread ID or canonical E2EE chat JID containing the target message. */
+  threadId: string;
+  /** Sender JID of the target E2EE message; required for reacting to someone else's group message. */
+  senderJid?: string;
+  /** Alias for senderJid for callers that prefer explicit target naming. */
+  targetSenderJid?: string;
+}
+
+export interface MuteThreadInput {
+  threadId: string;
+  /** Seconds to mute; -1 = forever, 0 = unmute */
+  muteSeconds: number;
+}
+
+export interface RenameThreadInput {
+  threadId: string;
+  newName: string;
+}
+
+export interface SetGroupPhotoInput {
+  threadId: string;
+  data: Buffer;
+  mimeType: string;
+}
+
+export interface DeleteThreadInput {
+  threadId: string;
+}
+
+export interface CreateThreadInput {
+  userId: string;
+}
+
+export interface SearchUsersInput {
+  query: string;
+}
+
+export interface GetUserInfoInput {
+  userId: string;
+}
+
+export interface DownloadMediaInput {
+  url: string;
+}

package/src/models/thread.ts

@@ -0,0 +1,69 @@
+import type { Thread } from "./domain.ts";
+
+export interface GetThreadListInput {
+  limit: number;
+  /** Pass timestamp from last thread to paginate */
+  beforeTimestamp?: number | null;
+  /** Thread folder: "" | "INBOX" | "PENDING" | etc. */
+  folder?: string;
+}
+
+export interface GetThreadHistoryInput {
+  threadId: string;
+  amount: number;
+  /** Fetch messages before this timestamp for pagination */
+  beforeTimestamp?: number;
+}
+
+export interface ForwardAttachmentInput {
+  attachmentId: string;
+  /** One or more thread IDs to forward to */
+  threadIds: string[];
+}
+
+export interface CreatePollInput {
+  threadId: string;
+  title: string;
+  /** Map of option text -> whether creator pre-votes for it */
+  options?: Record<string, boolean>;
+}
+
+export interface EditMessageInput {
+  messageId: string;
+  newText: string;
+}
+
+export interface AddGroupMemberInput {
+  threadId: string;
+  /** User ID(s) to add */
+  userIds: string[];
+}
+
+export interface RemoveGroupMemberInput {
+  threadId: string;
+  userId: string;
+}
+
+export interface ChangeAdminStatusInput {
+  threadId: string;
+  userId: string;
+  isAdmin: boolean;
+}
+
+export interface ThreadDetails extends Omit<Thread, "snippet"> {
+  unreadCount: number;
+  messageCount: number;
+  emoji: string | null;
+  muteUntil: number | null;
+  participantIds: string[];
+  adminIds: string[];
+  isArchived: boolean;
+  folder: string;
+  /** fca-unofficial can return null for snippet */
+  snippet: string | null | undefined;
+}
+
+export interface EditMessageResult {
+  messageId: string;
+  newText: string;
+}

package/src/repositories/session.repository.ts

@@ -0,0 +1,20 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import type { SessionData, SessionRepository } from "../models/client.ts";
+
+export class FileSessionRepository implements SessionRepository {
+  public async read(path: string): Promise<SessionData | null> {
+    try {
+      const content = await readFile(path, "utf-8");
+      return JSON.parse(content) as SessionData;
+    } catch {
+      return null;
+    }
+  }
+
+  public async write(path: string, session: SessionData): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(session, null, 2), "utf-8");
+  }
+}

package/src/services/auth.service.ts

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+
+import type { AppStateCookie } from "fca-unofficial";
+
+import type { AuthConfig } from "../models/config.ts";
+import type { SessionData, SessionRepository } from "../models/client.ts";
+
+export class AuthService {
+  public constructor(private readonly sessionRepository: SessionRepository) {}
+
+  public async readAppState(config: AuthConfig): Promise<AppStateCookie[]> {
+    let parsed: unknown;
+
+    if (config.appState) {
+      if (typeof config.appState === "string") {
+        parsed = JSON.parse(config.appState);
+      } else {
+        parsed = config.appState;
+      }
+    } else if (config.appStatePath) {
+      const raw = await readFile(config.appStatePath, "utf-8");
+      parsed = JSON.parse(raw);
+    } else {
+      throw new Error("Either appState or appStatePath must be provided");
+    }
+
+    if (!Array.isArray(parsed)) {
+      throw new Error("Invalid appState format: expected an array");
+    }
+
+    return parsed.map(item => {
+      const cookie = item as Record<string, unknown>;
+      return {
+        key: String(cookie.key ?? cookie.name ?? ""),
+        value: String(cookie.value ?? ""),
+        domain: typeof cookie.domain === "string" ? cookie.domain : ".facebook.com",
+        path: typeof cookie.path === "string" ? cookie.path : "/",
+        expires:
+          typeof cookie.expires === "number" && Number.isFinite(cookie.expires)
+            ? cookie.expires
+            : typeof cookie.expirationDate === "number" && Number.isFinite(cookie.expirationDate)
+              ? cookie.expirationDate
+              : Date.now() + 1000 * 60 * 60 * 24 * 365,
+      };
+    });
+  }
+
+  public async saveSession(path: string, session: SessionData): Promise<void> {
+    await this.sessionRepository.write(path, session);
+  }
+
+  public async loadSession(path: string): Promise<SessionData | null> {
+    return this.sessionRepository.read(path);
+  }
+}

package/src/services/e2ee.service.ts

@@ -0,0 +1,174 @@
+/**
+ * E2EEService - extension point for end-to-end encrypted media operations.
+ *
+ * The JS/TS side of this bridge keeps E2EE media upload/download separate
+ * from the non-E2EE Messenger gateway. fca-unofficial speaks to the
+ * standard Messenger LightSpeed API (non-E2EE) only.
+ *
+ * This service therefore acts as a typed facade that:
+ *  1. Documents the contract (what operations are expected, their inputs/outputs).
+ *  2. Provides an extension point where a future native-addon or WASM layer
+ *     can be plugged in.
+ *  3. Exposes a guard so callers know E2EE is not yet connected.
+ *
+ * Concrete implementations can extend or replace this class.
+ */
+
+import type {
+  E2EEDownloadOptions,
+  E2EEDownloadResult,
+  E2EESendAudioOptions,
+  E2EESendDocumentOptions,
+  E2EESendImageOptions,
+  E2EESendStickerOptions,
+  E2EESendVideoOptions,
+  E2EEUploadResult,
+} from "../models/e2ee.ts";
+import type { E2EEClient } from "../e2ee/application/e2ee-client.ts";
+import type { MediaUploadConfig } from "../models/media.ts";
+import { MediaType, type MediaTypeKey } from "../e2ee/media/media-crypto.ts";
+
+export class E2EEService {
+  private _connected = false;
+  private e2eeClient?: E2EEClient;
+  private uploadConfig?: MediaUploadConfig;
+
+  public setProvider(client: E2EEClient, uploadConfig: MediaUploadConfig): void {
+    this.e2eeClient = client;
+    this.uploadConfig = uploadConfig;
+    this._connected = true;
+  }
+
+  public get isConnected(): boolean {
+    return this._connected;
+  }
+
+  /** Called by an external E2EE provider when it establishes a connection. */
+  public markConnected(): void {
+    this._connected = true;
+  }
+
+  /** Called when the E2EE connection drops. */
+  public markDisconnected(): void {
+    this._connected = false;
+  }
+
+  public ensureEnabled(): void {
+    if (!this._connected || !this.e2eeClient) {
+      throw new Error("E2EE provider not connected");
+    }
+  }
+
+  public getClient(): E2EEClient {
+    this.ensureEnabled();
+    return this.e2eeClient!;
+  }
+
+  // Typed implementations wrapping E2EEClient
+
+  /** Send an E2EE image. Requires a concrete provider implementation. */
+  public async sendImage(opts: E2EESendImageOptions): Promise<E2EEUploadResult> {
+    this.ensureEnabled();
+    await this.e2eeClient!.encryptAndUploadMedia(
+      this.uploadConfig!,
+      opts.data,
+      "image",
+      opts.mimeType || "image/jpeg"
+    );
+    // TODO: Send ConsumerApplication protobuf via Transport
+    return {
+      messageId: "mock-id",
+      timestampMs: Date.now()
+    };
+  }
+
+  /** Send an E2EE video. */
+  public async sendVideo(opts: E2EESendVideoOptions): Promise<E2EEUploadResult> {
+    this.ensureEnabled();
+    await this.e2eeClient!.encryptAndUploadMedia(
+      this.uploadConfig!,
+      opts.data,
+      "video",
+      opts.mimeType || "video/mp4"
+    );
+    return { messageId: "mock-id", timestampMs: Date.now() };
+  }
+
+  /** Send an E2EE audio/voice message. */
+  public async sendAudio(opts: E2EESendAudioOptions): Promise<E2EEUploadResult> {
+    this.ensureEnabled();
+    await this.e2eeClient!.encryptAndUploadMedia(
+      this.uploadConfig!,
+      opts.data,
+      "audio",
+      opts.mimeType || "audio/ogg; codecs=opus"
+    );
+    return { messageId: "mock-id", timestampMs: Date.now() };
+  }
+
+  /** Send an E2EE document/file. */
+  public async sendDocument(opts: E2EESendDocumentOptions): Promise<E2EEUploadResult> {
+    this.ensureEnabled();
+    await this.e2eeClient!.encryptAndUploadMedia(
+      this.uploadConfig!,
+      opts.data,
+      "document",
+      opts.mimeType || "application/octet-stream"
+    );
+    return { messageId: "mock-id", timestampMs: Date.now() };
+  }
+
+  /** Send an E2EE sticker. */
+  public async sendSticker(opts: E2EESendStickerOptions): Promise<E2EEUploadResult> {
+    this.ensureEnabled();
+    await this.e2eeClient!.encryptAndUploadMedia(
+      this.uploadConfig!,
+      opts.data,
+      "image",
+      opts.mimeType || "image/webp"
+    );
+    return { messageId: "mock-id", timestampMs: Date.now() };
+  }
+
+  /** Download E2EE media by decrypting it with the provided keys. */
+  public async downloadMedia(opts: E2EEDownloadOptions): Promise<E2EEDownloadResult> {
+    this.ensureEnabled();
+    // Fetch encrypted payload from CDN
+    const resp = await fetch(opts.directPath);
+    if (!resp.ok) {
+      throw new Error(`Failed to fetch media from CDN: ${resp.status}`);
+    }
+    const encryptedData = Buffer.from(await resp.arrayBuffer());
+
+    // Determine MediaTypeKey
+    let type: MediaTypeKey;
+    switch (opts.mediaType) {
+      case "image": type = "image"; break;
+      case "video": type = "video"; break;
+      case "audio": type = "audio"; break;
+      case "voice": type = "audio"; break;
+      case "document": type = "document"; break;
+      case "sticker": type = "image"; break; // stickers use IMAGE crypto
+      default: type = "document"; break;
+    }
+
+    // Decrypt
+    const mediaKey = Buffer.from(opts.mediaKey, "base64");
+    const fileSHA256 = Buffer.from(opts.mediaSha256, "base64");
+    const fileEncSHA256 = opts.mediaEncSha256 ? Buffer.from(opts.mediaEncSha256, "base64") : undefined;
+
+    const decrypted = this.e2eeClient!.decryptMedia({
+      data: encryptedData,
+      mediaKey,
+      type: type,
+      fileSHA256,
+      fileEncSHA256
+    });
+
+    return {
+      data: decrypted,
+      mimeType: opts.mimeType || "application/octet-stream",
+      fileSize: decrypted.length
+    };
+  }
+}

package/src/services/facebook-gateway.service.ts

@@ -0,0 +1,245 @@
+import { createRequire } from "node:module";
+import { Readable } from "node:stream";
+import { Buffer } from "node:buffer";
+
+import type { FCAApi, LoginData } from "fca-unofficial";
+import { createHmac, createHash } from "node:crypto";
+import { logger } from "../utils/logger.ts";
+
+const require = createRequire(import.meta.url);
+const fcaLogin = require("fca-unofficial") as (
+  loginData: LoginData,
+  options: Record<string, unknown>,
+  callback: (err: unknown, api?: FCAApi) => void,
+) => void;
+
+function normalizeError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+  return new Error("Unknown FCA error");
+}
+
+export class FacebookGatewayService {
+  public async login(appState: LoginData["appState"]): Promise<FCAApi> {
+    return new Promise<FCAApi>((resolve, reject) => {
+      fcaLogin({ appState }, {}, (err, api) => {
+        if (err) {
+          reject(normalizeError(err));
+          return;
+        }
+        if (!api) {
+          reject(new Error("Login succeeded without API instance"));
+          return;
+        }
+        resolve(api);
+      });
+    });
+  }
+
+  public configure(api: FCAApi): void {
+    api.setOptions?.({
+      selfListen: false,
+      listenEvents: true,
+      autoMarkRead: false,
+      autoMarkDelivery: false,
+      online: true,
+    });
+  }
+
+  public async startListening(
+    api: FCAApi,
+    onEvent: (event: Record<string, unknown>) => void,
+    onError: (error: Error) => void,
+  ): Promise<void> {
+    await Promise.resolve(
+      api.listenMqtt((err, event) => {
+        if (err) {
+          onError(normalizeError(err));
+          return;
+        }
+        if (event && typeof event === "object") {
+          onEvent(event);
+        }
+      }),
+    );
+  }
+
+  public async sendMessage(
+    api: FCAApi,
+    threadId: string,
+    text: string,
+    replyToMessageId?: string,
+  ): Promise<Record<string, unknown>> {
+    const response = await Promise.resolve(api.sendMessage(text, threadId, undefined, replyToMessageId));
+    return (response ?? {}) as Record<string, unknown>;
+  }
+
+  public async sendAttachmentMessage(
+    api: FCAApi,
+    input: {
+      threadId: string;
+      data: Buffer;
+      fileName: string;
+      caption?: string;
+      replyToMessageId?: string;
+    },
+  ): Promise<Record<string, unknown>> {
+    const stream = Readable.from(input.data);
+    Object.assign(stream, { path: input.fileName });
+
+    const payload = {
+      body: input.caption ?? "",
+      attachment: stream,
+    };
+
+    const response = await Promise.resolve(
+      api.sendMessage(payload, input.threadId, undefined, input.replyToMessageId),
+    );
+    return (response ?? {}) as Record<string, unknown>;
+  }
+
+  public async sendReaction(
+    api: FCAApi,
+    messageId: string,
+    reaction: string,
+  ): Promise<void> {
+    if (!api.setMessageReaction) {
+      throw new Error("setMessageReaction is not available in fca-unofficial");
+    }
+    await Promise.resolve(api.setMessageReaction(reaction, messageId, undefined, true));
+  }
+
+  public async unsendMessage(api: FCAApi, messageId: string): Promise<void> {
+    if (!api.unsendMessage) {
+      throw new Error("unsendMessage is not available in fca-unofficial");
+    }
+    await Promise.resolve(api.unsendMessage(messageId));
+  }
+
+  public async sendTyping(api: FCAApi, threadId: string, isTyping: boolean): Promise<void> {
+    if (!api.sendTypingIndicator) {
+      throw new Error("sendTypingIndicator is not available in fca-unofficial");
+    }
+    await Promise.resolve(api.sendTypingIndicator(isTyping, threadId));
+  }
+
+  public async markAsRead(api: FCAApi, threadId: string): Promise<void> {
+    if (!api.markAsRead) {
+      throw new Error("markAsRead is not available in fca-unofficial");
+    }
+    await Promise.resolve(api.markAsRead(threadId, true));
+  }
+
+  public async sendStickerMessage(
+    api: FCAApi,
+    input: {
+      threadId: string;
+      stickerId: number;
+      replyToMessageId?: string;
+    },
+  ): Promise<Record<string, unknown>> {
+    const payload = { sticker: input.stickerId };
+    const response = await Promise.resolve(
+      api.sendMessage(payload, input.threadId, undefined, input.replyToMessageId),
+    );
+    return (response ?? {}) as Record<string, unknown>;
+  }
+
+  public stop(api: FCAApi): void {
+    api.stopListenMqtt?.();
+  }
+
+  /**
+   * Fetch the Crypto Auth Token (CAT) required for E2EE connection.
+   * This uses the MAWCatQuery GraphQL document.
+   */
+  public async fetchCAT(api: FCAApi): Promise<string> {
+    const fb_dtsg = (api as any).fb_dtsg;
+    const userId = (api as any).getCurrentUserID();
+
+    logger.debug("FacebookGatewayService", "Fetching CAT via GraphQL...");
+    const resText = await (api as any).httpPost("https://www.facebook.com/api/graphql/", {
+      fb_dtsg,
+      variables: "{}",
+      doc_id: "23999698219677129",
+      __user: userId,
+      __a: "1",
+      __jssesw: "1",
+      server_timestamps: "true",
+    });
+
+    const cleanText = resText.replace("for (;;);", "").trim();
+    let data;
+    try {
+      data = JSON.parse(cleanText);
+    } catch (e) {
+      logger.error("FacebookGatewayService", "Failed to parse CAT response:", resText);
+      throw new Error("Failed to parse CAT response");
+    }
+
+    const cat = data?.data?.secure_message_over_wa_cat_query?.encrypted_serialized_cat;
+
+    if (!cat) {
+      logger.error("FacebookGatewayService", "CAT GraphQL response (no cat):", resText);
+      throw new Error("Failed to extract CAT token from GraphQL response");
+    }
+
+    logger.debug("FacebookGatewayService", `CAT fetched successfully. Length: ${cat.length}, Prefix: ${cat.slice(0, 20)}...`);
+    return cat;
+  }
+
+
+  /**
+   * Fetch ICDC metadata for the user.
+   */
+  public async fetchICDC(api: FCAApi, fbid: string, deviceId: string, fbCat: Buffer): Promise<any> {
+    if (typeof (api as any).httpPost !== "function") {
+      throw new Error("api.httpPost is required for ICDC fetch");
+    }
+
+    const resText = await (api as any).httpPost("https://reg-e2ee.facebook.com/v2/fb_icdc_fetch", {
+      fbid: fbid,
+      fb_cat: fbCat.toString("utf8"), // Assuming it's the base64 string
+      app_id: "256002347743983",
+      device_id: deviceId,
+    });
+
+    if (!resText) throw new Error("Empty response from icdc_fetch");
+    return JSON.parse(resText);
+  }
+
+  /**
+   * Register the device for ICDC.
+   */
+  public async registerICDC(api: FCAApi, fbid: string, deviceId: string, fbCat: Buffer, payload: any): Promise<any> {
+    if (typeof (api as any).httpPost !== "function") {
+      throw new Error("api.httpPost is required for ICDC register");
+    }
+
+    const fullPayload = {
+      fbid: fbid,
+      fb_cat: fbCat.toString("base64"),
+      app_id: "256002347743983",
+      device_id: deviceId,
+      ...payload,
+    };
+    const appState = (api as any).getAppState?.();
+    const cookies = (appState as any[] || []).map(c => `${c.key}=${c.value}`).join("; ");
+    const userAgent = "Facebook Messenger/441.1.0.32.115 (Android 13; 480dpi; 1080x2236; Xiaomi; 2210132G; cupid; qcom; en_US; 555627749)";
+
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(fullPayload)) {
+      params.append(key, String(value));
+    }
+
+    logger.debug("FacebookGatewayService", "Sending ICDC registration via api.httpPost...");
+    const resText = await (api as any).httpPost("https://reg-e2ee.facebook.com/v2/fb_register_v2", fullPayload);
+    logger.debug("FacebookGatewayService", "Raw Register Response:", resText);
+    if (!resText) throw new Error("Empty response from icdc_register");
+    return JSON.parse(resText);
+  }
+}