Skip to content

feat: MCP 管理员工具门控(user_add/user_issue_key/user_revoke_key/audit)——#103 后续 - #104

Merged
Svtter merged 3 commits into
mainfrom
feat/mcp-server
Nov 19, 2026
Merged

Svtter merged 3 commits into
mainfrom
feat/mcp-server

Conversation

@Svtter

@Svtter Svtter commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Follow-up to #103 (merged at 10:02:14, before these commits landed on the branch — see issue below).

内容

#103 的两个管理员门控提交,因合并时序问题未进入 main,本 PR 补上:

  1. b7b38dc — user 管理工具门控:user_add / user_issue_key / user_revoke_key 可铸造凭据,是管理员能力;仅在 --allow-user-management 下注册
  2. 013ca1b — 同类问题排查扩展 + flag 更名:audit 工具读全员安全事件且 prune_days 可抹记录(反取证能力),一并门控;flag 更名 --allow-admin-tools(env STH_ALLOW_ADMIN_TOOLS)。关闭时 agent 在 tools/list 里根本看不到这些工具,只读 user_list 保持开放

验证

  • go test -race ./internal/... 5 包全绿(新增门控/暴露/调用不可达测试)
  • 真实 stdio 冒烟:默认 12 个 tools(管理类只剩 user_list),--allow-admin-tools 后 16 个

背景事故说明

#103 在 2026-11-18 10:02:14 由自动化以 Svtter 身份合并(rs 提交 CAN MERGE 后 4 秒),违反「agents 绝不手动合并」纪律;合并发生在门控提交推送到分支之前,导致本 PR 所补的两个提交未进 main。本 PR 按纪律只开不合并,请人工审阅后手动合并。

Closes #101 的收尾部分(主功能已在 #103 进 main)。

user_add / user_issue_key / user_revoke_key operate on the local SQLite
store with full operator privileges — creating users and minting API
keys — so an agent holding them can escalate from 'upload previews' to
'issue server credentials'. They are admin capabilities and are now only
registered when the human starting the MCP server passes
--allow-user-management (or STH_ALLOW_USER_MANAGEMENT=true); unregistered
tools are invisible in tools/list, so a prompt-injected agent cannot even
discover them. Read-only user_list stays available.

Startup prints a warning when the tools are exposed. Verified over real
stdio: 13 tools by default, 16 with the flag.
Same privilege-escalation class as user_add: the audit tool reads every
user's security events (actor, IP, user agent, login/share history — the
server deliberately exposes no HTTP endpoint for it) and its prune_days
can erase the trail, which is an anti-forensics capability.

Rename the gate to --allow-admin-tools (env STH_ALLOW_ADMIN_TOOLS) since
it now covers user_add / user_issue_key / user_revoke_key / audit; the
tools are not registered at all without the flag, so they are invisible
to tools/list and cannot be discovered by a prompt-injected agent.
Read-only user_list stays available. Verified over real stdio: 12 tools
by default, 16 with the flag.

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

⚠️ CONDITIONAL MERGE

评审详情

总体:默认关闭、fail-closed,门控发生在工具注册阶段(tools/list 里根本不存在),四个 admin 工具全覆盖(mcp.AddTool 全部集中在 internal/cli/mcp.go:86 的 registerMCPTools,13 个非门控 + 4 个门控 = 16 个,与文档一致),测试也同步改了 lifecycle/audit 用例并新增了负向/正向用例。没有发现权限旁路。可以合,但建议先处理下面两点。

Should-fix

  • internal/cli/mcp.go:45:--allow-admin-tools false(空格形式)会被静默当作开启。popBoolFlagWithPresence(internal/cli/cli.go:675)只识别 --flag 与 --flag=value,剩下的 false 落入 out,随后 flags, _, err := parseArgs(args) 把它当 positional 丢弃(runMCP 不检查 positionals),于是 resolveBool(true, true, ...) 返回 true——人以为关了、实际开了,且没有任何告警。--auth 有同样模式,但那里错的方向是安全的,这里是权限闸门。建议 runMCP 对残留 positional 直接报错(如 unexpected argument %q),或在 usage 里明确只支持 --allow-admin-tools=false。
  • internal/cli/mcp_test.go:184 / :339 / :684:新测试都直接构造 mcpConfig{allowAdminTools: true},绕过了真正新增的表面——runMCP 里的 flag 解析 + resolveBool 环境变量解析。也就是说 flag 名写错、=false 覆盖 env、STH_ALLOW_ADMIN_TOOLS 拼错,测试都不会红。建议把配置解析抽成可测的 parseMCPConfig(args []string) (*mcpConfig, error),并补三条断言:默认 false、env=true 生效、--allow-admin-tools=false 覆盖 env(并顺带覆盖上面那条 positional 行为)。

Nits

  • internal/cli/mcp.go:26-27:注释仍写 "whether user-management tools are exposed",但该开关现在也门控 audit(跨用户审计 + prune_days),改成 admin-class tools 以免后续误判范围。
  • CHANGELOG.md:6:同一版本条仍称暴露 "16 tools",与本条新增的"4 个默认不注册"读起来矛盾;建议改成 "16 tools (4 admin-gated)"。README.md:141 的 "Exposed tools mirror the CLI one-to-one" 同理,句内已有说明,可顺手写成 "up to 16"。
  • 范围提醒(非本 PR 必修):delete(不可逆软删)、share/unshare(把预览授权给任意用户)、send(读本机文件)同样是高影响能力却仍默认开放;文档已只声称门控 user/audit,措辞无误,但若目标是"限制被注入的 agent 的破坏面",后续可以考虑同类分组或至少加一条风险提示。

