@nirzon-islam/omega-fca 0.0.0-stage → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +155 -2
- package/docs/ARCHITECTURE.md +126 -0
- package/docs/AUTHENTICATION-ATTEMPT.md +52 -0
- package/docs/BROWSER-CAPTURE.md +74 -0
- package/docs/DEPLOYMENT.md +80 -0
- package/docs/FACEBOOK-MQTT-TRANSPORT.md +82 -0
- package/docs/GOATBOT-COMPATIBILITY-MATRIX.md +58 -0
- package/docs/GOATBOT-INTEGRATION-AUDIT.md +64 -0
- package/docs/IMPLEMENTATION-STATUS.md +51 -0
- package/docs/META-MESSENGER-TRANSPORT.md +78 -0
- package/docs/NESTED-REALTIME-PAYLOAD.md +16 -0
- package/docs/NTKHANG-REFERENCE-STUDY.md +69 -0
- package/docs/PROTOCOL-EVIDENCE.md +69 -0
- package/docs/REALTIME-FRAME-EVIDENCE.md +33 -0
- package/docs/REFERENCE-AUDIT.md +63 -0
- package/docs/SAFE-DIAGNOSTICS.md +39 -0
- package/examples/appstate-session-check.js +33 -0
- package/examples/meta-messenger-server.js +96 -0
- package/index.d.ts +407 -0
- package/index.js +62 -0
- package/package.json +63 -4
- package/src/api/client.js +308 -0
- package/src/auth/accountConfig.js +82 -0
- package/src/auth/authenticationAttempt.js +193 -0
- package/src/auth/facebookResponse.js +93 -0
- package/src/auth/facebookWebClient.js +133 -0
- package/src/auth/personalSession.js +335 -0
- package/src/auth/totp.js +39 -0
- package/src/compat/facebookMqttClient.js +74 -0
- package/src/compat/goatbotLogin.js +67 -0
- package/src/compat/legacyFcaTransport.js +136 -0
- package/src/events/dispatcher.js +69 -0
- package/src/license/provider.js +37 -0
- package/src/license/verify.js +42 -0
- package/src/network/cookieJar.js +72 -0
- package/src/network/requestClient.js +104 -0
- package/src/runtime/connection.js +231 -0
- package/src/security/cookies.js +104 -0
- package/src/security/diagnostics.js +98 -0
- package/src/security/redact.js +23 -0
- package/src/security/sessionCrypto.js +61 -0
- package/src/security/sessionState.js +23 -0
- package/src/security/sessionStore.js +64 -0
- package/src/transport/binaryPayloadInspector.js +131 -0
- package/src/transport/contract.js +39 -0
- package/src/transport/facebookGatewayProtocol.js +135 -0
- package/src/transport/facebookMqttDriver.js +60 -0
- package/src/transport/facebookMqttEvents.js +114 -0
- package/src/transport/facebookMqttProtocol.js +213 -0
- package/src/transport/facebookThreadApi.js +284 -0
- package/src/transport/messengerActions.js +64 -0
- package/src/transport/messengerSyncCursorStore.js +53 -0
- package/src/transport/metaMessenger.js +294 -0
- package/src/transport/mqtt311Codec.js +254 -0
- package/src/transport/mqtt311StreamDecoder.js +57 -0
- package/src/transport/mqttRequestTracker.js +60 -0
- package/src/transport/nativeRealtimeTransport.js +388 -0
- package/src/transport/realtimeFrameDecoder.js +92 -0
- package/src/transport/realtimeSyncEnvelope.js +84 -0
- package/src/update/manifest.js +102 -0
- package/tools/browser-capture.js +130 -0
- package/tools/termux-capture-setup.sh +26 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 NirZon
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,156 @@
|
|
|
1
|
-
#
|
|
1
|
+
# OmegA Bot — OmegA-FCA
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**An experimental, AppState-first personal Messenger client and FCA compatibility layer by NirZon.**
|
|
4
|
+
|
|
5
|
+
OmegA-FCA is the Facebook integration library maintained under the **OmegA Bot** brand by **NirZon**.
|
|
6
|
+
|
|
7
|
+
> **Status:** experimental native personal-account path. AppState session validation, MQTT/WebSocket bootstrap, a limited event normalizer, a limited action set, and GoatBot callback compatibility are implemented with synthetic tests. This is not yet a verified drop-in FCA replacement: live Facebook broker acceptance, complete event/action parity, and authorized-account end-to-end tests remain outstanding.
|
|
8
|
+
|
|
9
|
+
**Package:** `@nirzon-islam/omega-fca` · **Node.js:** 20+ · **Author:** NirZon
|
|
10
|
+
|
|
11
|
+
## Included
|
|
12
|
+
|
|
13
|
+
- AppState/cookie validation, secure encrypted session storage, secret redaction.
|
|
14
|
+
- `createDiagnosticRecorder()`: bounded request metadata reports that omit header values, query values, body values, response bodies and credentials.
|
|
15
|
+
- Native personal-session bootstrap for owner-supplied AppState, including HTTPS-only Facebook/Messenger requests, cookie rotation, and checkpoint/expiry detection.
|
|
16
|
+
- `createFacebookWebClient()`: bounded authenticated GET/POST/HEAD request layer, session-token injection for POST forms, redirect challenge classification, response normalization, and request/response size limits. It deliberately requires caller-supplied verified paths and payload schemas.
|
|
17
|
+
- AppState/cookie login is the only enabled login path in this phase. Direct email/username-password and 2FA login attempts are rejected before the authentication provider is called; credential login is deferred.
|
|
18
|
+
- Checkpoint/session-expiry classification. Challenges must be resolved by the account owner.
|
|
19
|
+
- Connection supervision, bounded reconnect/backoff and event dispatch.
|
|
20
|
+
- Bounded realtime binary-frame envelope inspection based on observed captures.
|
|
21
|
+
- Experimental Facebook Messenger MQTT 3.1 transport adapter using public FCA observations: `edge-chat.facebook.com/chat`, broker handshake, subscriptions and sync-queue bootstrap. Event normalization and live validation remain incomplete.
|
|
22
|
+
- `createFacebookMqttClient()`: first-party AppState-only client factory that wires the native personal-session bootstrap, MQTT driver, reconnect supervisor and GoatBot-style `listenMqtt` facade. Supply a WebSocket implementation; real Facebook broker acceptance is not yet verified.
|
|
23
|
+
- `inspectRealtimeSyncEnvelope()`: parses the captured outer sync JSON envelope and nested payload with size/type checks; it does not infer the unknown binary prefix or protocol semantics.
|
|
24
|
+
- `createLegacyFcaProvider()`: adapter for an existing callback-style personal-account FCA implementation.
|
|
25
|
+
- `createGoatBotLogin()`: callback-style GoatBot login adapter.
|
|
26
|
+
- Personal-account driver method forwarding for messaging, threads, reactions, typing, and group actions when the supplied FCA implementation supports those methods.
|
|
27
|
+
- Separate official Meta Messenger Page transport (not a personal-account replacement).
|
|
28
|
+
- TypeScript declarations, signed update-manifest verification, optional Ed25519 licensing.
|
|
29
|
+
|
|
30
|
+
## GoatBot account configuration
|
|
31
|
+
|
|
32
|
+
The current authentication phase is **AppState-only**. Email/password and username/password login are deferred and are not loaded from configuration or environment variables.
|
|
33
|
+
|
|
34
|
+
Put only an authorized cookie export in the project-root `account.txt`. Accepted formats are:
|
|
35
|
+
- Raw cookie header (`c_user=...; xs=...`).
|
|
36
|
+
- Netscape cookie export.
|
|
37
|
+
- JSON cookie array.
|
|
38
|
+
|
|
39
|
+
Alternatively, put a JSON cookie array in `appstate.json`. A non-empty `account.txt` takes precedence. Credential-like key/value text in `account.txt` is rejected. The loader deliberately does not fall back to `fb_email`, `fb_username`, passwords, 2FA values, or `FB_*` environment variables.
|
|
40
|
+
|
|
41
|
+
`account.txt`, `appstate.json`, passwords, cookies, 2FA seeds, and session keys must stay private and must not be committed. Email/password authentication will be implemented as a separate later phase; it is not available in this AppState-only release path.
|
|
42
|
+
|
|
43
|
+
## Personal AppState session foundation
|
|
44
|
+
|
|
45
|
+
The first native session layer can validate an owner-supplied AppState and issue bounded HTTPS requests only to Facebook/Messenger hosts. It preserves scoped response cookies and stops with an explicit checkpoint or expired-session error; it does not bypass either state.
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
const { createPersonalSession } = require("@nirzon-islam/omega-fca");
|
|
49
|
+
const session = await createPersonalSession({ appState: require("./account.json") });
|
|
50
|
+
const response = await session.request("https://www.facebook.com/");
|
|
51
|
+
console.log(session.userId, response.status);
|
|
52
|
+
// Call session.close() when finished.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
This is a session foundation only: it does not yet provide the full FCA action API or realtime listener.
|
|
56
|
+
|
|
57
|
+
## Experimental Messenger MQTT transport
|
|
58
|
+
|
|
59
|
+
`createFacebookMqttClient()` provides the first-party AppState-only path: it validates the supplied session, opens the native WebSocket/MQTT transport, subscribes and initializes sync, and exposes a GoatBot-style callback listener. Known Messenger delta classes are normalized conservatively; unknown classes remain explicit. A limited set of web/thread and MQTT actions is available, but this is not full FCA parity. The private broker protocol, delta schemas, and action payloads are unofficial and have not been validated against a live Facebook account. See [Facebook MQTT transport notes](docs/FACEBOOK-MQTT-TRANSPORT.md) and [implementation status](docs/IMPLEMENTATION-STATUS.md).
|
|
60
|
+
|
|
61
|
+
## Realtime frame inspection
|
|
62
|
+
|
|
63
|
+
The Android Messenger Web capture confirmed a successful `/ws/realtime` WebSocket handshake and binary frames containing a JSON-like `events` envelope with `name` and `args` fields. OmegA-FCA now includes `decodeRealtimeFrame()` and `summarizeRealtimeFrame()` for bounded inspection of that observed envelope. The undocumented binary prefix remains opaque; this is not yet a socket client, authentication flow, subscription/acknowledgement implementation, event semantic map, message sender, or E2EE implementation. See [Realtime frame evidence](docs/REALTIME-FRAME-EVIDENCE.md).
|
|
64
|
+
|
|
65
|
+
## Safe diagnostic reports
|
|
66
|
+
|
|
67
|
+
A secret-safe diagnostic recorder is available for the current AppState-backed session layer. It records request structure and response metadata, not secrets or payload contents. See [Safe diagnostics](docs/SAFE-DIAGNOSTICS.md) for usage.
|
|
68
|
+
|
|
69
|
+
**Important:** this currently instruments AppState session requests only. It cannot capture a username/password login trace because native Facebook credential login is not implemented yet.
|
|
70
|
+
|
|
71
|
+
## Legacy compatibility adapter (temporary migration/test utility)
|
|
72
|
+
|
|
73
|
+
The adapter is a temporary migration/test utility for AppState-backed sessions. It lets an existing FCA implementation plug into OmegA-FCA without pretending that the Facebook protocol has been reimplemented:
|
|
74
|
+
|
|
75
|
+
```js
|
|
76
|
+
const { createClient, createLegacyFcaProvider } = require("@nirzon-islam/omega-fca");
|
|
77
|
+
// Supply a caller-owned FCA implementation only when testing the migration adapter.
|
|
78
|
+
const legacyFcaLogin = require("your-existing-fca");
|
|
79
|
+
|
|
80
|
+
const authenticate = createLegacyFcaProvider({
|
|
81
|
+
login: legacyFcaLogin,
|
|
82
|
+
options: { forceLogin: false }
|
|
83
|
+
});
|
|
84
|
+
const client = createClient({ authenticate });
|
|
85
|
+
|
|
86
|
+
const api = await client.login({
|
|
87
|
+
mode: "appstate",
|
|
88
|
+
appState: require("./account.json")
|
|
89
|
+
});
|
|
90
|
+
api.listenMqtt((error, event) => {
|
|
91
|
+
if (error) console.error("FCA listener error:", error.message);
|
|
92
|
+
else if (event) console.log("Event:", event.type);
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Use only an account and session you own or are authorized to operate. Keep `account.json`, passwords, 2FA secrets, and session keys outside source control. If Facebook presents a checkpoint, resolve it through Facebook as the account owner and then retry with a fresh authorized session.
|
|
97
|
+
|
|
98
|
+
This adapter is optional and is not required by the first-party `createFacebookMqttClient()` path.
|
|
99
|
+
|
|
100
|
+
## Remaining standalone-replacement gates
|
|
101
|
+
|
|
102
|
+
- Native username/password authentication and owner-controlled 2FA/checkpoint continuation are deferred; AppState/cookie is the only native login path in this phase.
|
|
103
|
+
- Full Messenger event normalization, attachment handling, and the complete legacy FCA action catalog are not implemented.
|
|
104
|
+
- Facebook MQTT broker acceptance, event delivery, message send, reconnect recovery, and group operations still need authorized live-account verification.
|
|
105
|
+
- Complete legacy FCA behavior parity and GoatBot integration tests must pass before production migration.
|
|
106
|
+
|
|
107
|
+
Do not treat this experimental release as a drop-in production replacement until those gates pass. The official Meta Page transport is separate and does not satisfy personal-profile or group-chat requirements.
|
|
108
|
+
|
|
109
|
+
## Security
|
|
110
|
+
|
|
111
|
+
Never commit cookies, AppState, passwords, 2FA secrets, encryption keys, or tokens. The library does not bypass checkpoints, 2FA, rate limits, or platform security controls. Unofficial interfaces may change and may result in account restrictions.
|
|
112
|
+
|
|
113
|
+
## AppState-first test run
|
|
114
|
+
|
|
115
|
+
Email/password login is deferred for the current testing phase. To validate an authorized AppState session, place only the cookie export in the project-root `account.txt` (or `appstate.json`) and run:
|
|
116
|
+
|
|
117
|
+
~~~bash
|
|
118
|
+
npm ci
|
|
119
|
+
npm test
|
|
120
|
+
npm run test:syntax
|
|
121
|
+
npm run test:appstate
|
|
122
|
+
~~~
|
|
123
|
+
|
|
124
|
+
The live AppState check prints only the account ID and session status; it does not print cookies. It validates the HTTPS session bootstrap only—not Messenger realtime, message sending, or full GoatBot compatibility. See [AppState deployment/test instructions](docs/DEPLOYMENT.md).
|
|
125
|
+
|
|
126
|
+
## Development
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
npm ci
|
|
130
|
+
npm test
|
|
131
|
+
npm run test:syntax
|
|
132
|
+
npm pack --dry-run
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Ownership
|
|
136
|
+
|
|
137
|
+
**OmegA Bot** — developed and maintained by **NirZon**.
|
|
138
|
+
|
|
139
|
+
MIT License. See [LICENSE](LICENSE).
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
## Browser-based protocol capture
|
|
143
|
+
|
|
144
|
+
OmegA-FCA includes an owner-operated Playwright capture utility. On desktop it launches Chromium; on Android/Termux it can attach to an already-running Android Chrome browser through CDP when that browser exposes a debugging endpoint. Setup and privacy guidance: [Browser Capture](docs/BROWSER-CAPTURE.md).
|
|
145
|
+
|
|
146
|
+
Desktop:
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
npm install --no-save playwright
|
|
150
|
+
npx playwright install chromium
|
|
151
|
+
npm run capture:browser
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Android/Termux: run `bash tools/termux-capture-setup.sh`, pair/connect ADB Wireless debugging, forward Chrome's DevTools socket, then run `npm run capture:browser -- --cdp http://127.0.0.1:9222`. Lemur/other browser compatibility is not assumed; verify the CDP endpoint first.
|
|
155
|
+
|
|
156
|
+
The browser runs locally; it is not remotely visible to ChatGPT. The default report omits cookies, query strings, request/response bodies, and binary frame contents. An explicit `--save-private-frames` option stores raw WebSocket frames locally for owner-only inspection; those files may contain secrets or private messages and must not be shared unredacted.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# OmegA-FCA Architecture
|
|
2
|
+
|
|
3
|
+
> Status: design baseline for the transport implementation. This document does not claim that Facebook authentication or MQTT is implemented.
|
|
4
|
+
|
|
5
|
+
## Product direction
|
|
6
|
+
|
|
7
|
+
OmegA-FCA is an independently maintained Node.js library under the OmegA brand. It should provide:
|
|
8
|
+
|
|
9
|
+
- A stable CommonJS entry point for GoatBot and other Node.js applications.
|
|
10
|
+
- A promise-first API with a legacy callback adapter.
|
|
11
|
+
- A provider-owned authentication and transport implementation; no hidden third-party login relay.
|
|
12
|
+
- A normalized event model independent of raw transport frames.
|
|
13
|
+
- Encrypted session persistence, secret-safe diagnostics, bounded reconnect, and deterministic shutdown.
|
|
14
|
+
- Capability-aware API methods that fail clearly when a feature is unavailable.
|
|
15
|
+
- Synthetic unit tests and opt-in integration tests that never require real credentials in CI.
|
|
16
|
+
|
|
17
|
+
The library is unofficial and must not bypass account checkpoints, 2FA, platform rate limits, or other security controls. Users remain responsible for platform terms and account authorization.
|
|
18
|
+
|
|
19
|
+
## Runtime layers
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
Public API (login / createClient / callback adapter)
|
|
23
|
+
|
|
|
24
|
+
Client + capabilities
|
|
25
|
+
|
|
|
26
|
+
Session and auth lifecycle
|
|
27
|
+
|
|
|
28
|
+
Transport driver contract
|
|
29
|
+
/ \
|
|
30
|
+
HTTP request Realtime stream
|
|
31
|
+
layer (MQTT/WebSocket)
|
|
32
|
+
\ /
|
|
33
|
+
Event normalization
|
|
34
|
+
|
|
|
35
|
+
Event dispatcher / listeners
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### 1. Public API
|
|
39
|
+
|
|
40
|
+
Keep the current CommonJS export stable. Expose a promise-first client and an explicit GoatBot compatibility adapter. The adapter should translate callback signatures only; it must not contain transport logic.
|
|
41
|
+
|
|
42
|
+
### 2. Authentication and session lifecycle
|
|
43
|
+
|
|
44
|
+
Separate session input parsing from authentication. Support AppState/cookie input first. Credential login is a later, opt-in flow and must return explicit challenge/checkpoint outcomes for the account owner to complete; do not automate or bypass security challenges.
|
|
45
|
+
|
|
46
|
+
Authentication must:
|
|
47
|
+
- Use only reviewed first-party endpoints and a directly controlled request path.
|
|
48
|
+
- Avoid third-party credential relays and remote code execution.
|
|
49
|
+
- Return a typed session result with user identity, cookie jar, negotiated tokens, and expiry/health metadata.
|
|
50
|
+
- Distinguish logged-out, checkpoint-required, transient-network, malformed-session, and unknown states.
|
|
51
|
+
|
|
52
|
+
### 3. Transport contract
|
|
53
|
+
|
|
54
|
+
Retain the existing injectable driver contract, but make capabilities explicit. A driver should own its HTTP request context and realtime connection and expose:
|
|
55
|
+
- `connect()` / authentication result
|
|
56
|
+
- `listen(callback)` and idempotent `disconnect()`
|
|
57
|
+
- supported API methods and a capability map
|
|
58
|
+
- connection health and structured errors
|
|
59
|
+
|
|
60
|
+
Do not report a method as supported unless the active driver implements it. Avoid a permissive no-op fallback.
|
|
61
|
+
|
|
62
|
+
### 4. Realtime and event pipeline
|
|
63
|
+
|
|
64
|
+
Implement the realtime transport as a separately testable module. Keep wire decoding separate from event normalization. The normalized event pipeline should:
|
|
65
|
+
- validate incoming frame shape and size;
|
|
66
|
+
- normalize message, reply, unsend, reaction, typing, read/delivery, presence, and thread updates;
|
|
67
|
+
- preserve per-thread ordering;
|
|
68
|
+
- suppress duplicate event IDs with a bounded TTL cache;
|
|
69
|
+
- isolate listener exceptions and expose structured errors;
|
|
70
|
+
- support exactly one active transport listener per client unless multi-listener behavior is deliberately designed and tested.
|
|
71
|
+
|
|
72
|
+
Reconnect belongs to the connection supervisor. It must tear down stale sockets and subscriptions before reconnecting, use bounded exponential backoff with jitter, and stop promptly on logout.
|
|
73
|
+
|
|
74
|
+
### 5. HTTP and action layer
|
|
75
|
+
|
|
76
|
+
Keep request transport, action serialization, and response parsing separate. Every action should declare:
|
|
77
|
+
- required inputs and validation;
|
|
78
|
+
- supported capability;
|
|
79
|
+
- retry policy (default: no retry for non-idempotent sends);
|
|
80
|
+
- timeout and response normalization;
|
|
81
|
+
- structured error mapping.
|
|
82
|
+
|
|
83
|
+
Do not blindly retry message sends or other non-idempotent operations because that can duplicate user-visible actions.
|
|
84
|
+
|
|
85
|
+
### 6. Session security
|
|
86
|
+
|
|
87
|
+
Preserve the existing encrypted session helpers and secret redaction. Add atomic persistence and corruption handling before relying on session files in production. Never commit cookies, AppState, passwords, 2FA secrets, tokens, or encryption keys. Never include raw session values in logs or thrown errors.
|
|
88
|
+
|
|
89
|
+
### 7. Compatibility strategy
|
|
90
|
+
|
|
91
|
+
Implement the smallest stable compatibility surface first:
|
|
92
|
+
1. Login and logout lifecycle.
|
|
93
|
+
2. `getCurrentUserID`, `listen` / `listenMqtt`.
|
|
94
|
+
3. `sendMessage`, `markAsRead`, `sendTypingIndicator`.
|
|
95
|
+
4. Thread and user reads.
|
|
96
|
+
5. Reactions, unsend/edit, attachments.
|
|
97
|
+
6. Group administration and less common social APIs.
|
|
98
|
+
|
|
99
|
+
GoatBot integration must be gated by a compatibility test suite. Do not replace its existing FCA dependency until the required commands and events pass those tests.
|
|
100
|
+
|
|
101
|
+
## Test strategy and release gates
|
|
102
|
+
|
|
103
|
+
- Unit tests: synthetic cookies, request fixtures, transport state machine, frame decoder, event normalizer, action serializers, and error mapping.
|
|
104
|
+
- Contract tests: every driver must pass lifecycle, capability, listener, and shutdown tests.
|
|
105
|
+
- Integration tests: explicitly opt-in, isolated test account, no credentials in CI, and no high-volume actions.
|
|
106
|
+
- Compatibility tests: compare event and method shapes expected by GoatBot, including callback ordering and error-first callbacks.
|
|
107
|
+
- Release gates: syntax, unit tests, type/API surface checks, dependency audit, secret scan, and a documented integration smoke test.
|
|
108
|
+
|
|
109
|
+
A release must not be called production-ready while authentication, realtime transport, event decoding, or required API coverage is missing.
|
|
110
|
+
|
|
111
|
+
## Research references
|
|
112
|
+
|
|
113
|
+
These are study references, not runtime dependencies and not a statement that their code is copied:
|
|
114
|
+
|
|
115
|
+
- VangBanLaNhat/fca-unofficial: https://github.com/VangBanLaNhat/fca-unofficial
|
|
116
|
+
- Useful areas to study: separation of action modules, request/session helpers, event parsing, and MQTT integration.
|
|
117
|
+
- Its package metadata declares MIT, but a root LICENSE file was not available during this review. Do not copy code until the license grant and notices are independently confirmed.
|
|
118
|
+
- dongp06/fca-unofficial: https://github.com/dongp06/fca-unofficial
|
|
119
|
+
- Useful areas to study: documented flat compatibility API, namespaced facade, event-driven bot layer, and architecture docs.
|
|
120
|
+
- Repository is archived; use as a design reference only.
|
|
121
|
+
- anbuinfosec/fca-unofficial: https://github.com/anbuinfosec/fca-unofficial
|
|
122
|
+
- Useful as a GoatBot compatibility comparison, not as an authority for account safety or production reliability.
|
|
123
|
+
|
|
124
|
+
## Current implementation boundary
|
|
125
|
+
|
|
126
|
+
The current `createClient({ authenticate })` is a foundation, not an implemented Facebook client. The next engineering milestone is a reviewed transport design and independently testable session/HTTP/realtime boundaries. No placeholder provider, fake successful login, or dummy MQTT implementation should be added.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Authentication attempt coordinator
|
|
2
|
+
|
|
3
|
+
`createAuthenticationAttempt()` is a provider-neutral lifecycle helper for owner-mediated login challenges. It does not perform Facebook login and does not contain Facebook endpoints, cookies, credentials, or protocol assumptions.
|
|
4
|
+
|
|
5
|
+
A provider passed as `authenticate` returns one of:
|
|
6
|
+
|
|
7
|
+
- `{ status: "authenticated", session }` after it has independently completed authentication.
|
|
8
|
+
- `{ status: "challenge_required", challenge, resume(answer), cancel?() }` when the same provider-owned login attempt is waiting for an owner response. The optional `cancel()` hook releases provider-owned pending state when the attempt is closed or exceeds its challenge-round limit.
|
|
9
|
+
|
|
10
|
+
The coordinator exposes:
|
|
11
|
+
|
|
12
|
+
- `begin(credentials, options)` to start exactly one attempt.
|
|
13
|
+
- `snapshot()` to read a sanitized state and challenge description.
|
|
14
|
+
- `submitChallenge(answer)` to continue the provider-owned attempt once.
|
|
15
|
+
- `close()` to cancel a pending provider challenge, close an authenticated session, and discard retained references.
|
|
16
|
+
|
|
17
|
+
States: `idle`, `authenticating`, `challenge_required`, `verifying_challenge`, `authenticated`, `failed`, and `closed`.
|
|
18
|
+
|
|
19
|
+
Challenge answers are passed only to the provider's continuation callback. The coordinator does not log or persist them. The default maximum is three challenge rounds (configurable from one to five). Exceeding the limit fails the attempt. Challenge details exposed through `snapshot()` use a generic message and identifier-only type/method names so provider text cannot echo credentials or cookies. Error snapshots use a fixed message and do not expose provider-controlled error codes or names.
|
|
20
|
+
|
|
21
|
+
## Minimal provider contract
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
const { createAuthenticationAttempt } = require("@omega/fca");
|
|
25
|
+
|
|
26
|
+
const attempt = createAuthenticationAttempt({
|
|
27
|
+
authenticate: async ({ credentials, options }) => {
|
|
28
|
+
// Provider owns the actual login transport and its private session.
|
|
29
|
+
const pending = await provider.begin(credentials, options);
|
|
30
|
+
|
|
31
|
+
if (pending.status === "challenge_required") {
|
|
32
|
+
return {
|
|
33
|
+
status: "challenge_required",
|
|
34
|
+
challenge: pending.challenge,
|
|
35
|
+
resume: answer => pending.continue(answer),
|
|
36
|
+
cancel: () => pending.cancel?.()
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
return { status: "authenticated", session: pending.session };
|
|
41
|
+
}
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
const sessionOrNull = await attempt.begin({ username, password });
|
|
45
|
+
if (!sessionOrNull) {
|
|
46
|
+
const { challenge } = attempt.snapshot();
|
|
47
|
+
// Obtain the answer directly from the account owner, then:
|
|
48
|
+
const session = await attempt.submitChallenge(ownerSuppliedAnswer);
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The snippet is illustrative only: no Facebook credential provider is included yet. Do not store credentials or challenge answers in source control, logs, or shared services. Checkpoints must be resolved by the account owner through Facebook's own verification process.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# OmegA FCA Browser Capture
|
|
2
|
+
|
|
3
|
+
This owner-operated tool records HTTP/WebSocket metadata from a browser session for protocol research. It does not send captures to any server.
|
|
4
|
+
|
|
5
|
+
## Desktop setup
|
|
6
|
+
|
|
7
|
+
Node.js 20+ is required.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --no-save playwright
|
|
11
|
+
npx playwright install chromium
|
|
12
|
+
npm run capture:browser
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Sign in manually, open Messenger, and reproduce activity on an account you own. Press Ctrl+C to save `.omega-capture/capture-report.json`.
|
|
16
|
+
|
|
17
|
+
## Android / Termux
|
|
18
|
+
|
|
19
|
+
Termux cannot reliably launch Playwright's bundled desktop Chromium directly. On Android, use an installed Chromium-based browser with remote debugging enabled and attach over the Chrome DevTools Protocol (CDP). This is supported only if that browser exposes a CDP endpoint; Chrome's Android debugging is normally exposed through ADB. Browser builds such as Lemur may not expose a compatible endpoint.
|
|
20
|
+
|
|
21
|
+
1. Install Termux from a trusted source, then run:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
pkg update && pkg upgrade
|
|
25
|
+
pkg install nodejs-lts android-tools
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
2. In the FCA repo:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npm ci
|
|
32
|
+
npm install --no-save playwright
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
3. Enable **Wireless debugging** in Android Developer options. In Termux, pair/connect using the IP and ports displayed by Android:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
adb pair PHONE_IP:PAIR_PORT
|
|
39
|
+
adb connect PHONE_IP:DEBUG_PORT
|
|
40
|
+
adb forward tcp:9222 localabstract:chrome_devtools_remote
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
4. Open Chrome on Android, keep it running, then check the debugging endpoint:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
curl http://127.0.0.1:9222/json/version
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
If that endpoint responds with browser metadata, run:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
npm run capture:browser -- --cdp http://127.0.0.1:9222
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Log in and use Messenger in the already-open Android browser. The capture process attaches to that browser; it does not launch another one. If ADB pairing, the localabstract socket, or the endpoint is unavailable, that browser build/device does not expose CDP and this method will not work. Do not assume Lemur is compatible; verify its endpoint first.
|
|
56
|
+
|
|
57
|
+
## Capture privacy
|
|
58
|
+
|
|
59
|
+
The default report includes request method, origin/path (query strings omitted), response status/content type, WebSocket direction, frame size, and redacted text previews. It excludes HTTP bodies, cookie/header values, and browser storage.
|
|
60
|
+
|
|
61
|
+
For local binary protocol inspection only:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
npm run capture:browser -- --cdp http://127.0.0.1:9222 --save-private-frames
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Raw WebSocket frames are written to `.omega-capture/private/frames.ndjson` and may contain authentication material, identifiers, or private messages. Keep them on-device, never commit them, and never share them unredacted. The sanitized report is written to `.omega-capture/capture-report.json`.
|
|
68
|
+
|
|
69
|
+
## Limitations
|
|
70
|
+
|
|
71
|
+
- The browser and capture process run on the user's device; ChatGPT cannot see the live browser.
|
|
72
|
+
- CDP attachment requires a browser that explicitly exposes a compatible debugging endpoint.
|
|
73
|
+
- This tool does not bypass login, checkpoints, 2FA, rate limits, or platform security.
|
|
74
|
+
- Captures are evidence, not a protocol implementation. Native FCA behavior must be implemented only from reviewed, reproducible evidence.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Deployment and AppState test checklist
|
|
2
|
+
|
|
3
|
+
OmegA-FCA is a **Node.js library**, not a standalone web server. For the current testing phase, use the AppState session-validation smoke test. Do not deploy the Meta Page webhook example for personal-account testing.
|
|
4
|
+
|
|
5
|
+
## Current test scope
|
|
6
|
+
|
|
7
|
+
The AppState smoke test validates an owner-supplied Facebook session over HTTPS and reports the account ID, session state, and validation time. It does **not** establish the private Messenger realtime connection, subscribe to events, send messages, or make this package a drop-in GoatBot FCA replacement.
|
|
8
|
+
|
|
9
|
+
Native email/password login is intentionally deferred. The test runner rejects credential mode and only accepts cookie/AppState data.
|
|
10
|
+
|
|
11
|
+
## Requirements
|
|
12
|
+
|
|
13
|
+
- Node.js 20 or 22.
|
|
14
|
+
- The repository checked out on `public-package`.
|
|
15
|
+
- A valid, owner-controlled AppState/cookie export.
|
|
16
|
+
- Network access to Facebook over HTTPS.
|
|
17
|
+
|
|
18
|
+
## Prepare the AppState file
|
|
19
|
+
|
|
20
|
+
Put only the cookie/AppState data in the project-root `account.txt`. Accepted formats are:
|
|
21
|
+
- Raw cookie header (`c_user=...; xs=...`).
|
|
22
|
+
- Netscape cookie export.
|
|
23
|
+
- JSON cookie array.
|
|
24
|
+
|
|
25
|
+
Alternatively, put a JSON cookie array in `appstate.json`.
|
|
26
|
+
|
|
27
|
+
Do not put email, username, password, 2FA seed/code, or tokens in `account.txt`. Do not commit either file. Both are ignored by `.gitignore`.
|
|
28
|
+
|
|
29
|
+
## Run the smoke test
|
|
30
|
+
|
|
31
|
+
From the OmegA-FCA repository root:
|
|
32
|
+
|
|
33
|
+
~~~bash
|
|
34
|
+
npm ci
|
|
35
|
+
npm test
|
|
36
|
+
npm run test:syntax
|
|
37
|
+
npm run test:appstate
|
|
38
|
+
~~~
|
|
39
|
+
|
|
40
|
+
The AppState test command is a live network check and is intentionally **not** part of CI. It prints only the Facebook user ID, session state, timestamp, and a safe error summary; it never prints cookie values.
|
|
41
|
+
|
|
42
|
+
If the package is installed inside a GoatBot project and the account file is in the GoatBot project root, run the example from that project root:
|
|
43
|
+
|
|
44
|
+
~~~bash
|
|
45
|
+
node node_modules/@omega/fca/examples/appstate-session-check.js
|
|
46
|
+
~~~
|
|
47
|
+
|
|
48
|
+
This command validates the AppState session layer only. It does not prove that GoatBot can receive Messenger events through OmegA-FCA.
|
|
49
|
+
|
|
50
|
+
## Railway / Render notes
|
|
51
|
+
|
|
52
|
+
For this phase, deploy the **existing GoatBot application** with its currently working FCA dependency unchanged. Keep its `account.txt` as a private runtime file/volume or use the bot's existing secure session mechanism. Do not bake AppState into the image, commit it, print it in logs, or place it in a public build artifact.
|
|
53
|
+
|
|
54
|
+
OmegA-FCA can be installed as a package dependency only after the owner deliberately configures access to the private GitHub repository. Do not replace GoatBot's current FCA dependency yet: the full transport and API compatibility gates are not complete.
|
|
55
|
+
|
|
56
|
+
## Release / CI checks
|
|
57
|
+
|
|
58
|
+
The repository CI is intended to run on Node 20 and 22 and performs:
|
|
59
|
+
1. `npm ci`
|
|
60
|
+
2. `npm test`
|
|
61
|
+
3. Recursive JavaScript syntax validation.
|
|
62
|
+
4. Root package export smoke test.
|
|
63
|
+
5. `npm pack --dry-run --json`.
|
|
64
|
+
|
|
65
|
+
`prepublishOnly` repeats unit tests and syntax validation before npm publishing. This branch is not being published as an npm package during the AppState test phase.
|
|
66
|
+
|
|
67
|
+
## Not yet deploy-ready as a standalone personal FCA
|
|
68
|
+
|
|
69
|
+
These remain hard blockers for replacing the existing GoatBot FCA:
|
|
70
|
+
- Native email/password login (deferred by current project decision).
|
|
71
|
+
- A complete personal-account action/API layer.
|
|
72
|
+
- Messenger realtime transport, subscriptions, acknowledgements, and event decoding.
|
|
73
|
+
- Full legacy FCA method/event parity and GoatBot call-site coverage.
|
|
74
|
+
- Authorized end-to-end tests for message receive/send, groups, reconnect, and session expiry.
|
|
75
|
+
|
|
76
|
+
Do not point the live GoatBot deployment at OmegA-FCA as a drop-in replacement until those gates pass.
|
|
77
|
+
|
|
78
|
+
## Separate Page webhook example
|
|
79
|
+
|
|
80
|
+
The repository also contains an official Meta Messenger **Page** webhook example. It is unrelated to personal-profile AppState testing and requires a Page token, Meta app configuration, webhook verification, and separate deployment settings. Do not use it for this task.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Facebook Messenger MQTT transport (experimental)
|
|
2
|
+
|
|
3
|
+
This module is based on publicly available FCA implementation observations, not an official Meta personal-account API. Meta does not publish a supported personal Messenger API.
|
|
4
|
+
|
|
5
|
+
## Implemented
|
|
6
|
+
|
|
7
|
+
- WebSocket endpoint construction for `wss://edge-chat.facebook.com/chat`, with optional region, session ID and client/device ID.
|
|
8
|
+
- Browser-origin and owner-supplied cookie headers.
|
|
9
|
+
- MQTT 3.1 (`MQIsdp`, protocol version 3) CONNECT, CONNACK validation and the public FCA username metadata shape.
|
|
10
|
+
- The observed topic subscription family and QoS 1 SUBACK validation.
|
|
11
|
+
- Initial queue bootstrap via `/messenger_sync_create_queue`, or `/messenger_sync_get_diffs` when a caller supplies a sync token and sequence ID.
|
|
12
|
+
- QoS 1 PUBACK for inbound PUBLISH frames, outbound topic publish frames, and MQTT PINGREQ keepalive.
|
|
13
|
+
- Bounded `/ls_req` request publishing with numeric `request_id` allocation and `/ls_resp` correlation, timeout, pending-request cap and disconnect cleanup.
|
|
14
|
+
- Source-observed text/sticker/reply send task envelope builder (`createMessengerSendMessageRequest`) exposed through the native driver's `sendMessage()` method and bounded `/ls_req`–`/ls_resp` correlation. This is experimental and does not claim broker acceptance or delivery.
|
|
15
|
+
- Defensive `/t_ms` delta parsing for known message, reply, reaction, unsend, typing, read, presence and thread-event classes; unknown classes remain marked as `unknown_delta`.
|
|
16
|
+
- Conservative extraction of sync token / sequence cursor fields as `sync_cursor` events; when an account-bound `syncCursorStore` is explicitly supplied, cursors are AES-256-GCM encrypted at rest and reloaded on reconnect.
|
|
17
|
+
- Bounded WebSocket connection and protocol setup timeouts through the shared native realtime runtime.
|
|
18
|
+
|
|
19
|
+
## Example
|
|
20
|
+
|
|
21
|
+
The package deliberately does not add a WebSocket dependency. Supply a compatible implementation such as `ws` from your application:
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
const WebSocket = require("ws");
|
|
25
|
+
const {
|
|
26
|
+
createFacebookMqttProtocol,
|
|
27
|
+
createNativeRealtimeTransport
|
|
28
|
+
} = require("@omega/fca");
|
|
29
|
+
|
|
30
|
+
const config = createFacebookMqttProtocol({
|
|
31
|
+
userId: "YOUR_NUMERIC_USER_ID",
|
|
32
|
+
cookie: process.env.FB_COOKIE
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
const transport = createNativeRealtimeTransport({
|
|
36
|
+
url: config.url,
|
|
37
|
+
headers: config.headers,
|
|
38
|
+
protocol: config.protocol,
|
|
39
|
+
socketFactory: ({ url, headers }) => new WebSocket(url, { headers })
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
const driver = await transport.connect();
|
|
43
|
+
driver.listen((error, event) => {
|
|
44
|
+
if (error) console.error(error.message);
|
|
45
|
+
else if (event?.type === "mqtt_publish") {
|
|
46
|
+
console.log("MQTT topic:", event.topic);
|
|
47
|
+
}
|
|
48
|
+
});
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Do not log cookies or raw private message payloads. Store the AppState/cookie only in a private secret store or local environment variable; never commit it.
|
|
52
|
+
|
|
53
|
+
## Still required before calling this a complete FCA
|
|
54
|
+
|
|
55
|
+
- Decode Messenger sync queue responses and persist the latest sync token / sequence cursor.
|
|
56
|
+
- Validate delta field mappings against authorized live frames; current normalization is based on known public FCA shapes and preserves each raw delta for future mapping.
|
|
57
|
+
- Recover gaps after disconnect/restart using validated sync cursor handling.
|
|
58
|
+
- Implement source-verified Messenger task payload builders for send message, typing, read receipts and other FCA methods; the generic request correlation layer is now present but does not invent task schemas.
|
|
59
|
+
- Verify the handshake, queue bootstrap, receive and send behavior against an authorized live account, then test reconnect/long-running stability.
|
|
60
|
+
|
|
61
|
+
The endpoint, MQTT 3.1 metadata and topic/queue shapes are unofficial observations from public FCA source code and may change without notice. The implementation does not bypass Facebook checkpoints, 2FA or rate limits. The official Meta Page API remains a separate provider.
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
## Integrated AppState driver
|
|
65
|
+
|
|
66
|
+
`createFacebookMqttDriver()` composes the owner-supplied AppState validator, account-scoped cookie jar, MQTT protocol adapter and native WebSocket runtime. It requires an injected `socketFactory({ url, protocols, headers, signal })`, so applications can use a supported WebSocket implementation without this package silently downloading or selecting one. The returned driver exposes the current account ID, `listen`, `sendRequest`, `sendMessage` and `disconnect`.
|
|
67
|
+
|
|
68
|
+
Example:
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
const { createFacebookMqttDriver } = require("@omega/fca");
|
|
72
|
+
const WebSocket = require("ws");
|
|
73
|
+
|
|
74
|
+
const driver = await createFacebookMqttDriver({
|
|
75
|
+
appState: JSON.parse(process.env.FB_APPSTATE_JSON),
|
|
76
|
+
socketFactory: ({ url, protocols, headers }) =>
|
|
77
|
+
new WebSocket(url, protocols, { headers }),
|
|
78
|
+
mqtt: { keepAlive: 60 }
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
This example describes API wiring only. A fake-broker integration test verifies the local handshake sequence; it does not establish that Facebook currently accepts the observed MQTT metadata or that message sends are delivered. Keep AppState in a private secret store, never in source control or deployment logs.
|