@foxden-app/foxclaw 0.4.13 → 0.4.14

package/dist/telegram/gateway.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import crypto from 'node:crypto';
-import { callTelegramApi, downloadTelegramFile, getTelegramFile } from './api.js';
+import { callTelegramApi, callTelegramMultipartApi, downloadTelegramFile, getTelegramFile } from './api.js';
 import { getTelegramCommands } from '../i18n.js';
 import { toTelegramBridgeScopeId } from '../core/bridge_scope.js';
 import { createTelegramScopeId } from './scope.js';
@@ -56,6 +56,21 @@ export class TelegramGateway extends EventEmitter {
     async sendHtmlMessage(chatId, text, inlineKeyboard, messageThreadId) {
         return this.sendMessageWithOptions(chatId, text, inlineKeyboard, 'HTML', messageThreadId);
     }
+    async sendDocument(chatId, filename, contents, caption) {
+        const result = await callTelegramMultipartApi(this.botToken, 'sendDocument', {
+            chat_id: chatId,
+            ...(caption ? { caption } : {}),
+        }, [{
+                fieldName: 'document',
+                filename,
+                contents,
+                contentType: 'application/json',
+            }]);
+        if (!result.ok || !result.result) {
+            throw new Error(result.description || 'Failed to send Telegram document');
+        }
+        return result.result.message_id;
+    }
     async sendMessageDraft(chatId, draftId, text, messageThreadId) {
         const result = await callTelegramApi(this.botToken, 'sendMessageDraft', {
             chat_id: chatId,
@@ -197,8 +212,24 @@ export class TelegramGateway extends EventEmitter {
     }
     async handleUpdate(update) {
         if (update.message && update.message.from && this.isAllowedChat(update.message.chat)) {
-            if (String(update.message.from.id) !== this.allowedUserId)
+            if (String(update.message.from.id) !== this.allowedUserId) {
+                if (update.message.chat.type === 'private') {
+                    const text = update.message.text ?? update.message.caption ?? '';
+                    const attachments = extractAttachments(update.message);
+                    const document = attachments.find((attachment) => attachment.kind === 'document');
+                    if (document) {
+                        this.emit('peerDocument', {
+                            chatId: String(update.message.chat.id),
+                            userId: String(update.message.from.id),
+                            username: update.message.from.username ?? null,
+                            text,
+                            messageId: update.message.message_id,
+                            attachment: document,
+                        });
+                    }
+                }
                 return;
+            }
             const attachments = extractAttachments(update.message);
             const text = update.message.text ?? update.message.caption ?? '';
             const topicId = update.message.message_thread_id ?? null;

package/dist/types.d.ts

@@ -360,6 +360,20 @@ export interface RuntimeStatus {
         sourceLabel: string;
         syncedAt: string;
     } | null;
+    authSync?: {
+        enabled: boolean;
+        nodeId: string | null;
+        peers: string[];
+        pendingImports: number;
+        lastSentAt: string | null;
+        lastReceivedAt: string | null;
+        lastImportedAt: string | null;
+        lastImportCandidate: string | null;
+        lastPullAt: string | null;
+        lastPullCandidate: string | null;
+        lastError: string | null;
+        activeLeaseId: string | null;
+    } | null;
     lastUpdate?: {
         state: string;
         fromVersion: string;

package/docs/user-manual.md

@@ -417,6 +417,41 @@ The right-side `✅` / `⏸️` button controls whether the candidate participat
 
 OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token replay grace period. Codex refreshes automatically when an access token approaches expiry; when it cannot parse the access-token `exp`, current Codex uses a `last_refresh` fallback of about 8 days. The panel labels candidates without a refresh record in that interval as `not recently refreshed`, but this is only a maintenance hint. It does not prove expiry and does not trigger bulk keepalive refreshes. Do not use `/auth refresh all` as a routine keepalive command.
 
+### 6.4 Cross-Node Auth Sync
+
+Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. Enable Bot-to-Bot Communication Mode for the participating bots in BotFather first.
+
+Example:
+
+```dotenv
+AUTH_SYNC_ENABLED=true
+AUTH_SYNC_KEY=<shared key with at least 32 bytes>
+AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot
+AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
+# Optional; FoxClaw generates and persists a local node id when omitted.
+AUTH_SYNC_NODE_ID=workstation-a
+```
+
+Safety boundaries:
+
+- Telegram only carries ciphertext. Auth contents, candidate names, account ids, and `last_refresh` live inside the AES-256-GCM encrypted payload.
+- FoxClaw only accepts sync files from bots listed in `AUTH_SYNC_PEERS`; wrong key, cluster, nonce, or payload validation never writes files.
+- Remote imports wait for global local idleness, temporarily switch to the candidate for app-server usage validation, and only then write the candidate.
+- A same-name candidate known to belong to a different account id is never overwritten.
+- Cross-node recovery only pulls an already-held valid peer copy. It does not automatically rotate refresh tokens; if no peer has a usable copy, it stops and asks you to maintain auth on one node manually.
+
+Dual-active behavior:
+
+- Push: after local login, Codex automatic refresh, or `/auth refresh all` succeeds and passes local mirror validation, the newer candidate is encrypted and pushed to peers.
+- Pull: before auth switch or reload, FoxClaw first searches local runtimes for a newer same-account candidate; if none is found, it asks peers for a newer same-name same-account copy.
+- Lease: `/auth refresh all confirm` requests a cross-node refresh lease before rotating tokens. Any busy, denying, or non-responsive peer blocks the refresh.
+
+Commands:
+
+- `/auth sync status`: show node id, peers, recent sends/receives/imports, pending imports, and the latest error.
+- `/auth sync test`: send an encrypted ping to verify peer config, shared key, and Bot-to-Bot private messages.
+- `/auth sync push all`: manually broadcast all locally verified candidates without refreshing tokens.
+
 Equivalent commands:
 
 - `/auth` or `/auth list [keyword]`: show candidates, optionally filtered by filename.
@@ -428,6 +463,7 @@ Equivalent commands:
 - `/auth reload` or `/auth_reload`: restart app-server and reload the current `auth.json`.
 - `/auth refresh all`: show the refresh-token rotation risk confirmation.
 - `/auth refresh all confirm`: run Refresh all after accepting the token-rotation risk.
+- `/auth sync status|test|push all`: inspect, test, or manually push cross-node auth sync.
 
 If the requesting bot runtime has active turns, pending approvals, pending user inputs, or MCP elicitations, FoxClaw refuses manual auth switching to avoid changing accounts mid-request; another idle bot is unaffected.
 

package/docs/zh/user-manual.md

@@ -417,6 +417,41 @@ Candidates: 2
 
 OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放宽限期。Codex 会在 access token 临近到期时自动刷新；如果 access token 里无法解析 `exp`，Codex 当前使用 `last_refresh` 超过约 8 天作为兜底刷新条件。面板把超过 8 天没有刷新记录的候选标为“长期未刷新”，但这只是维护提醒，不代表 refresh token 已经过期，也不会触发批量保活刷新。不要把 `/auth refresh all` 当作日常保活命令。
 
+### 6.4 跨节点 auth 同步
+
+跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP；需要先在 BotFather 为参与同步的 bot 开启 Bot-to-Bot Communication Mode。
+
+配置示例：
+
+```dotenv
+AUTH_SYNC_ENABLED=true
+AUTH_SYNC_KEY=<至少32字节的共享密钥>
+AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot
+AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
+# 可选；不填时 FoxClaw 会生成并持久化本机 node id
+AUTH_SYNC_NODE_ID=workstation-a
+```
+
+安全边界：
+
+- Telegram 只承载密文；auth 文件内容、候选名、account id、`last_refresh` 都在 AES-256-GCM 加密 payload 内。
+- 只接收 `AUTH_SYNC_PEERS` 中 peer bot 发来的同步文件；密钥、cluster、nonce 或 payload 校验失败时不会写盘。
+- 远端导入必须等本机全局空闲，再临时切换到待验证 auth、重启 app-server、读取 usage 验证成功后才写入候选。
+- 同名候选如果已知属于不同 account id，永远拒绝覆盖。
+- 跨节点恢复只拉取 peer 已持有的有效副本，不会自动触发 refresh token 轮换；找不到有效副本时会停止，提示你在一个节点手动维护授权。
+
+双主动流程：
+
+- push：本节点登录、Codex 自动刷新或 `/auth refresh all` 成功并通过本机镜像验证后，会主动把较新的候选加密推送给 peer。
+- pull：本节点切换或重载 auth 前如果发现本地候选不是最新，会先查本机其他 runtime；仍找不到时，再向 peer 拉取同名同账号的较新副本。
+- lease：执行会旋转 refresh token 的 `/auth refresh all confirm` 前，会向 peer 申请跨节点刷新锁。任一 peer 忙碌、拒绝或无响应都会阻止刷新。
+
+命令：
+
+- `/auth sync status`：查看 node id、peer、最近收发、最近导入、待导入和最近错误。
+- `/auth sync test`：发送加密 ping，确认 peer、共享密钥和 Bot-to-Bot 私聊可用。
+- `/auth sync push all`：手动广播当前节点已验证的全部候选，不刷新 token。
+
 命令等价用法：
 
 - `/auth` 或 `/auth list [关键词]`：查看候选，可按文件名搜索。
@@ -428,6 +463,7 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 - `/auth reload` 或 `/auth_reload`：重启 app-server，重新加载当前 `auth.json`。
 - `/auth refresh all`：显示 refresh token 轮换风险确认。
 - `/auth refresh all confirm`：接受 token 轮换风险后执行刷新全部。
+- `/auth sync status|test|push all`：查看、测试或手动推送跨节点 auth 同步。
 
 切换 auth 时，如果当前 bot runtime 还有活跃 turn、待审批、待用户输入或 MCP elicitation，FoxClaw 会先拒绝切换，避免中途换号破坏正在进行的请求；另一个空闲 bot 不受影响。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",

package/skills/foxclaw/SKILL.md

@@ -70,6 +70,8 @@ Telegram behavior:
 - `/auth` paginates large candidate inventories at 8 rows per page, supports all/enabled/attention filters and filename search, renders actual observed quota windows in text rows, uses compact two-number remaining quota labels on buttons, and omits the repeated `auth.json_` prefix from panel labels without renaming files
 - treat the `/auth` `not recently refreshed` state as a maintenance hint only: OpenAI does not publish a fixed ChatGPT refresh-token lifetime or replay grace period, and FoxClaw must not add routine bulk keepalive refreshes
 - `/auth refresh all` remains a command-only maintenance action, not a panel button; it requires explicit token-rotation risk confirmation, then force-refreshes every ChatGPT candidate through Codex `account/read refreshToken=true`, validates usage, mirrors successful candidates, and restores the original current auth while every runtime is globally idle
+- optional cross-node auth sync uses Telegram Bot-to-Bot private messages with encrypted auth bundles; configure `AUTH_SYNC_ENABLED=true`, a shared `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS`, then use `/auth sync status`, `/auth sync test`, and `/auth sync push all`; cross-node recovery pulls already-held valid peer copies and does not auto-refresh tokens
+- when cross-node auth sync is enabled, `/auth refresh all confirm` must obtain a cross-node refresh lease before rotating refresh tokens; any busy, denying, or non-responsive peer blocks the refresh
 - if `TG_BOT_TOKEN` is also set to one exact token from `TG_BOT_TOKENS`, that bot uses the default/shared-terminal runtime instead of an isolated Telegram home
 - if Weixin is enabled alongside multiple Telegram bots, it remains on the default Codex runtime instead of borrowing a Telegram bot runtime
 - in a group with multiple configured bots, address a bot by mention, reply, or suffixed command such as `/status@botname`