permissions

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package permissions 实现分级访问控制(AGENTS.md §3.4:有人在场,可交互)。

在 ACP 的 RequestPermission 回调里(工具执行前),按规则集路由裁决:

  • allow → 自动放行(不弹窗)
  • deny → 自动拒绝(不弹窗)
  • ask → 弹前端确认(当前默认行为)

规则维度(命中 = 全部非空约束同时满足,空约束 = 通配):

  • ToolName:ACP ToolKind 字符串(read/edit/execute/...)
  • ActionType:动作分组(read/write/exec),由 ToolKind 派生
  • PathPattern:glob,对 ToolCall 的任一 location 命中即算命中
  • CommandPattern:正则,对从 RawInput 抽取的命令(bash 等)匹配

本包是纯逻辑(无 DB / 无 ACP 依赖),单测注入规则即可(§5.1)。

Index

Constants

View Source
const (
	LevelAllow = "allow" // 自动放行
	LevelAsk   = "ask"   // 弹前端确认
	LevelDeny  = "deny"  // 自动拒绝
)

决策档位(§3.4)。

View Source
const (
	ActionRead  = "read"  // read/search/think/fetch
	ActionWrite = "write" // edit/delete/move
	ActionExec  = "exec"  // execute
	ActionOther = "other" // switch_mode/other/未知
	ActionAny   = "any"   // 通配:规则不限动作
)

动作分组(由 ToolKind 派生,§3.4「按动作类型 read/write/exec」)。

Variables

This section is empty.

Functions

func ActionOfKind

func ActionOfKind(kind string) string

ActionOfKind 把 ACP ToolKind 派生为动作分组(§3.4 read/write/exec)。 未知/空 kind 归 other。

func ExtractCommand

func ExtractCommand(raw any) string

ExtractCommand 从工具 RawInput 抽取命令字符串(镜像前端 extractBashCommand,§4.4)。 覆盖:字符串原样返回;对象取 command/cmd/line;argv 数组拼回单行。抽不到返回空。

Types

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine 规则匹配器(不可变快照,便于并发读)。零值可用(无规则 → 一律 fallback)。

func NewEngine

func NewEngine(rules []Rule) *Engine

NewEngine 构造一个规则匹配器。传入的 rules 按给定 SortOrder 判定(调用方负责排序)。

func (*Engine) Decide

func (e *Engine) Decide(req MatchRequest, fallback string) string

Decide 返回裁决(allow/ask/deny)。无规则命中时返回 fallback(默认 ask)。

type MatchRequest

type MatchRequest struct {
	ToolKind  string   // req.ToolCall.Kind
	Locations []string // req.ToolCall.Locations[].Path(已展平)
	RawInput  any      // req.ToolCall.RawInput(用于抽命令)
}

MatchRequest 一次权限判定的输入(从 acp.RequestPermissionRequest 提取)。

type Rule

type Rule struct {
	ID             string `json:"id"`
	ToolName       string `json:"toolName"`       // 匹配 ACP ToolKind;"" = 任意工具
	ActionType     string `json:"actionType"`     // read/write/exec/other/any;"" 视作 any
	PathPattern    string `json:"pathPattern"`    // glob(对任一 location);"" = 任意路径
	CommandPattern string `json:"commandPattern"` // 正则(对抽取的命令);仅 exec 相关;"" = 任意命令
	Level          string `json:"level"`          // allow | ask | deny
	SortOrder      int    `json:"sortOrder"`      // 优先级:小者先判定
	Enabled        bool   `json:"enabled"`
}

Rule 一条权限规则。空约束字段 = 通配。

命中语义:一条规则命中,当且仅当它的所有非空约束同时被满足(AND)。 规则集按 SortOrder 升序逐条判定,首条命中者决定裁决;无命中 → fallback。

func DefaultRules

func DefaultRules() []Rule

DefaultRules 返回开箱默认规则集(§3.4「只读 allow、写/执行 ask、危险模式 deny」)。 顺序即优先级(前面的先判定)。调用方据此写库(sort_order = 下标)。

设计:

  1. 最先判定「危险命令 deny」——即使后续有宽泛的 allow,也不会让 rm -rf 漏过。
  2. 只读类(read/search/fetch)→ allow:agent 反复读代码无需反复确认。
  3. 写类(edit/delete/move)→ ask:改动有副作用,保留人工裁决。
  4. 命令执行(execute)→ ask:bash 默认需确认(危险模式已被第 1 条 deny 截走)。
  5. 兜底未匹配的 → ask(fallback,在 Engine.Decide 里实现,不入库)。

func ExactMatchRule

func ExactMatchRule(req MatchRequest) Rule

ExactMatchRule builds an "exact match" allow rule from one permission request (§3.4 "allow globally" decision).

When the user picks "allow globally" in the frontend (onRespond("global")), the current request's identity is frozen into a level=allow rule so later "same tool + same command" or "same tool + same path" requests are auto-allowed by the rule engine — globally across sessions/projects (unlike session/project memory, which is in-memory only and dies with the session). The rule is persisted to the DB via the service and takes effect immediately after all live sessions' rule snapshots are refreshed.

Identity selection ("exact match" = every non-empty constraint needed to reproduce the current request, AND semantics):

  • ToolName = req.ToolKind (exact tool, primary discriminator; different kinds never match)
  • ActionType = ActionOfKind(ToolKind) (consistent with kind, for grouping/display)
  • With command (exec kinds): CommandPattern = ^escaped command$ (anchored + escaped, strict full equality)
  • No command with paths (fs kinds): PathPattern from the first location. Read actions generalize to the basename ("read once by name → same-named files anywhere allowed"; reads are side-effect free so name-level generalization matches user intuition). Write actions stay the absolute path (side-effectful; a same-named file in another project must not be silently allowed). The engine's matchPath already matches basename for "/"-free patterns, so no engine change is needed.
  • No command no path: tool + action only (the narrowest expressible "same tool" scope)

Pure logic, no side effects; unit tests verify the request → rule shape directly (§5.1).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL