fb-messenger-e2ee 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# FME - FB Messenger E2EE
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**FME - FB Messenger E2EE** is a TypeScript/Bun toolkit focused on Facebook Messenger E2EE flows built on Noise, WA-binary, protobuf, and the Signal Protocol. Plaintext/non-E2EE messaging is intentionally left to `fca-unofficial` directly.
+
+---
+
+## Key Features
+
+- **Native E2EE path**: Signal Protocol sessions, prekeys, sender keys, Noise socket frames, and WA-binary nodes for encrypted Messenger chats.
+- **Group sender-key support**: group `skmsg` decrypt/encrypt plus participant fanout of sender-key distribution messages (`skdm`).
+- **Device persistence**: JSON-backed `DeviceStore` keeps Noise keys, Signal identity, sessions, prekeys, signed prekeys, and sender keys across restarts.
+- **Automatic prekey maintenance**: replenishes server-side one-time prekeys without deleting or re-registering the E2EE device.
+- **Typed E2EE events**: catch-all and typed event subscriptions for E2EE messages, receipts, reactions, errors, and raw frames.
+- **DGW support**: optional Direct Gateway / LightSpeed socket helpers.
+
+---
+
+## Tech Stack
+
+- **Runtime**: [Bun](https://bun.sh/) / Node-compatible APIs
+- **Language**: [TypeScript](https://www.typescriptlang.org/)
+- **Encryption**: [@signalapp/libsignal-client](https://github.com/signalapp/libsignal-client)
+- **Protocol**: ProtobufJS + manual WA-binary/protobuf encoders
+- **Auth bootstrap bridge**: [fca-unofficial](https://github.com/VangBanLaNhat/fca-unofficial) is used internally only for appState login/CAT bootstrap; use it directly for non-E2EE messaging.
+
+---
+
+## Getting Started
+
+### 1. Installation
+
+```bash
+npm install fb-messenger-e2ee
+# or
+bun add fb-messenger-e2ee
+```
+
+### 2. Basic Usage
+
+```typescript
+import { FBClient } from "fb-messenger-e2ee";
+
+const client = new FBClient({
+  appStatePath: "./appstate.json",
+  sessionStorePath: "./session.json",
+  platform: "facebook",
+});
+
+const { userId } = await client.connect();
+
+// Keep this file. It is the registered E2EE device identity and Signal state.
+await client.connectE2EE("./device-store.json", userId);
+
+client.onEvent((event) => {
+  if (event.type === "e2ee_connected") {
+    console.log("E2EE stream is ready");
+  }
+
+  if (event.type === "e2ee_message") {
+    console.log(`[E2EE] ${event.data.threadId} ${event.data.senderJid}: ${event.data.text}`);
+  }
+
+  if (event.type === "error") {
+    console.error("Client error:", event.data.message);
+  }
+});
+
+await client.sendMessage({
+  threadId: "1234567890", // user ID, *.@msgr JID, or group JID
+  text: "Hello from the secure side!",
+});
+```
+
+---
+
+## Device Store & Key Maintenance
+
+`connectE2EE(deviceStorePath, userId)` loads or creates a persistent device store. Do **not** delete it as a normal recovery step:
+
+- Deleting it generates a new Noise key, Signal identity, registration ID, `facebook_uuid`, and device registration.
+- Keeping it lets the same registered E2EE device continue using existing sessions and sender keys.
+- The client now refreshes one-time prekeys automatically and does not need a new device registration for normal prekey exhaustion.
+
+Configurable environment variables:
+
+| Env | Default | Purpose |
+|---|---:|---|
+| `FB_E2EE_PREKEY_SYNC_INTERVAL_MS` | `1800000` | Periodic prekey check interval. Set `0` to disable. |
+| `FB_E2EE_PREKEY_MIN_COUNT` | `5` | Upload more prekeys when server count falls below this. |
+| `FB_E2EE_PREKEY_UPLOAD_COUNT` | `50` | Number of fresh one-time prekeys to upload per refill. |
+
+Group decrypt note: if local `sender_keys` for a group/sender are truly missing, the client cannot derive that key locally. On retryable decrypt failures it sends an E2EE retry receipt to request a resend/SKDM from the sender/server. The send path also keeps a short in-memory retry cache so incoming `receipt type="retry"` requests for recently-sent messages can be re-encrypted directly to the requesting device. This is different from prekey exhaustion.
+
+E2EE event identity model:
+
+- `threadId`: stable conversation ID. For DMs this is the bare Facebook user ID; for groups it is the group JID.
+- `chatJid`: canonical E2EE chat JID. For DMs this is `user.0@msgr`; for groups it is `group@g.us`.
+- `senderJid`: device-specific sender JID such as `user.160@msgr`.
+- `senderDeviceId`: numeric Messenger E2EE device ID when available.
+- `kind`: normalized content kind (`text`, `image`, `reaction`, `edit`, etc.). Empty optional fields are omitted from the event payload.
+
+---
+
+## Project Structure
+
+```text
+src/
+├── controllers/    # Thin orchestration + receive handlers
+├── core/           # Public FBClient facade
+├── e2ee/
+│   ├── application/ # E2EEClient, retry/prekey/cache/fanout runtime helpers
+│   ├── store/       # DeviceStore + JSON migration/repository
+│   ├── transport/   # Noise, WA-binary, DGW sockets
+│   ├── signal/      # Signal sessions, prekeys, sender keys
+│   ├── message/     # Protobuf writer/builders/codecs/schemas
+│   ├── media/       # Media crypto/upload
+│   └── facebook/    # FB-specific SKMSG/SKDM/ICDC helpers
+├── models/         # TypeScript interfaces & domain models
+├── services/       # Auth/CAT bridge, ICDC, E2EE facade, media helpers
+├── repositories/   # Session persistence
+└── utils/          # Logger and conversion helpers
+```
+
+---
+
+## Testing
+
+```bash
+npm run typecheck
+npm test -- --runInBand
+```
+
+Manual echo script:
+
+```bash
+bun run tests/script/echo-e2ee.ts
+```
+
+---
+
+## Documentation
+
+For the API reference and operational notes, see [DOCS.md](./DOCS.md).
+
+---
+
+## License
+
+MIT © [VangBanLaNhat](https://github.com/VangBanLaNhat)