permission

package
v0.6.4 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package permission owns the coding product's tool authorization policy. It describes tool effects, resolves filesystem scope, and asks an approver when the policy cannot allow an operation automatically.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Access 

type Access struct {
	Action          Action
	Path            string
	Command         string
	ResolvedPath    string
	Location        Location
	Sensitive       SensitiveKind
	ResolutionError string
}

Access is one effect of a validated tool call. Tools fill Path or Command; Service fills ResolvedPath, Location, and Sensitive before applying policy.

type Action 

type Action string

Action describes the kind of access a tool call performs. 

const (
	Read     Action = "read"
	Write    Action = "write"
	Execute  Action = "execute"
	Internal Action = "internal"
)

type ApprovalChoice 

type ApprovalChoice string

ApprovalChoice is the user's response to an approval request. 

const (
	AllowOnce ApprovalChoice = "allow_once"
	Reject    ApprovalChoice = "deny"
)

type ApprovalRequest 

type ApprovalRequest struct {
	Request Request
	Reason  string
}

ApprovalRequest is sent to the product surface when policy returns Ask.

type ApprovalResponse 

type ApprovalResponse struct {
	Choice ApprovalChoice
}

ApprovalResponse is deliberately extensible beyond a boolean so later milestones can add session grants without replacing the transport contract.

type Approver 

type Approver interface {
	Decide(context.Context, ApprovalRequest) (ApprovalResponse, error)
}

Approver obtains a user decision. Implementations must honor ctx cancellation so aborting a run cannot leave a tool preflight blocked.

type Behavior 

type Behavior string

Behavior is the policy outcome for a tool call. 

const (
	Allow Behavior = "allow"
	Ask   Behavior = "ask"
	Deny  Behavior = "deny"
)

type Decision 

type Decision struct {
	Behavior Behavior
	Reason   string
}

Decision is a structured authorization result.

func DefaultPolicy 

func DefaultPolicy(req Request) Decision

DefaultPolicy is the conservative ask-before-changes mode.

type Location 

type Location string

Location describes where a filesystem access resolves relative to the session workspace. 

const (
	LocationUnknown  Location = "unknown"
	Workspace        Location = "workspace"
	OutsideWorkspace Location = "external"
)

type Mode 

type Mode string

Mode is the session-wide baseline applied before any one-off approval. 

const (
	ModeAsk        Mode = "ask"
	ModeAutoEdit   Mode = "auto_edit"
	ModeReadOnly   Mode = "read_only"
	ModeFullAccess Mode = "full_access"
)

func NormalizeMode 

func NormalizeMode(mode Mode) Mode

NormalizeMode keeps missing or unknown persisted values on the conservative default. API handlers still reject invalid values supplied by clients.

func (Mode) Valid 

func (mode Mode) Valid() bool

Valid reports whether mode is accepted from a client or persisted record.

type PathResolver 

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

PathResolver classifies filesystem targets against one canonical workspace.

func NewPathResolver 

func NewPathResolver(workspace string) (PathResolver, error)

NewPathResolver canonicalizes workspace, including symlinks when possible.

func (PathResolver) Resolve 

func (r PathResolver) Resolve(access Access) Access

Resolve enriches a filesystem access with its canonical target and scope. An uncertain target stays LocationUnknown so policy fails closed to Ask.

type Policy 

type Policy func(Request) Decision

Policy maps a resolved request to an authorization decision.

func PolicyForMode 

func PolicyForMode(mode Mode) Policy

PolicyForMode returns the baseline policy for one session permission mode.

type Request 

type Request struct {
	ToolCallID string
	Tool       string
	Args       map[string]any
	Accesses   []Access
}

Request is the complete permission input for one validated tool call.

type SensitiveKind added in v0.6.2 

type SensitiveKind string

SensitiveKind classifies a filesystem target that needs approval on its own merits, independent of where it sits. A secret inside the workspace is still a secret, so Location alone cannot decide these. 

const (
	// NotSensitive is an ordinary file, judged only by Location.
	NotSensitive SensitiveKind = ""
	// SecretFile customarily holds credentials. Reading one puts its contents
	// into the model's context and the durable transcript, so it is never an
	// automatic workspace read.
	SecretFile SensitiveKind = "secret_file"
	// RepositoryInternals is Git's own state. Writing there changes what later
	// git commands do — hooks and config select programs to execute — so it is
	// not an ordinary workspace edit even when edits are enabled.
	RepositoryInternals SensitiveKind = "repository_internals"
)

func ClassifySensitive added in v0.6.2 

func ClassifySensitive(path string) SensitiveKind

ClassifySensitive reports whether path needs approval on its own merits. It matches on names alone: it never opens the file, so it is cheap enough to run on every resolved access and cannot be defeated by the file's contents.

It is deliberately generous. The outcome of a match is one approval prompt, so a false positive costs a click while a false negative leaks a credential.

type Service 

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

Service resolves tool effects, applies policy, and coordinates interactive approval without coupling the reusable agent loop to product permissions.

func NewService 

func NewService(workspace string, policy Policy, approver Approver) (*Service, error)

NewService creates one authorization service for a session workspace.

func (*Service) Authorize 

func (s *Service) Authorize(ctx context.Context, req Request) (Decision, error)

Authorize returns the final decision for a validated tool call.

func (*Service) SetPolicy 

func (s *Service) SetPolicy(policy Policy)

SetPolicy replaces the policy used by subsequent calls. Product code changes it only while a session is idle; the lock also keeps direct callers safe.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.