未验证项:无法用工具执行 go test/go build,SDK 对未注册工具返回协议错误的行为(mcp_test.go:167 依赖此点)只能从测试意图推断,未实际运行。


由 review-server-neo 自动生成。新 push 会重新评审。

Details

Comment thread internal/cli/mcp.go
// the CLI functionality as tools. The MCP protocol occupies stdout, so this
// command must not write anything there; diagnostics go to stderr.
func runMCP(args []string, _ io.Writer, stderr io.Writer) error {
args, allowAdminSet, allowAdminFlag, err := popBoolFlagWithPresence(args, "allow-admin-tools")

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[should-fix] internal/cli/mcp.go:45:--allow-admin-tools false(空格形式)会被静默当作开启。popBoolFlagWithPresence(internal/cli/cli.go:675)只识别 --flag 与 --flag=value,剩下的 false 落入 out,随后 flags, _, err := parseArgs(args) 把它当 positional 丢弃(runMCP 不检查 positionals),于是 resolveBool(true, true, ...) 返回 true——人以为关了…

Comment thread internal/cli/mcp_test.go
t.Parallel()

dbPath, _ := newMCPTestDB(t)
cs := newMCPClient(t, &mcpConfig{dbPath: dbPath, allowAdminTools: true})

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[should-fix] internal/cli/mcp_test.go:184 / :339 / :684:新测试都直接构造 mcpConfig{allowAdminTools: true},绕过了真正新增的表面——runMCP 里的 flag 解析 + resolveBool 环境变量解析。也就是说 flag 名写错、=false 覆盖 env、STH_ALLOW_ADMIN_TOOLS 拼错,测试都不会红。建议把配置解析抽成可测的 parseMCPConfig(args []string) (*mcpConfig, error),并补三条断言:默认 false、env=tru…

Address rs review on #104:

- popBoolFlagWithPresence only understands --flag and --flag=value, so
  '--allow-admin-tools false' (space form) silently left admin tools
  ENABLED: the stray token fell into positionals and was dropped. With a
  privilege gate on this command that must fail loudly — parseMCPConfig
  now rejects leftover positionals with 'unexpected argument %q'
- extract parseMCPConfig from runMCP and cover the real parsing surface
  with tests: default off, STH_ALLOW_ADMIN_TOOLS=true, explicit
  --allow-admin-tools=false overriding the env, stray-token rejection,
  and ordinary flag parsing
- nits: mcpConfig comment now says admin-class tools; CHANGELOG and
  README say 'up to 16 tools (4 admin-gated)' instead of a bare 16

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

✅ CAN MERGE

评审详情

上一轮的两个 Should-fix 都已修复,其余 nits 也一并处理:

  • 位置参数静默吞掉的问题已解决:internal/cli/mcp.go:48 新增 parseMCPConfig,internal/cli/mcp.go:58 对残留 positional 直接报错(unexpected argument %q (sth mcp takes only --flags)),--allow-admin-tools false 这种空格形式现在会失败而不是静默开启。方向正确(fail loudly → fail closed)。
  • 解析层测试补齐:internal/cli/mcp_test.go:867 TestMCPParseMCPConfig 覆盖默认 false、--allow-admin-tools、STH_ALLOW_ADMIN_TOOLS=true、--allow-admin-tools=false 覆盖 env,以及空格形式的报错;strings 已在文件 import 中(internal/cli/mcp_test.go:4),不会编译失败。
  • 文档/注释 nits 已修:internal/cli/mcp.go:25-27 注释改为 admin-class tools(含 audit);CHANGELOG.md:6 与 README.md:141 / README.cn.md:157 改为 "up to 16 / 最多 16 个,其中 4 个为管理员门控"。
  • 门控本身仍然正确:所有 mcp.AddTool 都集中在 registerMCPTools(internal/cli/mcp.go:86),四个 admin 工具在 cfg.allowAdminTools 为 false 时根本不注册;user_list 保持可用;开启时有 stderr 提示。

仅剩 nits(不阻塞):

  • internal/cli/mcp_test.go:870 开头两条断言隐含依赖进程环境里 STH_ALLOW_ADMIN_TOOLS 未设置;建议函数入口先 t.Setenv("STH_ALLOW_ADMIN_TOOLS", ""),避免本地/CI 环境残留导致假失败。
  • parseArgs 没有 flag allowlist,拼错的未知 flag(如 --allow-admintools true)会被静默忽略——对本开关是 fail-closed,安全上没问题,但如果想更严格可以给 sth mcp 加一份允许的 flag 集合。
  • 范围提示(原样保留,非本 PR 必修):delete / share / unshare / send 同样是高影响能力但仍默认开放;文档已只声称门控 user/audit,措辞无误。

未验证项:无法用工具执行 go test / go build,上述结论基于代码与测试源码阅读。


由 review-server-neo 自动生成。新 push 会重新评审。

Details

@Svtter
Svtter merged commit fbc8007 into main Nov 19, 2026
3 checks passed
Svtter added a commit that referenced this pull request Nov 19, 2026
feat: admin tools 按身份授权——API key 须属于 admin 用户(#104 后续)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: MCP server 支持——sth mcp 子命令,把 CLI 能力暴露为 MCP tools

1 participant