feat(controller): capability foundation for the L2 permission model (#1220)

[LUOSENGWA]

Capability foundation for the L2 permission model (#1220)

Summary

This PR is step 1 of the #1220 sequencing — the capability model foundation: grantable, queryable, auditable, but gating no existing operation. It adds:

• Human.spec.capabilities — the five-value set from Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §3 (full_access, channel_secrets, external_sources, approval_policy, secret_reveal); unknown values are rejected at admission. CRD schemas (controller + helm) updated, deepcopy regenerated.
• PUT /api/v1/humans/{name} — a new merge-patch capabilities field mirroring the accessibleTeams pattern from feat(controller): add human update endpoint (PUT /api/v1/humans/{name}) #1209: absent = unchanged, explicit list = replace, [] = clear, unknown value = 400 listing the valid set. Stored normalized (deduped + sorted). Admin/manager-only as before — self-grant is structurally impossible (authorizer default-deny, pre-existing pin test).
• auth.HasCapability(caller, cap) — role baseline first (admin/manager true, worker false, human/team-leader set membership with full_access as a meta-implication). A capability never implies team scope; consumers compose the Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §3 check order (role baseline AND TeamMatches AND HasCapability). Populated for L2 humans where the Human CR is already fetched (zero new I/O); SA identities never carry it (Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §5 — leaders never hold capabilities).
• internal/audit — dual-layer audit client (Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §8): an immediate structured log line + append-only daily audit/<YYYY-MM-DD>.jsonl with ETag-optimistic writes (3 retries, 100/200/400 ms + jitter). Closed event schema — never secret values. Wired for capability grant/revoke (one event per changed value).

Interface-stability promise for the follow-on PRs: the Capability type, the five constants, and the HasCapability signature are the consumer contract and will not be renamed.

Design

Decision	Rationale
Five-value set, unknown values rejected at admission	#1220 §3 fixes the value set; open-ended strings would let the audit taxonomy and the UI picker drift. A drift-pin test asserts the set against the spec.
Merge-patch semantics (absent / replace / clear)	Mirrors the accessibleTeams pattern from #1209 — the human-update API is a single merge-patch endpoint, and a third "set" mode would be inconsistent with it.
HasCapability = role baseline first, and never implies team scope	The #1220 §3 check order is role baseline AND TeamMatches AND HasCapability; a helper that implied scope would let a consumer skip TeamMatches and silently widen scope.
SA identities never carry capabilities	#1220 §5: leaders (SA) never hold capabilities. The authenticator never populates the field for SAs (pinned both ways).
Dual-layer audit: log line + JSONL append-only	#1220 §8: the log line is the immediate trail, the JSONL is the durable replayable record. ETag-optimistic append with 3 retries keeps the single-replica deployment conflict-free and makes exhaustion all-or-nothing.
Zero gating	This PR changes no existing decision: no endpoint gains a new rejection, no authorizer path is consulted. The field is data until a consumer PR (per #1220 §12) opts in.

What this PR does not do

• No existing operation is gated or newly rejected — purely additive (verified: HasCapability has zero production call sites; the audit wiring is grant/revoke events only).
• No queryable audit store (Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §13 Q3) and no audit rotation — the durable layer assumes a single controller replica, the embedded and k8s deployment forms today.
• No secret_reveal consumer (reserved value; the secret contract is a follow-on PR).
• No MCP/ACP or worker-app change; the only CRD shape change is the additive capabilities field.

Tests

• merge-patch semantics — apply / dedupe / omit / clear / unknown-value 400 (5 cases)
• HasCapability matrix — admin / manager / L2±value / full_access / worker / leader / nil caller
• value-set drift pin against Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §3 (renaming or dropping a value fails CI)
• Matrix authenticator population ± (L2 human carries the set; SA never does)
• audit client — create / append / retry-on-conflict / exhausted-retries all-or-nothing / 20-way concurrency with no dropped lines / closed-schema secret hygiene (7 tests)
• handler wiring E2E — PUT /humans grant×2 + revoke → JSONL event assertions
• Gates: gofmt / go build ./... / go vet ./... / go test ./... — 22 packages ok, zero failures (baseline + the new internal/audit package). Branch diff scanned: no credential patterns.
• The three commits are independently reviewable: ① CRD + value set + HasCapability + authenticator population ② API field + validation + tests ③ audit client + wiring + docs.

Related

• Implements Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §12 sequencing step 1 (capability foundation).
• Consumers (follow-on PRs, per Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §12): the approval_policy OFF gate for feat(controller): add team-scoped worker tool approval endpoints for L2 humans #1216's already-merged approval endpoints, the mcpServers/remoteSkills restore with external_sources, and feat(controller): add worker channel configuration proxy endpoints #1219 (secret contract) with channel_secrets/secret_reveal.
• feat(controller): add team-scoped worker tool approval endpoints for L2 humans #1216 (merged at f65d6e1a) — its OFF gate is currently a pure role gate; the error text says "pending the Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 design", i.e. the capability check this PR lands.
• feat(controller): add human update endpoint (PUT /api/v1/humans/{name}) #1209 — the human-update merge-patch pattern precedent this PR mirrors.

---

L2 权限模型的 capability 地基（#1220）

摘要

本 PR 是 #1220 定序的第 1 步——capability 模型地基：可授、可查、可审计，但不门控任何现有操作。新增：

• Human.spec.capabilities —— Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §3 五值集（full_access/channel_secrets/external_sources/approval_policy/secret_reveal），未知值准入即拒。CRD schema（controller + helm）已更新，deepcopy 已再生成。
• PUT /api/v1/humans/{name} —— 新增 merge-patch 语义的 capabilities 字段，镜像 feat(controller): add human update endpoint (PUT /api/v1/humans/{name}) #1209 的 accessibleTeams 模式：省略=不变 / 显式列表=替换 / []=清空 / 未知值=400（错误信息列合法值集）。存储前规范化（去重+排序）。沿用 admin/manager 独占——self-grant 结构上不可能（authorizer 默认拒绝，既有钉测试在位）。
• auth.HasCapability(caller, cap) —— 角色基线优先（admin/manager 恒真、worker 恒假、human/team-leader 集成员 + full_access 元值蕴含）。capability 从不蕴含团队范围；消费侧按 Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §3 顺序组合（角色基线 AND TeamMatches AND HasCapability）。L2 human 在 Human CR 已拉取处填充（零新增 I/O）；SA 身份永不携带（Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §5——leader 永不持有 capability）。
• internal/audit —— 双层审计 client（Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §8）：即时结构化日志行 + 每日 audit/<YYYY-MM-DD>.jsonl 追加写（ETag 乐观并发，3 次重试 100/200/400ms + 抖动）。事件为封闭 schema——永不记 secret 值。已接线 capability grant/revoke（每变更值一条事件）。

接口稳定承诺（面向后续 PR）：Capability 类型、五个常量、HasCapability 签名 = 消费契约，不改名。

设计

决策	理由
五值集，未知值准入即拒	#1220 §3 固定值集；开放字符串会让审计分类和 UI picker 漂移。漂移钉测试对值集断言。
merge-patch 语义（省略/替换/清空）	镜像 #1209 的 accessibleTeams 模式——human-update API 是单一 merge-patch 端点，再加第三种 "set" 模式不自洽。
HasCapability = 角色基线优先，且从不蕴含团队范围	#1220 §3 检查顺序 = 角色基线 AND TeamMatches AND HasCapability；若 helper 蕴含 scope，消费侧可能跳过 TeamMatches 而静默扩大范围。
SA 身份永不携带 capability	#1220 §5：leader（SA）永不持有 capability。authenticator 对 SA 永不填充该字段（正负向钉住）。
双层审计：日志行 + JSONL 追加写	#1220 §8：日志行是即时轨迹，JSONL 是持久可回放记录。ETag 乐观追加 + 3 次重试在单副本部署下无冲突，重试耗尽 = 全或无。
零门控	本 PR 不改变任何现有决策：没有端点新增拒绝，没有鉴权路径被咨询。字段是数据，直到消费方 PR（按 #1220 §12）显式接入。

本 PR 不做

• 不门控、不新增拒绝任何现有操作——纯增量（实锤：HasCapability 0 生产调用；审计接线仅 grant/revoke 事件）。
• 无可查询审计库（Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §13 Q3）、无审计轮转——持久层假设单 controller 副本（当前 embedded 与 k8s 部署形态）。
• 无 secret_reveal 消费方（保留值；secret 契约是后续 PR）。
• 不碰 MCP/ACP、worker-app；CRD 形状唯一变化 = additive capabilities 字段。

测试

• merge-patch 语义——应用/去重/省略/清空/未知值 400（5 例）
• HasCapability 矩阵——admin/manager/L2±值/full_access/worker/leader/nil caller
• 值集对 Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §3 漂移钉（改名或删值 CI 即红）
• Matrix 认证填充正负向（L2 human 带值集；SA 永不带）
• 审计 client——创建/追加/冲突重试/重试耗尽原子性/20 路并发无丢行/封闭 schema secret 卫生（7 测试）
• handler 接线 E2E——PUT /humans grant×2 + revoke → JSONL 事件断言
• 门：gofmt / go build ./... / go vet ./... / go test ./...——22 包全 ok、0 失败（基线 + 新 internal/audit 包）。分支 diff 扫描：无凭据形态。
• 三个 commit 各自独立可 review：① CRD+值集+HasCapability+认证填充 ② API 字段+校验+测试 ③ 审计 client+接线+文档。

相关

• 落地 Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §12 定序第 1 步（capability foundation）。
• 消费方（后续 PR，按 Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 §12）：feat(controller): add team-scoped worker tool approval endpoints for L2 humans #1216 已合并审批端点的 approval_policy OFF 门控、带 external_sources 的 mcpServers/remoteSkills 恢复、feat(controller): add worker channel configuration proxy endpoints #1219（secret 契约）带 channel_secrets/secret_reveal。
• feat(controller): add team-scoped worker tool approval endpoints for L2 humans #1216（已合 f65d6e1a）——其 OFF 门控现状 = 纯角色门，错误文案明说 "pending the Design: L2 permission & capability model (worker config, channels, approval, skill catalog) #1220 design" = 本 PR 落地的 capability 检查。
• feat(controller): add human update endpoint (PUT /api/v1/humans/{name}) #1209——本 PR 镜像的 human-update merge-patch 模式先例。