@openclaw/crabline 0.1.11 → 0.1.12

package/README.md

@@ -41,6 +41,11 @@ pnpm dev fixtures --config fixtures/examples/crabline.example.yaml
 pnpm dev roundtrip telegram-dm --config fixtures/examples/crabline.example.yaml
 ```
 
+The source checkout does not link its own `crabline` bin into
+`node_modules/.bin`, so use `pnpm dev` there rather than
+`pnpm exec crabline`. An installed package exposes the `crabline` command used
+in the examples below.
+
 ## Quality Gate
 
 ```bash
@@ -98,6 +103,10 @@ Telegram `secretToken`, and Zalo `webhookSecret` enforce provider-native
 webhook authentication. Feishu `verificationToken` remains an additional or
 loopback-only callback check. Microsoft Teams also requires `appId` for
 non-loopback or explicitly public webhook endpoints.
+Authenticated external webhook ingress must advertise an HTTPS `publicUrl`;
+plain HTTP is limited to loopback-local testing.
+Feishu text callbacks require valid JSON-encoded `message.content`; malformed
+content is rejected.
 
 ## Built-In Mock Channels
 
@@ -138,11 +147,54 @@ them only from sources you trust and review changes before use.
 preferred Smoke CI path because OpenClaw still uses its normal channel adapter,
 but the provider endpoint is local and deterministic.
 
+Commands in this section use the installed-package form. In a source checkout,
+replace `crabline` with `pnpm dev`.
+
+`serve` never accepts credential values in command-line arguments. Set
+`CRABLINE_ACCESS_TOKEN`, `CRABLINE_ADMIN_TOKEN`, `CRABLINE_BOT_TOKEN`, or
+`CRABLINE_SIGNING_SECRET`, or pass a bounded JSON object through a file
+descriptor. Package runners should use stdin:
+
+```bash
+pnpm dev --json serve slack --credentials-fd 0 < .crabline/serve-credentials.json
+```
+
+The installed CLI can also use an inherited descriptor when its launcher
+preserves descriptors above 2:
+
+```bash
+crabline --json serve slack --credentials-fd 3 3< .crabline/serve-credentials.json
+```
+
+The JSON fields are `accessToken`, `adminToken`, `botToken`, and
+`signingSecret`. File-descriptor values override environment fallbacks. Do not
+pass descriptors above 2 through package runners such as `pnpm`; use fd 0
+instead. Keep credential files owner-readable or pipe the JSON directly from a
+secret manager.
+
+Ready files contain generated provider and admin credentials. Crabline creates
+or replaces them with POSIX mode `0600`, but the parent directory still needs
+to be private. Exclude ready files from version control and CI artifact
+collection, and delete them after use. On non-POSIX or shared filesystems,
+verify the effective ACLs before publishing one.
+
 Library callers can pass `onEvent` to `startCrablineServer`, an individual
 provider server, or `startOpenClawCrablineAdapter`. Crabline awaits the callback
 after appending each API/admin event to `recorderPath`, so callers can react in
 process while retaining the JSONL artifact as durable evidence.
 
