fb-messenger-e2ee 0.1.0

package/src/models/client.ts

@@ -0,0 +1,26 @@
+import type { MessengerEvent, Platform } from "./domain.ts";
+
+export interface ClientOptions {
+  appStatePath?: string;
+  appState?: any[] | string;
+  sessionStorePath?: string;
+  platform?: Platform;
+}
+
+export interface SessionData {
+  userId: string;
+  appState: Array<{ key: string; value: string }>;
+  platform: Platform;
+  updatedAt: number;
+}
+
+export interface SessionRepository {
+  read(path: string): Promise<SessionData | null>;
+  write(path: string, session: SessionData): Promise<void>;
+}
+
+export type MessengerEventMap = {
+  [E in MessengerEvent as E["type"]]: E["data"];
+} & {
+  event: MessengerEvent;
+};

package/src/models/config.ts

@@ -0,0 +1,14 @@
+import type { Platform } from "./domain.ts";
+
+export interface AppEnv {
+  appStatePath?: string;
+  appState?: any[] | string;
+  sessionStorePath?: string;
+  platform: Platform;
+}
+
+export interface AuthConfig {
+  appStatePath?: string;
+  appState?: any[] | string;
+  platform: Platform;
+}

package/src/models/domain.ts

@@ -0,0 +1,299 @@
+export type Platform = "facebook" | "messenger";
+
+// Auth / Session
+
+
+// Attachment (mirrors bridge-go Attachment struct)
+
+export type AttachmentType = "image" | "video" | "audio" | "voice" | "file" | "sticker" | "gif" | "location" | "link" | "photo";
+
+export interface BaseAttachment {
+  url?: string;
+  fileName?: string;
+  mimeType?: string;
+  fileSize?: number;
+  /** For E2EE media download - base64-encoded */
+  mediaKey?: string;
+  mediaSha256?: string;
+  mediaEncSha256?: string;
+  directPath?: string;
+}
+
+export interface ImageAttachment extends BaseAttachment {
+  type: "image" | "gif" | "photo";
+  width?: number;
+  height?: number;
+  previewUrl?: string;
+}
+
+export interface VideoAttachment extends BaseAttachment {
+  type: "video";
+  width?: number;
+  height?: number;
+  duration?: number;
+  previewUrl?: string;
+}
+
+export interface AudioAttachment extends BaseAttachment {
+  type: "audio" | "voice";
+  duration?: number;
+}
+
+export interface FileAttachment extends BaseAttachment {
+  type: "file";
+}
+
+export interface StickerAttachment extends BaseAttachment {
+  type: "sticker";
+  stickerID: number;
+}
+
+export interface LocationAttachment extends BaseAttachment {
+  type: "location";
+  latitude: number;
+  longitude: number;
+}
+
+export interface LinkAttachment extends BaseAttachment {
+  type: "link";
+  description?: string;
+  sourceText?: string;
+  previewUrl?: string;
+}
+
+export type Attachment =
+  | ImageAttachment
+  | VideoAttachment
+  | AudioAttachment
+  | FileAttachment
+  | StickerAttachment
+  | LocationAttachment
+  | LinkAttachment;
+
+// Mention / ReplyTo
+
+export interface Mention {
+  userId: string;
+  /** UTF-16 code unit offset in the message text */
+  offset: number;
+  /** UTF-16 code unit length */
+  length: number;
+  /** "user" | "thread" | "group" */
+  type?: string;
+}
+
+export interface ReplyTo {
+  messageId: string;
+  senderId?: string;
+  text?: string;
+}
+
+// Thread / UserInfo
+
+export interface Thread {
+  id: string;
+  /** 1 = DM, 2 = group */
+  type: number;
+  name: string;
+  lastActivityTimestampMs: number;
+  snippet?: string;
+}
+
+export interface UserInfo {
+  id: string;
+  name: string;
+  firstName?: string;
+  username?: string;
+  profilePictureUrl?: string;
+  isMessengerUser?: boolean;
+  isVerified?: boolean;
+  gender?: number;
+  canViewerMessage?: boolean;
+}
+
+// Messages
+
+export interface MessengerMessage {
+  id: string;
+  threadId: string;
+  senderId: string;
+  text: string;
+  timestampMs: number;
+  replyTo?: ReplyTo;
+  attachments?: Attachment[];
+  mentions?: Mention[];
+  isAdminMsg?: boolean;
+}
+
+export type E2EEMessageKind =
+  | "text"
+  | "image"
+  | "video"
+  | "audio"
+  | "document"
+  | "sticker"
+  | "reaction"
+  | "edit"
+  | "revoke"
+  | "unknown";
+
+export interface BaseE2EEMessage {
+  id: string;
+  /** Stable conversation ID. For DMs this is the bare Facebook user ID; for groups it is the group JID. */
+  threadId: string;
+  /** Canonical E2EE chat JID. For DMs this uses the bare .0 Messenger device; senderJid keeps the actual sender device. */
+  chatJid: string;
+  /** Device-specific sender JID, e.g. user.device@msgr. */
+  senderJid: string;
+  /** Bare Facebook sender/user ID. */
+  senderId: string;
+  senderDeviceId?: number;
+  isGroup: boolean;
+  kind: E2EEMessageKind;
+  /** Text body when present; empty string for non-text E2EE events. */
+  text: string;
+  timestampMs: number;
+  attachments?: Attachment[];
+  replyTo?: ReplyTo;
+  mentions?: Mention[];
+}
+
+export interface E2EETextMessage extends BaseE2EEMessage {
+  kind: "text";
+  text: string;
+}
+
+export interface E2EEMediaMessage extends BaseE2EEMessage {
+  kind: "image" | "video" | "audio" | "document" | "sticker";
+  media?: unknown;
+}
+
+export interface E2EEReactionMessage extends BaseE2EEMessage {
+  kind: "reaction";
+  reaction: string;
+  targetId?: string;
+}
+
+export interface E2EEEditMessage extends BaseE2EEMessage {
+  kind: "edit";
+  targetId?: string;
+}
+
+export interface E2EERevokeMessage extends BaseE2EEMessage {
+  kind: "revoke";
+  targetId?: string;
+  fromMe?: boolean;
+}
+
+export interface E2EEUnknownMessage extends BaseE2EEMessage {
+  kind: "unknown";
+  raw?: unknown;
+}
+
+export type E2EEMessage =
+  | E2EETextMessage
+  | E2EEMediaMessage
+  | E2EEReactionMessage
+  | E2EEEditMessage
+  | E2EERevokeMessage
+  | E2EEUnknownMessage;
+
+// Input types - messaging
+
+
+
+// Input types - thread management (mirrors media.go)
+
+
+// Input types - media download
+
+
+// Events
+
+export type MessengerEvent =
+  | { type: "message"; data: MessengerMessage }
+  | {
+    type: "messageEdit";
+    data: {
+      messageId: string;
+      threadId: string;
+      newText: string;
+      editCount: number;
+      timestampMs: number;
+    };
+  }
+  | {
+    type: "reaction";
+    data: {
+      messageId: string;
+      threadId: string;
+      actorId: string;
+      /** Empty string = reaction removed */
+      reaction: string;
+      timestampMs: number;
+    };
+  }
+  | {
+    type: "typing";
+    data: {
+      threadId: string;
+      senderId: string;
+      isTyping: boolean;
+    };
+  }
+  | {
+    type: "message_unsend";
+    data: {
+      messageId: string;
+      threadId: string;
+      actorId: string;
+      timestampMs: number;
+    };
+  }
+  | {
+    type: "read_receipt";
+    data: {
+      threadId: string;
+      readerId: string;
+      readWatermarkTimestampMs?: number;
+      timestampMs: number;
+    };
+  }
+  | {
+    type: "presence";
+    data: {
+      userId: string;
+      isOnline: boolean;
+      lastActiveTimestampMs?: number;
+    };
+  }
+  | { type: "e2ee_connected"; data: Record<string, never> }
+  | { type: "e2ee_message"; data: E2EEMessage }
+  | {
+    type: "e2ee_reaction";
+    data: {
+      messageId: string;
+      chatJid: string;
+      senderJid: string;
+      senderId: string;
+      /** Empty string = unreaction */
+      reaction: string;
+    };
+  }
+  | {
+    type: "e2ee_receipt";
+    data: {
+      type: string;
+      chat: string;
+      sender: string;
+      messageIds: string[];
+    };
+  }
+  | {
+    type: "disconnected";
+    data: { isE2EE?: boolean };
+  }
+  | { type: "reconnected"; data: Record<string, never> }
+  | { type: "ready"; data: { isNewSession: boolean } }
+  | { type: "raw"; data: Record<string, unknown> }
+  | { type: "error"; data: { message: string; code?: number } };

