@foxden-app/foxclaw 0.4.12 → 0.4.14

package/.env.example

@@ -35,8 +35,18 @@ DEFAULT_SANDBOX_MODE=workspace-write
 TELEGRAM_POLL_INTERVAL_MS=1200
 TELEGRAM_PREVIEW_THROTTLE_MS=800
 THREAD_LIST_LIMIT=10
-CODEX_CLI_BIN=/absolute/path/to/codex
-
+CODEX_CLI_BIN=/absolute/path/to/codex
+
+# Optional cross-node Codex auth sync.
+# Disabled by default. When enabled, FoxClaw uses Telegram Bot-to-Bot private
+# messages to move encrypted auth bundles between nodes. Enable Bot-to-Bot
+# Communication Mode for the participating bots in BotFather first.
+# 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
+# AUTH_SYNC_NODE_ID=
+
 # Optional: standard HTTP(S) proxy for Telegram and ChatGPT/Codex backend requests.
 # Put these in the same env file that `foxclaw start` installs into systemd/launchd.
 # FoxClaw passes them to the service and enables Node's env proxy support.

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.4.14 - 2026-06-04
+
+### 中文
+- 新增可选跨节点 auth 同步：通过 Telegram Bot-to-Bot 私聊传输 AES-GCM 加密 auth 包，无需公网 IP 或 FRP。
+- 跨节点同步支持双主动：本机验证刷新后主动 push，切换/重载前本机恢复失败时主动 pull peer 已持有的有效副本。
+- `/auth sync status|test|push all` 可查看状态、测试 peer/密钥、手动推送全部已验证候选；远端导入必须等全局空闲并通过 usage 验证后才写盘。
+- `/auth refresh all confirm` 在启用跨节点同步时会先申请跨节点刷新锁；任一 peer 忙碌、拒绝或无响应都会阻止 refresh token 轮换。
+
+### English
+- Added optional cross-node auth sync using AES-GCM encrypted auth bundles over Telegram Bot-to-Bot private messages, with no public IP or FRP required.
+- Added dual-active sync behavior: locally validated refreshes are pushed, and auth switch/reload recovery can pull an already-held valid peer copy when local recovery fails.
+- Added `/auth sync status|test|push all` for status, peer/key testing, and manual broadcast of verified candidates. Remote imports wait for global idleness and usage validation before writing files.
+- When cross-node sync is enabled, `/auth refresh all confirm` requests a cross-node refresh lease first; any busy, denying, or non-responsive peer blocks refresh-token rotation.
+
+## 0.4.13 - 2026-06-03
+
+### 中文
+- `/update` 完成回报新增 Codex CLI 版本变化，和 FoxClaw 版本变化并排行展示。
+- `/auth` 文本列表继续保留额度窗口详情，候选按钮改为只显示两个剩余百分比数字，未知值用 `—`，减少窄屏按钮截断。
+
+### English
+- Added Codex CLI from/to version reporting to completed `/update` messages alongside the FoxClaw version change.
+- Kept quota-window detail in `/auth` text rows, while compacting candidate buttons to two remaining-percent numbers with `—` for unknown values.
+
 ## 0.4.12 - 2026-06-02
 
 ### 中文

package/README.md

@@ -85,7 +85,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 配置文件默认在 `~/.foxclaw/.env`。想放别处的话设 `FOXCLAW_ENV=/path/to/.env`。
 
-`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，尝试同步升级 npm/pnpm 安装的 Codex CLI，再完成安装、自检和服务重启。
+`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，尝试同步升级 npm/pnpm 安装的 Codex CLI，再完成安装、自检和服务重启，并在聊天回报 FoxClaw 与 Codex CLI 的版本变化。
 
 FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不代表群里所有人都能用。
 
@@ -128,7 +128,7 @@ FoxClaw 的一大特色是自动多账号切换。当一个账号触发用量限
 3. 用 `/auth` 查看所有候选账号状态。
 4. 用 `/auth enable <n>` / `/auth disable <n>` 控制哪些账号参与自动轮换。
 
-候选较多时，`/auth` 每页显示 8 个账号，并提供翻页、`全部 / 已启用 / 需关注` 筛选。也可以用 `/auth list <关键词>` 搜索文件名，或用 `/auth page <页码>` 直接跳页。额度窗口按 Codex 实际返回值展示，例如 `5h:20|7d:25` 或单月窗口 `30d:97`。面板会省略候选名中重复的 `auth.json_` 前缀，磁盘文件名保持不变。
+候选较多时，`/auth` 每页显示 8 个账号，并提供翻页、`全部 / 已启用 / 需关注` 筛选。也可以用 `/auth list <关键词>` 搜索文件名，或用 `/auth page <页码>` 直接跳页。文本列表的额度窗口按 Codex 实际返回值展示，例如 `5h:20|7d:25` 或单月窗口 `30d:97`；按钮只显示紧凑的两个剩余数字，例如 `20|25`，未知值显示为 `—`。面板会省略候选名中重复的 `auth.json_` 前缀，磁盘文件名保持不变。
 
 当 Codex 报告用量限制错误时，FoxClaw 会自动：
 - 切换到下一个未失败的候选账号
