fb-messenger-e2ee 0.1.0

package/src/types/advanced-types.ts

@@ -0,0 +1,61 @@
+import { EventEmitter } from "node:events";
+
+/**
+ * A type-safe version of Node.js EventEmitter.
+ * T is a record where keys are event names and values are payload types.
+ */
+export class TypedEventEmitter<T extends Record<string, any>> extends EventEmitter {
+  override on<K extends keyof T>(event: K | (string & symbol) | string | symbol, listener: (data: T[K]) => void): this {
+    return super.on(event as string | symbol, listener as any);
+  }
+
+  override once<K extends keyof T>(event: K | (string & symbol) | string | symbol, listener: (data: T[K]) => void): this {
+    return super.once(event as string | symbol, listener as any);
+  }
+
+  override off<K extends keyof T>(event: K | (string & symbol) | string | symbol, listener: (data: T[K]) => void): this {
+    return super.off(event as string | symbol, listener as any);
+  }
+
+  override emit<K extends keyof T>(event: K | (string & symbol) | string | symbol, data: T[K]): boolean {
+    return super.emit(event as string | symbol, data);
+  }
+
+  override removeAllListeners<K extends keyof T>(event?: K | (string & symbol) | string | symbol): this {
+    return super.removeAllListeners(event as string | symbol);
+  }
+}
+
+/**
+ * Recursively makes all properties in T readonly.
+ */
+
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends (infer U)[]
+    ? readonly DeepReadonly<U>[]
+    : T[P] extends object
+    ? DeepReadonly<T[P]>
+    : T[P];
+};
+
+/**
+ * Recursively makes all properties in T optional.
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends (infer U)[]
+    ? DeepPartial<U>[]
+    : T[P] extends object
+    ? DeepPartial<T[P]>
+    : T[P];
+};
+
+/**
+ * Asserts that two types are equal at the type level.
+ * Useful for type-level testing.
+ */
+export type AssertEqual<T, U> =
+  [T] extends [U]
+    ? [U] extends [T]
+      ? true
+      : false
+    : false;

package/src/types/fca-unofficial.d.ts

