policy

type AllowAllPDP ¶

type AllowAllPDP struct{}

AllowAllPDP allows every call. Identity surface for "no policy configured."

func (AllowAllPDP) Evaluate(_ context.Context, _ *PDPRequest) PDPDecision

type CanonicalRegistry ¶

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

CanonicalRegistry maps a binary name to the toolbox that owns it.

When a plugin's Bash toolbox parses a command and finds the leaf program is in this registry, it MUST refuse and tell the agent to invoke the canonical toolbox instead. The canonical-tool routing is the high-level enforcement layer — the OS sandbox is the belt-and-suspenders below it.

Population:

• At plugin manifest load time, every plugin's `canonical_for:` list contributes to the registry. Each binary name may have exactly one canonical owner; a conflict is a load-time error (caught early, not at first invocation).

• A built-in fallback covers binaries no plugin has claimed yet (`git`, `docker`, `nix`, `kubectl`, `helm`, `curl`, `wget`). Default behavior for the fallback set: DenyMissingToolbox — refuse with a clear "install the X toolbox" hint, instead of silently letting bash run the binary unsupervised.

func NewCanonicalRegistry() *CanonicalRegistry

func (r *CanonicalRegistry) Claim(owner string, binaries ...string) error

func (r *CanonicalRegistry) Lookup(bin string) *Decision

func (r *CanonicalRegistry) Owners() []OwnerEntry

type Decision ¶

type Decision struct {
	// Routed indicates the binary has a canonical toolbox; the bash
	// executor must refuse and direct the caller there.
	Routed bool

	// Owner is the plugin name that owns the canonical surface, or ""
	// for the built-in fallback (no plugin yet ships the toolbox; the
	// binary is denied with a hint to install one).
	Owner string

	// Reason is the human-readable explanation for the routing —
	// suitable for surfacing verbatim in the bash-toolbox error.
	Reason string
}

Decision is the result of looking up a binary in the registry.

type DenyAllPDP ¶

type DenyAllPDP struct{}

DenyAllPDP denies every call. Useful in tests + as a sanity check.

func (DenyAllPDP) Evaluate(_ context.Context, _ *PDPRequest) PDPDecision

type JSONPDP ¶

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

JSONPDP evaluates a JSONPolicy. Construct with NewJSONPDPFromFile or directly via NewJSONPDP for in-memory use (tests).

func NewJSONPDP(p JSONPolicy) *JSONPDP

func NewJSONPDPFromFile(path string) (*JSONPDP, error)

{
  "default": "deny",
  "rules": [
    {"toolbox": "git", "allow": true},
    {"toolbox": "docker", "tool": "docker.list_containers", "allow": true},
    {"toolbox": "web", "allow": false, "reason": "no outbound HTTP from this workspace"}
  ]
}

func (j *JSONPDP) Evaluate(_ context.Context, req *PDPRequest) PDPDecision

type JSONPolicy ¶

type JSONPolicy struct {
	Default string       `json:"default"` // "allow" or "deny"
	Rules   []PolicyRule `json:"rules"`
}

JSONPolicy is a minimal-but-real allow-list. Each rule names a toolbox + tool (or "*" for any) and a verdict. First match wins; the default if no rule matches is Default (typically "deny" for safety, "allow" for development).

Why this exists alongside a Rego target: Rego is great for expressive policies (group membership, attribute-based access), but it's heavy and operators often start with "git is allowed, docker is not." The JSON shape covers that without dragging in the OPA Go library.

Migrate to Rego when you find yourself writing predicates the JSON shape can't express (boolean logic across attributes, time-of-day rules, etc.). Same PDP interface; different evaluator.

type MapExpander ¶

type MapExpander map[string]string

MapExpander is the standard PathExpander backed by an explicit map of placeholder name (without the ${}) → expansion. Use NewExpander to construct one with sensible defaults seeded from the current process (HOME, TMPDIR) plus a caller-supplied WORKSPACE.

Lookups for placeholders not in the map fail loud — that's the contract: a typo in a manifest must surface at load time, never silently expand to "".

func NewExpander(workspace string) MapExpander

func (e MapExpander) Expand(s string) (string, error)

type NetworkPolicy ¶

type NetworkPolicy string

NetworkPolicy mirrors sandbox.NetworkPolicy but is the YAML-facing type. Translation is one-way at policy.Apply time.

const (
	// NetworkDeny severs all network access. Default for new
	// manifests; explicit zero value avoids "what does empty mean?"
	// ambiguity.
	NetworkDeny NetworkPolicy = "deny"

	// NetworkOpen leaves network unrestricted. Explicit opt-in only.
	// Auditors should grep for `network: open` in manifests.
	NetworkOpen NetworkPolicy = "open"

	// NetworkLoopback allows 127.0.0.1 only — required for the
	// agent loader's gRPC handshake to reach the plugin's
	// loopback listener, while denying every external connection.
	// Recommended secure default for plugin manifests.
	NetworkLoopback NetworkPolicy = "loopback"
)