@@ -211,6 +211,8 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw 仍然只运行一个系统服务。默认情况下，它会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新在线验证后镜像同步；切换或重载前还会从其他 Codex home 恢复同账号较新凭据。各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、runtime 类型、当前 auth 和活动 turn 摘要。
 
+多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_bot`。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。
+
 如果你需要一路 Telegram 与终端互通 session，把同一个 token 同时填入 `TG_BOT_TOKENS` 和 `TG_BOT_TOKEN`。这个 bot 使用默认 `CODEX_HOME`（未设置时通常是 `~/.codex`）和默认 auth，因此能看到终端 Codex 的本地线程；它不再享有隔离 runtime 的“互不影响”保证，切换 auth 会影响终端和其他默认 runtime。
 
 **怎么找群组和话题 ID：**
@@ -260,7 +262,7 @@ FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pi
 - `/status`、`/account`、`/quota`、`/update`
 - `/quota_nudge <credits|usage_limit> confirm`
 - `/login_device`、`/login_cancel [id]`、`/logout confirm`
-- `/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|add <name>]`
+- `/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|sync <status|test|push all>|add <name>]`
 - `/threads [query]`、`/threads archived`、`/open <n>`
 - `/goal [objective|pause|resume|done|budget <tokens|off>|clear confirm]`
 - `/history [limit]`、`/files <query>`、`/remote`

package/README_EN.md

@@ -85,7 +85,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 The default config file is `~/.foxclaw/.env`. Set `FOXCLAW_ENV=/path/to/.env` if you want to keep it somewhere else.
 
-`foxclaw start` runs checks and installs or restarts the background service. For later upgrades, run `foxclaw update`; it preserves the current npm/pnpm global-install method, attempts to update an npm/pnpm-managed Codex CLI, runs checks, and restarts the service.
+`foxclaw start` runs checks and installs or restarts the background service. For later upgrades, run `foxclaw update`; it preserves the current npm/pnpm global-install method, attempts to update an npm/pnpm-managed Codex CLI, runs checks, restarts the service, and reports both FoxClaw and Codex CLI version changes in chat.
 
 FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a group does not make it available to every group member.
 
@@ -128,7 +128,7 @@ Setup:
 3. Use `/auth` to view all candidate account statuses.
 4. Use `/auth enable <n>` / `/auth disable <n>` to control which accounts participate in auto-rotation.
 
-For larger inventories, `/auth` shows 8 candidates per page with paging and `All / Enabled / Attention` filters. Use `/auth list <keyword>` to search filenames or `/auth page <n>` to jump directly. Quota windows use the values reported by Codex, for example `5h:20|7d:25` or a single monthly window such as `30d:97`. The panel omits the repeated `auth.json_` prefix from candidate labels without renaming files on disk.
+For larger inventories, `/auth` shows 8 candidates per page with paging and `All / Enabled / Attention` filters. Use `/auth list <keyword>` to search filenames or `/auth page <n>` to jump directly. Candidate rows use the quota windows reported by Codex, for example `5h:20|7d:25` or a single monthly window such as `30d:97`; buttons use compact remaining numbers such as `20|25`, with `—` for unknown values. The panel omits the repeated `auth.json_` prefix from candidate labels without renaming files on disk.
 
 When Codex reports a usage-limit error, FoxClaw automatically:
 - Switches to the next non-failed candidate account
@@ -211,6 +211,8 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw remains one system service. By default, it starts an independent `codex app-server` and `CODEX_HOME` for each bot. While bot A is running a turn, bot B can switch its own `/auth` selection. Candidate credentials are mirrored only after online-validated login or refresh; before switching or reloading, FoxClaw also restores a newer same-account credential from another Codex home when available. Current selections remain independent. Send `/help` and `/status` in a private chat with each bot after installation; `/auth` names the runtime being managed, and `/status` summarizes every bot's connection, runtime type, selected auth, and active turns.
 
+When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_bot`. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease.
+
 To keep one Telegram bot interoperable with terminal Codex sessions, put the same token in both `TG_BOT_TOKENS` and `TG_BOT_TOKEN`. That bot uses the default `CODEX_HOME` (usually `~/.codex` when unset) and default auth, so it can see local terminal sessions. It no longer has the isolated runtime guarantee: `/auth` switches also affect the terminal and other default runtimes.
 
 **How to find group and topic IDs:**