+Recorder files should normally have one filesystem name. If multiple processes
+cannot share the same OS account home, the home is read-only, or they write
+through hardlinks to the same recorder inode, set
+`CRABLINE_RECORDER_LOCK_DIR` to the same absolute writable directory for every
+writer. Pre-create that directory with the ownership, group, or ACLs required
+by those writers. Crabline refuses hardlinked server-recorder writes without
+this shared lock namespace. The configured path must be canonical and contain
+no symlink components. Scope each lock directory to one recorder filesystem;
+lock identities omit device numbers so containers that mount the same inode
+under different device IDs still coordinate. Otherwise, Unix writers coordinate
+through the OS account's `~/.cache/crabline/locks/server-recorder` namespace.
+
 Mattermost:
 
 ```bash
@@ -153,6 +205,7 @@ The JSON manifest contains:
 
 - `baseUrl`: OpenClaw `channels.mattermost.baseUrl` / `MATTERMOST_URL`
 - `botToken`: OpenClaw `channels.mattermost.botToken` / `MATTERMOST_BOT_TOKEN`
+- `webhookToken` / `MATTERMOST_TOKEN`: verifies native outgoing webhook posts
 - `endpoints.websocketUrl`: native Mattermost WebSocket endpoint
 - `adminToken`: send this as the `X-Crabline-Admin-Token` header when posting
   test user messages
@@ -163,7 +216,10 @@ The server implements a Mattermost API subset for text DM and channel
 roundtrips, including REST authentication/status codes, WebSocket
 authentication and `hello`, sequenced events, typing, and post
 create/edit/delete events. Admin ingress is only the test control plane;
-injected messages are delivered to clients as native `posted` events.
+injected messages require native 26-character lowercase channel/user IDs and
+are delivered to clients as channel-scoped native `posted` events. Optional
+`channelName` and `channelDisplayName` values populate the native event fields.
+`POST /api/v4/posts` requires a JSON media type.
 
 Matrix:
 
@@ -187,7 +243,9 @@ The server implements an unencrypted Matrix Client-Server API subset including
 `whoami`, filters, push rules, joined rooms and members, room state, `/sync`,
 room event sends, typing, and read receipts. Admin ingress is only the test
 control plane; injected messages are delivered to clients as native
-`m.room.message` events through `/sync`.
+`m.room.message` events through `/sync`. Optional `roomName` sets newly created
+room state, `direct: true` publishes `m.direct` account data, and `threadId`
+accepts the raw Matrix root event ID used in the native thread relation.
 
 Slack:
 
@@ -208,8 +266,8 @@ The JSON manifest contains:
 - `endpoints.eventsUrl`: local Slack Events API endpoint
 - `recorderPath`: JSONL file of local provider API/admin traffic
 
-The admin token is generated randomly unless `--admin-token <token>` is
-provided. Implemented Slack Web API endpoints include `auth.test`,
+The admin token is generated randomly unless `adminToken` is supplied through
+the credential ingress above. Implemented Slack Web API endpoints include `auth.test`,
 `chat.postMessage`, `conversations.open`, `conversations.info`,
 `conversations.history`, and `conversations.replies`.
 
@@ -251,16 +309,19 @@ The JSON manifest contains:
   messages; OpenClaw reads them through Telegram `getUpdates`
 - `recorderPath`: JSONL file of local provider API/admin traffic
 
-The admin token is generated randomly unless `--admin-token <token>` is
-provided. The inbound endpoint rejects requests without the matching admin
-header (or `Authorization: Bearer <token>`).
+The admin token is generated randomly unless `adminToken` is supplied through
+the credential ingress above. The inbound endpoint rejects requests without
+the matching admin header (or `Authorization: Bearer <token>`).
 
 Implemented Telegram Bot API endpoints include `getMe`, `sendMessage`,
 `sendPhoto`, `sendDocument`, `sendVideo`, `sendAudio`, `sendAnimation`, `editMessageText`,
 `deleteMessage`, `setMessageReaction`, `createForumTopic`, `editForumTopic`,
 `pinChatMessage`, `unpinChatMessage`, `getUpdates`, `deleteWebhook`,
 `setWebhook`, `setMyCommands`, `deleteMyCommands`, `sendChatAction`, and
-`answerCallbackQuery`.
+`answerCallbackQuery`. Webhook secrets use Telegram's 1-256 character
+letter/digit/underscore/hyphen alphabet. Text and caption fields enforce native
+string types and 4,096/1,024 UTF-16 limits, entity metadata is retained, and
+`@username` method targets resolve to numeric `Chat.id` values.
 
 WhatsApp:
 
@@ -301,7 +362,8 @@ Group outbound uses sender-key `skmsg` encryption and is outside this supported
 subset, so OpenClaw Crabline outbound targets are direct users only. Group
 inbound injection remains supported. The WebSocket endpoint rejects clients
 that do not present the access token embedded in the manifest URL. The admin
-token is generated randomly unless `--admin-token <token>` is provided.
+token is generated randomly unless `adminToken` is supplied through the
+credential ingress above.
 
 OpenClaw bridge callers should post injected user messages with the
 `providerUrl`, `providerHeaders`, and `providerBody` returned by
@@ -331,7 +393,9 @@ API methods accept GET query parameters or POST requests. Admin
 ingress injects a native Zalo update into the active polling or webhook
 transport. Webhook delivery posts the native `{ event_name, message }` update
 directly. OpenClaw-specific endpoint, config, and target mapping remain in the
-isolated bridge.
+isolated bridge. Programmatic `startZaloServer()` callers can tune the retained
+polling queue with `maxPendingInboundEvents` and `maxPendingInboundBytes`; the
+byte limit defaults to 64 MiB.
 
 The admin ingress accepts JSON like:
 
@@ -367,13 +431,34 @@ target:
 Examples:
 
 - Slack conversations: `C1234567890`, `G1234567890`, or `D1234567890`
+- Slack direct sends may also target user IDs such as `U1234567890` or
+  `W1234567890`
 - Slack threads: `1700000000.000100`
 - Telegram chats: `-1001234567890` or `@channelusername`
 - Telegram topics: `42`
-- WhatsApp Cloud API users: digits-only `wa_id` values such as `15551234567`
-- WhatsApp groups: `120363001234567890@g.us`
+- Telegram username targets require `@`, contain 5-32 letters, digits, or
+  underscores, and normalize to lowercase. Numeric chat IDs must be nonzero and
+  have an absolute value no greater than `2^52 - 1`.
+- Built-in WhatsApp Cloud API users: digits-only `wa_id` values such as
+  `15551234567`
+- Built-in WhatsApp Cloud API fixtures do not support `threadId` targets.
+- OpenClaw WhatsApp bridge users: `15551234567@s.whatsapp.net`
+  (legacy `15551234567@c.us` inputs are accepted and canonicalized)
+- OpenClaw WhatsApp bridge groups: `120363001234567890@g.us`
 - Discord channels and threads: Discord snowflake ids such as
   `123456789012345678`
+- iMessage recipients: E.164 phone numbers such as `+15551234567`, email
+  addresses such as `user@example.com`, or chat GUIDs such as
+  `iMessage;-;chat-guid` and `SMS;+;chat-guid`
+- Matrix rooms: scoped IDs such as `!abcdef:matrix.org` or Matrix v12
+  domainless room IDs; thread IDs are raw root event IDs such as
+  `$eventid:matrix.org`
+- Mattermost channels, users, and root posts: exactly 26 lowercase alphanumeric
+  characters, such as `abcdefghijklmnopqrstuvwx12`
+- Microsoft Teams: non-empty opaque Bot Connector `conversation.id` values such
+  as `a:opaque-conversation-id` or `19:conversation@thread.v2`
+- Zalo users, OAs, and chats: non-whitespace provider IDs such as `user-1` or
+  `group-1`
 
 ## Webhooks
 
@@ -403,6 +488,8 @@ Nested message payloads are also accepted:
 ```
 
 Malformed webhooks return `400`, and non-JSON requests return `415`.
