lark-remote 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-06
+
+Initial release.
+
+### Added
+
+- Feishu private-chat ↔ local coding agent bridge (Claude Code / Codex / opencode / pi / Kimi)
+- CardKit 2.0 single-card streaming: one card per run, updated in place via `im.v1.message.patch`
+- Run card: thinking, text, tool summaries; terminal states (done/error/interrupted/idle_timeout/finalizing)
+- Bash card: `!<cmd>` executes bash with streaming card output (bypasses serial queue)
+- Serial work queue + stop control lane for concurrency safety
+- 5 agent runners with JSONL/NDJSON parsing, lifecycle management, and orphan process handling
+- 5 session readers with unified contract (`listSessions`/`readSessionContent`)
+- `/config` interactive card (agent-aware): switch agent, model, reasoning effort, idle watchdog
+- `/order` global prompt storage with `order.exec` dispatch
+- `/resume` paginated session list with per-agent filtering
+- `/active` in-memory dashboard of running sessions
+- `/cd`, `/ls` (paginated file browser), `/ws` (workspace aliases)
+- `/restart` in-place self-restart with process handoff
+- `/stop` immediate SIGKILL; stop button on run cards
+- QR-code scan-to-create wizard for first-time Feishu app setup
+- Single-instance lock per config directory
+- Startup notification to most recent private chat
+- Session persistence across bridge restarts (`last-session.json`)
+- Agent switch session restore with `previousSessions`/`arrivalSessions` dual-field design
+- Idle watchdog with configurable timeout
+- Run card progressive degradation under 28KB budget (text > thinking > tools)
+- 28KB+ budget enforcement using `Buffer.byteLength` (UTF-8)
+- Dedup TTL workaround for SDK `safety.dedup` toggle button issue
+- `classifyRejection` for SDK throttle/detach rejection (recoverable 4xx → log only)
+- `SpawnHeartbeat` for spawn-stage stall detection (30s, log-only)
+- Atomic file writes (tmp + rename, EXDEV fallback)
+- Daily log rotation (file-only, no stdout)
+- Node.js 20+ compatible (zero Bun runtime APIs in src/)
+- Bilingual documentation (Chinese + English)
+- MIT License
+
+### Security
+
+- Full-permission agent execution (hardcoded `bypassPermissions`/`approval_policy=never`)
+- Designed for single-user p2p private chat only — never add bot to group chats
+- Credentials stored locally in `config.yaml`, never committed to repository
+- Live Feishu API tests gated behind `FEISHU_LIVE_TEST=1` (external contributors can run full test suite without credentials)
+
+[0.1.0]: https://github.com/hhr-code/lark-remote/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hhr-code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,162 @@
+# lark-remote
+
+English | [简体中文](README.md)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/lark-remote.svg)](https://www.npmjs.com/package/lark-remote)
+[![CI](https://github.com/hhr-code/lark-remote/actions/workflows/ci.yml/badge.svg)](https://github.com/hhr-code/lark-remote/actions/workflows/ci.yml)
+
+A bridge between Feishu (Lark) private chat and local coding agents. Talk to Claude Code (or Codex / opencode / pi / Kimi) from Feishu — the agent reads/writes files and runs commands in a local directory you pick, with execution streamed live into a single CardKit 2.0 card.
+
+Designed for a single-user, peer-to-peer private chat. The agent's system prompt is never modified.
+
+![Streaming card demo](docs/images/demo.gif)
+
+> **New here? Start with [docs/en/getting-started.md](docs/en/getting-started.md).**
+
+## ⚠️ Security Warning (read first)
+
+This tool turns Feishu messages directly into local agent executions, and agents run with **full permissions** by default (Claude `bypassPermissions`, Codex `approval_policy=never` + full access) — effectively handing a shell on your machine to whoever can chat with the bot. You MUST:
+
+- **Use it only in your own private (p2p) chat.** Never add the bot to any group chat; never let anyone else talk to it.
+- Restrict the app's visibility to **yourself only** in the Feishu Open Platform.
+- Don't run it on a machine holding data you can't afford to lose; prefer a dedicated user / machine / container.
+- Keep credentials such as `appSecret` in your local `config.yaml` only — **never commit them anywhere**.
+
+## Prerequisites
+
+- OS: macOS / Linux. **Windows is not supported yet** (relies on POSIX behaviors such as Unix signals, bash, and file locks)
+- Node.js 20+ ([Bun](https://bun.sh/) for development)
+- A Feishu custom app (either way): scan-to-create (a QR code pops up in the terminal on first launch; scan it with the Feishu app to create the app and write credentials automatically); or create one manually in the Open Platform — enable bot capability, subscribe to `im.message.receive_v1` and `card.action.trigger` via **long connection** (WebSocket, no public address needed), with at least the `im:message` scope.
+- Claude Code CLI installed locally and logged in once in a terminal (`claude` → browser OAuth). Same idea for other agents (codex / opencode / pi / kimi): install the corresponding CLI first.
+
+## Installation
+
+Option 1: npm / npx (no clone needed):
+
+```bash
+npx lark-remote          # run directly
+# or install globally
+npm install -g lark-remote
+lark-remote
+```
+
+Option 2: from source:
+
+```bash
+git clone https://github.com/hhr-code/lark-remote.git
+cd lark-remote
+bun install
+bun run build
+bun install -g "$(pwd)"  # install globally as the lark-remote command (bun parses `.` as an empty package name; use an absolute path)
+```
+
+## Configuration
+
+On first launch, if no Feishu credentials are found: an interactive terminal enters the scan-to-create wizard (a QR code is printed; scan it with the Feishu app to create the app, write credentials, and continue startup); non-interactive environments generate a template at `~/.lark-remote/config.yaml` and exit — fill in your credentials and restart. See [`docs/en/usage.md`](docs/en/usage.md) for all fields. Key options:
+
+```yaml
+feishu:
+  appId: cli_xxx
+  appSecret: xxx
+
+# default agent: claude | codex | opencode | pi | kimi (default: claude)
+defaultAgent: claude
+
+claude:
+  binary: claude
+  model: claude-opus-4-8
+  effort: medium            # low | medium | high | xhigh | max
+  # permissionMode is hardcoded to bypassPermissions (inside the runner)
+  stopGraceMs: 5000
+
+output:
+  showThinking: true
+  showToolUse: true
+  showToolResult: true
+
+logging:
+  level: info               # debug | info | warn | error
+
+idle:
+  watchdogMinutes: 15       # 0 disables the idle watchdog
+```
+
+Override the config directory with `--config-dir <path>`; override the Claude settings path with `--settings <path>` or the `CLAUDE_SETTINGS_PATH` environment variable.
+
+## Running
+
+```bash
+lark-remote                                     # after global install / via npx
+bun run dev                                     # development (run TS directly with bun)
+bun run build && node dist/index.js             # run the compiled output
+
+# CLI flags
+lark-remote --config-dir ~/.lark-remote-test    # custom config dir (multiple instances on one machine)
+lark-remote --settings ~/.claude/settings.json  # specify Claude settings file
+```
+
+The bridge prints nothing to the terminal after startup; logs go to `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log` (rotated daily, one subdirectory per day). Only one `lark-remote` instance is allowed per `configDir` — a duplicate start fails with the existing pid. After connecting to Feishu, a startup notification (with start time and pid) is sent to the most recent private chat.
+
+For automatic process restart, set up your own supervisor such as systemd, launchd, or pm2.
+
+Each agent run creates one CardKit 2.0 card that updates in place with thinking, body text, and tool summaries in real time.
+Timestamps are read from the JSONL and shown in local time as `YYYY-MM-DD HH:mm` for thinking, body, tool call/result, and session history events.
+The card clearly shows completion, error, interruption, or idle timeout at the end; the in-card "⏹ Stop" button is equivalent to `/stop`.
+Cards use a lossy rolling summary — very long histories are not kept in full.
+Your original message also gets an emoji reaction: `Typing` while the run is in progress, then the terminal-state emoji at the end — `Done` (finished), `ERROR` (failed), `Alarm` (idle timeout), or `SHHH` (you stopped it with `/stop`). `!` bash commands always end with `Done`.
+
+## Commands
+
+| Command | Alias | Behavior |
+|---------|-------|----------|
+| `/help` | `/h` | Command list |
+| `/cd <path>` | - | Switch agent working directory (`~`, absolute/relative; clears the session) |
+| `/ls [dir]` | - | Directory/file card; click a directory to switch, click a file ≤30MB to send it to Feishu; paginates beyond 30 entries |
+| `/ws save\|use\|remove` | - | Named directory aliases (`/ws` lists by default) |
+| `/resume [agent] [N\|id]` | `/r` | List/switch agent sessions for the current directory (card) |
+| `/active` | - | List all running sessions |
+| `/new` | - | Clear the current session (keeps cwd) |
+| `/status` | `/s` | Current directory, session, model, process status |
+| `/stop` | `/t` | Kill the current agent process (SIGKILL) |
+| `/ps` | - | Whether a process is running |
+| `/reconnect` | - | Reconnect to Feishu |
+| `/restart` | - | In-place bridge self-restart (new process takes over with the same config) |
+| `/config get\|set` | `/c` | View/change runtime config (agent-aware card) |
+| `/order save\|list` | `/o` | Save or list frequently used prompts |
+| `!<cmd>` | - | Run a bash command with streaming card output (bypasses the serial queue) |
+| `/exit` | `/e` | Exit the bridge |
+
+Any message not starting with `/` is forwarded to the current default agent.
+
+## Testing
+
+```bash
+bun run test          # vitest (unit/integration tests, all run offline)
+bun run typecheck     # tsc --noEmit
+bun run lint          # eslint
+
+# Live Feishu API integration tests (skipped by default; need valid
+# credentials under ~/.lark-remote-test)
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-card-form-error.test.ts
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
+```
+
+## Documentation
+
+Full docs under [`docs/`](docs/):
+
+- Getting started: [`docs/en/getting-started.md`](docs/en/getting-started.md)
+- Usage guide (install, commands, workflows): [`docs/en/usage.md`](docs/en/usage.md)
+- Overall design, JSONL events, known pitfalls: [`docs/en/architecture/design.md`](docs/en/architecture/design.md)
+- Single-card streaming architecture and Feishu acceptance: [`docs/en/architecture/streaming-card.md`](docs/en/architecture/streaming-card.md)
+- Template for adding a new agent: [`docs/en/guides/add-new-agent.md`](docs/en/guides/add-new-agent.md)
+- Codex config card guide: [`docs/en/guides/codex-config.md`](docs/en/guides/codex-config.md)
+- Feishu CardKit 2.0 component reference: [Feishu Open Platform official docs](https://open.feishu.cn/document/feishu-cards/card-json-v2-components/component-json-v2-overview)
+- AI collaboration rules and red lines: [`CLAUDE.md`](CLAUDE.md)
+
+> This package is a CLI tool only — no programmatic API is exposed.
+
+## License
+
+[MIT](LICENSE) © hhr-code

package/README.md

@@ -0,0 +1,161 @@
+# lark-remote
+
+[English](README.en.md) | 简体中文
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/lark-remote.svg)](https://www.npmjs.com/package/lark-remote)
+[![CI](https://github.com/hhr-code/lark-remote/actions/workflows/ci.yml/badge.svg)](https://github.com/hhr-code/lark-remote/actions/workflows/ci.yml)
+
+飞书私聊 ↔ 本地 Coding Agent 桥接。在飞书里和 Claude Code（或 Codex / opencode / pi / Kimi）对话，agent 在你指定的本地目录里读写文件、跑命令，执行过程以 CardKit 2.0 卡片**单卡实时流式**呈现。
+
+单用户、p2p 私聊场景设计，不修改 agent 的 system prompt。
+
+![流式卡片演示](docs/images/demo.gif)
+
+> **第一次接触本项目？先看 [docs/zh/getting-started.md](docs/zh/getting-started.md)。**
+
+## ⚠️ 安全警告（必读）
+
+本工具会把飞书消息直接转为本地 agent 执行，agent 默认以**完全权限**运行（Claude `bypassPermissions`、Codex `approval_policy=never` + full access），等价于把一台机器的 shell 交给聊天对端。请务必：
+
+- **仅限你自己的私聊（p2p）使用**。不要把机器人拉进任何群聊，不要让任何其他人能与它对话。
+- 在飞书开放平台把应用可见范围限制到**只有你自己**。
+- 运行本工具的机器上不要存放与损失承受力不符的数据；建议在独立用户/机器/容器里运行。
+- `appSecret` 等凭据只在本地 `config.yaml`，**不要提交到任何仓库**。
+
+## 前置条件
+
+- 操作系统：macOS / Linux。**暂不支持 Windows**（依赖 Unix 信号、bash、文件锁等 POSIX 行为）
+- Node.js 20+（开发时用 [Bun](https://bun.sh/)）
+- 飞书自建应用（二选一）：扫码创建（首次启动终端弹二维码，飞书 App 扫码即自动创建并写入凭据）；或手动在开放平台建应用——开启机器人能力，订阅 `im.message.receive_v1` 和 `card.action.trigger`，订阅方式选「长连接」（WebSocket，无需公网地址），权限至少 `im:message`。
+- Claude Code CLI：本地安装并在终端完成一次登录（`claude` → 浏览器 OAuth）。使用其他 agent（codex / opencode / pi / kimi）同理，先装好对应 CLI。
+
+## 安装
+
+方式一：npm / npx（无需 clone）：
+
+```bash
+npx lark-remote          # 直接运行
+# 或全局安装
+npm install -g lark-remote
+lark-remote
+```
+
+方式二：从源码安装：
+
+```bash
+git clone https://github.com/hhr-code/lark-remote.git
+cd lark-remote
+bun install
+bun run build
+bun install -g "$(pwd)"  # 全局安装为 lark-remote 命令（相对路径 `.` 会触发 bun unsafe name bug，须绝对路径）
+```
+
+## 配置
+
+首次启动若检测不到飞书凭据：交互式终端会进入扫码创建向导（终端打印二维码，飞书 App 扫码即创建应用并写入凭据，随后继续启动）；非交互环境则在 `~/.lark-remote/config.yaml` 生成模板并退出，填写凭据后重启。完整字段见 [`docs/zh/usage.md`](docs/zh/usage.md)，关键项：
+
+```yaml
+feishu:
+  appId: cli_xxx
+  appSecret: xxx
+
+# 默认 agent：claude | codex | opencode | pi | kimi，默认 claude
+defaultAgent: claude
+
+claude:
+  binary: claude
+  model: claude-opus-4-8
+  effort: medium            # low | medium | high | xhigh | max
+  # permissionMode 硬编码为 bypassPermissions（runner 内部）
+  stopGraceMs: 5000
+
+output:
+  showThinking: true
+  showToolUse: true
+  showToolResult: true
+
+logging:
+  level: info               # debug | info | warn | error
+
+idle:
+  watchdogMinutes: 15       # 0 关闭空闲看门狗
+```
+
+配置目录可用 `--config-dir <path>` 覆盖；Claude settings 路径可用 `--settings <path>` 或 `CLAUDE_SETTINGS_PATH` 环境变量覆盖。
+
+## 运行
+
+```bash
+lark-remote                                     # 全局安装 / npx 后直接用
+bun run dev                                     # 开发（bun 直跑 TS）
+bun run build && node dist/index.js             # 编译后运行
+
+# CLI 参数
+lark-remote --config-dir ~/.lark-remote-test    # 自定义配置目录（同机多实例）
+lark-remote --settings ~/.claude/settings.json  # 指定 Claude 配置文件
+```
+
+bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log`（按日期轮转，每天一个子目录）。同一 `configDir` 只允许一个 `lark-remote` 实例，重复启动会直接报错并提示已有 pid。连接飞书成功后会向最近私聊用户发送启动通知，包含启动时间和进程号。
+
+如需进程自动重启，可自行配置 systemd / launchd / pm2 等守护方案。
+
+每次 agent 运行会创建一张 CardKit 2.0 卡片，并在原地实时更新 thinking、正文和工具摘要。
+卡片会读取 JSONL 的 `timestamp`，以本地时间 `YYYY-MM-DD HH:mm` 显示 thinking、正文、tool call/result 和会话历史事件。
+结束时卡片明确显示完成、出错、中断或空闲超时；运行中的「⏹ 终止」按钮与 `/stop` 等价。
+卡片采用有损滚动摘要，超长历史不会完整保留。
+你的原消息上会收到表情回应：处理中先打 `Typing`，结束时按终态补打 `Done`（完成）/ `ERROR`（出错）/ `Alarm`（空闲超时）/ `SHHH`（你主动 `/stop`）；`!` bash 命令结束时固定打 `Done`。
+
+## 命令
+
+| 命令 | 别名 | 行为 |
+|------|------|------|
+| `/help` | `/h` | 命令列表 |
+| `/cd <path>` | - | 切换 agent 工作目录（支持 `~`、绝对/相对路径，清空会话） |
+| `/ls [dir]` | - | 弹出目录/文件卡片；点击目录切换，点击 30MB 内文件发送到飞书；条目 >30 时支持翻页 |
+| `/ws save\|use\|remove` | - | 命名目录别名管理（`/ws` 默认列出） |
+| `/resume [agent] [N\|id]` | `/r` | 列出/切换当前目录的 agent session（卡片） |
+| `/active` | - | 列出所有正在进行中的 session |
+| `/new` | - | 清空当前会话（保留工作目录） |
+| `/status` | `/s` | 当前目录、session、模型、进程状态 |
+| `/stop` | `/t` | 终止当前 agent 进程（SIGKILL） |
+| `/ps` | - | 是否有进程在跑 |
+| `/reconnect` | - | 重连飞书 |
+| `/restart` | - | 原地自重启 bridge（新进程同 config 接管） |
+| `/config get\|set` | `/c` | 查改运行时配置（agent-aware 卡片） |
+| `/order save\|list` | `/o` | 保存或列出常用指令 |
+| `!<cmd>` | - | 执行 bash 命令并流式输出到卡片（绕过串行队列） |
+| `/exit` | `/e` | 退出 bridge |
+
+直接发非 `/` 开头的消息即转发给当前默认 agent。
+
+## 测试
+
+```bash
+bun run test          # vitest（单元/集成测试，全部离线可跑）
+bun run typecheck     # tsc --noEmit
+bun run lint          # eslint
+
+# 真实飞书 API 集成测试（默认跳过，需要 ~/.lark-remote-test 下的有效凭据）
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-card-form-error.test.ts
+FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
+```
+
+## 文档
+
+完整文档目录 [`docs/`](docs/)：
+
+- 入门指南：[`docs/zh/getting-started.md`](docs/zh/getting-started.md)
+- 使用指南（安装、命令、工作流示例）：[`docs/zh/usage.md`](docs/zh/usage.md)
+- 整体设计、JSONL 事件、已知坑点：[`docs/zh/architecture/design.md`](docs/zh/architecture/design.md)
+- 单卡流式架构与飞书验收：[`docs/zh/architecture/streaming-card.md`](docs/zh/architecture/streaming-card.md)
+- 新增 agent 接入模板：[`docs/zh/guides/add-new-agent.md`](docs/zh/guides/add-new-agent.md)
+- Codex 配置卡片指南：[`docs/zh/guides/codex-config.md`](docs/zh/guides/codex-config.md)
+- 飞书 CardKit 2.0 组件参考：[飞书开放平台官方文档](https://open.feishu.cn/document/feishu-cards/card-json-v2-components/component-json-v2-overview)
+- AI 协作规则与红线：[`CLAUDE.md`](CLAUDE.md)
+
+> 本包为纯 CLI 工具，不提供编程 API。
+
+## License
+
+[MIT](LICENSE) © hhr-code

package/dist/binder.d.ts

@@ -0,0 +1,57 @@
+import { StartupContactStore } from './startup-contact.js';
+/** 入站私聊消息的绑定/授权判定结果。 */
+type BindDecision = {
+    kind: 'owner';
+} | {
+    kind: 'rejected';
+} | {
+    kind: 'bind_success';
+} | {
+    kind: 'pin_wrong';
+};
+/**
+ * Owner 绑定器：首次私聊输入正确 PIN 完成"认领"，此后仅该 openId 可用。
+ *
+ * 设计依据（第一性原理）：bridge 进程持有用户本机完整权限，唯一合法主体是
+ * owner 本人。任何入站事件都必须认证到该单一主体。`chatType==='p2p'` 不是认证
+ * （任何能私聊机器人的用户都满足）。本类以"首次绑定 + openId 强校验"实现认证，
+ * 复用已有 startup-contact.json，不新增配置字段。
+ *
+ * 状态机：
+ * - 未绑定：生成 PIN（控制台展示），等待 owner 私聊输入正确 PIN -> 写入绑定。
+ *   输错 PIN 完全静默（不回复、不提醒）；首次启动仅用户本机可见，无需严格防枚举。
+ * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
+ *
+ * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
+ */
+export declare class OwnerBinder {
+    private readonly store;
+    private pin;
+    private rejectedTotal;
+    constructor(store: StartupContactStore);
+    /** 仅未绑定时返回待输入的 PIN（控制台展示用）。 */
+    get pendingPin(): string | undefined;
+    isBound(): boolean;
+    /** 已绑定的 owner openId；未绑定时 undefined。 */
+    boundOpenId(): string | undefined;
+    /** 卡片操作者是否为已绑定的 owner（未绑定返回 false）。 */
+    isOwner(openId: string): boolean;
+    /** 累计被拒（非 owner）消息/卡片数，用于 DoS 可观测。 */
+    get rejectedCount(): number;
+    /**
+     * 对入站私聊消息做绑定/授权判定，含副作用：
+     * - `owner`：放行，调用方继续正常处理
+     * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
+     * - `bind_success`：未绑定且 PIN 正确，写入绑定并清除 PIN
+     * - `pin_wrong`：未绑定且 PIN 错误，静默丢弃（不回复、不提醒）
+     */
+    classify(senderId: string, content: string, chatId: string): BindDecision;
+    /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
+    recordRejectedCardAction(openId: string): void;
+}
+/**
+ * 控制台 PIN 引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog
+ * 重定向到 daemon 日志）。绑定后此文案不再出现。
+ */
+export declare function formatPinGuidance(pin: string): string;
+export {};

package/dist/binder.js

@@ -0,0 +1,105 @@
+import crypto from 'node:crypto';
+import { getLogger } from './logger/index.js';
+/** 绑定 PIN 位数。4 位数字便于人工输入。 */
+const PIN_DIGITS = 4;
+/** 用 CSPRNG 生成固定长度、零填充的数字 PIN（首位可为 0）。 */
+function generatePin() {
+    const n = crypto.randomInt(0, 10 ** PIN_DIGITS);
+    return String(n).padStart(PIN_DIGITS, '0');
+}
+/**
+ * Owner 绑定器：首次私聊输入正确 PIN 完成"认领"，此后仅该 openId 可用。
+ *
+ * 设计依据（第一性原理）：bridge 进程持有用户本机完整权限，唯一合法主体是
+ * owner 本人。任何入站事件都必须认证到该单一主体。`chatType==='p2p'` 不是认证
+ * （任何能私聊机器人的用户都满足）。本类以"首次绑定 + openId 强校验"实现认证，
+ * 复用已有 startup-contact.json，不新增配置字段。
+ *
+ * 状态机：
+ * - 未绑定：生成 PIN（控制台展示），等待 owner 私聊输入正确 PIN -> 写入绑定。
+ *   输错 PIN 完全静默（不回复、不提醒）；首次启动仅用户本机可见，无需严格防枚举。
+ * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
+ *
+ * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
+ */
+export class OwnerBinder {
+    store;
+    pin;
+    rejectedTotal = 0;
+    constructor(store) {
+        this.store = store;
+        if (!store.getContact()) {
+            this.pin = generatePin();
+        }
+    }
+    /** 仅未绑定时返回待输入的 PIN（控制台展示用）。 */
+    get pendingPin() {
+        return this.pin;
+    }
+    isBound() {
+        return this.store.getContact() !== undefined;
+    }
+    /** 已绑定的 owner openId；未绑定时 undefined。 */
+    boundOpenId() {
+        return this.store.getContact()?.userId;
+    }
+    /** 卡片操作者是否为已绑定的 owner（未绑定返回 false）。 */
+    isOwner(openId) {
+        const bound = this.store.getContact()?.userId;
+        return bound !== undefined && bound === openId;
+    }
+    /** 累计被拒（非 owner）消息/卡片数，用于 DoS 可观测。 */
+    get rejectedCount() {
+        return this.rejectedTotal;
+    }
+    /**
+     * 对入站私聊消息做绑定/授权判定，含副作用：
+     * - `owner`：放行，调用方继续正常处理
+     * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
+     * - `bind_success`：未绑定且 PIN 正确，写入绑定并清除 PIN
+     * - `pin_wrong`：未绑定且 PIN 错误，静默丢弃（不回复、不提醒）
+     */
+    classify(senderId, content, chatId) {
+        const bound = this.store.getContact();
+        if (bound) {
+            if (senderId === bound.userId)
+                return { kind: 'owner' };
+            this.rejectedTotal++;
+            getLogger().debug(`[binder] rejected message from ${senderId} (total rejected=${this.rejectedCount})`);
+            return { kind: 'rejected' };
+        }
+        // 未绑定：要求 PIN（精确匹配 trim 后内容，避免部分匹配绕过）
+        if (this.pin !== undefined && content.trim() === this.pin) {
+            this.store.save({ chatId, userId: senderId });
+            this.pin = undefined;
+            getLogger().info(`[binder] owner bound: openId=${senderId} chatId=${chatId}`);
+            return { kind: 'bind_success' };
+        }
+        // 输错 PIN：完全静默（不回复、不提醒、不计数），仅内部 debug 日志
+        getLogger().debug('[binder] wrong pin (unbound, ignored)');
+        return { kind: 'pin_wrong' };
+    }
+    /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
+    recordRejectedCardAction(openId) {
+        this.rejectedTotal++;
+        getLogger().debug(`[binder] rejected card action from ${openId} (total rejected=${this.rejectedCount})`);
+    }
+}
+/**
+ * 控制台 PIN 引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog
+ * 重定向到 daemon 日志）。绑定后此文案不再出现。
+ */
+export function formatPinGuidance(pin) {
+    return [
+        '',
+        '🔒 首次绑定',
+        '请在飞书私聊本应用，发送以下 4 位数字完成绑定：',
+        '',
+        `    ${pin}`,
+        '',
+        '绑定后仅该账号可使用本应用。',
+        '需更换账号：删除 <configDir>/startup-contact.json 后重启。',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=binder.js.map