clawgram 2.21.1 → 2.23.0

package/README.md

@@ -18,9 +18,9 @@ Clawgram is a personal-Telegram channel plugin for [OpenClaw](https://github.com
 > it can read private and group conversations within its configured scope and send messages that are
 > indistinguishable from ones you typed yourself. Recipients cannot tell an assistant reply from a
 > human one. Treat the account as compromised-if-leaked: `apiHash` and `sessionString` are bearer
-> credentials for everything that account can reach. Scope reads with `readChats`, gate senders with
-> `allowFrom`, and prefer a dedicated account over your primary one — see
-> [Security and privacy](#security-and-privacy).
+> credentials for everything that account can reach. Scope reads with `readChats`, scope sends with
+> `sendChats`, gate senders with `allowFrom`, and prefer a dedicated account over your primary one —
+> see [Security and privacy](#security-and-privacy).
 
 
 ## Features
@@ -184,6 +184,13 @@ openclaw gateway restart
 openclaw gateway restart
 ```
 
+**What `--auth` writes is closed, on purpose.** The first config allows only the
+account that authorised (`allowFrom: [<your id>]`), seeds no group entry, and
+writes `readChats: []`. Until 2.21.1 it seeded `allowFrom: ["*"]` with an
+enabled wildcard group, so a freshly authorised account answered any Telegram
+user and read the history of every chat it belonged to. Widen both lists
+deliberately; the flow prints who can reach the agent before it exits.
+
 One restart after installation is enough. From 2.17.0 the plugin declares
 `channels.clawgram` as a hot-reloadable prefix, so later edits under it —
 `allowFrom`, `groups`, `readChats`, proxy — are picked up by the Gateway's
@@ -249,6 +256,7 @@ loud where it does occur.
 | `apiHash` | string | required | Telegram API hash |
 | `sessionString` | string | `""` | Authenticated StringSession |
 | `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames for direct messages only. Three states: absent means everyone, `[]` denies everyone (a warning is logged at account start), a list allows those senders |
+| `operatorIds` | string[] | — | Who receives core's operational telemetry in a DM (tool-failure warnings, fallback notices). They quote shell commands and secret-store paths, so they go only to these ids. Absent falls back to `allowFrom` when it is a concrete list; a wildcard or an empty list means no operator is identified and the notices are dropped everywhere — they stay in the run diagnostics and the gateway log |
 | `groups` | object | `{}` | Allowed groups map keyed by explicit group id or `*` |
 | `proxy` | object | unset | Optional SOCKS4/SOCKS5 proxy for this account — see [Proxy (SOCKS4/SOCKS5)](#proxy-socks4socks5) |
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
@@ -809,10 +817,27 @@ nothing is not an error — it says which nothing it was:
 A reading that fails while the download succeeded still returns `ok: true`, with `readError` beside
 the path: the bytes are already there and can still be forwarded.
 
-**Fetched files live in the system temp directory** (`clawgram-fetched/`), named after the chat and
-message they came from, and are pruned after 24 hours by the next fetch. Nothing else removes them,
-and nothing sends them anywhere — putting a fetched file in a chat is an ordinary `upload-file`,
-with whatever confirmation the deployment requires for that.
+**Fetched files live under the OpenClaw state directory** (`$OPENCLAW_STATE_DIR/tmp/clawgram-fetched/`,
+falling back to the system temp directory when that variable is unset), named after the chat and
+message they came from, and are pruned an hour later by the next fetch. The directory is created
+0700 and each file written 0600: these are private-chat images and voice notes, and until 2.21.1
+they sat in a shared `/tmp` at 0644 for a day, readable by every local account on the host. Nothing
+else removes them, and nothing sends them anywhere — putting a fetched file in a chat is an ordinary
+`upload-file`, with whatever confirmation the deployment requires for that.
+
+## Dependencies are pinned, and the lock ships
+
+`installDependencies: true` tells OpenClaw to run an install in the plugin
+directory, so what lands on the host is whatever the registry serves that day —
+and the MTProto client sees `apiHash`, `sessionString`, the proxy credentials
+and every message. Since 2.21.1 the two runtime dependencies are pinned to
+exact versions and `npm-shrinkwrap.json` is part of the published tarball, so an
+install reproduces the tree the tests ran against rather than resolving a caret
+range. `npm ci --ignore-scripts` verifies it.
+
+The transitive `ip-address` is held at 10.7.0 through `overrides`: everything at
+or below 10.3.0 carries three advisories about SSRF and trust-boundary bypass,
+and it sits under the SOCKS proxy path this channel uses.
 
 ## Security and privacy
 
@@ -825,9 +850,10 @@ that means in practice, and what the code does about it:
 | Proxy password | `accounts.*.proxy.password`, or a secret store | Also accepts a SecretRef since 2.2.0. Marked `sensitive` in `uiHints`; diagnostics say `socks4`/`socks5` and nothing more. An invalid proxy fails the account rather than falling back to a direct connection, which would leak the host IP to Telegram |
 | Message bodies | channel logs | **Not logged.** Outbound sends record recipient, ids and `textLength`. Until 2.1.0 the full outbound text was written to the channel log — if you ran 2.0.x, treat those journal entries as containing private correspondence |
 | Read scope | `accounts.*.readChats` | History, membership and attachment fetches are confined to the listed chats. Absent means no restriction; an empty array denies everything. Telegram's own service chat (`777000`, where login codes arrive) is refused unconditionally, including under a wildcard |
+| Send scope | `accounts.*.sendChats` | `send`, `upload-file`, `react` and core's delivery path are confined to the listed chats. Same shape as `readChats`: absent means no restriction, `[]` denies everything, `["*"]` allows every chat. **A phone number is refused whatever the list says** — messaging a raw number starts a conversation with someone who never contacted the account. Without the list, an injected turn can write to strangers from the owner's account or move a work chat's content into a DM one send at a time (2.22.0) |
 | Manage scope | `accounts.*.manageChats` | Creating groups, changing membership, admin rights, ownership and invite links are confined to the listed chats — and **off entirely** when the key is absent or empty (opposite default to `readChats`, because these actions change chats rather than read them) |
 | 2FA password | `accounts.*.twoFaPassword`, or a secret store | Read only by `transferOwnership`, exchanged for an SRP proof in-process. Accepts a SecretRef since 2.12.0; `sensitive` in `uiHints`; on the forbidden-log-keys list the static tests enforce |
-| Who may talk to it | `allowFrom`, `groups.*.groupPolicy` | Direct-message senders and group behaviour are allowlisted; `mention` limits group replies to explicit mentions |
+| Who may talk to it | `allowFrom`, `groups.*.groupPolicy` | Direct-message senders and group behaviour are allowlisted; `mention` limits group replies to explicit mentions. **Write ids, not handles:** an `@username` entry is a claim about a handle, and a released handle can be taken by someone else, after which the entry admits a stranger. The account logs a warning at start-up for every handle entry (2.22.0) |
 
 Two static tests (`test/no-secret-logging.test.ts`) fail the build if a message body or a credential
 is ever added back to a log call, or if the auth flow prints the session string unprompted.

package/dist/actions.js

@@ -0,0 +1,124 @@
+"use strict";
+// Имена действий: что принимается и во что разрешается.
+//
+// Вынесено из channel.ts, который был единственным файлом на 3274 строки при
+// следующем по величине 1165 (находка A6-11). Здесь нет ни рантайма, ни
+// конфига — только словарь, поэтому читать и править его можно, не открывая
+// диспетчер.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANAGE_ACTIONS = exports.CORE_ACTION_SYNONYMS = void 0;
+exports.canonicalAction = canonicalAction;
+/**
+ * Every accepted spelling of an action, mapped to its canonical name.
+ *
+ * One table, not three. The synonyms used to live in
+ * `CORE_ACTION_SYNONYMS`, again in `MANAGE_ACTION_ALIASES`, and a third time
+ * as `action === "…" || …` chains inside the dispatcher — and the dispatcher
+ * read only the chains. A name could therefore be added to a table and to the
+ * advertised list and still reach nothing, with the suite none the wiser:
+ * it only ever dispatched the native spellings (finding A6-10).
+ *
+ * `canonicalAction` is now the only place a name is resolved, and
+ * `CORE_ACTION_SYNONYMS` below is derived from this table rather than kept
+ * beside it.
+ */
+const ACTION_ALIASES = {
+    send: "send",
+    read: "read",
+    // `list` is accepted so a caller that guessed the other obvious name is not
+    // silently refused.
+    list: "read",
+    react: "react",
+    joins: "joins",
+    "upload-file": "upload-file",
+    sendAttachment: "upload-file",
+    "fetch-media": "fetch-media",
+    fetchMedia: "fetch-media",
+    "download-media": "fetch-media",
+    downloadMedia: "fetch-media",
+    getMedia: "fetch-media",
+    "download-file": "fetch-media",
+    participants: "participants",
+    members: "participants",
+    "member-info": "participants",
+    topics: "topics",
+    forumTopics: "topics",
+    "thread-list": "topics",
+    dialogs: "dialogs",
+    chats: "dialogs",
+    "channel-list": "dialogs",
+    chatInfo: "chatInfo",
+    getChatInfo: "chatInfo",
+    "channel-info": "chatInfo",
+    chatMetadata: "chatInfo",
+    getChatMetadata: "chatInfo",
+    // Chat management. `kick` was already accepted; the rest were advertised
+    // under names core does not know and were therefore never callable from the
+    // tool at all — 2.19.4 gives them core's nearest name. `transferOwnership`
+    // and `inviteLink` have no counterpart in that vocabulary and stay
+    // gateway-only, as does `joins`.
+    createGroup: "createGroup",
+    createChat: "createGroup",
+    "create-group": "createGroup",
+    "channel-create": "createGroup",
+    addMembers: "addMembers",
+    addMember: "addMembers",
+    "add-members": "addMembers",
+    addParticipant: "addMembers",
+    removeMember: "removeMember",
+    removeMembers: "removeMember",
+    "remove-member": "removeMember",
+    kick: "removeMember",
+    promoteAdmin: "promoteAdmin",
+    promote: "promoteAdmin",
+    "promote-admin": "promoteAdmin",
+    setAdmin: "promoteAdmin",
+    "role-add": "promoteAdmin",
+    demoteAdmin: "demoteAdmin",
+    demote: "demoteAdmin",
+    "demote-admin": "demoteAdmin",
+    "role-remove": "demoteAdmin",
+    transferOwnership: "transferOwnership",
+    transferOwner: "transferOwnership",
+    "transfer-ownership": "transferOwnership",
+    inviteLink: "inviteLink",
+    exportInviteLink: "inviteLink",
+    "invite-link": "inviteLink",
+};
+/** The canonical action for a spelling; an unknown name stays itself. */
+function canonicalAction(action) {
+    return ACTION_ALIASES[action] ?? action;
+}
+/**
+ * Core's own name for a clawgram action, and the only thing that makes the
+ * action reachable from the agent's `message` tool.
+ *
+ * Core keys its target policy by `CHANNEL_MESSAGE_ACTION_NAMES`, and an action
+ * outside that vocabulary is simultaneously "requires a target" and "does not
+ * accept a target" — there is no call that satisfies both. Declaring `chatId`
+ * through `messageActionTargetAliases` looks like the fix and is not: core
+ * resolves the channel with `getBootstrapChannelPlugin`, which only knows
+ * bundled channels, so a plugin channel's declaration is never read. Measured
+ * on 2026-08-30 — `thread-list` reached `handleAction` and `topics` did not,
+ * from the same caller, on the same chat.
+ *
+ * Every name on the right maps to core target mode `"none"` except
+ * `channel-info`, which is `"channelId"`: the chat arrives in
+ * `params.channelId`, a spelling no parser here read until 2.21.0 — so the
+ * call fell through to the current chat and answered about the wrong one.
+ * `readChatTargetParam` is the single list of accepted spellings now.
+ *
+ * These spellings are derived from `ACTION_ALIASES` rather than kept beside
+ * it; that core actually knows each of them is asserted against the installed
+ * core in `core-action-synonyms.test.ts`.
+ */
+const CORE_VOCABULARY_SPELLINGS = [
+    "thread-list", "channel-list", "channel-info", "member-info", "download-file",
+    "channel-create", "addParticipant", "kick", "role-add", "role-remove",
+];
+exports.CORE_ACTION_SYNONYMS = Object.fromEntries(CORE_VOCABULARY_SPELLINGS.map((name) => [name, ACTION_ALIASES[name]]));
+/** Canonical actions that go through the chat-management gate. */
+exports.MANAGE_ACTIONS = new Set([
+    "createGroup", "addMembers", "removeMember",
+    "promoteAdmin", "demoteAdmin", "transferOwnership", "inviteLink",
+]);

package/dist/attachments.js

@@ -0,0 +1,142 @@
+"use strict";
+// Входящее вложение: скачать, понять, отдать текстом.
+//
+// Вынесено из channel.ts — файла на 3145 строк при следующем по величине
+// 1165 (находка A6-11). Ни диспетчера, ни конфигурации канала здесь нет:
+// только путь «файл → текст», общий у входящего контура и у `fetch-media`.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INBOUND_MEDIA_MAX_BYTES = void 0;
+exports.understandAttachmentFile = understandAttachmentFile;
+exports.readInboundAttachment = readInboundAttachment;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const media_1 = require("./media");
+const state_dir_1 = require("./state-dir");
+/** Attachments above this are left unread: a long recording or a huge image is
+ *  a different conversation from a spoken line or a screenshot, and the
+ *  transfer is not free. */
+exports.INBOUND_MEDIA_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * Locates the agent directory that image understanding needs.
+ *
+ * Image models are called with the agent's own credentials, so the pipeline
+ * refuses to run without this path — audio does not need it, which is why
+ * voice notes worked before images did. The platform exposes no resolver to
+ * plugins, so the documented layout is reconstructed here and checked before
+ * use: a wrong guess would fail the read anyway, and returning undefined lets
+ * the caller degrade instead of throwing.
+ */
+function resolveAgentDirForMedia(cfg) {
+    const stateDir = (0, state_dir_1.resolveStateDir)();
+    const configuredId = cfg?.agents?.defaults?.id;
+    const agentId = typeof configuredId === "string" && configuredId.trim() ? configuredId.trim() : "main";
+    const dir = node_path_1.default.join(stateDir, "agents", agentId, "agent");
+    return (0, node_fs_1.existsSync)(dir) ? dir : undefined;
+}
+/**
+ * Turns a downloaded attachment into text.
+ *
+ * Shared by the inbound path and by `fetch-media`: the backend choice lives in
+ * `runtime.mediaUnderstanding`, and both callers have to make exactly the same
+ * call — an image read on arrival and the same image read on request must not
+ * become two different readings because two call sites drifted.
+ */
+async function understandAttachmentFile(params) {
+    const media = params.runtime?.mediaUnderstanding;
+    if (!media)
+        return undefined;
+    const result = params.understanding === "transcript"
+        ? await media.transcribeAudioFile({
+            filePath: params.filePath,
+            cfg: params.cfg,
+            mime: params.mimeType,
+        })
+        : await media.describeImageFile({
+            filePath: params.filePath,
+            cfg: params.cfg,
+            mime: params.mimeType,
+            agentDir: resolveAgentDirForMedia(params.cfg),
+        });
+    const text = typeof result?.text === "string" ? result.text.trim() : "";
+    return text || undefined;
+}
+async function readInboundAttachment(params) {
+    const media = params.runtime?.mediaUnderstanding;
+    const message = params.event?.message;
+    if (!media || !message) {
+        return undefined;
+    }
+    let downloaded;
+    try {
+        downloaded = await (0, media_1.downloadInboundMediaToTempFile)({
+            client: params.gram.getClient(),
+            message,
+            maxBytes: exports.INBOUND_MEDIA_MAX_BYTES,
+            tmpDir: node_os_1.default.tmpdir(),
+        });
+    }
+    catch (err) {
+        params.log?.info?.("clawgram attachment download failed", {
+            accountId: params.accountId,
+            chatId: params.chatId,
+            messageId: params.messageId,
+            error: String(err),
+        });
+        return undefined;
+    }
+    if (!downloaded) {
+        return undefined;
+    }
+    try {
+        const read = await understandAttachmentFile({
+            runtime: params.runtime,
+            cfg: params.cfg,
+            filePath: downloaded.path,
+            mimeType: downloaded.mimeType,
+            understanding: downloaded.understanding,
+        });
+        if (!read) {
+            params.log?.info?.("clawgram attachment read empty", {
+                accountId: params.accountId,
+                chatId: params.chatId,
+                messageId: params.messageId,
+                understanding: downloaded.understanding,
+            });
+            return undefined;
+        }
+        params.log?.info?.("clawgram attachment read", {
+            accountId: params.accountId,
+            chatId: params.chatId,
+            messageId: params.messageId,
+            understanding: downloaded.understanding,
+            characters: read.length,
+        });
+        return { text: read, understanding: downloaded.understanding };
+    }
+    catch (err) {
+        params.log?.info?.("clawgram attachment read failed", {
+            accountId: params.accountId,
+            chatId: params.chatId,
+            messageId: params.messageId,
+            understanding: downloaded.understanding,
+            error: String(err),
+        });
+        return undefined;
+    }
+    finally {
+        void (async () => {
+            try {
+                const { rm } = await import("node:fs/promises");
+                const { dirname } = await import("node:path");
+                await rm(dirname(downloaded.path), { recursive: true, force: true });
+            }
+            catch {
+                // Leaving a temp file behind is not worth failing a delivered message.
+            }
+        })();
+    }
+}