package/src/models/e2ee.ts

@@ -0,0 +1,295 @@
+import type {
+  PreKeyRecord,
+  SignedPreKeyRecord,
+  KyberPreKeyRecord,
+} from "@signalapp/libsignal-client";
+import type { MediaTypeKey } from "../e2ee/media/media-crypto.ts";
+import type { MmsTypeStr } from "./media.ts";
+
+// Storage & Keys
+
+export type ProtocolAddressStr = `${string}:${number}`;
+export type SenderKeyId = `${ProtocolAddressStr}:${string}`;
+
+export interface DeviceJSON {
+  /** schema version for local migrations; absent in old stores */
+  schema_version?: number;
+  /** base64, 32 bytes - Noise handshake key */
+  noise_key_priv: string;
+  /** base64, 32 bytes - Signal identity key */
+  identity_key_priv: string;
+  /** base64, 32 bytes - Signal signed prekey */
+  signed_pre_key_priv: string;
+  signed_pre_key_id: number;
+  /** base64, 64 bytes - Ed25519 sig of signed prekey by identity key */
+  signed_pre_key_sig: string;
+  registration_id: number;
+  /** base64, 32 bytes */
+  adv_secret_key: string;
+  /** uuid v4 */
+  facebook_uuid: string;
+  jid_user?: string;
+  jid_device?: number;
+  /** address -> base64(32B identity pub key) */
+  identities?: Record<string, string>;
+  /** address -> base64(serialized SessionRecord) */
+  sessions?: Record<string, string>;
+  /** id(number) -> base64(32B priv key) */
+  pre_keys?: Record<string, string>;
+  /** "groupJID:senderAddress" -> base64(serialized SenderKeyRecord) */
+  sender_keys?: Record<string, string>;
+  /** id(number) -> base64(serialized SignedPreKeyRecord) */
+  signed_pre_keys?: Record<string, string>;
+  /** next prekey ID to generate */
+  next_pre_key_id: number;
+}
+
+export interface NoiseKeyPair {
+  priv: Buffer;
+  pub: Buffer;
+}
+
+// PreKeys
+
+export interface GeneratedPreKey {
+  id: number;
+  record: PreKeyRecord;
+}
+
+export interface PreKeyUploadPayload {
+  registrationId: number;
+  identityKey: Uint8Array; // 32 bytes, X25519 pub
+  signedPreKey: {
+    keyId: number;
+    publicKey: Uint8Array; // 32 bytes
+    signature: Uint8Array; // 64 bytes
+  };
+  preKeys: Array<{
+    keyId: number;
+    publicKey: Uint8Array; // 32 bytes
+  }>;
+}
+
+export interface RawPreKeyBundle {
+  registrationId: number;
+  deviceId: number;
+  identityKey: Uint8Array; // 33 bytes (serialize() DER compressed)
+  signedPreKey: {
+    keyId: number;
+    publicKey: Uint8Array;
+    signature: Uint8Array;
+  };
+  /** Optional: one-time prekey (may be absent if server ran out) */
+  preKey?: {
+    keyId: number;
+    publicKey: Uint8Array;
+  };
+  /**
+   * Optional: Kyber (PQ) prekey.
+   */
+  kyberPreKey?: {
+    keyId: number;
+    publicKey: Uint8Array;
+    signature: Uint8Array;
+  };
+}
+
+// Handshake & Socket
+
+export interface NoiseSocket {
+  sendFrame(data: Buffer): Promise<void>;
+  readFrame(): Promise<Buffer>;
+  close(): void;
+}
+
+export interface RawWebSocket {
+  send(data: Buffer): void;
+  readRaw(len?: number): Promise<Buffer>;
+  close(): void;
+}
+
+export interface HandshakeResult {
+  socket: NoiseSocket;
+}
+
+// Client Options & Results
+
+export interface E2EESendTextOptions {
+  /** Recipient JID (DM) or group JID */
+  toJid: string;
+  text: string;
+  isGroup: boolean;
+  /** Own JID - required for all sends (self address in Signal protocol) */
+  selfJid: string;
+  replyToId?: string;
+  replyToSenderJid?: string;
+}
+
+export interface E2EESendTextResult {
+  /** Encrypted MessageTransport bytes - feed into Signal cipher */
+  plaintext: Buffer;
+  /** frankingTag for the message node */
+  frankingTag: Buffer;
+}
+
+export interface E2EEEncryptMediaOptions {
+  type: MediaTypeKey;
+  data: Buffer;
+  mmsType: MmsTypeStr; // From media-upload.ts
+}
+
+export interface E2EEEncryptMediaResult {
+  mediaKey: Buffer;
+  fileSHA256: Buffer;
+  fileEncSHA256: Buffer;
+  fileLength: number;
+  directPath: string;
+  /** Upload handle returned by the media CDN. Useful for parity with native clients. */
+  handle: string;
+  /** CDN object ID returned by upload; encoded into WAMediaTransport ancillary data. */
+  objectId: string;
+  /** Pre-built MediaFields for encodeImageMessage / encodeVideoMessage / etc. */
+  mediaFields: Omit<MediaFields, "caption" | "ptt" | "fileName">;
+}
+
+export interface E2EEDecryptMediaOptions {
+  data: Buffer;
+  mediaKey: Buffer;
+  type: MediaTypeKey;
+  fileSHA256?: Buffer;
+  fileEncSHA256?: Buffer;
+}
+
+export type EncryptionResult =
+  | { type: "dm"; encrypted: { type: "msg" | "pkmsg"; ciphertext: Buffer }; frankingTag: Buffer; messageApp: Buffer }
+  | {
+    type: "group";
+    messageApp: Buffer;
+    groupCiphertext: Buffer;
+    devicePayload: Buffer;
+    selfDevicePayload: Buffer;
+    skdmPayload: Buffer;
+    skdm: { groupId: string; skdmBytes: Buffer; distributionId: string };
+    frankingTag: Buffer;
+  };
+
+// Message Builder
+
+export interface MediaFields {
+  caption?: string;
+  mimeType: string;
+  fileSHA256: Buffer;
+  fileLength: number;
+  mediaKey: Buffer;
+  fileEncSHA256: Buffer;
+  directPath: string;
+  /** Optional CDN object ID from media upload response. */
+  objectId?: string;
+  /** Unix timestamp seconds for the media key. Defaults to current time when encoding. */
+  mediaKeyTimestamp?: number;
+  width?: number;
+  height?: number;
+  seconds?: number;
+  ptt?: boolean;
+  fileName?: string;
+}
+
+export interface MessageTransportOptions {
+  /** Application payload. Omit for SKDM-only device fanout. */
+  messageApp?: Buffer;
+  /** Included only when sending a copy to own other devices */
+  dsm?: {
+    destinationJid: string;
+    phash: string;
+  };
+  /** Included only for group messages */
+  skdm?: {
+    groupId: string;
+    skdmBytes: Buffer;
+  };
+  /** Included for group sends with backup directive metadata. */
+  backupDirective?: {
+    messageId: string;
+    actionType?: "UPSERT" | "REMOVE";
+  };
+  padding?: Buffer;
+}
+
+// E2EEService types
+
+export interface E2EEUploadResult {
+  messageId: string;
+  timestampMs: number;
+}
+
+export interface E2EEDownloadResult {
+  data: Buffer;
+  mimeType: string;
+  fileSize: number;
+}
+
+export interface E2EESendImageOptions {
+  chatJid: string;
+  data: Buffer;
+  mimeType?: string;
+  caption?: string;
+  width?: number;
+  height?: number;
+  replyToId?: string;
+  replyToSenderJid?: string;
+}
+
+export interface E2EESendVideoOptions {
+  chatJid: string;
+  data: Buffer;
+  mimeType?: string;
+  caption?: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  replyToId?: string;
+  replyToSenderJid?: string;
+}
+
+export interface E2EESendAudioOptions {
+  chatJid: string;
+  data: Buffer;
+  mimeType?: string;
+  duration?: number;
+  ptt?: boolean;
+  replyToId?: string;
+  replyToSenderJid?: string;
+}
+
+export interface E2EESendDocumentOptions {
+  chatJid: string;
+  data: Buffer;
+  fileName: string;
+  mimeType?: string;
+  replyToId?: string;
+  replyToSenderJid?: string;
+}
+
+export interface E2EESendStickerOptions {
+  chatJid: string;
+  data: Buffer;
+  mimeType?: string;
+  width?: number;
+  height?: number;
+  replyToId?: string;
+  replyToSenderJid?: string;
+}
+
+export interface E2EEDownloadOptions {
+  directPath: string;
+  /** Base64-encoded */
+  mediaKey: string;
+  /** Base64-encoded */
+  mediaSha256: string;
+  /** Base64-encoded */
+  mediaEncSha256?: string;
+  /** "image" | "video" | "audio" | "voice" | "document" | "sticker" */
+  mediaType: string;
+  mimeType?: string;
+  fileSize?: number;
+}

package/src/models/media.ts

@@ -0,0 +1,41 @@
+export interface MediaKeys {
+  iv: Buffer;
+  cipherKey: Buffer;
+  macKey: Buffer;
+  refKey: Buffer;
+}
+
+export interface EncryptMediaResult {
+  dataToUpload: Buffer;
+  fileSHA256: Buffer;
+  fileEncSHA256: Buffer;
+  fileLength: number;
+  mediaKey: Buffer;
+}
+
+export interface DecryptMediaOptions {
+  data: Buffer;
+  mediaKey: Buffer;
+  type: any; // MediaTypeKey (avoiding circular dep for now)
+  fileSHA256?: Buffer;
+  fileEncSHA256?: Buffer;
+}
+
+export interface MediaUploadConfig {
+  /** From server's media connection response */
+  auth: string;
+  /** Host to upload to - Messenger prefers the last host (rupload.facebook.com) */
+  host: string;
+  ttl?: number;
+  authTtl?: number;
+  fetchedAtMs?: number;
+}
+
+export interface MediaUploadResult {
+  url: string;
+  directPath: string;
+  handle: string;
+  objectId: string;
+}
+
+export type MmsTypeStr = "image" | "video" | "ptt" | "document" | "sticker";