permission

package

v0.6.0 Latest Latest Go to latest Published: Jul 30, 2026 License: MIT Imports: 8 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ktsoator/or

Links

Open Source Insights

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 ¶

type Access
type Action
type ApprovalChoice
type ApprovalRequest
type ApprovalResponse
type Approver
type Behavior
type Decision
- func DefaultPolicy(req Request) Decision
type Location
type Mode
- func NormalizeMode(mode Mode) Mode
- func (mode Mode) Valid() bool
type PathResolver
- func NewPathResolver(workspace string) (PathResolver, error)
- func (r PathResolver) Resolve(access Access) Access
type Policy
- func PolicyForMode(mode Mode) Policy
type Request
type Service
- func NewService(workspace string, policy Policy, approver Approver) (*Service, error)
- func (s *Service) Authorize(ctx context.Context, req Request) (Decision, error)
- func (s *Service) SetPolicy(policy Policy)

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
	ResolutionError string
}

Access is one effect of a validated tool call. Tools fill Path or Command; Service fills ResolvedPath and Location 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"
)

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 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

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