@@ -0,0 +1,212 @@
+declare module "fca-unofficial" {
+  export interface SendMessagePayload {
+    body?: string;
+    attachment?: unknown;
+    url?: string;
+    sticker?: number;
+    mentions?: Array<{
+      id: string;
+      tag: string;
+      fromIndex: number;
+    }>;
+  }
+
+  export interface AppStateCookie {
+    key: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+  }
+
+  export interface LoginData {
+    appState: AppStateCookie[];
+  }
+
+  export interface FriendInfo {
+    name: string;
+    firstName?: string;
+    vanity?: string;
+    thumbSrc?: string;
+    profileUrl?: string;
+    gender?: number;
+    type?: string;
+    isFriend?: boolean;
+    isBirthDay?: boolean;
+  }
+
+  export interface ThreadParticipant {
+    accountType: string;
+    userID: string;
+    name: string;
+    url?: string;
+    profilePicture?: string;
+    username?: string | null;
+    gender?: string;
+    isViewerFriend?: boolean;
+    isMessengerUser?: boolean;
+    isVerified?: boolean;
+  }
+
+  export interface ThreadListItem {
+    threadID: string;
+    name: string | null;
+    unreadCount: number;
+    messageCount: number;
+    imageSrc: string | null;
+    emoji: string | null;
+    color: string | null;
+    nicknames: Array<{ userID: string; nickname: string }>;
+    muteUntil: number | null;
+    participants: ThreadParticipant[];
+    participantIDs: string[];
+    adminIDs: string[];
+    folder: string;
+    isGroup: boolean;
+    isArchived: boolean;
+    isSubscribed: boolean;
+    timestamp: string;
+    snippet: string | null;
+    snippetSender: string | null;
+    lastMessageTimestamp: string | null;
+    lastReadTimestamp: string | null;
+    approvalMode: boolean;
+    threadType: 1 | 2;
+  }
+
+  export interface HistoryMessage {
+    type: string;
+    senderID: string;
+    body: string;
+    threadID: string;
+    messageID: string;
+    attachments: unknown[];
+    mentions: Record<string, string>;
+    timestamp: string;
+    isGroup: boolean;
+    isUnread?: boolean;
+    messageReactions?: unknown[] | null;
+  }
+
+  export interface FCAApi {
+    getCurrentUserID?(): string;
+    getAppState?(): AppStateCookie[];
+    setOptions?(options: Record<string, unknown>): void;
+    listenMqtt(
+      callback: (err: unknown, event?: Record<string, unknown>) => void,
+    ): Promise<void> | void;
+    sendMessage(
+      message: string | SendMessagePayload,
+      threadID: string,
+      callback?: unknown,
+      replyToMessage?: string,
+    ): Promise<Record<string, unknown>> | void;
+    setMessageReaction?(
+      reaction: string,
+      messageID: string,
+      callback?: unknown,
+      forceCustomReaction?: boolean,
+    ): Promise<void> | void;
+    unsendMessage?(messageID: string, callback?: unknown): Promise<void> | void;
+    sendTypingIndicator?(
+      isTyping: boolean,
+      threadID: string,
+      callback?: unknown,
+    ): Promise<void> | void;
+    markAsRead?(threadID: string, read?: boolean, callback?: unknown): Promise<void> | void;
+    changeGroupImage?(image: unknown, threadID: string, callback?: unknown): Promise<void> | void;
+    setTitle?(newTitle: string, threadID: string, callback?: unknown): Promise<void> | void;
+    muteThread?(threadID: string, muteSeconds: number, callback?: unknown): Promise<void> | void;
+    deleteThread?(threadOrThreads: string | string[], callback?: unknown): Promise<void> | void;
+    stopListenMqtt?(): void;
+    /** Download a media URL and return raw buffer */
+    getAttachmentStream?(url: string, callback?: unknown): Promise<Buffer> | void;
+    /** Search users by query */
+    searchUsers?(
+      name: string,
+      callback?: (err: unknown, users?: Record<string, FriendInfo>[]) => void,
+    ): Promise<Record<string, FriendInfo>[]> | void;
+    /** Get user info for one or multiple IDs */
+    getUserInfo?(
+      ids: string | string[],
+      callback?: (err: unknown, info?: Record<string, FriendInfo>) => void,
+    ): Promise<Record<string, FriendInfo>> | void;
+    /** Create a new thread with a user */
+    createNewGroup?(
+      userIDs: string[],
+      groupTitle: string,
+      callback?: unknown,
+    ): Promise<Record<string, unknown>> | void;
+
+    /** Get paginated thread list */
+    getThreadList?(
+      limit: number,
+      timestamp: number | null,
+      tags: string[],
+      callback?: (err: unknown, threads?: ThreadListItem[]) => void,
+    ): Promise<ThreadListItem[]> | void;
+
+    /** Get message history for a thread */
+    getThreadHistory?(
+      threadID: string,
+      amount: number,
+      timestamp: number | undefined,
+      callback?: (err: unknown, messages?: HistoryMessage[]) => void,
+    ): Promise<HistoryMessage[]> | void;
+
+    /** Forward a media attachment to one or more threads */
+    forwardAttachment?(
+      attachmentID: string,
+      userOrUsers: string | string[],
+      callback?: unknown,
+    ): Promise<void> | void;
+
+    /** Create a poll in a thread */
+    createPoll?(
+      title: string,
+      threadID: string,
+      options?: Record<string, boolean>,
+      callback?: unknown,
+    ): Promise<void> | void;
+
+    /** Edit an already-sent message (requires MQTT) */
+    editMessage?(
+      text: string,
+      messageID: string,
+      callback?: unknown,
+    ): Promise<Record<string, unknown>> | void;
+
+    /** Add user(s) to a group thread */
+    addUserToGroup?(
+      userID: string | string[],
+      threadID: string,
+      callback?: unknown,
+    ): Promise<void> | void;
+
+    /** Remove a user from a group thread */
+    removeUserFromGroup?(
+      userID: string,
+      threadID: string,
+      callback?: unknown,
+    ): Promise<void> | void;
+
+    /** Change admin status of a user in a group */
+    changeAdminStatus?(
+      threadID: string,
+      userID: string,
+      adminStatus: boolean,
+      callback?: unknown,
+    ): Promise<void> | void;
+
+    /** Get the logged-in user's friends list */
+    getFriendsList?(
+      callback?: (err: unknown, friends?: Record<string, FriendInfo>) => void,
+    ): Promise<Record<string, FriendInfo>> | void;
+  }
+
+  export default function login(
+    loginData: LoginData,
+    options: Record<string, unknown>,
+    callback: (err: unknown, api?: FCAApi) => void,
+  ): void;
+}

package/src/types/protocol-types.ts

