permissions

package
v0.107.11 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	Normal     = "normal"
	Plan       = "plan"
	AutoEdit   = "auto_edit"
	FullAccess = "full_access"
	Always     = "always"
	AutoReview = "auto_review"
)

Variables

This section is empty.

Functions

func CommandPrefix

func CommandPrefix(tokens []string) []string

CommandPrefix returns the leading words of a command that identify what it does, e.g. `git checkout` for `git checkout main` and `npm run dev` for `npm run dev --x`.

func IsEdit

func IsEdit(tool string) bool

func IsReadOnlyCommand

func IsReadOnlyCommand(command, shell string) bool

IsReadOnlyCommand reports a shell command whose every simple command only reads. The list is an allow list on purpose: unknown commands and aliases are not read-only.

func IsReadOnlyTool

func IsReadOnlyTool(tool string) bool

IsReadOnlyTool reports tools that only read inside the run's authorized roots; the root policy, not this list, keeps them from reading elsewhere.

func ProjectRulesPath

func ProjectRulesPath(root string) (string, error)

ProjectRulesPath is the project-scope rules file for an absolute project root. It lives in the K-brain data directory so that remembering a rule never writes into the user's repository.

func ProjectRulesPathIn

func ProjectRulesPathIn(dir, root string) (string, error)

ProjectRulesPathIn is ProjectRulesPath for the data directory dir.

func RemoveRule

func RemoveRule(path, id string) (bool, error)

RemoveRule deletes a rule by ID and reports whether it existed.

func SplitCommand

func SplitCommand(command, shell string) ([][]string, bool)

SplitCommand splits a shell command into the simple commands it runs, each as its words with quotes removed. ok is false whenever the command could run something the words do not show: command or process substitution, subshells and script blocks, control keywords, redirection to anything but the null device, input redirection, comments, leading variable assignments, and wrappers such as sudo, xargs, eval or `bash -c`.

Unknown shells are parsed strictly: a construct that separates commands in any supported shell separates them here, and anything the shells read differently fails.

func Suggest

func Suggest(req Request, opts Options) []string

Suggest returns the rules that "allow and remember" would store for a request, or nil when it should only be allowed once. Shell commands get one prefix rule per simple command (read-only ones are skipped when opts lets them through anyway); edits get their directory.

func UserRulesPath

func UserRulesPath() (string, error)

UserRulesPath is the user-scope rules file in the K-brain data directory.

func UserRulesPathIn

func UserRulesPathIn(dir string) string

UserRulesPathIn is the user-scope rules file of the data directory dir.

func Validate

func Validate(mode string) error

Types

type Decision

type Decision struct {
	Effect Effect
	Source Source
	// Rule lists the rules that decided, comma separated when several segments of
	// one command matched different rules.
	Rule  string
	Scope Scope
}

Decision is the outcome of Evaluate. An empty Effect means no rule decided and the caller should ask.

func Evaluate

func Evaluate(req Request, opts Options, sets ...RuleSet) Decision

Evaluate decides a request from the rule sets. Deny rules win over allow rules and over read-only access in every scope. A shell command is allowed only when each of its simple commands is covered, by a rule or, with AllowReadOnly, by being read-only; a command that cannot be split safely is never decided by a rule.

type Effect

type Effect string

Effect is what a matching rule does to a gated tool call.

const (
	Allow Effect = "allow"
	Deny  Effect = "deny"
	// Ask is never stored. Evaluate returns it when a command cannot be checked
	// against the deny rules that exist for its tool, so that the caller asks even
	// in a mode that would otherwise allow it.
	Ask Effect = "ask"
)

type File

type File struct {
	Version        int          `json:"version"`
	ProjectRoot    string       `json:"project_root,omitempty"`
	ImportedLegacy bool         `json:"imported_legacy,omitempty"`
	Rules          []StoredRule `json:"rules"`
}

File is the on-disk format of every scope.

func LoadFile

func LoadFile(path string) (File, error)

LoadFile reads a rules file. A missing file is an empty rule set; a corrupt one is an error, never silently an empty set.

type Options

type Options struct {
	// ProjectRoot resolves relative path rules and relative request paths.
	ProjectRoot string
	// AllowReadOnly lets read-only tools and commands through without a rule.
	AllowReadOnly bool
}

type Request

type Request struct {
	Tool    string
	Command string
	Shell   string
	// Poll marks a call that only reads the output of a process or terminal the
	// session started (wait, status, read_log, ReadTerminal); Command is its id.
	Poll bool
	// OtherDir marks a command that runs outside the session's working directory (a
	// cwd argument): judged as if a cd came first.
	OtherDir bool
}

Request is one gated tool call. Command is the command line for shell tools and the target path for file tools; Shell names the shell that will run the command, and an empty Shell parses strictly.

type Rule

type Rule struct {
	Tool    string
	Pattern string
	Prefix  bool
	// contains filtered or unexported fields
}

Rule is a parsed permission rule, written like Claude Code's:

Bash(npm test:*)   commands starting with `npm test`
Bash(git status)   exactly `git status`
Edit(src/**)       edits and writes under src/ of the project root
mcp__srv__tool     every call of that tool

func ParseRule

func ParseRule(text string) (Rule, error)

ParseRule parses and normalizes a rule string.

func (Rule) String

func (r Rule) String() string

type RuleSet

type RuleSet struct {
	Scope Scope
	Rules []StoredRule
}

RuleSet is the rules of one scope.

func LoadRuleSet

func LoadRuleSet(path string, scope Scope) (RuleSet, error)

LoadRuleSet reads one scope's rules file.

func LoadUserRules

func LoadUserRules() (RuleSet, error)

LoadUserRules reads the user-scope rules. The first time, when no rules file exists yet, it imports the TUI's legacy permissions.json and leaves that file as it is.

func LoadUserRulesIn

func LoadUserRulesIn(dir string) (RuleSet, error)

LoadUserRulesIn is LoadUserRules for the data directory dir.

type Scope

type Scope string

Scope says where a rule is stored and how far it reaches.

const (
	ScopeSession Scope = "session"
	ScopeProject Scope = "project"
	ScopeUser    Scope = "user"
)

func DefaultScope

func DefaultScope(text string) Scope

DefaultScope is where "allow and remember" stores a rule. A relative path rule such as Edit(sub/**) names a folder of the project it was approved in, so it stays with that project; command, tool and absolute path rules apply in every project.

type Source

type Source string

Source explains why Evaluate allowed a call without asking.

const (
	SourceRule     Source = "rule"
	SourceReadOnly Source = "read_only"
)

type StoredRule

type StoredRule struct {
	ID            string    `json:"id"`
	Rule          string    `json:"rule"`
	Effect        Effect    `json:"effect"`
	CreatedAt     time.Time `json:"created_at"`
	SourceSession string    `json:"source_session,omitempty"`
}

StoredRule is one rule as kept on disk.

func AddRule

func AddRule(path, projectRoot string, rule StoredRule) (StoredRule, error)

AddRule stores a rule, normalized, unless the same rule with the same effect is already there; it returns the stored entry either way. projectRoot is recorded in project files so that they can be listed by their project.

Jump to

Keyboard shortcuts

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