@foxden-app/foxclaw 0.4.13 → 0.4.15

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.15 - 2026-06-04
+
+### 中文
+- 更新 FoxClaw 收尾 skill：发布前固定检查设计文档、中文/英文使用手册和对外公开文档。
+- 涉及 Telegram 设置的变更，使用手册必须写清 `@BotFather` 操作步骤；npm 发布 skill 也会遵守该项目文档门槛。
+
+### English
+- Updated the FoxClaw wrap-up skill to require design docs, Chinese/English user manuals, and public-facing docs before release.
+- Telegram setup changes must document the exact `@BotFather` steps in the manuals; the npm publish skill now honors this project documentation gate too.
+
+## 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
 
 ### 中文

package/README.md

@@ -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

@@ -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;