@@ -0,0 +1,43 @@
+/**
+ * Protocol-specific Type Definitions
+ */
+
+export interface E2EEMessagePayload {
+  kind?: "text" | "image" | "video" | "audio" | "document" | "sticker" | "reaction" | "edit" | "revoke" | "unknown";
+  type?: "text" | "media" | "decryption_failed";
+  senderJid: string;
+  senderId?: string;
+  senderDeviceId?: number;
+  chatJid?: string;
+  messageId: string;
+  timestampMs: number;
+  text?: string;
+  isArmadillo?: boolean;
+  error?: string;
+}
+
+export interface DecryptedConsumerApplication {
+  payload?: {
+    type: string;
+    data: number[];
+  };
+  version?: number;
+}
+
+export interface DecryptedArmadillo {
+  payload?: {
+    type: string;
+    data: number[];
+  };
+}
+
+export interface DecryptedMessageApplication {
+  payload?: {
+    subProtocol?: {
+      consumerMessage?: DecryptedConsumerApplication;
+      armadillo?: DecryptedArmadillo;
+      futureProof?: string;
+    };
+  };
+  metadata?: any;
+}

package/src/utils/fca-utils.ts

@@ -0,0 +1,30 @@
+/**
+ * FCA Utilities
+ * 
+ * Re-implementation of basic FCA utility functions to avoid heavy dependencies.
+ */
+
+export function str(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+  return "";
+}
+
+export function num(v: unknown): number {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+export function date(v: unknown): number {
+  if (v instanceof Date) return v.getTime();
+  if (typeof v === "number") return v;
+  if (typeof v === "string") {
+    const d = new Date(v);
+    return isNaN(d.getTime()) ? Date.now() : d.getTime();
+  }
+  return Date.now();
+}
+
+export function now(): number {
+  return Date.now();
+}

package/src/utils/logger.ts

@@ -0,0 +1,24 @@
+/**
+ * Centralized logging utility for FME.
+ * 
+ * Controlled by process.env.DEBUG.
+ */
+
+const isDebug = !!process.env.DEBUG || process.env.NODE_ENV === "development";
+
+export const logger = {
+  info: (...args: any[]) => {
+    console.log(...args);
+  },
+  debug: (...args: any[]) => {
+    if (isDebug) {
+      console.log(...args);
+    }
+  },
+  warn: (...args: any[]) => {
+    console.warn(...args);
+  },
+  error: (...args: any[]) => {
+    console.error(...args);
+  }
+};

package/src/utils/mime.ts

@@ -0,0 +1,51 @@
+import { extname } from "node:path";
+
+const MIME_BY_EXT: Record<string, string> = {
+  ".apng": "image/apng",
+  ".avif": "image/avif",
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".svg": "image/svg+xml",
+  ".mp4": "video/mp4",
+  ".m4v": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+  ".mpeg": "video/mpeg",
+  ".mpg": "video/mpeg",
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".aac": "audio/aac",
+  ".ogg": "audio/ogg; codecs=opus",
+  ".opus": "audio/ogg; codecs=opus",
+  ".wav": "audio/wav",
+  ".flac": "audio/flac",
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".zip": "application/zip",
+};
+
+export type FileMediaKind = "image" | "video" | "audio" | "file";
+
+/**
+ * Infer a MIME type from a filename/path extension.
+ *
+ * This intentionally avoids async/content sniffing so public send APIs can make
+ * mimeType optional without adding filesystem reads or external dependencies.
+ */
+export function inferMimeTypeFromFileName(fileName: string, fallback = "application/octet-stream"): string {
+  const ext = extname(fileName).toLowerCase();
+  return MIME_BY_EXT[ext] ?? fallback;
+}
+
+export function inferFileMediaKindFromMimeType(mimeType: string): FileMediaKind {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("video/")) return "video";
+  if (mimeType.startsWith("audio/")) return "audio";
+  return "file";
+}

package/tests/.env.example