+Configured webhook paths must be canonical URL pathnames without normalization,
+query, or fragment ambiguity.
 
 ## Evidence Flow
 

package/dist/src/bin/crabline.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { runCli } from "../cli/program.js";
-const exitCode = await runCli(process.argv);
+const exitCode = await runCli(process.argv, {
+    forceExit: (code) => process.exit(code),
+});
 if (exitCode !== 0) {
     process.exitCode = exitCode;
 }

package/dist/src/bin/crabline.js.map

@@ -1 +1 @@
-{"version":3,"file":"crabline.js","sourceRoot":"","sources":["../../../src/bin/crabline.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC5C,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { runCli } from \"../cli/program.js\";\n\nconst exitCode = await runCli(process.argv);\nif (exitCode !== 0) {\n  process.exitCode = exitCode;\n}\n"]}
+{"version":3,"file":"crabline.js","sourceRoot":"","sources":["../../../src/bin/crabline.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;IAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;CACxC,CAAC,CAAC;AACH,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { runCli } from \"../cli/program.js\";\n\nconst exitCode = await runCli(process.argv, {\n  forceExit: (code) => process.exit(code),\n});\nif (exitCode !== 0) {\n  process.exitCode = exitCode;\n}\n"]}

package/dist/src/cli/program.d.ts

@@ -16,6 +16,10 @@ type ProgramDependencies = {
     removeReadyFile?: (filePath: string, expectedContents: string, expectedIdentity: ReadyFileIdentity) => Promise<void>;
     startServer?: (params: StartCrablineServerParams) => Promise<StartedCrablineServer>;
 };
+type RunCliOptions = {
+    dependencies?: ProgramDependencies;
+    forceExit?: (code: number) => never;
+};
 export declare function createProgram(setExitCode?: SetExitCode, dependencies?: ProgramDependencies): Command;
 type ShutdownSignal = "SIGINT" | "SIGTERM";
 type SignalTarget = {
@@ -25,5 +29,5 @@ type SignalTarget = {
 export declare function publishReadyFile(filePath: string, contents: string): Promise<ReadyFileIdentity>;
 export declare function removeReadyFile(filePath: string, expectedContents: string, expectedIdentity: ReadyFileIdentity): Promise<void>;
 export declare function waitForShutdown(close: () => Promise<void>, signalTarget?: SignalTarget): Promise<void>;
-export declare function runCli(argv: string[]): Promise<number>;
+export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;
 export {};