clawgram 2.21.0 → 2.22.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.