docs: add detailed answers for 21 learning roadmap questions
This commit is contained in:
166
docs/answers/03-permissions-and-security.md
Normal file
166
docs/answers/03-permissions-and-security.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# Q7-Q9: 权限与安全
|
||||
|
||||
---
|
||||
|
||||
## Q7: 用户身份怎么确定？owner / admin / member 三级权限检查在哪里完成？
|
||||
|
||||
### 答案
|
||||
|
||||
**用户身份确定（两步）：**
|
||||
|
||||
`src/modules/permissions/index.ts:67-103` — `extractAndUpsertUser` 函数：
|
||||
|
||||
1. **解析原始 handle：** 从入站消息 JSON payload 的三处位置按优先级查找：`senderId`、`sender`、`author.userId`（chat-sdk-bridge 的嵌套格式）。三处都没有返回 `null`
|
||||
2. **命名空间标准化：** 如果原始 handle 已含 `:` 前缀（如 `slack:U0ABC`），直接使用；否则前缀 `channelType:` → 全局唯一 `userId`
|
||||
3. **Upsert：** `users` 表中不存在则创建（`db/users.ts:13-22`），`kind` 记录 channel 类型，`display_name` 从消息中提取
|
||||
|
||||
这个 resolver 通过 `setSenderResolver(extractAndUpsertUser)` 注册到 router（`index.ts:171`），在 agent 解析**之前**执行（`router.ts:252`），确保即使后续被拒绝访问，`users` 行也已存在。
|
||||
|
||||
**三级权限表：**
|
||||
|
||||
| 表 | 用途 | 关键字段 |
|
||||
|-----|------|---------|
|
||||
| `users` | 用户身份 | `id`（命名空间化的userId），`kind`，`display_name` |
|
||||
| `user_roles` | 特权角色 | `user_id`，`role`（owner/admin），`agent_group_id`（NULL=全局） |
|
||||
| `agent_group_members` | 非特权成员 | `user_id`，`agent_group_id` |
|
||||
|
||||
**`canAccessAgentGroup` 完整逻辑：**
|
||||
|
||||
`src/modules/permissions/access.ts:21-28` — 五步短路求值：
|
||||
|
||||
```typescript
|
||||
function canAccessAgentGroup(userId: string, agentGroupId: string): AccessDecision {
|
||||
if (!getUser(userId)) return { allowed: false, reason: 'unknown_user' }; // Gate 0
|
||||
if (isOwner(userId)) return { allowed: true, reason: 'owner' }; // Gate 1
|
||||
if (isGlobalAdmin(userId)) return { allowed: true, reason: 'global_admin' };// Gate 2
|
||||
if (isAdminOfAgentGroup(userId, agentGroupId)) return { allowed: true, reason: 'admin_of_group' };// Gate 3
|
||||
if (isMember(userId, agentGroupId)) return { allowed: true, reason: 'member' };// Gate 4
|
||||
return { allowed: false, reason: 'not_member' };
|
||||
}
|
||||
```
|
||||
|
||||
**查库函数**（`db/user-roles.ts`）：
|
||||
- `isOwner`：`role='owner' AND agent_group_id IS NULL`（line 36-41）—— owner 必须全局
|
||||
- `isGlobalAdmin`：`role='admin' AND agent_group_id IS NULL`（line 43-48）
|
||||
- `isAdminOfAgentGroup`：`role='admin' AND agent_group_id=<id>`（line 50-55）
|
||||
|
||||
**`isMember` 的隐式 admin 语义**（`db/agent-group-members.ts:28-36`）：
|
||||
先检查 `isOwner || isGlobalAdmin || isAdminOfAgentGroup` 再查 `agent_group_members` 表——owner 和 admin **自动成为 member**，不需要额外插入行。
|
||||
|
||||
---
|
||||
|
||||
## Q8: 陌生人在群里 @bot，系统怎么决定忽略、审批、还是直接响应？
|
||||
|
||||
### 答案
|
||||
|
||||
**`unknown_sender_policy` 三态**（`src/types.ts:31`，默认 `'strict'`）：
|
||||
|
||||
| 值 | 行为 |
|
||||
|-----|------|
|
||||
| `public` | 完全跳过访问检查。`router.ts` access gate 在 `index.ts:175` 直接返回 `{ allowed: true }` |
|
||||
| `strict` | 非 member 的消息静默丢弃，记录到 `unregistered_senders`，不发送通知 |
|
||||
| `request_approval` | 非 member 的消息被丢弃 + 发起一轮审批流程：DM 一个 admin/owner，展示 Approve/Deny 卡片 |
|
||||
|
||||
注意：即使 `unknown_sender_policy='public'`，`sender_scope='known'` 仍可作为更严格的叠加层（`router.ts:284` `senderScopeGate`）。
|
||||
|
||||
**完整决策链路**（`src/router.ts` `routeInbound`）：
|
||||
|
||||
1. Message interceptor 先检查拦截器 hook 是否消费了该消息
|
||||
2. Messaging group 解析 → sender resolver → agent fan-out
|
||||
3. **Access gate**（line 283）：就是 `canAccessAgentGroup` —— 此处 `unknown_sender_policy` 生效
|
||||
4. **Sender scope gate**（line 284）：per-wiring 的 `sender_scope='known'` 额外检查
|
||||
5. 如果 access gate 拒绝 → `handleUnknownSender`
|
||||
|
||||
### sender-approval 完整流程
|
||||
|
||||
**Phase 1: 触发与去重**（`permissions/index.ts:113-169`）：
|
||||
- 记录 `dropped_message`，reason=`unknown_sender_request_approval`
|
||||
- 调用 `requestSenderApproval`
|
||||
- **去重门控**（`sender-approval.ts:59-65`）：检查 `pending_sender_approvals` 表中的 `UNIQUE(messaging_group_id, sender_identity)` —— 同一个人已有 pending 卡片时，后续消息静默丢弃
|
||||
|
||||
**Phase 2: 选择审批者**（`sender-approval.ts:67-87`）：
|
||||
- `pickApprover(agentGroupId)` → scoped admins → global admins → owners（`primitive.ts:76-93`）
|
||||
- `pickApprovalDelivery`（`primitive.ts:103-119`）：遍历审批者，调用 `ensureUserDm` 找到可 DM 的人，优先同 channel 类型
|
||||
|
||||
**Phase 3: 创建 pending + 发送卡片**：
|
||||
- 标题和内容：`"New sender / <name> wants to talk to your agent. Allow?"`
|
||||
- `ask_question` 卡片，通过 `deliveryAdapter.deliver` 发到审批者 DM
|
||||
|
||||
**Phase 4: 审批响应**（`index.ts:225-283`）：
|
||||
|
||||
**APPROVE：**
|
||||
1. **授权验证**（line 234-244）：检查点击者是不是 `approver_user_id` **或**有 admin 权限——防止随机用户通过转发卡片自我授权
|
||||
2. `addMember` 添加到 `agent_group_members`（line 249-254）
|
||||
3. **先删除 pending 行**（line 264），**再**重新调用 `routeInbound(event)`（line 268）——此时重试经过 access gate，user 已是 member
|
||||
|
||||
**DENY：**
|
||||
- 仅删除 `pending_sender_approvals` 行
|
||||
- **不创建拒收列表**——同一发送者的新消息会重新触发新审批卡片
|
||||
|
||||
### 失败模式
|
||||
|
||||
- 没有 owner/admin → 消息永久丢弃
|
||||
- 没有任何审批者可达（无 DM channel）→ 同上
|
||||
- 没有 delivery adapter → pending 行仍创建（可手动查看），但卡片不发送
|
||||
- 卡片发送异常 → error log，消息已丢弃
|
||||
|
||||
---
|
||||
|
||||
## Q9: Agent 在容器里能用 `ncl` 命令吗？能查其他 agent group 的数据吗？`cli_scope` 的三个值在哪里被检查？
|
||||
|
||||
### 答案
|
||||
|
||||
**`cli_scope` 的三个值**（`container_configs` 表，迁移 015 添加，默认 `'group'`）：
|
||||
|
||||
| 值 | 含义 |
|
||||
|-----|------|
|
||||
| `disabled` | Agent 完全不知道 ncl 存在；host 拒绝所有 CLI 请求 |
|
||||
| `group`（默认） | Agent 只能操作自己的 group（4个资源），args 被自动绑定到自己 group；无法查看其他 group 数据 |
|
||||
| `global` | 无限制。仅通过 `init-first-agent` 脚本为 owner 的 agent group 设置 |
|
||||
|
||||
### 四层防御
|
||||
|
||||
**防御层 1：CLAUDE.md 层面** — `src/claude-md-compose.ts:82-90`
|
||||
`cli_scope === 'disabled'` 时，`cli.instructions.md` 从 CLAUDE.md 的 fragment 列表中排除。Agent 学不到 ncl 命令的存在。
|
||||
|
||||
**防御层 2：Host dispatch 核心强制** — `src/cli/dispatch.ts`
|
||||
|
||||
- **disabled 检查**（line 46-48）：所有 CLI 请求立即拒绝
|
||||
- **资源白名单**（line 51-55）：`group` 只允许 `groups`、`sessions`、`destinations`、`members` 四种资源
|
||||
- **参数强制绑定**（line 60-72）：检查 `agent_group_id`、`group`、`--id` 参数，不匹配调用者的 group 则拒绝
|
||||
- **特权升级阻止**（line 74-77）：拒绝任何包含 `cli_scope` 或 `cli-scope` 参数的命令
|
||||
- **自动填充**（line 81-90）：主动填充 `agent_group_id`、`group`、`--id` 为调用者的 group ID——agent 不需要也不能指定
|
||||
- **sessions-get 防 existence oracle**（line 95-100）：如果传入 session UUID 属于其他 group，返回 "not found" 而非 "forbidden"
|
||||
- **Post-handler 过滤**（line 150-173）：对 `list` 返回的 rows 按 `scopeField` 再次过滤，丢弃不属于调用者 group 的行
|
||||
|
||||
各资源的 `scopeField` 映射（`src/cli/resources/`）：
|
||||
- `groups` → `'id'`（`groups.ts:41`）
|
||||
- `sessions` → `'agent_group_id'`（`sessions.ts:10`）
|
||||
- `destinations` → `'agent_group_id'`（`destinations.ts:11`）
|
||||
- `members` → `'agent_group_id'`（`members.ts:11`）
|
||||
|
||||
**防御层 3：Container 端** — `container/agent-runner/src/cli/ncl.ts`
|
||||
Container 内的 ncl **不做任何权限检查**——它是纯粹的 DB transport 客户端。将 CLI 请求写入 `outbound.db`，从 `inbound.db` poll 响应。权限检查全在 host 端。Container 无法绕过，因为它只能访问 session DB，不能直接连中央库或 socket server。
|
||||
|
||||
**防御层 4：Command Gate（斜杠命令）** — `src/command-gate.ts:23-63`
|
||||
|
||||
独立于 `cli_scope`，在消息写入 `messages_in` 之前运行（`router.ts:430-448`）：
|
||||
- **Filtered commands**（`/help`, `/login`, `/logout`, `/doctor`, `/config`, `/remote-control`）→ 静默丢弃永不进容器
|
||||
- **Admin commands**（`/clear`, `/compact`, `/context`, `/cost`, `/files`）→ 仅 owner / admin 可通过。否则直接写 `messages_out` 返回权限拒绝
|
||||
- **降级安全**（line 51）：`user_roles` 表不存在 → 所有 admin 命令放行
|
||||
|
||||
### 跨层防御矩阵总结
|
||||
|
||||
| 防御层 | disabled | group | global |
|
||||
|--------|----------|-------|--------|
|
||||
| CLAUDE.md 隐藏 ncl | ✅ 排除 | ❌ 包含 | ❌ 包含 |
|
||||
| Host dispatch 拒绝所有 | ✅ 拒绝 | ❌ | ❌ |
|
||||
| 资源白名单 | N/A | ✅ 4种 | ❌ 无限制 |
|
||||
| 参数强制绑定 | N/A | ✅ 自动填+拒绝跨界 | ❌ |
|
||||
| `cli_scope` 自我修改阻止 | N/A | ✅ 拒绝 | ❌ |
|
||||
| Post-handler rows 过滤 | N/A | ✅ scopeField | ❌ |
|
||||
| Sessions oracle 防护 | N/A | ✅ fail-closed | ❌ |
|
||||
| Command gate 斜杠命令 | ✅ | ✅ | ✅ |
|
||||
| Approval gating（非host） | N/A | ✅ | ✅ |
|
||||
|
||||
**关键 gotcha：** group-scoped agent 可以通过 `ncl groups config get` 读到自己的完整 config（包括 `cli_scope` 字段），所以知道自己在 `group` 范围内。但由于 `cli_scope` 参数被第 74-77 行硬阻止，不能修改自己的 scope。
|
||||
Reference in New Issue
Block a user