@@ -0,0 +1,87 @@
+###############################################
+# Core runtime
+###############################################
+
+# Optional. Defaults shown here.
+FB_APPSTATE_PATH=./tests/appstate.json
+FB_SESSION_STORE_PATH=./tests/session.json
+FB_PLATFORM=facebook
+
+
+###############################################
+# DGW integration inside FBClient.connectE2EE
+# Used by src/controllers/client.controller.ts
+###############################################
+
+# Enable DGW bootstrap in connectE2EE
+# 0 = off (default), 1 = on
+FB_DGW_ENABLE=0
+
+# Captured WebSocket endpoints from browser session
+FB_DGW_URL_LIGHTSPEED=wss://gateway.facebook.com/ws/lightspeed?x-dgw-appid=2220391788200892&x-dgw-appversion=0&x-dgw-authtype=1:0&x-dgw-version=5&x-dgw-uuid=100050349247667&x-dgw-tier=prod&x-dgw-loggingid=REPLACE_ME&x-dgw-regionhint=HIL&x-dgw-deviceid=REPLACE_ME
+FB_DGW_URL_STREAMCONTROLLER=wss://gateway.facebook.com/ws/streamcontroller?x-dgw-appid=2220391788200892&x-dgw-appversion=0&x-dgw-authtype=1:0&x-dgw-version=5&x-dgw-uuid=100050349247667&x-dgw-tier=prod&x-dgw-deviceid=REPLACE_ME&x-dgw-app-stream-group=group1
+FB_DGW_URL_REALTIME=wss://gateway.facebook.com/ws/realtime?x-dgw-appid=2220391788200892&x-dgw-appversion=0&x-dgw-authtype=1:0&x-dgw-version=5&x-dgw-uuid=100050349247667&x-dgw-tier=prod&x-dgw-deviceid=REPLACE_ME&x-dgw-app-stream-group=group1
+
+# Optional override headers
+FB_DGW_UA=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36
+FB_DGW_ORIGIN=https://www.facebook.com
+FB_DGW_REFERER=https://www.facebook.com/
+FB_DGW_ACCEPT_LANGUAGE=en-US,en;q=0.9
+
+# Optional bootstrap OPEN frame tuning
+FB_DGW_STREAM_ID=1
+FB_DGW_BOOTSTRAP_METHOD=FBGQLS:XDT_DIRECT_REALTIME_EVENT
+FB_DGW_BOOTSTRAP_DOC_ID=9712315318850438
+FB_DGW_BOOTSTRAP_ROUTING_HINT=useIGDTypingIndicatorSubscription
+FB_DGW_BOOTSTRAP_BODY=true
+FB_DGW_BOOTSTRAP_ACCEPT_ACK=RSAck
+FB_DGW_BOOTSTRAP_REFERER=https://www.facebook.com/messages/
+
+# Optional DATA bootstrap frame (after OPEN)
+# Option A: provide raw payload hex directly
+FB_DGW_BOOTSTRAP_DATA_PAYLOAD_HEX=
+
+# Option B: build payload as prefixHex + JSON + suffixHex
+FB_DGW_BOOTSTRAP_DATA_JSON=
+# Auto build default JSON payload when FB_DGW_BOOTSTRAP_DATA_JSON is empty.
+# Default = 1 (enabled). Set 0 to disable auto payload.
+FB_DGW_BOOTSTRAP_DATA_AUTO=1
+FB_DGW_BOOTSTRAP_DATA_PREFIX_HEX=2c1878
+FB_DGW_BOOTSTRAP_DATA_SUFFIX_HEX=0000
+FB_DGW_BOOTSTRAP_DATA_TARGETS=realtime,streamcontroller
+FB_DGW_BOOTSTRAP_DATA_REQUIRES_ACK=1
+FB_DGW_BOOTSTRAP_DATA_ACK_ID=0
+
+
+###############################################
+# Standalone DGW probe script
+# Used by tests/script/probe-dgw.ts
+###############################################
+
+# Full cookie header string from logged-in browser session
+DGW_COOKIE=c_user=...; xs=...; fr=...; datr=...;
+
+# Usually same as FB_DGW_UA / FB_DGW_ORIGIN
+DGW_UA=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36
+DGW_ORIGIN=https://www.facebook.com
+DGW_TIMEOUT_MS=12000
+
+# Reuse same endpoint values if desired
+DGW_URL_LIGHTSPEED=
+DGW_URL_STREAMCONTROLLER=
+DGW_URL_REALTIME=
+
+###############################################
+# E2EE media upload / send-image script
+###############################################
+
+# Optional override for tests/script/send-e2ee-image.ts.
+# Leave FB_E2EE_MEDIA_UPLOAD_AUTH empty to query a fresh media_conn token from the E2EE stream.
+FB_E2EE_MEDIA_UPLOAD_AUTH=
+FB_E2EE_MEDIA_UPLOAD_HOST=rupload.facebook.com
+
+# Optional overrides for tests/script/send-e2ee-image.ts
+TEST_E2EE_IMAGE_JID=100042415119261.0@msgr
+TEST_E2EE_IMAGE_PATH=./tests/data/1x1.png
+TEST_E2EE_IMAGE_MIME=image/png
+TEST_E2EE_IMAGE_CAPTION=

package/tests/data/example.txt

@@ -0,0 +1 @@
+test