@@ -260,7 +262,7 @@ No static Codex app-server port is required in normal installs.
 - `/status`, `/account`, `/quota`, `/update`
 - `/quota_nudge <credits|usage_limit> confirm`
 - `/login_device`, `/login_cancel [id]`, `/logout confirm`
-- `/auth [list [keyword]|filter <all|enabled|attention>|page <n>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|add <name>]`
+- `/auth [list [keyword]|filter <all|enabled|attention>|page <n>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|sync <status|test|push all>|add <name>]`
 - `/threads [query]`, `/threads archived`, `/open <n>`
 - `/goal [objective|pause|resume|done|budget <tokens|off>|clear confirm]`
 - `/history [limit]`, `/files <query>`, `/remote`

package/dist/auth/cross_node_sync.d.ts

@@ -0,0 +1,112 @@
+import type { Logger } from '../logger.js';
+import type { AuthMirrorCandidateRecord, AuthMirrorImportResult } from './mirror.js';
+export interface AuthSyncConfig {
+    enabled: boolean;
+    transport: 'telegram-private';
+    key: string | null;
+    peers: string[];
+    nodeId: string | null;
+    clusterId: string;
+    statePath: string;
+    tempDir: string;
+}
+export interface AuthSyncPeerIdentity {
+    userId: string;
+    username: string | null;
+}
+export interface AuthSyncStatus {
+    enabled: boolean;
+    nodeId: string | null;
+    transport: 'telegram-private';
+    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;
+}
+export interface AuthSyncValidationResult {
+    ok: boolean;
+    reason?: string | null;
+}
+export interface AuthSyncImportCallbacks {
+    readLocalCandidate: (candidateName: string) => Promise<AuthMirrorCandidateRecord | null>;
+    listLocalCandidates: () => Promise<AuthMirrorCandidateRecord[]>;
+    validateCandidate: (candidateName: string, raw: string, expectedAccountId: string) => Promise<AuthSyncValidationResult>;
+    importCandidate: (candidateName: string, raw: string, source: {
+        nodeId: string;
+        label?: string | null;
+    }) => Promise<AuthMirrorImportResult>;
+    isIdle: () => boolean;
+}
+export interface AuthSyncTransport {
+    send: (peer: string, envelope: string) => Promise<void>;
+}
+export interface AuthSyncLeaseResult {
+    ok: boolean;
+    leaseId: string | null;
+    reason?: string | null;
+}
+export declare class CrossNodeAuthSync {
+    private readonly config;
+    private readonly logger;
+    private readonly transport;
+    private readonly callbacks;
+    private nodeId;
+    private key;
+    private readonly peers;
+    private readonly peerKeys;
+    private readonly pendingImports;
+    private readonly pendingPulls;
+    private readonly pendingLeases;
+    private seenNonces;
+    private timer;
+    private activeRemoteLease;
+    private activeLocalLease;
+    private state;
+    constructor(config: AuthSyncConfig, logger: Logger, transport: AuthSyncTransport, callbacks: AuthSyncImportCallbacks);
+    initialize(): Promise<void>;
+    start(): void;
+    stop(): void;
+    getStatus(): AuthSyncStatus;
+    isIdle(): boolean;
+    publishCandidate(candidateName: string): Promise<boolean>;
+    pushAll(): Promise<{
+        sent: number;
+        skipped: number;
+    }>;
+    publishDigest(): Promise<void>;
+    requestRecovery(candidateName: string, current?: {
+        accountId: string | null;
+        lastRefreshMs: number | null;
+    }): Promise<boolean>;
+    acquireRefreshLease(reason: string): Promise<AuthSyncLeaseResult>;
+    releaseRefreshLease(leaseId: string | null): Promise<void>;
+    testPeers(): Promise<{
+        sent: number;
+    }>;
+    handleIncomingEnvelope(rawEnvelope: string, peer: AuthSyncPeerIdentity): Promise<boolean>;
+    private handleMessage;
+    private handlePullRequest;
+    private handlePullResponse;
+    private handleDigest;
+    private handleLeaseRequest;
+    private handleLeaseReply;
+    private enqueueImport;
+    private processPendingImports;
+    private validateAndImport;
+    private sendToAll;
+    private sendToPeer;
+    private sealEnvelope;
+    private openEnvelope;
+    private isReady;
+    private isAllowedPeer;
+    private expireLeases;
+    private recordError;
+    private writeState;
+}
+export declare function readAccessTokenExpiresAtMs(raw: string): number | null;