type OwnerEntry ¶

type OwnerEntry struct {
	Binary string
	Owner  string
	Reason string
}

OwnerEntry is one row in a registry snapshot.

type PDP ¶

type PDP interface {
	Evaluate(ctx context.Context, req *PDPRequest) PDPDecision
}

PDP is the policy decision point a toolbox dispatch layer consults before invoking a tool. Implementations:

• AllowAll: always allows; the codefly default while operators migrate. Useful for development.
• DenyAll: always denies; useful in tests + as a sanity check that the wrap is wired (a flipped flag should refuse every call, surfacing the wrap's effect).
• JSONPDP: reads a JSON allow-list from disk. Working default for production until a real Rego policy is in place.
• (operator-supplied) RegoPDP: github.com/open-policy-agent/opa/rego.Rego. Registered via a small adapter the operator writes; codefly does NOT depend on OPA directly (heavy transitive surface).

The interface is intentionally tiny so any of the above is a drop-in replacement.

type PDPDecision ¶

type PDPDecision struct {
	// Allow is the load-bearing field. When false, the toolbox
	// dispatch layer short-circuits with Reason as the user-visible
	// refusal.
	Allow bool

	// Reason is required when Allow is false; ignored when true.
	// Surface verbatim — the model uses it to decide whether to
	// retry with different arguments, escalate to the user, or
	// abandon the path.
	Reason string
}

PDPDecision is what the PDP returns. Allow/Deny are exhaustive — "no decision" maps to Deny per zero-trust. Reason carries a human- readable explanation that surfaces back to the agent so the model understands WHY it was refused (and can plan around it).

type PDPRequest ¶

type PDPRequest struct {
	Toolbox  string         // identity from manifest, e.g. "git"
	Tool     string         // dotted tool name, e.g. "git.status"
	Args     map[string]any // structured arguments (post-decoded)
	Identity map[string]any // caller attribution (agent id, user id, ...)
}

PDPRequest is everything a policy decision point needs to make a call. Mirrors the toolbox CallTool surface so a Rego policy can reason about exactly what's about to happen — toolbox name, tool name, structured arguments, and the calling identity.

Identity is intentionally a free-form map so callers can route whatever attribution context the host has (an agent ID, a user ID, the parent session). The PDP is responsible for interpreting the keys it cares about; unknown keys are ignored.

type PathExpander ¶

type PathExpander interface {
	Expand(s string) (string, error)
}

PathExpander resolves placeholders in path strings: ${WORKSPACE}, ${TMPDIR}, ${HOME}. Implementations are caller-provided so the policy package doesn't need to know how to find the workspace.

type PolicyRule ¶

type PolicyRule struct {
	Toolbox string `json:"toolbox,omitempty"` // "" = any
	Tool    string `json:"tool,omitempty"`    // "" = any (matches with or without dotted prefix)
	Allow   bool   `json:"allow"`
	Reason  string `json:"reason,omitempty"` // surfaced when Allow=false; ignored when true
}

PolicyRule matches a tool call. Empty fields are wildcards (treat as "any"). Allow controls the decision when the rule matches.

type SandboxPolicy ¶

type SandboxPolicy struct {
	ReadPaths   []string      `yaml:"read_paths,omitempty" json:"read_paths,omitempty"`
	WritePaths  []string      `yaml:"write_paths,omitempty" json:"write_paths,omitempty"`
	Network     NetworkPolicy `yaml:"network,omitempty" json:"network,omitempty"`
	UnixSockets []string      `yaml:"unix_sockets,omitempty" json:"unix_sockets,omitempty"`
}

SandboxPolicy is the YAML-shaped permission block a plugin manifest declares. Example:

sandbox:
  read_paths:
    - "${WORKSPACE}"
  write_paths:
    - "${WORKSPACE}"
    - "${TMPDIR}"
  network: deny
  unix_sockets:
    - "/var/run/docker.sock"  # if this plugin needs docker access

Path strings may use ${WORKSPACE}, ${TMPDIR}, ${HOME} placeholders that are expanded at Apply time. Absolute paths pass through.

func (p *SandboxPolicy) Apply(sb sandbox.Sandbox, expand PathExpander) error

sb, _ := sandbox.New()
policy.Apply(&pol, sb, expand)   // configure
cmd := exec.Command("...")
sb.Wrap(cmd)                     // use; no further With* calls

func (p *SandboxPolicy) Validate() error