@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.
Files changed (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +155 -2
  3. package/docs/ARCHITECTURE.md +126 -0
  4. package/docs/AUTHENTICATION-ATTEMPT.md +52 -0
  5. package/docs/BROWSER-CAPTURE.md +74 -0
  6. package/docs/DEPLOYMENT.md +80 -0
  7. package/docs/FACEBOOK-MQTT-TRANSPORT.md +82 -0
  8. package/docs/GOATBOT-COMPATIBILITY-MATRIX.md +58 -0
  9. package/docs/GOATBOT-INTEGRATION-AUDIT.md +64 -0
  10. package/docs/IMPLEMENTATION-STATUS.md +51 -0
  11. package/docs/META-MESSENGER-TRANSPORT.md +78 -0
  12. package/docs/NESTED-REALTIME-PAYLOAD.md +16 -0
  13. package/docs/NTKHANG-REFERENCE-STUDY.md +69 -0
  14. package/docs/PROTOCOL-EVIDENCE.md +69 -0
  15. package/docs/REALTIME-FRAME-EVIDENCE.md +33 -0
  16. package/docs/REFERENCE-AUDIT.md +63 -0
  17. package/docs/SAFE-DIAGNOSTICS.md +39 -0
  18. package/examples/appstate-session-check.js +33 -0
  19. package/examples/meta-messenger-server.js +96 -0
  20. package/index.d.ts +407 -0
  21. package/index.js +62 -0
  22. package/package.json +63 -4
  23. package/src/api/client.js +308 -0
  24. package/src/auth/accountConfig.js +82 -0
  25. package/src/auth/authenticationAttempt.js +193 -0
  26. package/src/auth/facebookResponse.js +93 -0
  27. package/src/auth/facebookWebClient.js +133 -0
  28. package/src/auth/personalSession.js +335 -0
  29. package/src/auth/totp.js +39 -0
  30. package/src/compat/facebookMqttClient.js +74 -0
  31. package/src/compat/goatbotLogin.js +67 -0
  32. package/src/compat/legacyFcaTransport.js +136 -0
  33. package/src/events/dispatcher.js +69 -0
  34. package/src/license/provider.js +37 -0
  35. package/src/license/verify.js +42 -0
  36. package/src/network/cookieJar.js +72 -0
  37. package/src/network/requestClient.js +104 -0
  38. package/src/runtime/connection.js +231 -0
  39. package/src/security/cookies.js +104 -0
  40. package/src/security/diagnostics.js +98 -0
  41. package/src/security/redact.js +23 -0
  42. package/src/security/sessionCrypto.js +61 -0
  43. package/src/security/sessionState.js +23 -0
  44. package/src/security/sessionStore.js +64 -0
  45. package/src/transport/binaryPayloadInspector.js +131 -0
  46. package/src/transport/contract.js +39 -0
  47. package/src/transport/facebookGatewayProtocol.js +135 -0
  48. package/src/transport/facebookMqttDriver.js +60 -0
  49. package/src/transport/facebookMqttEvents.js +114 -0
  50. package/src/transport/facebookMqttProtocol.js +213 -0
  51. package/src/transport/facebookThreadApi.js +284 -0
  52. package/src/transport/messengerActions.js +64 -0
  53. package/src/transport/messengerSyncCursorStore.js +53 -0
  54. package/src/transport/metaMessenger.js +294 -0
  55. package/src/transport/mqtt311Codec.js +254 -0
  56. package/src/transport/mqtt311StreamDecoder.js +57 -0
  57. package/src/transport/mqttRequestTracker.js +60 -0
  58. package/src/transport/nativeRealtimeTransport.js +388 -0
  59. package/src/transport/realtimeFrameDecoder.js +92 -0
  60. package/src/transport/realtimeSyncEnvelope.js +84 -0
  61. package/src/update/manifest.js +102 -0
  62. package/tools/browser-capture.js +130 -0
  63. package/tools/termux-capture-setup.sh +26 -0
@@ -0,0 +1,58 @@
1
+ # GoatBot compatibility matrix
2
+
3
+ **Target:** `nirzon-islam/OmegA-Goatbot`
4
+ **GoatBot branch reviewed:** `fca-migration-cleanup`
5
+ **OmegA-FCA branch:** `public-package`
6
+ **Status:** Native AppState/MQTT integration wired on the working branch; live acceptance and full FCA parity are still unverified.
7
+
8
+ This matrix separates what the current OmegA-FCA facade exposes from what still requires a real transport and end-to-end verification. A method appearing in the facade means only that the injected driver supplied it; it does not mean Facebook behavior is implemented by this package.
9
+
10
+ ## Login and lifecycle
11
+
12
+ | GoatBot expectation | Current OmegA-FCA status | Notes |
13
+ |---|---|---|
14
+ | `login({ appState }, options, callback)` | Native AppState path wired | `createGoatBotLogin` maps AppState arrays to `createFacebookMqttClient`; native HTTPS session validation and MQTT setup run before callback success. Real-account acceptance is still pending. |
15
+ | `getCurrentUserID()` | Conditional | Exposed after login; returns the driver identity converted to a string, or null. |
16
+ | `listenMqtt(callback)` | Native adapter wired | Adapts the native driver's `listen` to error-first `(error, event)` and emits a `ready` event after successful MQTT setup. Live event compatibility remains unverified. |
17
+ | `stopListening(callback?)` | Implemented at facade boundary | Detaches the active listener and invokes an optional callback. |
18
+ | `sessionGuard(path, options)` | Pass-through only | Exposed only if the injected driver implements it; no built-in account-file watcher. |
19
+ | `stopSessionGuard()` | Pass-through only | Exposed only if supplied by the driver. |
20
+ | `setOptions(options)` | Pass-through only | Exposed only if supplied by the driver. |
21
+ | `e2ee.isConnected()` | Not implemented | No E2EE implementation in this branch. |
22
+
23
+ ## Conditional driver API
24
+
25
+ The client exposes each method below only when the injected driver provides that function. No successful Facebook action is implied by the method name.
26
+
27
+ | Method | License feature gate (when licensing enabled) | Current status |
28
+ |---|---|---|
29
+ | `sendMessage`, `unsendMessage`, `markAsRead`, `sendTypingIndicator` | `messaging` | Driver pass-through only |
30
+ | `getUserInfo`, `getThreadInfo`, `getThreadList`, `getThreadHistory`, `getMessage`, `getFriendsList`, `getUserID` | `threads` | Driver pass-through only |
31
+ | `addUserToGroup`, `removeUserFromGroup`, `createNewGroup`, `changeNickname` | `groups` | Driver pass-through only |
32
+ | `setMessageReaction` | `reactions` | Driver pass-through only |
33
+
34
+ ## Required work before migration
35
+
36
+ - Complete live validation of the owner-supplied AppState session; username/password and 2FA login remain deferred, and checkpoint resolution remains manual.
37
+ - Implement HTTP action serialization, response/error normalization, and safe retry policy. Do not automatically retry non-idempotent sends.
38
+ - Validate native MQTT frame decoding, event normalization, readiness, reconnect and deterministic shutdown against an authorized account; synthetic fake-broker coverage is not live acceptance.
39
+ - Inventory every FCA call site across GoatBot commands, events, dashboard, database and custom scripts; this document is not a complete call-site inventory.
40
+ - Add contract tests for every required method and callback shape, then opt-in integration tests using an authorized test account.
41
+ - Verify CI on the target branch and run GoatBot's own tests before considering a dependency switch.
42
+
43
+ ## Release decision
44
+
45
+ **Do not treat the working branch as production-accepted until an authorized live account test passes.** AppState session setup and native MQTT transport are now wired, but private Facebook endpoint behavior, message delivery, complete API parity, E2EE, and all call-site coverage remain unverified or unimplemented. Never put live AppState, cookies, passwords, 2FA material, or session keys in fixtures, logs, commits, or CI.
46
+
47
+
48
+ ## Working-branch integration update
49
+
50
+ The GoatBot `fca-migration-cleanup` branch now uses the first-party
51
+ `createFacebookMqttClient()` factory through `createGoatBotLogin`. The
52
+ `@eryxenx/fca` dependency has been removed from that branch, and OmegA-FCA
53
+ owns its WebSocket runtime through its package dependency.
54
+
55
+ This is a native code-path integration milestone, not live acceptance. The
56
+ Facebook-specific MQTT handshake, task schemas, event deltas, and private web
57
+ action endpoints remain experimental until an authorized live account test
58
+ proves login readiness, message receive/send, and recovery.
@@ -0,0 +1,64 @@
1
+ # GoatBot integration audit
2
+
3
+ **Target:** `nirzon-islam/OmegA-Goatbot`
4
+ **Branch reviewed:** `fca-migration-cleanup`
5
+ **OmegA-FCA branch:** `public-package`
6
+ **Review status:** partial source audit; not a migration approval.
7
+
8
+ ## Verified integration contract
9
+
10
+ The current GoatBot login module imports `@eryxenx/fca` and invokes it using the callback form:
11
+
12
+ ```js
13
+ login({ appState }, options, callback)
14
+ ```
15
+
16
+ The successful callback is expected to provide an API object with at least:
17
+
18
+ - `getCurrentUserID()` — used immediately to set `global.GoatBot.botID` and `global.botID`.
19
+ - `listenMqtt(callback)` — used as the long-lived Messenger event stream.
20
+ - `stopListening(callback?)` — used by GoatBot's listener lifecycle and account-switch/recovery flow.
21
+
22
+ Additional API surface used or explicitly probed by the login module:
23
+
24
+ - `sessionGuard(accountPath, options)` — optional account-file/session guard.
25
+ - `stopSessionGuard()` — optional guard shutdown.
26
+ - `setOptions(options)` — exposed by some FCA builds and relevant to runtime option updates.
27
+ - `e2ee.isConnected()` — optional E2EE status probe; absence is tolerated.
28
+
29
+ The login flow also expects the MQTT callback convention `(error, event)`, and it uses the ready event to determine whether a candidate session has become usable. A callback-compatible login adapter alone is therefore insufficient: the transport must deliver the expected event lifecycle.
30
+
31
+ ## Input formats currently accepted by GoatBot
32
+
33
+ The current account loader supports several formats before it calls FCA:
34
+
35
+ - AppState JSON array, including legacy `name` cookie keys and `key` cookie keys.
36
+ - Cookie header string.
37
+ - Netscape cookie text.
38
+ - The current OmegA-FCA `public-package` branch is AppState-only at the account-loader boundary. Direct credential-mode plumbing exists for an injected provider, but no native credential login or interactive challenge UI is implemented here.
39
+ - Legacy token-based input paths.
40
+
41
+ The current OmegA-FCA client has explicit `appstate`, `cookie`, and `credentials` modes. The compatibility adapter currently maps AppState arrays and email/password credentials; it does not yet reproduce every legacy account-file parser or interactive login behavior.
42
+
43
+ ## Confirmed compatibility gaps
44
+
45
+ 1. OmegA-FCA's `createClient` still requires an injected `authenticate` transport provider. It does not perform Facebook authentication itself.
46
+ 2. There is no native Facebook HTTP action implementation or MQTT/WebSocket transport/event decoder in this branch yet.
47
+ 3. The current GoatBot adapter is callback-style at the login boundary, but GoatBot's full event lifecycle and session helper expectations are not yet implemented as a complete compatibility layer.
48
+ 4. OmegA-FCA's exposed driver method list must be compared against all GoatBot command, event, dashboard, database, and custom-script call sites before claiming drop-in compatibility.
49
+ 5. E2EE is not implemented by the current OmegA-FCA client.
50
+
51
+ ## Migration gate
52
+
53
+ Do not change GoatBot's dependency or replace its existing FCA until all of the following are true:
54
+
55
+ - Native authentication and transport are implemented using owner-controlled, legitimate platform login flows.
56
+ - MQTT readiness, reconnect, event ordering, and shutdown behavior pass synthetic and opt-in integration tests.
57
+ - The complete GoatBot API call inventory is mapped to OmegA-FCA methods and callback/promise semantics.
58
+ - Session guard and account-switch behavior have tested equivalents or an explicitly approved compatibility plan.
59
+ - Existing GoatBot secure-session tests and the OmegA-FCA test suite pass in CI.
60
+ - A controlled test branch run confirms startup, message receive/send, thread/group operations, and recovery without exposing live cookies or credentials.
61
+
62
+ ## Security and scope
63
+
64
+ Never put live cookies, AppState, passwords, 2FA material, or session keys in tests, commits, logs, or CI artifacts. Checkpoints and 2FA challenges must remain owner-controlled; do not bypass them. This audit does not authorize replacing the GoatBot dependency, merging branches, or deploying either project.
@@ -0,0 +1,51 @@
1
+ # OmegA-FCA implementation status
2
+
3
+ ## Implemented in the current branch
4
+
5
+ - Node.js 20+ CommonJS package, root exports and TypeScript declarations.
6
+ - Cookie/AppState parsing and validation, encrypted session helpers, restrictive file permissions and secret redaction.
7
+ - **Updated:** account configuration is AppState-only for this phase. `account.txt` accepts cookie/AppState data only and rejects credential-like key/value text. The loader does not read email, username, password, 2FA, or `FB_*` environment credentials; credential login is deferred.
8
+ - **New AppState test entry point:** `npm run test:appstate` validates an owner-supplied AppState from `account.txt` (or the documented `appstate.json` fallback), reports only non-secret session metadata, and is deliberately excluded from CI because it requires a real authorized session and network access.
9
+ - **New native personal-session foundation:** `createPersonalSession()` validates an owner-supplied AppState against Facebook over HTTPS, scopes session cookies to Facebook/Messenger hosts, provides bounded-time authenticated web requests, and reports expired sessions/checkpoints without bypassing them.
10
+ - Bounded HTTPS request helper and secure cookie jar.
11
+ - **New safe diagnostics utility:** bounded metadata-only recorder, integrated with AppState-backed personal-session requests; excludes header/query/body/response values and credential material.
12
+ - **New authenticated Facebook web client:** `createFacebookWebClient()` adds token-aware POST form serialization, GET/HEAD/POST handling, strict Facebook/Messenger HTTPS host validation, manual redirect classification (checkpoint/expired/unexpected), normalized JSON/error responses, and 2 MiB inbound/outbound body limits. It intentionally does not invent private action endpoints or payload schemas.
13
+ - Connection supervisor with bounded reconnect/backoff, listener recovery and abortable connect attempts.
14
+ - Event dispatcher with duplicate coalescing, success-only acknowledgement and per-thread ordering.
15
+ - Injectable transport contract and GoatBot callback-login adapter. The public client login facade currently accepts AppState/cookie modes only; username/email-password login is explicitly rejected until its later implementation phase.
16
+ - **New protocol-neutral native WebSocket runtime:** bounded connect/close waits, abort-aware connection setup, protocol-adapter hooks for authentication/subscription/frame decoding/action encoding, bounded frame handling, listener lifecycle, diagnostics metadata, and deterministic fake-socket tests. This is transport infrastructure only; it does not include Facebook's private handshake, endpoint, subscription topics, or action schemas.
17
+ - **New Facebook web realtime gateway adapter:** `createFacebookGatewayProtocol()` builds the `gateway.facebook.com/ws/realtime` upgrade URL and owner-cookie headers, sends the numbered subscription frames used by public FCA implementations, and decodes notification/presence gateway payloads. This is a separate web notification/presence channel; it is not the Messenger private message-sync channel and does not claim send-message support. The endpoint/subscription family is unofficial and may change server-side.
18
+ - **New MQTT 3.1/3.1.1 codec and stream primitives:** CONNECT, PUBLISH, SUBSCRIBE, UNSUBSCRIBE, packet acknowledgements, PINGREQ and DISCONNECT encoding plus bounded packet decoding. Includes legacy `MQIsdp` protocol version 3 support used by public FCA implementations.
19
+ - **New Facebook Messenger MQTT adapter:** observed `edge-chat.facebook.com/chat` URL construction, cookie/Origin headers, MQTT 3.1 CONNECT metadata, CONNACK validation, topic subscription, `/messenger_sync_create_queue` or `/messenger_sync_get_diffs` bootstrap, QoS 1 acknowledgement, publish actions and keepalive PINGREQ. This is an experimental native transport layer. It includes conservative known-shape `/t_ms` delta normalization, encrypted account-bound sync cursor storage with reconnect reload, bounded `/ls_req`–`/ls_resp` correlation, and an observed text/sticker/reply task builder exposed as `sendMessage`. Task schemas and broker acceptance remain unverified against a live account; this is not yet a drop-in FCA replacement.
20
+ - **New research register (2026-11-20):** separates Meta's historical MQTT/snapshot-delta architecture statements, OASIS MQTT 3.1.1 normative transport rules, and unofficial FCA source observations from current Facebook-specific facts.
21
+ - **New:** `createLegacyFcaProvider()` bridges an existing callback-style personal-account FCA implementation into OmegA-FCA's transport contract. It maps AppState or credentials login, manual 2FA inputs, current-user lookup, MQTT listener lifecycle and supported FCA methods.
22
+ - Checkpoint and expired-session classification. The owner must resolve Facebook challenges through Facebook. Credential/2FA login is deferred and rejected by the current public client login facade.
23
+ - Provider-neutral authentication-attempt coordinator with bounded challenge rounds, single-use continuation, optional provider cleanup on cancellation, and secret-safe public snapshots. This is lifecycle plumbing only; no Facebook credential provider is included.
24
+ - Optional Ed25519 licensing and signed update-manifest verification.
25
+ - Separate official Meta Messenger Page transport and webhook example.
26
+
27
+ ## Public-FCA-style web action layer
28
+
29
+ - Added AppState-session-backed `getThreadList`, `getThreadInfo`, `getThreadHistory`, and `getUserInfo` adapters using the legacy public FCA GraphQL-batch and `/chat/user_info/` conventions, with normalized responses, validation, pagination, and Promise/callback forms.
30
+ - Added `addUserToGroup`, `removeUserFromGroup`, `changeNickname`, `setMessageReaction`, and `markAsRead` using public FCA request patterns. Wired into the first-party MQTT driver.
31
+ - Synthetic request/response tests cover these adapters. Facebook private endpoints and document IDs are unofficial and may change; live account acceptance remains unverified. `createNewGroup` is intentionally not exposed until its request contract is evidenced.
32
+
33
+ ## Not yet implemented — standalone personal FCA blockers
34
+
35
+ This package is **not yet a standalone, drop-in personal-account FCA replacement**.
36
+
37
+ - OmegA-FCA does not yet implement the full personal-account authentication flow (username/password + 2FA), complete Facebook private HTTP/GraphQL action catalog or endpoint-specific payload schemas. The new AppState session bootstrap and generic authenticated web-client layer are session/request foundations only; they do not constitute the FCA action API. Username/password login is not yet implemented natively; the username field is currently an input contract for the future auth provider.
38
+ - The Facebook web realtime notification/presence gateway adapter is implemented separately from Messenger MQTT.
39
+ - The Messenger MQTT adapter now implements observed connection/queue bootstrap, conservative delta normalization, optional encrypted cursor persistence/reload, bounded request correlation, and an experimental message-send task builder. Cursor persistence requires the caller to explicitly configure `syncCursorStore`. It does not yet guarantee missed-event recovery or broker compatibility against a live account.
40
+ - The Messenger MQTT adapter now has an integrated `createFacebookMqttDriver()` path and a first-party `createFacebookMqttClient()` factory. The factory wires AppState validation, cookie scoping, native WebSocket/MQTT handshake, connection supervision, identity lookup, callback-compatible `listenMqtt`, legacy callback and Promise `sendMessage` signatures, `getUserID` alias, correlated requests and the experimental message-send method. The package now supplies its own `ws` WebSocket implementation by default (injection remains available for tests). This wiring is covered by deterministic fake-broker tests, not a real Facebook account. Public FCA wire observations are not an officially supported Meta personal-account API; endpoint, metadata, topics, delta mappings and task schemas still require live authorized-account verification.
41
+ - Full parity with every legacy FCA method, event shape, and GoatBot call site has not been proven.
42
+ - No authorized live personal-account end-to-end test has been run from this repository. The new AppState smoke-test command is prepared but has not yet been run against a real account.
43
+ - The GoatBot `fca-migration-cleanup` branch has now been switched to the first-party `createFacebookMqttClient()` path and no longer declares `@eryxenx/fca`. The callback login adapter now receives a native-ready event after AppState validation, MQTT CONNACK, and topic subscription. This is code-level integration only; full FCA method parity and a real authorized account test remain outstanding.
44
+
45
+ The personal-account MQTT adapter is experimental and based on public FCA wire observations, not an officially supported Meta personal-account API. The Page transport is separate and is not a substitute for a personal account.
46
+
47
+ ## Verification gate
48
+
49
+ Synthetic AppState session, authenticated web-client, redirect-classification, body-limit and adapter tests have been added. GitHub Actions must run on the latest branch commit before claiming the test suite passes. A real authorized account test is still required for login, MQTT readiness, message receive/send, group actions, reconnect, and checkpoint/session-expiry reporting.
50
+
51
+ Never commit live cookies, AppState, passwords, 2FA material, Page tokens, or encryption keys. Do not bypass checkpoints or platform security controls.
@@ -0,0 +1,78 @@
1
+ # Official Meta Messenger transport
2
+
3
+ This transport is for a Facebook Page connected to the official Meta Messenger Platform. It is intentionally separate from the personal-account FCA/AppState interface.
4
+
5
+ ## Requirements
6
+
7
+ - A Meta app configured for Messenger Platform and a Facebook Page.
8
+ - A Page access token with the permissions required by your app and recipient.
9
+ - A supported Graph API version configured explicitly.
10
+ - A public HTTPS webhook endpoint subscribed to the Page's Messenger events.
11
+ - The app secret for verifying `X-Hub-Signature-256`.
12
+
13
+ Meta's official Messenger Platform is Page-based. It does not provide the personal-account API surface exposed by unofficial FCA packages. This provider does not emulate browser sessions and does not use MQTT.
14
+
15
+ ## Outbound messages
16
+
17
+ ```js
18
+ const { createMetaMessengerTransport } = require("@omega/fca");
19
+
20
+ const transport = createMetaMessengerTransport({
21
+ pageAccessToken: process.env.META_PAGE_ACCESS_TOKEN,
22
+ pageId: process.env.META_PAGE_ID,
23
+ apiVersion: process.env.META_GRAPH_API_VERSION,
24
+ appSecret: process.env.META_APP_SECRET
25
+ });
26
+
27
+ const result = await transport.sendMessage("RECIPIENT_PSID", {
28
+ text: "Hello from OmegA"
29
+ });
30
+
31
+ console.log(result.message_id);
32
+ ```
33
+
34
+ The Page token is sent as an Authorization Bearer header and is never added to the request URL. Send requests are not automatically retried, avoiding accidental duplicate actions. `sendTypingIndicator(recipientId, typing = true)` maps to Meta sender actions `typing_on` / `typing_off`, and `markAsRead(recipientId)` maps to `mark_seen`. The transport also exposes `getUserInfo(psid, fields)` for the Messenger User Profile API (basic fields default to first name, last name, and profile picture; optional locale/timezone/gender fields require the corresponding Meta permissions), plus `getThreadList(limit, after)`, `getThreadInfo(conversationId)`, `getThreadHistory(conversationId, limit, after)`, and `getMessage(messageId)` through the official Page Conversations and Conversation Messages Graph API edges. These read operations require the Page permissions documented by Meta and return Graph API data/pagination objects rather than pretending to provide the legacy personal-account FCA response shape. Profile-picture URLs may expire and should not be stored as permanent assets.
35
+
36
+ ## Inbound webhook events
37
+
38
+ The host application owns the HTTPS server and Meta webhook subscription. Preserve the exact raw request bytes before parsing JSON, then pass the raw bytes and `X-Hub-Signature-256` value to `publishWebhook`. The provider verifies the HMAC-SHA256 signature over the original bytes, parses JSON from those same verified bytes, and only then emits normalized events for the configured Page ID. Events for other Page IDs are ignored. Webhook bodies are limited to 1 MiB.
39
+
40
+ ```js
41
+ const rawBody = Buffer.from(requestBodyBytes);
42
+ const signature = request.headers["x-hub-signature-256"];
43
+
44
+ transport.listen((error, event) => {
45
+ if (error) return console.error(error);
46
+ console.log(event.type, event.senderID, event);
47
+ });
48
+
49
+ transport.publishWebhook(rawBody, signature);
50
+ ```
51
+
52
+ Do not parse and re-serialize the body before signature verification: the signature is calculated over the original bytes. Reject webhook requests that fail verification. For the GET verification handshake, use the exported `verifyWebhookChallenge(query, verifyToken)` helper; it returns the challenge string only when `hub.mode=subscribe` and the verify token matches, otherwise `null`. Configure the HTTPS endpoint in your application; this package does not create or expose a web server.
53
+
54
+ Normalized event types currently include `message`, `postback`, `delivery`, `read`, `account_linking`, and `referral`.
55
+
56
+ ## Runnable webhook server example
57
+
58
+ A built-in Node.js HTTP server example is available at `examples/meta-messenger-server.js`. It handles the GET challenge, enforces a 1 MiB POST body limit, verifies the signature against the original request bytes, and returns a generic error body on invalid requests. Put it behind a trusted HTTPS ingress and do not expose the plain HTTP listener directly to the public internet.
59
+
60
+ Run it with:
61
+
62
+ ```bash
63
+ node examples/meta-messenger-server.js
64
+ ```
65
+
66
+ ## Lifecycle and limitations
67
+
68
+ Call `await transport.disconnect()` when the host application shuts down. `getCapabilities()` explicitly reports `userSessionEmulation: false` and `mqtt: false`.
69
+
70
+ This provider does not implement personal-profile inbox access, AppState login, private browser endpoints, group-chat administration, or the legacy GoatBot FCA API. Those capabilities must not be inferred from the shared method names.
71
+
72
+
73
+ ## Conversation read permissions
74
+
75
+ For Messenger Page conversations, Meta documents the Page access token and the `pages_manage_metadata`, `pages_read_engagement`, and `pages_messaging` permissions. The transport does not attempt to grant permissions or bypass App Review. See the [Page Conversations reference](https://developers.facebook.com/docs/graph-api/reference/page/conversations) and [Conversation Messages reference](https://developers.facebook.com/docs/graph-api/reference/conversation/messages/).
76
+
77
+
78
+ The [Messenger User Profile API](https://developers.facebook.com/docs/messenger-platform/reference/user-profile-api/) returns Page-scoped profile information only for people who have interacted with the Page and only for fields permitted to the app. A PSID is Page-specific; it is not a global Facebook user ID.
@@ -0,0 +1,16 @@
1
+ # Nested realtime payload inspection
2
+
3
+ Some observed Messenger WebSocket frames contain an outer JSON envelope with a
4
+ Base64 string in `payload`. This helper decodes only that Base64 layer and
5
+ reports bounded structural metadata.
6
+
7
+ When the decoded bytes form a valid Protocol Buffers wire-compatible stream,
8
+ the summary reports field numbers, wire types, and length-delimited byte counts.
9
+ It never returns field values, strings, IDs, message contents, or raw bytes.
10
+ A successful structural scan does **not** prove that the payload uses a
11
+ particular .proto schema or identify its semantic meaning. Unknown payloads
12
+ remain classified as opaque binary.
13
+
14
+ This is a diagnostic primitive only. It does not authenticate, connect,
15
+ subscribe, acknowledge, send, decrypt, or map Messenger events. Raw captures
16
+ and account/session identifiers must not be committed.
@@ -0,0 +1,69 @@
1
+ # NTKhang GoatBot FCA — Independent Architecture Study
2
+
3
+ Reviewed: 2026-11-19
4
+ Target: OmegA-FCA native personal-account engine
5
+ Reference: https://github.com/ntkhang03/Goat-Bot-V2/tree/main/fb-chat-api
6
+
7
+ This is an independent behavioral and architectural study. It contains no copied implementation code and does not claim that historical protocol details remain current.
8
+
9
+ ## Reference repository and licensing boundary
10
+
11
+ The GoatBot V2 repository identifies its bundled fb-chat-api as a detached FCA implementation. Its root LICENSE states MIT License (No Derivatives). OmegA-FCA must not copy, adapt, translate, or vendor that implementation. We can study externally observable behavior, public API contracts, and architectural separation, then implement our own code and tests from independently established requirements.
12
+
13
+ ## What the reference implementation does
14
+
15
+ ### 1. Login/bootstrap is a staged session lifecycle
16
+
17
+ The reference separates credential submission from authenticated API construction:
18
+ 1. Create an isolated HTTP session and cookie jar for one account.
19
+ 2. Fetch the login page and collect the session's current form state and cookies.
20
+ 3. Submit the owner's username/email and password using the session's current form state.
21
+ 4. Classify the result: invalid credentials, checkpoint/challenge, or authenticated session.
22
+ 5. If the platform requires an owner challenge, suspend login and expose an explicit continuation operation. Do not treat a challenge page as successful login.
23
+ 6. After owner verification, revalidate the same session and only then construct the authenticated API context.
24
+ 7. Derive account identity from the authenticated session, not the supplied username.
25
+ 8. Keep the cookie jar and account-specific tokens isolated to that client instance.
26
+
27
+ OmegA requirement: model this as a typed state machine: idle, authenticating, challenge_required, verifying_challenge, authenticated, failed, closed. Challenge continuation must be bound to the live attempt/session, reject stale or repeated submissions, preserve the same attempt, and never log challenge codes or secrets. Unknown challenge types must stop safely and explain that owner action is required.
28
+
29
+ ### 2. Authenticated API construction is separate from login
30
+
31
+ The reference builds an account context after session establishment. API methods share that context and common request helpers rather than creating unrelated sessions.
32
+
33
+ OmegA requirement: one private session context owns the cookie jar and account identity; current request tokens and refresh lifecycle; HTTP client and redirect/challenge classifier; realtime connection and sync cursor state; request correlation and pending operation registry; lifecycle state and cleanup. No method may silently replace the authenticated client's account cookie jar.
34
+
35
+ ### 3. Realtime is a protocol subsystem, not just a WebSocket
36
+
37
+ The reference listener uses MQTT over WebSocket, account/session identity, a connection lifecycle, topic subscriptions, initial synchronization, and incremental updates. It tracks synchronization cursor/token values and normalizes incoming message categories before exposing events.
38
+
39
+ OmegA requirement: separate endpoint/session bootstrap and handshake; MQTT connection adapter; subscription and sync coordinator; packet decoding and validation; delta/event normalization; public event dispatcher; reconnect and cursor recovery. A connected socket is not a ready listener. Emit ready only after required synchronization completes. Contain malformed/unknown packets. Reconnect must not duplicate listeners or acknowledge an event before processing succeeds.
40
+
41
+ ### 4. HTTP actions need per-operation contracts
42
+
43
+ The reference exposes individual actions such as message send, thread queries, group operations, reactions, and attachment upload through shared request helpers. Each action has its own validation, serialization, response extraction, and error behavior.
44
+
45
+ OmegA requirement: build an action catalog from the actual GoatBot call-site inventory. For every method record exact public signature and callback/promise behavior; input validation and normalized identifiers; request operation and current token requirements; response schema and output normalization; retry safety; typed error mapping and session-state effects. Do not automatically retry non-idempotent writes without verified idempotency. Unknown response shapes must produce typed errors, not fabricated success objects.
46
+
47
+ ### 5. Compatibility is larger than the login callback
48
+
49
+ The legacy GoatBot-facing surface includes identity lookup, MQTT listener lifecycle, ready/error events, messaging/thread/group operations, options, and cleanup. Method names alone do not prove compatibility: argument positions, callback conventions, event shapes, and stop/reconnect semantics matter.
50
+
51
+ OmegA requirement: use audited GoatBot call sites as the compatibility source of truth. Keep unsupported methods explicit until implemented; do not return dummy values.
52
+
53
+ ## OmegA-FCA implementation sequence
54
+
55
+ 1. Native session/auth engine: independent account-scoped HTTP session, credential login, explicit challenge state and owner-only continuation; retain AppState/cookie login as separate paths.
56
+ 2. Session bootstrap: authenticated identity, token extraction/refresh, checkpoint/logout detection, secure persistence opt-in, and cleanup.
57
+ 3. Realtime engine: independently implemented MQTT/WebSocket lifecycle, readiness/sync state, cursor handling, decoder, normalized events, reconnect and listener teardown.
58
+ 4. Action engine: implement and test methods required by GoatBot first, then expand the documented FCA surface.
59
+ 5. Compatibility facade: match callback and promise contracts, ready/error events, stopListening, options and account switching.
60
+ 6. Verification: deterministic sanitized fixtures, full Node 20+ test/syntax suite, then opt-in tests against an account the owner controls. Verify login, manual challenge, ready, receive/send, reconnect, logout and checkpoint reporting before calling it production-ready.
61
+
62
+ ## Evidence and release rules
63
+
64
+ - The inspected reference source is historical implementation evidence, not a current Facebook protocol specification.
65
+ - Its observed routes, form fields, MQTT topics, packet fields, and event payloads must not be copied as assumed-current facts.
66
+ - No endpoint, GraphQL document identifier, MQTT topic, payload field, or challenge form is accepted into the native engine without current, repeatable evidence and tests.
67
+ - Never bypass checkpoint, 2FA, login approvals, rate limits, or other platform security controls.
68
+ - Never store live credentials, cookies, AppState, 2FA codes/seeds, or session tokens in source, fixtures, logs, or CI.
69
+ - Do not switch GoatBot's production dependency, merge branches, or deploy until release gates in PROTOCOL-EVIDENCE.md and the GoatBot integration audit pass.
@@ -0,0 +1,69 @@
1
+ # Facebook Personal-Account Protocol Evidence
2
+
3
+ This document separates publicly documented architecture from historical observations and unverified implementation details. It is an engineering evidence register, not a claim that OmegA-FCA currently implements these protocols.
4
+
5
+ ## Evidence matrix
6
+
7
+ | Area | Public evidence | What it supports | What it does not prove | OmegA-FCA status |
8
+ |---|---|---|---|---|
9
+ | Messenger realtime architecture | Meta Engineering, [Building Facebook Messenger](https://engineering.fb.com/2011/08/12/android/building-facebook-messenger/) and [Under the Hood: Messenger for Windows](https://engineering.fb.com/2012/03/08/web/under-the-hood-building-facebook-messenger/) | Meta historically described MQTT as a persistent realtime channel for Messenger. | Current personal-profile endpoint, handshake, headers, client identity, topics, packet extensions, or current browser compatibility. | Not implemented |
10
+ | Snapshot + delta sync | Meta Engineering, [Building Mobile-First Infrastructure for Messenger](https://engineering.fb.com/2014/10/09/production-engineering/building-mobile-first-infrastructure-for-messenger/) | Meta described an initial snapshot followed by ordered delta updates over MQTT, backed by Iris. | Current public API, exact snapshot query, queue cursor format, or event payload schema. | Not implemented |
11
+ | Legacy FCA listener contract | [facebook-chat-api DOCS.md](https://github.com/Schmavery/facebook-chat-api/blob/master/DOCS.md) | Historical public FCA documentation describes callback-style `listenMqtt(callback)`, error/event callbacks, and stop-listening behavior. | That the historical implementation or event format still works today. | Compatibility facade only; no native listener |
12
+ | Historical credential login and 2FA | [fbchat session source](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_session.py) | A public historical client shows one observed password-login flow and an owner-supplied 2FA callback. | That the route, form fields, redirect sequence, or challenge flow is current or safe to reuse. | Not implemented |
13
+ | Recent unofficial implementation claims | [@dongdev/fca-unofficial](https://github.com/donyst/fca-unofficial) | A maintained third-party project claims to implement browser-session HTTP/GraphQL and MQTT behavior. | Independent verification of its current wire protocol, endpoint stability, or compliance. | Reference for further audit only |
14
+
15
+
16
+ ## Research update — 2026-11-20
17
+
18
+ ### Independently checked public sources
19
+
20
+ | Source | Directly supported finding | Boundary |
21
+ |---|---|---|
22
+ | Meta Engineering, [Building Facebook Messenger](https://engineering.fb.com/2011/08/12/android/building-facebook-messenger/) | Meta described MQTT as a persistent real-time channel in Messenger. | Historical architecture only; not a current personal-profile wire specification. |
23
+ | Meta Engineering, [Building Mobile-First Infrastructure for Messenger](https://engineering.fb.com/2014/10/09/production-engineering/building-mobile-first-infrastructure-for-messenger/) | Meta described snapshot-plus-delta synchronization, with MQTT delivering ordered real-time updates through Iris. | Does not publish current client handshake, broker configuration, subscriptions, or payload schemas. |
24
+ | OASIS, [MQTT 3.1.1 specification](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html), Sections 3 and 6 | Defines standard MQTT CONNECT/SUBSCRIBE/PUBLISH packet behavior and MQTT over WebSocket transport requirements, including binary WebSocket frames and the MQTT subprotocol. | Defines MQTT generally; it does not establish which MQTT version, extensions, credentials, or packet fields a current Facebook client uses. |
25
+ | [VangBanLaNhat/fca-unofficial](https://github.com/VangBanLaNhat/fca-unofficial) | Public source contains an MQTT listener and event normalization implementation; its package metadata currently requires Node.js 22+. | Unofficial reverse-engineered code is an observation, not a Facebook specification or proof of present-day compatibility. OmegA-FCA must not vendor or copy it. |
26
+ | [dongp06/fca-unofficial](https://github.com/dongp06/fca-unofficial) | Public documentation describes a two-layer HTTP/GraphQL + MQTT API and a realtime listener/event API. | GitHub marks this repository archived on 2026-05-09. Its own documentation is not independent verification of current Facebook behavior. |
27
+ | Meta Messenger Platform [Webhooks](https://developers.facebook.com/docs/graph-api/webhooks/getting-started/webhooks-for-messenger/) and [Quick Start](https://developers.facebook.com/docs/messenger-platform/getting-started/quick-start) | Official supported product flow is Page-based Webhooks and Send API. | Not a personal-profile FCA replacement. |
28
+
29
+ ### Engineering conclusions
30
+
31
+ 1. A WebSocket lifecycle wrapper alone is not an MQTT client and cannot be called a working Messenger realtime transport.
32
+ 2. Standard MQTT 3.1.1 packet handling can be implemented and tested against the OASIS specification without assuming Facebook-specific behavior.
33
+ 3. The Facebook-specific adapter remains blocked until current, repeatable, authorized evidence establishes the selected MQTT/WebSocket protocol version, broker/session negotiation, required client metadata, sync bootstrap, subscription/acknowledgement behavior, and event/action envelopes.
34
+ 4. Historical topic names, endpoint strings, client metadata, GraphQL identifiers, and payload fields found in public forks are not accepted as current facts.
35
+ 5. No checkpoint, 2FA, anti-abuse, rate-limit, or other account security challenge is to be bypassed.
36
+ 6. The next implementation slice may build a standards-compliant MQTT 3.1.1 codec/client behind the transport boundary with spec-derived fixtures. It must remain broker-agnostic until the Facebook-specific evidence gate passes.
37
+
38
+ ## Implementation rules
39
+
40
+ 1. Do not infer current endpoints, GraphQL document IDs, MQTT topics, packet fields, login forms, or event schemas from architecture articles.
41
+ 2. Historical open-source code is an observation, not a current protocol specification.
42
+ 3. A protocol feature is not marked implemented until its behavior is covered by deterministic fixtures and tests, then validated with an account the tester owns and explicitly authorizes.
43
+ 4. Authentication must stop and return a clear state when Facebook requests a checkpoint, 2FA, or other owner action. Do not automate challenge bypass.
44
+ 5. Never place passwords, cookies, AppState, 2FA seeds/codes, or session tokens in tests, fixtures, logs, commits, or issue reports.
45
+ 6. The official Meta Messenger Platform is Page-based and must not be represented as a personal-profile FCA replacement.
46
+
47
+ ## Current package boundary
48
+
49
+ The current package provides configuration parsing, AppState validation, bounded HTTPS session primitives, token extraction, a generic transport contract, connection supervision, and a GoatBot login adapter. Credentials mode currently delegates to an injected authentication provider. The legacy FCA adapter delegates to an externally supplied implementation.
50
+
51
+ Therefore the following remain **not implemented** in the native OmegA engine:
52
+
53
+ - Facebook username/email + password authentication and owner-controlled 2FA handoff.
54
+ - Native personal-account realtime transport and event decoding.
55
+ - Verified message/thread/action request catalog and payload schemas.
56
+ - Full callback/API parity with the target GoatBot FCA usage.
57
+ - Authorized live-account end-to-end verification.
58
+
59
+ ## Release gate
60
+
61
+ Do not describe this package as a standalone FCA replacement or switch GoatBot's production dependency until every item above is implemented and the following pass:
62
+
63
+ - Unit tests for login state transitions, cookie/session lifecycle, reconnect behavior, event decoding, and action serialization.
64
+ - Protocol fixtures sourced from repeatable, authorized observations with secrets removed.
65
+ - Node.js 20+ syntax and test suites.
66
+ - An authorized end-to-end test covering login (including manual challenge handoff where applicable), listener startup, inbound event parsing, outbound messaging, logout, and reconnect.
67
+ - GoatBot integration test proving the expected callback signatures and methods.
68
+
69
+ Last reviewed: 2026-11-19.
@@ -0,0 +1,33 @@
1
+ # Realtime frame evidence
2
+
3
+ ## What the Android capture establishes
4
+
5
+ The user-provided Messenger Web DevTools screenshots show a successful WebSocket handshake for the gateway.messenger.com /ws/realtime endpoint (HTTP 200) and binary frames in its Messages panel. A selected frame's hex/ASCII view visibly contains a JSON-like object with an events array and event objects containing name and args fields.
6
+
7
+ ## What it does not establish
8
+
9
+ The screenshots do not provide a complete, sanitized frame corpus, a reliable mapping of event names to semantics, the binary prefix/length encoding, subscription/acknowledgement rules, reconnect behavior, send-command format, authentication requirements, or message encryption/decryption. No raw frame payloads, cookies, authorization headers, or tokens have been committed.
10
+
11
+ ## Decoder scope
12
+
13
+ src/transport/realtimeFrameDecoder.js implements only the evidence-backed portion: bounded extraction of a JSON object containing an events array whose entries have string name fields. The binary prefix is intentionally opaque. summarizeRealtimeFrame returns event names and counts without payload values, suitable for safe diagnostics.
14
+
15
+ This is a frame-inspection primitive, not a working Messenger transport. It does not connect to Facebook, authenticate, subscribe, acknowledge frames, send messages, or decode E2EE content. Do not infer event semantics from names alone.
16
+
17
+
18
+ ## Additional owner-provided outgoing frame sample (2026-11-20)
19
+
20
+ A later DevTools capture supplied four outgoing binary frames and one one-byte incoming frame. The outgoing frame bodies contain a small binary prefix followed by an outer JSON envelope with an `app_id`, a JSON-encoded `payload` string, `request_id`, and `type`. The payload string itself contains synchronization metadata.
21
+
22
+ Observed payload fields across the supplied samples:
23
+
24
+ - One request used a `trq` queue name, label `145`, and a batch of task identifiers (approximately 172–187 in the inspected sample). This is evidence of a queue/task request shape only; task semantics are unknown.
25
+ - Three subsequent request envelopes carried `database` values `1`, `2`, and `16`, with request IDs `6`, `7`, and `8` respectively. They also carried `epoch_id`, `failure_count: null`, `last_applied_cursor`, `sync_params`, and `version` fields.
26
+ - The sample for database `2` and database `16` had `sync_params.locale = "en_GB"` and a null `last_applied_cursor`; the database `1` sample included a non-null cursor and null `sync_params`.
27
+ - The only supplied incoming frame was a single byte `0A`. With no surrounding exchange or schema, it cannot be assigned a reliable acknowledgement, error, or control meaning.
28
+
29
+ These observations add a synchronization-request shape to the evidence register, but they do **not** establish the binary prefix grammar, the meaning of database numbers, epoch/cursor lifecycle, task semantics, response correlation, acknowledgement rules, authentication, subscription setup, or action encoding. The sample is not sufficient to implement a working Facebook realtime client. Raw frames and cursor values are intentionally not stored in this repository.
30
+
31
+ ## Implementation consequence
32
+
33
+ Do not add a speculative decoder or claim a native socket is ready from this sample. The next protocol milestone requires a sanitized, paired request/response capture covering connection setup, sync response bodies, task completion/acknowledgement, event delivery, and a benign owner-triggered action, with sensitive identifiers and message contents removed. Keep the existing envelope inspector bounded and prefix-agnostic until the framing grammar is independently verified.
@@ -0,0 +1,63 @@
1
+ # OmegA-FCA Reference Audit
2
+
3
+ Reviewed on 2026-11-19. This is a design and risk audit, not a certification of either reference implementation.
4
+
5
+ ## VangBanLaNhat/fca-unofficial
6
+
7
+ Repository: https://github.com/VangBanLaNhat/fca-unofficial
8
+
9
+ Observed structure:
10
+ - A central login/bootstrap module builds the API and wires action modules.
11
+ - Action methods are separated by operation.
12
+ - Shared request/session helpers own cookie handling, request defaults, token extraction, and response parsing.
13
+ - Realtime MQTT is part of the runtime and is exposed through the legacy listen surface.
14
+
15
+ Important findings:
16
+ - The package metadata declares MIT, but the root LICENSE file could not be retrieved from the repository during this audit. Treat the declared license as unverified until the actual grant and notices are checked.
17
+ - The inspected package manifest still depends on legacy `request`, Bluebird, and old MQTT/websocket-era dependencies; it targets Node.js >=22.
18
+ - The inspected login module contains special-case checkpoint behavior (including an automated checkpoint path). OmegA-FCA will not adopt checkpoint bypass or automatic challenge handling.
19
+ - Cookie and HTML/token parsing are tightly coupled to Facebook page structure. OmegA should isolate these parsers, validate inputs, and return explicit unsupported/challenge outcomes rather than assuming page markup remains stable.
20
+ - Some retry behavior is response-status driven. OmegA must distinguish idempotent reads from non-idempotent sends before retrying.
21
+
22
+ Decision: use the module boundaries and API coverage as study material only. Do not add this package as a runtime dependency, and do not copy source until its license and required notices are verified.
23
+
24
+ ## dongp06/fca-unofficial
25
+
26
+ Repository: https://github.com/dongp06/fca-unofficial
27
+
28
+ Observed documentation describes:
29
+ - A legacy-compatible flat API and a namespaced client facade.
30
+ - Promise and callback login surfaces.
31
+ - A high-level event-driven bot/context layer.
32
+ - Explicit MQTT lifecycle, event types, and reconnect behavior.
33
+ - A TypeScript build/typecheck/test toolchain.
34
+
35
+ Important findings:
36
+ - GitHub marks the repository archived (read-only).
37
+ - The documented architecture is useful for API ergonomics and separation of concerns, but it is not a suitable active dependency.
38
+
39
+ Decision: use as a documentation and API-design reference only.
40
+
41
+ ## anbuinfosec/fca-unofficial
42
+
43
+ Repository: https://github.com/anbuinfosec/fca-unofficial
44
+
45
+ The README claims GoatBot-V2 compatibility and describes broad authentication, MQTT resilience, delivery fallback, and metrics features. These are claims in the repository documentation, not independently verified guarantees.
46
+
47
+ Decision: compare expected GoatBot API shapes against it, but do not inherit claims or code without source-level review and testing.
48
+
49
+ ## OmegA implementation choices
50
+
51
+ 1. Keep the existing OmegA security/session and connection foundations.
52
+ 2. Implement AppState/cookie session bootstrap before considering credential login.
53
+ 3. Keep challenge/checkpoint completion manual and account-owner controlled.
54
+ 4. Use a modern, maintained HTTP/WebSocket/MQTT dependency only after checking its current maintenance, license, and Node.js support.
55
+ 5. Keep MQTT frame decoding, event normalization, and event dispatch as separate modules.
56
+ 6. Use capability declarations and typed unsupported-method errors.
57
+ 7. Never automatically retry a non-idempotent send unless a verified idempotency mechanism exists.
58
+ 8. Keep all live-account integration tests opt-in and outside CI; CI uses synthetic fixtures only.
59
+ 9. Do not replace GoatBot's current FCA dependency until compatibility tests pass for the commands and event types it actually uses.
60
+
61
+ ## Evidence limits
62
+
63
+ This audit inspected repository metadata, README/API documentation, selected source modules, and the current OmegA-FCA public branch. It did not execute the reference packages, authenticate to Facebook, capture live protocol traffic, or verify that undocumented endpoints still work. No production readiness claim should be made from this review alone.
@@ -0,0 +1,39 @@
1
+ # Safe diagnostic reports
2
+
3
+ OmegA-FCA exports `createDiagnosticRecorder()` for collecting bounded request metadata while developing an authorized integration.
4
+
5
+ The recorder stores only:
6
+ - HTTP method, URL origin and path (query values are discarded)
7
+ - A filtered list of non-sensitive query parameter and request field names
8
+ - An allowlisted set of request header names (never header values)
9
+ - Request/response byte counts, response status/content type, duration and safe error codes
10
+
11
+ It never stores request body values, response bodies, cookie values, authorization values, passwords, AppState, tokens or 2FA codes. Events are capped (100 by default, 1,000 maximum).
12
+
13
+ ## Usage with the current AppState session layer
14
+
15
+ ```js
16
+ const { createPersonalSession, createDiagnosticRecorder } = require("@omega/fca");
17
+
18
+ const diagnostics = createDiagnosticRecorder({ maxEvents: 100 });
19
+ const session = await createPersonalSession({
20
+ appState: require("./appstate.json"),
21
+ onDiagnostic: event => diagnostics.record(event)
22
+ });
23
+
24
+ // Exercise only the authorized session operations you are debugging.
25
+ await session.request("https://www.facebook.com/");
26
+
27
+ require("node:fs").writeFileSync(
28
+ "./omega-fca-diagnostics.json",
29
+ diagnostics.toJSON(),
30
+ { mode: 0o600 }
31
+ );
32
+ session.close();
33
+ ```
34
+
35
+ Keep the report private until you have reviewed it. Although values are excluded, paths and field names can still reveal which features were used.
36
+
37
+ ## Important limitation
38
+
39
+ This hook currently instruments the AppState-backed personal-session bootstrap and requests. It does **not** capture a username/password login flow because native Facebook credential login is not implemented yet. It cannot manufacture the missing login trace or discover Facebook's private login protocol by itself. Do not paste cookies, AppState, passwords, tokens or 2FA codes into a report or chat.
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+
3
+ const { loadAccountConfig, createPersonalSession } = require("../index");
4
+
5
+ async function main() {
6
+ const account = loadAccountConfig();
7
+ if (account.mode !== "appstate") {
8
+ throw new Error("This test is AppState-only. Put an authorized cookie export in account.txt or appstate.json.");
9
+ }
10
+
11
+ let session;
12
+ try {
13
+ session = await createPersonalSession({ appState: account.appState });
14
+ console.log("OmegA-FCA AppState validation: SUCCESS");
15
+ console.log("Facebook user ID:", session.userId);
16
+ console.log("Session state:", session.state);
17
+ console.log("Validated at:", new Date(session.validatedAt).toISOString());
18
+ console.log("No cookie values or session tokens were printed.");
19
+ } catch (error) {
20
+ console.error("OmegA-FCA AppState validation: FAILED");
21
+ console.error("Code:", error.code || "FCA_SESSION_VALIDATION_FAILED");
22
+ console.error("State:", error.sessionState || "unknown");
23
+ console.error("Reason:", error.message);
24
+ process.exitCode = 1;
25
+ } finally {
26
+ if (session) session.close();
27
+ }
28
+ }
29
+
30
+ main().catch(error => {
31
+ console.error("AppState test could not start:", error.message);
32
+ process.exitCode = 1;
33
+ });