policy

type AllowAllPDP ¶

type AllowAllPDP struct{}

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

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

type AllowAlwaysToolPolicy ¶ added in v0.1.160

type AllowAlwaysToolPolicy struct {
	TTL     time.Duration
	MaxUses int
}

AllowAlwaysToolPolicy permits every call with default TTL and max_uses. Useful for tests and for operators who don't have custom rules — the role-grant check is still the gate.

func (p AllowAlwaysToolPolicy) Evaluate(_ context.Context, _ EvaluationInput) (ResolvedToolPolicy, error)

type AllowlistSpec ¶ added in v0.1.160

type AllowlistSpec struct {
	// ContextKey is the field in EvaluationInput.Context to check.
	ContextKey string `yaml:"context_key" json:"context_key"`
	// Allowed is the set of acceptable values.
	Allowed []string `yaml:"allowed" json:"allowed"`
	// MatchMode: "equals" (default) | "any_of_list" (context value is a list, any matches)
	MatchMode string `yaml:"match_mode,omitempty" json:"match_mode,omitempty"`
}

type AuthorizeRequest ¶ added in v0.1.160

type AuthorizeRequest struct {
	PrincipalID string `json:"principal_id"`
	Action      string `json:"action"`
	Resource    string `json:"resource,omitempty"`
	OrgID       string `json:"org_id,omitempty"`
}

AuthorizeRequest is the JSON payload from plugin → host. Field names map to saas-starter's Decide RPC for trivial pass-through.

type AuthorizeResponse ¶ added in v0.1.160

type AuthorizeResponse struct {
	Allowed bool   `json:"allowed"`
	Reason  string `json:"reason,omitempty"`
}

AuthorizeResponse is the JSON payload from host → plugin.

HTTP semantics:

• 200 + Allowed=true → plugin proceeds
• 200 + Allowed=false → policy deny; plugin surfaces Reason
• 5xx → fail-closed; plugin treats as deny (never as allow)

type Authorizer ¶ added in v0.1.160

type Authorizer interface {
	// Authorized reports whether the principal on ctx is
	// permitted to perform action on resource.
	//
	// **Three return values, three failure modes:**
	//
	//   - (true, "", nil)        — proceed
	//   - (false, reason, nil)   — policy says no; surface reason
	//   - (false, "", err)       — backend failure (network, etc).
	//                              Caller decides whether to fail
	//                              closed (recommended) or treat
	//                              the operation as best-effort.
	//
	// Distinct (false, reason, nil) vs (false, "", err) semantics
	// matter: a clean policy deny is the model's responsibility to
	// handle (retry differently, ask for help). A backend error is
	// an operational issue (saas-starter unreachable) — the model
	// can't recover by retrying with different args.
	Authorized(ctx context.Context, action, resource string) (allowed bool, reason string, err error)
}

Authorizer is the plugin-facing permission interface.

**Why this is separate from Decider.** Plugin authors should never construct a PDPRequest by hand. The plugin doesn't know about caveats, delegation proofs, manifest declarations, or risk levels — those are host concerns. The plugin asks one question: "may the calling principal do action X on resource Y?" and gets a yes/no with a reason.

Authorizer wraps a Decider. The wrapping handles:

• Pulling the Principal from ctx (placed by the principal interceptor — see core/agents/principal_interceptor.go)
• Building the PDPRequest with the right Toolbox identity
• Caching positive decisions briefly to avoid hammering saas-starter when a plugin loops over many resources
• Mapping policy denies into a clear (false, reason) shape

**Plugin authors:** read PLUGIN_AUTHORS.md. The short version is `policy.AuthorizerFromContext(ctx).Authorized(ctx, action, resource)` returns `(allowed bool, reason string, err error)`. Use it for sub-operation gating within a tool that's already outer-authorized; never as a substitute for declaring permissions in your manifest.

func AuthorizerFromContext(ctx context.Context) Authorizer

func NewCallbackAuthorizer(socketPath string, timeout time.Duration) Authorizer

func NewCallbackAuthorizerFromEnv() Authorizer

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 CaveatPrecheck ¶ added in v0.1.160

type CaveatPrecheck func(ctx context.Context, in EvaluationInput) error

CaveatPrecheck runs at mint time to decide if the caller may proceed. Returns nil = proceed; non-nil error = deny with reason. Stateful caveats (rate_limit) are the typical implementers.

type CaveatProducer ¶ added in v0.1.160

type CaveatProducer func(in EvaluationInput) (any, error)

CaveatProducer computes a caveat value from the call context at token-mint time. The output is what the verifier matches at plugin side.

Example: a "ci_status" caveat producer reads in.Context["ci_status"] and returns the value, baking the snapshot into the token. If CI status changes between mint and verify, the verifier still sees the snapshot — that's correct: the gateway authorized THIS call based on THIS state.

type CaveatProducerFactory ¶ added in v0.1.160

type CaveatProducerFactory func(spec CaveatSpec) (producer CaveatProducer, precheck CaveatPrecheck, err error)

CaveatProducerFactory builds a CaveatProducer + a deny-at-mint pre-check from a YAML spec. Called once per tool policy at load time.

Returns:

• producer (optional): if non-nil, runs at mint time to compute a value baked into the token's caveats map.
• precheck (optional): if non-nil, runs at mint time. nil return = mint-allowed; non-nil error = mint-deny with reason. Used for stateful caveats like rate_limit that decide allow/deny at the gateway, no token value needed.

At least one of (producer, precheck) must be non-nil. Factories that return both are valid (snapshot + state check).

type CaveatSpec ¶ added in v0.1.160

type CaveatSpec map[string]any

CaveatSpec is the YAML-derived configuration for a single caveat instance. Each registered caveat factory parses Spec into its concrete type (e.g. TimeWindowSpec for time_window).

Using map[string]any keeps the YAML parser caveat-agnostic — it just collects Spec fields and hands them to the factory.

type CaveatVerifier ¶ added in v0.1.160

type CaveatVerifier func(value any) error

CaveatVerifier checks a single caveat against the call context. Return nil to accept; return error (with reason) to reject.

type CaveatVerifierFactory ¶ added in v0.1.160

type CaveatVerifierFactory func(spec CaveatSpec) (CaveatVerifier, error)

CaveatVerifierFactory builds a CaveatVerifier from a YAML spec. Plugins instantiate these at startup from the same YAML the gateway used; the spec carries the policy parameters the verifier needs.

For caveats whose verification depends ONLY on the token's snapshot (no spec needed at verify time), the factory ignores spec and returns a verifier that closes over the snapshot.

type CeilingPDP ¶ added in v0.1.160

type CeilingPDP struct {
	// Inner is the role-grant PDP (typically SaasPDP). Required.
	Inner PDP

	// Manifest is the plugin's declared authority. The ceiling
	// check uses Manifest.Allows(action, resource).
	Manifest PermissionPolicy

	// RequireManifest controls behavior when Manifest is empty
	// (zero PermissionPolicy):
	//
	//   - false (default during M4 rollout): empty manifest =
	//     "no ceiling enforced", every action passes through to
	//     Inner. This preserves backwards-compat with plugins
	//     that haven't declared permissions yet.
	//
	//   - true (after M4 enforcement flip): empty manifest =
	//     "no actions allowed", every action denied. This is the
	//     production target: every plugin MUST declare its
	//     permissions before the host accepts it.
	//
	// Operators flip this via CODEFLY_PDP_REQUIRE_MANIFEST=true
	// once every plugin has been audited.
	RequireManifest bool
}

CeilingPDP enforces the manifest declarations as the maximum authority a plugin can ever exercise — even if a saas-starter role grants more, this layer denies actions outside the manifest.

**Why this wrapper exists separately from the inner PDP.** The role-grant check (saas-starter) and the manifest-ceiling check answer different questions:

• Role-grant: "is this principal CURRENTLY allowed to do X?" (mutable; revokable by an admin in real time)
• Manifest-ceiling: "does this plugin's manifest CLAIM the authority to do X?" (set at install; immutable until re-install with a new manifest)

Putting them in the same wrapper makes the order explicit:

1. Manifest ceiling — fast, local, fail-loud on undeclared
2. Inner PDP (typically saas-starter) — slower, remote, deals with role grants and approval flows

First-deny-wins. If the manifest doesn't declare the action, the inner PDP is never consulted — saves a network round-trip for actions the plugin couldn't perform anyway.

**Why this is "defense in depth."** Without the ceiling, a compromised plugin could have an admin-mistake role grant expanded into authority the user never reviewed. With the ceiling, the install-time review IS the contract — the plugin can never silently exceed it, no matter what role grants happen later.

func NewCeilingPDP(inner PDP, manifest PermissionPolicy, requireManifest bool) CeilingPDP

func (c CeilingPDP) Evaluate(ctx context.Context, req *PDPRequest) PDPDecision

type Decider ¶ added in v0.1.160

type Decider = PDP

Decider is the host-facing interface for permission decisions.

Conceptually identical to PDP — the same Evaluate signature. The alias exists for *documentation clarity*: when reading host code (Mind, gateway, CLI) alongside plugin code, "Decider" pairs naturally with "Authorizer" — different audiences, different shapes, same engine underneath.

┌──────────────┐      ┌──────────────┐
│ host (Mind,  │      │ plugin       │
│  gateway)    │      │              │
└──────────────┘      └──────────────┘
      │                       │
      │ Decider                │ Authorizer
      │ (full PDPRequest +     │ (action, resource → bool)
      │  PDPDecision shape)    │
      ▼                       ▼
   ┌─────────────────────────────────┐
   │ Same underlying engine          │
   │ (CeilingPDP → SaasPDP → … )     │
   └─────────────────────────────────┘

Implementations:

• SaasPDP (pdp_saas.go) — calls saas-starter's Decide RPC
• CeilingPDP (pdp_ceiling.go) — manifest enforcement wrapper
• ShadowPDP (pdp_shadow.go) — observability-only wrapper
• JSONPDP (pdp.go) — file-backed allow-list for dev/test
• FakePDP (testharness/pdp.go) — programmable test double

Production hosts compose the stack via BuildPDP (pdp_mode.go).

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 DecisionEvent ¶ added in v0.1.160

type DecisionEvent struct {
	// Toolbox + Tool — what was being authorized.
	Toolbox string
	Tool    string

	// PrincipalID — who was asking. Empty when no Principal was
	// stamped on the call (legacy paths).
	PrincipalID string

	// PrincipalKind — "human" | "service" | "agent" | "" if unset.
	PrincipalKind string

	// AgentID — publisher/name:version for kind=agent; empty otherwise.
	AgentID string

	// DelegationDepth — 0 if the call wasn't delegated; else the
	// length of the delegation chain. Useful for "show me deeply-
	// delegated calls" audit queries.
	DelegationDepth int

	// Decision — the verdict.
	Decision PDPDecision

	// Latency — wall time from PDP entry to verdict. Includes
	// network calls to the auth backend; useful for SLI alerting.
	Latency time.Duration

	// CacheHit — true if the decision came from local cache (no
	// backend round-trip).
	CacheHit bool

	// FailClosed — true if the backend was unreachable and the PDP
	// defaulted to deny. Distinct from a normal Deny.
	FailClosed bool
}

DecisionEvent describes one PDP decision for observability. Carries the structured fields downstream backends (logs, metrics, traces) need. Fields are flat / primitive so backends don't need codec tricks to serialize.

type DelegationLink ¶ added in v0.1.160

type DelegationLink struct {
	// PrincipalID is the lender at this link.
	PrincipalID string

	// Kind mirrors Principal.Kind for the lender.
	Kind string

	// DisplayName mirrors Principal.DisplayName for the lender.
	// Surfaced in audit + approval UI; not authoritative for auth.
	DisplayName string

	// GrantID is the saas-starter delegation_grants.id row that
	// authorized this hop. Lets auditors trace from a tool call back
	// to the exact grant that allowed it. Empty if this link
	// pre-dates the delegation_grants table (legacy delegation).
	GrantID string
}

DelegationLink is one node in a chain of authority lending. Carries enough to audit who-lent-what without requiring a roundtrip to saas-starter to resolve.

type DenyAllPDP ¶

type DenyAllPDP struct{}

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

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

type DenyAlwaysToolPolicy ¶ added in v0.1.160

type DenyAlwaysToolPolicy struct {
	Reason string
}

DenyAlwaysToolPolicy is the symmetric opposite: refuses every call with the supplied reason. Useful for kill-switch-style configurations ("temporarily block all force-push tool calls").

func (p DenyAlwaysToolPolicy) Evaluate(_ context.Context, _ EvaluationInput) (ResolvedToolPolicy, error)

type EscalationDecision ¶ added in v0.1.160

type EscalationDecision int

EscalationDecision is the grantor's verdict.

const (
	EscalationDecisionUnspecified EscalationDecision = iota
	// EscalationApproved: grantor approved; the gateway minted
	// a fresh ScopedAuthorization (in EscalationResult.Token).
	EscalationApproved
	// EscalationDenied: grantor explicitly refused. Reason in
	// EscalationResult.Reason.
	EscalationDenied
	// EscalationTimedOut: nobody decided within the request's
	// Timeout. Distinct from EscalationDenied so the SDK can
	// surface "no answer yet" vs "explicit no".
	EscalationTimedOut
)

func (d EscalationDecision) String() string

type EscalationGrantor ¶ added in v0.1.160

type EscalationGrantor interface {
	// Request submits the escalation, blocks until decided OR
	// the request's Timeout elapses, returns the result.
	//
	// Errors are for INFRASTRUCTURE failures (network,
	// auth-backend down). A grantor-decided deny is NOT an
	// error — it's EscalationResult{Decision: EscalationDenied,
	// Reason: ...}. The SDK treats infrastructure errors as
	// fail-closed (the action doesn't proceed); a deny is
	// distinguished from a timeout so the model knows whether
	// to retry differently or give up.
	Request(ctx context.Context, req EscalationRequest) (*EscalationResult, error)
}

EscalationGrantor is the interface mind/saas-starter implements. Concrete implementations route the request through their notification + approval pipeline (Slack, in-app inbox, email, etc.) and return the grantor's verdict synchronously.

**Why this is a one-method interface.** The agent SDK's flow is: build a request, call Request, get a result. Anything richer (the request_id mid-flight, polling, etc.) is the implementation's concern.

**Why core defines the interface but no implementation.** Core has zero dependency on saas-starter (one-way arrow). Operators implementing this interface call their own RequestDelegation / WaitForDelegation RPCs and translate to/from these types.

func GetGlobalEscalationGrantor() EscalationGrantor

type EscalationRequest ¶ added in v0.1.160

type EscalationRequest struct {
	// Action and Resource are what's being requested. Must match
	// the failed authorization attempt — the elevated token
	// will authorize EXACTLY this (action, resource).
	Action   string
	Resource string

	// Principal is who's requesting. Bound to the spawn-time
	// principal so the plugin can't request escalation as
	// someone else.
	Principal *Principal

	// Justification is the human-readable reason this principal
	// needs the action right now. Surfaced to the grantor in
	// the approval UI. Required — empty justifications are
	// rejected; without one, the grantor has no basis to decide.
	//
	// Examples:
	//   "PR has 2 approvals, CI green, auto-merge label"
	//   "Customer support ticket #123 needs db access"
	//   "Out-of-hours hotfix for INC-456"
	Justification string

	// Grantor optionally targets a specific approver or role
	// ("user:antoine", "team:engineering", "role:admin"). Empty
	// means "the saas-starter default approver chain for this
	// (action, resource)" — typically anyone with the matching
	// role assignment.
	Grantor string

	// Timeout caps how long RequestEscalation blocks. Defaults
	// to 5 minutes if zero. A timeout produces a timeout-deny
	// response (caller distinguishes from a grantor-deny).
	Timeout time.Duration

	// Context carries metadata for the approval UI (PR number,
	// commit sha, etc.). Same shape as EvaluationInput.Context
	// so callers can pass through without translation.
	Context map[string]any

	// PriorRequestID, when set, references a previous
	// RequireApproval decision that triggered this escalation.
	// The grantor can correlate the request with the failed
	// authorization attempt in audit logs.
	PriorRequestID string
}

EscalationRequest is the input to RequestEscalation. The agent SDK builds one from the failed authz attempt + the plugin's caller-supplied justification.

**Why a separate type from PDPRequest.** PDPRequest is for fast authorization decisions (microseconds). EscalationRequest can block for minutes waiting for human approval; carries notification-relevant fields (justification, requested grantor, urgency) that don't belong in a PDP request.

func (r *EscalationRequest) Validate() error

type EscalationResult ¶ added in v0.1.160

type EscalationResult struct {
	// Decision is the verdict.
	Decision EscalationDecision

	// Token is the encoded ScopedAuthorization minted on
	// approve. Empty on deny / timeout.
	Token string

	// Authorization is the decoded form (same data as Token) for
	// inspection / audit logging.
	Authorization *ScopedAuthorization

	// Reason is human-readable. Required on deny; optional on
	// approve (some approvers add a note explaining why); empty
	// on timeout.
	Reason string

	// Decider is the principal that made the decision. Empty on
	// timeout. Always populated on approve/deny so audit traces
	// which grantor signed off.
	Decider string

	// GrantID is the saas-starter delegation_grants.id row that
	// recorded this decision. Lets auditors trace from a tool
	// call back to the exact grant that allowed it.
	GrantID string
}

EscalationResult is the grantor's response. On Approved, Token carries a ScopedAuthorization the agent can attach to its retry via the standard metadata header.

type EvaluationInput ¶ added in v0.1.160

type EvaluationInput struct {
	Principal *Principal
	Toolbox   string // canonical identity, e.g. "codefly.dev/github-bot:0.1.0"
	Tool      string // dotted action, e.g. "github.merge_pr"
	Resource  string // typed identifier, e.g. "repo:codefly/x"

	// Context is the runtime context for caveat evaluation
	// (ci_status, labels, request body summary, etc.). Tool
	// policies consume this; pass through to caveats.
	Context map[string]any
}

EvaluationInput carries the call context the gateway needs to produce a decision.

type EvaluationResult ¶ added in v0.1.160

type EvaluationResult struct {
	// Token is the encoded ScopedAuthorization, ready to attach
	// to outgoing gRPC metadata via AttachToOutgoingContext.
	Token string

	// Authorization is the decoded form (same data as Token)
	// for inspection / audit.
	Authorization *ScopedAuthorization

	// DecisionPath is a trace-style explanation of how the
	// decision was reached ("manifest-allow → role-grant:
	// editor → tool-policy: ci-green").
	DecisionPath string
}

EvaluationResult is what EvaluateAndMint returns on success.

type ExternalDecision ¶ added in v0.1.160

type ExternalDecision struct {
	// Allow is the verdict.
	Allow bool

	// Reason is required when Allow is false. Surfaces to the
	// model via the gateway's deny path.
	Reason string

	// TTL — token lifetime when Allow=true. Zero uses
	// GatewayEvaluator.DefaultTTL.
	TTL time.Duration

	// MaxUses — single-shot (0 → 1) by default.
	MaxUses int

	// Caveats — name → value pairs to bake into the token.
	// Plugin verifiers must be registered for each name.
	Caveats map[string]any
}

ExternalDecision is what an external engine returns. Maps 1:1 to the gateway's ResolvedToolPolicy plus a deny path.

type ExternalPolicyEvaluator ¶ added in v0.1.160

type ExternalPolicyEvaluator interface {
	Evaluate(ctx context.Context, in EvaluationInput) (ExternalDecision, error)
}

ExternalPolicyEvaluator is the bridge interface. Implementations wrap a Cedar bundle, OPA bundle, or any other rule engine.

**Implementation notes:**

• Evaluate is on the gateway hot path. Cache aggressively inside your implementation (Cedar's PolicySet is already-compiled; OPA's prepared queries are cheap to reuse).

• Return errors only for genuine evaluation faults (engine bug, malformed policy data). A clean policy deny is NOT an error — return ExternalDecision{Allow: false, Reason: ...}. Errors are reported as ErrGatewayDeny by the adapter.

• The Caveats map in ExternalDecision is what gets baked into the ScopedAuthorization. Engines that compute conditional allows (e.g. "allow only when ci_status=green") should snapshot the matched values here so the plugin's verifiers re-check them.

type ExternalToolPolicy ¶ added in v0.1.160

type ExternalToolPolicy struct {
	// Evaluator is the wrapped engine. Required.
	Evaluator ExternalPolicyEvaluator
}

ExternalToolPolicy wraps an ExternalPolicyEvaluator as a ToolPolicy GatewayEvaluator can consume.

Usage:

cedarEngine := myteam.NewCedarEngine(policyBundle)  // your code
gatewayPolicies := map[string]policy.ToolPolicy{
    "codefly.dev/github-bot:0.1.0:*": &policy.ExternalToolPolicy{
        Evaluator: cedarEngine,
    },
}

func (e *ExternalToolPolicy) Evaluate(ctx context.Context, in EvaluationInput) (ResolvedToolPolicy, error)

type FakeBackend ¶ added in v0.1.160

type FakeBackend struct {

	// Err, when non-nil, makes EVERY call return Err. Used to
	// exercise the fail-closed path. Takes precedence over rules.
	Err error
	// contains filtered or unexported fields
}

FakeBackend is an in-memory PermissionsBackend used by tests of SaasPDP and any code that takes a PermissionsBackend. It records calls and answers from a programmable rule set.

Concurrent-safe. Tests of cache behavior under load rely on this.

func NewFakeBackend(defaultAllow bool) *FakeBackend

func (f *FakeBackend) Allow(principalID, action, resource, orgID string) *FakeBackend

func (f *FakeBackend) CallCount() int

func (f *FakeBackend) Calls() []FakeBackendCall

func (f *FakeBackend) Decide(ctx context.Context, principalID, action, resource, orgID, scope string) (bool, string, string, error)

func (f *FakeBackend) Deny(principalID, action, resource, orgID, reason string) *FakeBackend

func (f *FakeBackend) Reset()

type FakeBackendCall ¶ added in v0.1.160

type FakeBackendCall struct {
	PrincipalID  string
	Action       string
	Resource     string
	OrgID        string
	Scope        string
	Decision     bool
	Reason       string
	DecisionPath string
}

FakeBackendCall is one recorded Decide call. Snapshot — safe to retain after Calls() returns.

type GatewayEvaluator ¶ added in v0.1.160

type GatewayEvaluator struct {
	// ToolPolicies maps "<toolbox>:<tool>" or "<toolbox>:*" to
	// the operator's tool policy. Lookups try the exact key
	// first, then the wildcard. nil/missing = manifest-only
	// policy (no operator rules).
	ToolPolicies map[string]ToolPolicy

	// Decider is the inner role-grant check. Typically a
	// SaasPDP that calls saas-starter's Decide RPC.
	Decider Decider

	// Secret is the HMAC key used to sign minted tokens. Must
	// be at least 32 bytes (enforced at Mint time).
	Secret []byte

	// DefaultTTL is the time window applied when the tool
	// policy doesn't specify. Recommended: 120s. Operators
	// who need different windows configure per-tool.
	DefaultTTL time.Duration

	// Metrics, if non-nil, gets every decision recorded.
	Metrics *PDPMetrics
}

GatewayEvaluator is the host-side composer of tool policies and role grants. Hosts (Mind, codefly's gateway, the CLI) construct one of these at startup and call EvaluateAndMint per outgoing CallTool.

Responsibilities:

1. Look up the registered ToolPolicy for the (toolbox, tool).
2. Run the tool policy against the input (manifest ceiling + operator rules).
3. Run the inner Decider (typically SaasPDP) for the role- grant check.
4. If both pass, mint a ScopedAuthorization carrying the resolved decision (action, resource, principal, time window, max uses, computed caveats).
5. Record observability for every decision (allow/deny/error).

The gateway is the FIRST defense layer; the plugin's Guard is the second. Even if a host bug causes the gateway to mint a fraudulent token, the plugin's Guard verifies the signature and — if absent or invalid — falls back to the PDP-via-callback path. Three independent layers; defense in depth.

func GetGlobalGatewayEvaluator() *GatewayEvaluator

func (g *GatewayEvaluator) EvaluateAndMint(ctx context.Context, in EvaluationInput) (*EvaluationResult, error)

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 ManifestCeilingPolicy ¶ added in v0.1.160

type ManifestCeilingPolicy struct {
	Manifest PermissionPolicy
	TTL      time.Duration
	MaxUses  int
}

ManifestCeilingPolicy enforces that the tool MUST be declared in the plugin's PermissionPolicy. Mirrors the M4 CeilingPDP logic at the gateway layer — moves the manifest check upstream of the plugin process.

**Why duplicate the M4 check at the gateway.** Defense in depth. If the gateway evaluates first and denies undeclared actions, the plugin never sees them — minimizing attack surface and audit noise. The plugin's CeilingPDP is still the second defense layer (catches anything the gateway missed).

func (p ManifestCeilingPolicy) Evaluate(_ context.Context, in EvaluationInput) (ResolvedToolPolicy, error)

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 MintInput ¶ added in v0.1.160

type MintInput struct {
	Principal  *Principal // required; supplies PrincipalID/Kind/OrgID
	Action     string     // required
	Resource   string     // optional; "" = any resource
	AudienceID string     // recommended; binds to a specific plugin
	TTL        time.Duration
	MaxUses    int            // 0 → defaults to 1
	Caveats    map[string]any // optional
	NowFunc    func() time.Time
	IDFunc     func() string
}

MintInput carries everything Mint needs to produce a signed token. Fields are required unless tagged optional.

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.

func BuildPDP(mode PDPMode, inner PDP, manifest PermissionPolicy, requireManifest bool, metrics *PDPMetrics) PDP

func NewCallbackPDPFromEnv() PDP

pdp := policy.NewCallbackPDPFromEnv()
guard := policyguard.New(myToolbox, pdp, audience)
agents.Serve(agents.PluginRegistration{Toolbox: guard})

type PDPDecision ¶

type PDPDecision struct {
	// Allow is the load-bearing field. When false (and
	// RequireApproval is also 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

	// RequireApproval signals that the action is conditionally
	// permitted but needs a grantor's approval first (M7+
	// synchronous escalation flow). Distinct from a plain Deny:
	// the agent SDK will turn this into a RequestEscalation call
	// rather than failing the model's plan immediately.
	//
	// Until M7 lands, no PDP returns this — the field is reserved
	// so M7's introduction is a backwards-compatible additive
	// change rather than a breaking enum bump.
	RequireApproval bool

	// ApprovalRequestID is the saas-starter delegation_grants.id
	// row created for a RequireApproval decision. The agent SDK
	// passes this to WaitForDelegation. Empty when RequireApproval
	// is false.
	ApprovalRequestID string
}

PDPDecision is what the PDP returns. Three terminal states:

• Allow=true: action permitted; dispatch proceeds
• Allow=false, RequireApproval=false: refused; surface Reason
• Allow=false, RequireApproval=true: held pending approval; the agent SDK can request escalation and retry (M7+)

"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 PDPMetrics ¶ added in v0.1.160

type PDPMetrics struct {
	// DecisionsTotal is bumped on every Evaluate call, regardless
	// of outcome. Pair with AllowsTotal/DeniesTotal/RequireApprovalsTotal
	// to get the breakdown.
	DecisionsTotal atomic.Int64

	// AllowsTotal — successful authorizations.
	AllowsTotal atomic.Int64

	// DeniesTotal — refused authorizations. A spike here is the
	// signal that triggers operator alerts.
	DeniesTotal atomic.Int64

	// RequireApprovalsTotal — calls that returned RequireApproval
	// (M7+). Until the synchronous escalation flow lands, this stays
	// at zero in production.
	RequireApprovalsTotal atomic.Int64

	// CacheHitsTotal — Decide call short-circuited via the local
	// cache (see SaasPDP, M3+). Used to verify cache effectiveness
	// in load tests.
	CacheHitsTotal atomic.Int64

	// FailClosedTotal — PDP couldn't reach saas-starter (or other
	// backend failure) and defaulted to deny. Critical reliability
	// signal: spikes here mean the auth backend is unreachable.
	FailClosedTotal atomic.Int64

	// LatencyNanosTotal + LatencySamples let callers compute mean
	// decision latency without keeping a histogram. For p99-grade
	// observability operators should plug in a real histogram via
	// the wool span on each call (Tracer adds the span timing).
	LatencyNanosTotal atomic.Int64
	LatencySamples    atomic.Int64
}

PDPMetrics is the lightweight, in-process metric surface for the permission system. We intentionally don't depend on Prometheus or OpenTelemetry here:

1. core/ ships as a library; pulling in Prometheus drags a 10MB+ transitive dependency onto every plugin
2. operators who DO want Prometheus can wire their backend by reading these counters periodically — the type stays simple
3. tests can assert against the counters directly without setting up a metric backend

The fields are atomic.Int64 so callers can read them concurrently with Decide loops. Use Snapshot() to grab a coherent set of values at a single instant.

func (m *PDPMetrics) Reset()

func (m *PDPMetrics) Snapshot() PDPMetricsSnapshot

type PDPMetricsSnapshot ¶ added in v0.1.160

type PDPMetricsSnapshot struct {
	DecisionsTotal        int64
	AllowsTotal           int64
	DeniesTotal           int64
	RequireApprovalsTotal int64
	CacheHitsTotal        int64
	FailClosedTotal       int64
	MeanLatency           time.Duration
}

PDPMetricsSnapshot is an immutable copy of PDPMetrics at one instant. Returned by Snapshot() for stable reads.

type PDPMode ¶ added in v0.1.160

type PDPMode string

PDPMode is the env-driven mode selector for the permission system.

Operators set CODEFLY_PDP_MODE before starting codefly host. The chosen mode determines which PDP wrappers stack on the inner (saas-starter-backed) PDP at startup, controlling how decisions surface in production.

**Why an env var rather than config file.** Mode flipping is an ops-time operation (switching enforce on after a shadow burn-in) that should be a single env-var change + restart, not a code release. Same pattern as CODEFLY_DEBUG, OTEL_*, etc.

const (
	// PDPModeOff disables permission enforcement entirely. NO Guard
	// is wired around the toolbox; every CallTool passes through.
	// Used for development, tests, and any deploy where saas-starter
	// isn't available.
	//
	// **Production should NEVER run with mode=off.** Operators must
	// flip to shadow first (decisions logged) before enforce.
	PDPModeOff PDPMode = "off"

	// PDPModeShadow logs every decision via observability but always
	// returns Allow. Use this DURING the M5 rollout: real PDP runs
	// against real traffic, you watch what would-have-been denied,
	// fix policy drift, then flip to enforce. Without shadow, the
	// first deny in production is also the first time anyone sees
	// what enforce mode would block — high incident risk.
	PDPModeShadow PDPMode = "shadow"

	// PDPModeEnforce is the production target. Decisions are honored
	// (deny short-circuits the call). Only flip to enforce after a
	// burn-in period in shadow mode shows zero false-deny against
	// legitimate traffic.
	PDPModeEnforce PDPMode = "enforce"
)

func ResolvePDPMode() (PDPMode, error)

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 PermissionDeclaration ¶ added in v0.1.160

type PermissionDeclaration struct {
	// Action is the canonical dotted name. Examples:
	//   "github.read_pr", "fs.write", "deploy.staging".
	// May contain "*" for wildcards. Empty Action is invalid.
	Action string `yaml:"action" json:"action"`

	// Resource is the typed resource pattern.
	// Examples: "repo:${ORG}/*", "env:staging", "file:/tmp/*".
	// May contain "*" wildcards. Placeholders (${ORG}, ${WORKSPACE})
	// are expanded at install time, not at PDP-call time.
	// Empty Resource means "any resource of any type".
	Resource string `yaml:"resource" json:"resource"`

	// Reason is a human-readable explanation surfaced in the
	// install-time review. The user sees this when granting or
	// rejecting the plugin's permissions; an empty Reason makes
	// the manifest LESS reviewable, so we require it for
	// "required" entries (see PermissionPolicy.Validate).
	Reason string `yaml:"reason" json:"reason"`
}

PermissionDeclaration is one entry in a plugin's permissions manifest block. Mirrors saas-starter's role_permissions row shape, with a `Reason` field that surfaces in the install-time review UI ("this plugin wants Action X to do Y").

Strings are matched as glob patterns at PDP time:

• "*" matches anything
• "repo:codefly-dev/*" matches any repo path under that org
• "github.merge_pr" matches exactly that action

func (d PermissionDeclaration) String() string

type PermissionPolicy ¶ added in v0.1.160

type PermissionPolicy struct {
	// Required permissions MUST be granted at install. If any
	// required entry has no matching role grant, the install
	// fails. Plugin code can assume required permissions are
	// available.
	Required []PermissionDeclaration `yaml:"required,omitempty" json:"required,omitempty"`

	// Optional permissions enhance functionality. Plugin code
	// must handle their absence gracefully — a denied optional
	// permission must not crash; it must skip the dependent
	// behavior or fall back.
	Optional []PermissionDeclaration `yaml:"optional,omitempty" json:"optional,omitempty"`

	// RiskLevels maps action name → risk tier. Used by the PDP
	// to decide whether an action with role-grant should also
	// require human approval (M7+ flow). Valid values: "low",
	// "medium", "high", "critical". Missing entries default to
	// "low".
	RiskLevels map[string]string `yaml:"risk_levels,omitempty" json:"risk_levels,omitempty"`
}

PermissionPolicy is the YAML-shaped authority block a plugin manifest declares. Example:

permissions:
  required:
    - action: github.read_pr
      resource: "repo:${ORG}/*"
      reason: "Inspect PRs to decide auto-merge eligibility"
    - action: github.merge_pr
      resource: "repo:${ORG}/*"
      reason: "Auto-merge approved PRs with green CI"
  optional:
    - action: github.deploy_staging
      resource: "env:staging"
      reason: "Trigger staging deploy after merge"
  risk_levels:
    github.merge_pr: medium
    github.force_push: critical

**required vs optional:**

• Required entries MUST be granted at install. Without them, the plugin can't function — refusing to install fails fast before any tool call.
• Optional entries CAN be granted, but the plugin advertises graceful degradation when they're not. The plugin must still handle "permission denied" responses for optional actions without crashing.

**risk_levels** annotate actions with a risk tier (low/medium/ high/critical). At PDP time, high-risk actions can require approval (M7 escalation flow) even when the role grants them. Manifest is the source of truth for risk classification — the plugin author knows the impact of their actions best.

func (p PermissionPolicy) All() []PermissionDeclaration

func (p PermissionPolicy) Allows(action, resource string) bool

func (p PermissionPolicy) IsEmpty() bool

func (p PermissionPolicy) RiskLevelOf(action string) string

func (p *PermissionPolicy) Validate() error

type PermissionsBackend ¶ added in v0.1.160

type PermissionsBackend interface {
	// Decide answers "is this principal allowed to perform this
	// action on this resource?" via the backing policy store.
	//
	// Inputs:
	//
	//   - principalID: opaque identifier the principal carries
	//     (saas-starter's principals.id).
	//   - action: dotted name. Mirrors the codefly tool name when
	//     the call is routed from a tool dispatch, but backends
	//     may also see synthetic actions emitted by Authorizer.
	//   - resource: typed identifier ("repo:foo/bar", "env:staging").
	//   - orgID: organization scope. Required when the backend
	//     enforces per-org isolation.
	//   - scope: optional fine-grained scope (saas-starter's
	//     role_assignments.scope column).
	//
	// Outputs:
	//
	//   - allowed: the verdict.
	//   - reason: human-readable when allowed=false. Surfaces to
	//     the model so it can plan around the limitation.
	//   - decisionPath: trace-style explanation
	//     ("role:editor → perm:github.read_pr"). Optional;
	//     backends that can't trace return "".
	//   - err: only for backend faults (network, deserialization).
	//     Policy denies are NOT errors — they're (false, reason, "").
	//     Errors trigger fail-closed at the SaasPDP layer.
	Decide(ctx context.Context, principalID, action, resource, orgID, scope string) (allowed bool, reason, decisionPath string, err error)
}

PermissionsBackend is the THINNEST interface that a saas-starter gRPC client implementation must satisfy. Pulling this out (rather than importing saas-starter's full gen package into core) keeps the dependency graph one-way: core has no compile-time knowledge of saas-starter; saas-starter (or any other backend) wires itself into core via this interface.

**Why a separate interface from Decider/PDP.** Decider speaks "PDPRequest with caveats and delegation_proof"; PermissionsBackend speaks the simpler shape that maps 1:1 to saas-starter's gRPC. SaasPDP is the bridge: it takes a PermissionsBackend and adapts it to the Decider interface, layering caching + observability + metrics on top.

Implementations:

• core/policy/pdp_saas_grpc.go (next session) — concrete client against saas-starter's PermissionService.Decide RPC
• testharness/pdp.go (in-memory) — for tests
• operator-supplied (e.g. Cedar/OPA bridge) — for custom policy

type PermissionsCallbackServer ¶ added in v0.1.160

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

PermissionsCallbackServer is the host-side HTTP server that answers Authorize requests from spawned plugins. One server per plugin spawn; the socket path is unique per spawn so concurrent plugins don't share a listener (and can't cross-query each other's PDPs).

**Lifecycle:**

srv, err := policy.NewPermissionsCallbackServer(decider)
defer srv.Close()
// pass srv.SocketPath() into env, spawn plugin

Close removes the socket file and shuts the listener cleanly. If the plugin process is killed, defer cleanup catches it; an orphaned socket on disk only happens on host crash and is removed on next start (NewPermissionsCallbackServer unlinks existing files at the path).

func NewPermissionsCallbackServer(decider Decider) (*PermissionsCallbackServer, error)

func (s *PermissionsCallbackServer) Close() error

func (s *PermissionsCallbackServer) SocketPath() string

func (s *PermissionsCallbackServer) WithPrincipalProvider(p func() *Principal) *PermissionsCallbackServer

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 Principal ¶ added in v0.1.160

type Principal struct {
	// ID is the saas-starter principals.id UUID. Stable across
	// credential rotations; this is what audit logs reference and
	// what role assignments target.
	ID string

	// Kind is the principal's flavor: "human", "service", or "agent".
	// Used for filtering and UI affordances. NEVER branch on Kind for
	// authorization decisions — that's the auth layer's job, and
	// branching here re-introduces the special-casing the unified
	// model exists to avoid.
	Kind string

	// OrgID is the organization the principal belongs to. Cross-org
	// access requires an explicit cross-org grant, never inferred
	// from the principal alone.
	OrgID string

	// AgentID is the publisher/name:version identifier when Kind is
	// "agent"; empty otherwise. Lets the host correlate a Principal
	// back to a specific agent manifest at install time.
	AgentID string

	// DisplayName is human-readable. NEVER use as an identity key
	// (display names change; IDs don't). Surfaced in audit log
	// previews and approval-request UI.
	DisplayName string

	// Token is the verified credential the principal presented. Held
	// here so downstream layers (PDP, audit) can include it in
	// requests without re-extracting from gRPC metadata. Format is
	// opaque to most callers — the PDP knows whether it's JWT,
	// Biscuit, or something else.
	Token string

	// ExpiresAt is when the credential expires. Independent of the
	// principal's lifetime in saas-starter (a service principal can
	// live forever; this token might be 15 minutes old). Code that
	// caches Principals MUST honor this — refusing the cache hit
	// past expiry is what prevents stale-credential authority.
	ExpiresAt time.Time

	// DelegationChain records the principals whose authority is
	// being acted on, oldest-first. Empty for non-delegated calls;
	// length 1+ when authority was lent. The actor is always the
	// last entry (or the Principal itself if the chain is empty).
	//
	// Example: User U invokes Agent A; A acquires escalation from
	// User V to merge a PR. The chain on the resulting tool call is
	// [U, V] — A's own ID is the Principal.ID; the chain shows whose
	// authority is in play. Audit logs the full chain verbatim.
	DelegationChain []DelegationLink
}

Principal is the unified identity type for everything codefly authorizes — humans, services, and agents. It exists at the core layer so the runners, agent loader, and PDP can all speak the same vocabulary without one of them owning the others.

**Why one type for humans + services + agents.** The auth layer shouldn't care whether a row in saas-starter's principals table represents Antoine, the auto-merge bot, or Mind. They all hold permissions via the same role-assignment table. Kind is metadata for the UI ("show me my agents") and audit ("filter to humans"), not a fundamental of the auth model. Treating them uniformly is what lets a service principal request escalation from a human principal using the same delegation primitive that a user uses to invoke an agent.

**What this type is NOT.** It's not the credential. The credential (JWT/Biscuit/...) lives in Token; Principal is the resolved identity claims after the credential has been verified. Code that receives a Principal can trust the fields — verification has already happened upstream.

func DecodePrincipalToken(s string) (*Principal, error)

func PrincipalFrom(ctx context.Context) *Principal

func (p *Principal) AsIdentity() map[string]any

func (p *Principal) IsExpired() bool

func (p *Principal) IsExpiredAt(now time.Time) bool

func (p *Principal) Validate() error

type RateLimitSpec ¶ added in v0.1.160

type RateLimitSpec struct {
	PerMinute int    `yaml:"per_minute" json:"per_minute"`
	Scope     string `yaml:"scope,omitempty" json:"scope,omitempty"` // "principal" (default) | "global" | "principal_org"
}

RateLimitSpec configures rate_limit. PerMinute is the maximum number of mint operations per (principal_id, action) tuple in the most recent 60-second window.

**Mint-only.** rate_limit decides at the gateway and emits no caveat into the token. The plugin doesn't know about rate limits — by design, that's a gateway concern. Once the token is minted, rate-limit was already accepted; using it within the (short) TTL is fine.

type ReplayTracker ¶ added in v0.1.160

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

ReplayTracker records token consumption to enforce MaxUses. Plugin holds one of these per Guard. Tracker doesn't survive process restart — that's acceptable: tokens expire in seconds, so a restart-induced replay window is bounded by the token's own expiry.

Implementation: in-memory map keyed by token ID. Entries are pruned lazily — we don't run a background sweeper because tokens self-expire within seconds.

func NewReplayTracker() *ReplayTracker

func (r *ReplayTracker) Consume(sa *ScopedAuthorization) error

func (r *ReplayTracker) Size() int

type ResolvedToolPolicy ¶ added in v0.1.160

type ResolvedToolPolicy struct {
	// TTL is how long the minted token should live. Zero =
	// use GatewayEvaluator.DefaultTTL.
	TTL time.Duration

	// MaxUses caps token reuse. Zero = single-shot (1).
	MaxUses int

	// Caveats produced by the policy. CaveatProducer functions
	// run at allow time to compute caveat values from the call
	// context (e.g. snapshot the ci_status into the caveat).
	CaveatProducers map[string]CaveatProducer
}

ResolvedToolPolicy is what a ToolPolicy returns on allow. It configures the token mint — TTL, MaxUses, plus any caveats the policy wants baked into the token for plugin-side verification.

func (r ResolvedToolPolicy) ResolvedCaveats(ctxData map[string]any) map[string]any

type SaasPDP ¶ added in v0.1.160

type SaasPDP struct {
	// Backend is the saas-starter (or test) implementation that
	// answers Decide. Required.
	Backend PermissionsBackend

	// CacheTTL is how long a positive decision stays valid in the
	// local LRU. Zero disables the cache entirely (every call
	// hits the backend). Recommended: 5-30 seconds for hot paths.
	// Longer TTLs trade staleness for latency.
	CacheTTL time.Duration

	// Metrics, when non-nil, gets every decision recorded via
	// RecordDecision. Wire to Prometheus/OTEL via Snapshot().
	Metrics *PDPMetrics

	// FailClosed controls behavior when Backend returns err. Default
	// (zero value) is fail-closed: backend faults deny. Setting to
	// false would fail-open — STRONGLY discouraged for production.
	// Kept as a field (not a constant) so tests can exercise the
	// fail-open path explicitly.
	//
	// **For production:** leave default. The whole architecture
	// rests on "saas-starter unreachable → calls deny". Without
	// this, a network blip becomes a permission bypass.
	FailClosed bool
	// contains filtered or unexported fields
}

SaasPDP is the production Decider for hosts that authenticate against saas-starter (or any other backend exposing a PermissionsBackend). It adapts the simpler backend shape into the full PDP/Decider interface, layering on:

• Local cache of positive decisions (TTL, configurable)
• NEVER cache denies (a freshly-revoked grant must fail immediately on the next call)
• Observability: every decision goes through RecordDecision so dashboards reflect real production traffic
• Fail-closed: backend errors surface as deny+FailClosed, NEVER as silent allow
• Latency tracking: PDPMetrics gets the wall-time per call

**Why this lives in core, not in saas-starter.** core has no compile-time dependency on saas-starter — SaasPDP takes a PermissionsBackend interface that saas-starter (or any other implementation) wires concretely. The dependency arrow is always saas-starter → core, never the reverse.

**Cache invalidation.** TTL only, no broadcast invalidation in v1. Operators tune Cache TTL per their tolerance for stale allows. M10 hardening adds Postgres NOTIFY-driven invalidation for permission changes.

func NewSaasPDP(backend PermissionsBackend) *SaasPDP

func (s *SaasPDP) Evaluate(ctx context.Context, req *PDPRequest) PDPDecision

func (s *SaasPDP) WithCache(ttl time.Duration) *SaasPDP

func (s *SaasPDP) WithMetrics(m *PDPMetrics) *SaasPDP

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

type ScopedAuthorization ¶ added in v0.1.160

type ScopedAuthorization struct {
	// ID is a unique identifier for THIS specific mint. ULID-
	// shaped (time-ordered, base32). Used for audit correlation
	// and replay tracking.
	ID string `json:"id"`

	// Format is the envelope format tag. v1-hmac is the only
	// recognized value today; future formats (e.g. v2-biscuit
	// for M6) coexist via dispatch on this field.
	Format string `json:"fmt"`

	// Principal claims — match what's stamped on the request ctx.
	PrincipalID    string `json:"principal_id"`
	PrincipalKind  string `json:"principal_kind,omitempty"`
	PrincipalOrgID string `json:"principal_org_id,omitempty"`

	// Action+Resource scope. The verifier matches these against
	// the actual call; mismatch → reject.
	Action   string `json:"action"`
	Resource string `json:"resource,omitempty"`

	// IssuedAtUnix / ExpiresAtUnix bound the time window. Both
	// are unix seconds. ExpiresAt is an absolute deadline; clock
	// skew tolerance is applied at verify time.
	IssuedAtUnix  int64 `json:"iat"`
	ExpiresAtUnix int64 `json:"exp"`

	// MaxUses caps reuse. Most actions are single-shot (1).
	// Bulk operations may opt up. Verifier tracks consumption
	// per-token-id; max_uses=0 is treated as 1 for safety.
	MaxUses int `json:"max_uses,omitempty"`

	// AudienceID is the canonical identifier of the plugin that
	// may verify this token. "" means "any audience" — used in
	// tests; production tokens always set this.
	AudienceID string `json:"audience,omitempty"`

	// Caveats carry per-tool conditions the verifier checks. The
	// keys are well-known names (ci_status, labels, body_hash,
	// ip_range, ...) plus operator-defined extensions. The
	// verifier consults a registered caveat-checker per key;
	// unknown caveats fail closed (refuse to verify).
	Caveats map[string]any `json:"caveats,omitempty"`
}

ScopedAuthorization is a short-lived, signed bearer token that proves "this principal has been authorized for this action on this resource by the gateway, valid for this time window".

See TWO_LEVEL_AUTHZ.md for the full design rationale. Quick recap of the security properties:

• Time-bounded: tokens have an explicit ExpiresAt; expired tokens fail verification.
• Use-bounded: MaxUses caps reuse; the verifier tracks consumption per-token-id in an in-memory LRU.
• Audience-bound: AudienceID names the plugin that may verify; tokens minted for plugin A fail at plugin B.
• Action+resource-scoped: the verifier matches the token's declared (action, resource) against the request — leaked tokens grant minimal authority.
• Per-spawn signing key: the HMAC secret is generated by manager.Load per plugin spawn; secret leak only forges tokens for one plugin's lifetime.

**Wire format.** `<canonical-json>.<base64url-hmac>` — same shape as JWT/HS256 for debuggability (`cut -d. -f1 | base64 -d` shows the envelope as JSON). Distinct format tag (`fmt:v1-hmac`) so future formats (Biscuit, M6) coexist via tag dispatch.

**What this is NOT:**

• Not a JWT. We could have used JWT/HS256 verbatim, but the simpler envelope keeps the format tag explicit (we'll need to migrate to Biscuit) and avoids dragging a JWT library.
• Not encryption. Tokens carry no secrets — they're verified- authorization claims that the verifier matches against the request. Tampering is detected via HMAC; the contents are intentionally readable for debugging.

func Mint(input MintInput, secret []byte) (string, *ScopedAuthorization, error)

func MintEd25519(input MintInput, privateKey ed25519.PrivateKey) (string, *ScopedAuthorization, error)

pub, priv, err := ed25519.GenerateKey(crypto/rand.Reader)

func ScopedAuthFrom(ctx context.Context) *ScopedAuthorization

func Verify(token string, expect VerifyExpectations, secret []byte) (*ScopedAuthorization, error)

func VerifyEd25519(token string, expect VerifyExpectations, publicKey ed25519.PublicKey) (*ScopedAuthorization, error)

type ShadowPDP ¶ added in v0.1.160

type ShadowPDP struct {
	// Inner is the real PDP whose decisions are recorded but
	// ignored. Required.
	Inner PDP

	// Metrics, if non-nil, gets the standard counters bumped per
	// the inner PDP's decision. Lets operators graph "shadow-mode
	// would-deny rate" alongside production allow rate.
	Metrics *PDPMetrics
}

ShadowPDP wraps another PDP and logs its decisions, but ALWAYS returns Allow. Used during M5 production rollout: operators flip `CODEFLY_PDP_MODE=shadow` before flipping to enforce, watch the audit logs for false-deny patterns, and fix policy drift before any developer actually gets locked out of their own tools.

**Design contract:**

• Inner.Evaluate is called for every request — produces the decision the operator WOULD see in enforce mode.
• Decision is logged via RecordDecision (Counter + structured wool entry) so dashboards show "what would have been denied" without affecting plugin behavior.
• Returned decision is always Allow with a reason that makes the shadow nature obvious in any error surface that might accidentally surface it. (It shouldn't — shadow always allows — but defense at the boundary is cheap.)

**What this is NOT:**

• Not a fail-closed wrapper. ShadowPDP can't fail closed by design. If the inner PDP errors, ShadowPDP still allows. The error is logged; no enforcement.
• Not for production enforce mode. Production must use the bare PDP (not Shadow). Operators graduate from Shadow → bare PDP after burn-in.

Usage:

innerPDP := NewSaasPDP(...)
pdp := ShadowPDP{Inner: innerPDP, Metrics: &metrics}
// Plug pdp into PluginRegistration.PDP — every tool call now
// surfaces "what would have happened" in observability.

func NewShadowPDP(inner PDP, metrics *PDPMetrics) ShadowPDP

func (s ShadowPDP) Evaluate(ctx context.Context, req *PDPRequest) PDPDecision

type TimeWindowSpec ¶ added in v0.1.160

type TimeWindowSpec struct {
	StartHour  int      `yaml:"start_hour" json:"start_hour"`
	EndHour    int      `yaml:"end_hour" json:"end_hour"`
	Timezone   string   `yaml:"timezone,omitempty" json:"timezone,omitempty"` // IANA name; default UTC
	DaysOfWeek []string `yaml:"days_of_week,omitempty" json:"days_of_week,omitempty"`
}

TimeWindowSpec configures the time_window caveat. Hours are 0-23 in the configured timezone; DaysOfWeek is a list of strings ("mon", "tue", ...) — empty means "any day".

Both the producer (gateway) and verifier (plugin) check current time against the window. The token carries a snapshot of the SPEC (not the current time), so verifier re-checks against its own clock. This catches drift: even if the gateway's clock was off, the plugin's clock check has the operator-authored window.

type TokenRevocationList ¶ added in v0.1.160

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

TokenRevocationList holds a set of token IDs that must be rejected even with valid signatures. Used to invalidate compromised or otherwise-suspect tokens before they expire.

**Where this fits.** Verify (v1 + v2) accepts tokens based on signature + claims. The TRL is consulted INSIDE the Guard alongside the replay tracker — both check token id; replay rejects "seen before for this token", TRL rejects "this token is revoked, period".

**Distribution.** Operators populate TRL in two ways:

1. Programmatic: call Add(tokenID) when receiving a revocation event (e.g. from saas-starter via Postgres NOTIFY or webhook).

2. File-backed: TrackFile(path) watches a JSON file containing the revoked-id list. Reload on file change. Useful for kubectl-style ConfigMap distribution.

**Why not "always check saas-starter on every call".** It'd be trivially correct, but the M3-era PDP cache exists exactly to avoid that round-trip on every request. TRL is the invalidation channel for the cache: revocations push, the cache reads from local TRL.

func NewTokenRevocationList() *TokenRevocationList

func (t *TokenRevocationList) Add(tokenID string)

func (t *TokenRevocationList) AddMany(tokenIDs []string)

func (t *TokenRevocationList) IsRevoked(tokenID string) bool

func (t *TokenRevocationList) Remove(tokenID string)

func (t *TokenRevocationList) Replace(tokenIDs []string)

func (t *TokenRevocationList) Size() int

type TokenVerifier ¶ added in v0.1.160

type TokenVerifier struct {
	// HMACSecret accepts v1-hmac tokens. Empty disables v1.
	HMACSecret []byte

	// PublicKeys are the ed25519 public keys that accept
	// v2-ed25519 tokens. Multi-key for rotation; first match
	// wins. Empty disables v2.
	PublicKeys []ed25519.PublicKey
}

TokenVerifier verifies scoped-auth tokens, dispatching on the envelope's `fmt:` tag. Holds the keys for each format it accepts. Zero value rejects every token (no keys configured) — callers must explicitly opt in via WithHMACSecret / WithEd25519PublicKey.

func NewTokenVerifier() *TokenVerifier

func (v *TokenVerifier) Verify(token string, expect VerifyExpectations) (*ScopedAuthorization, error)

func (v *TokenVerifier) WithEd25519PublicKey(key ed25519.PublicKey) *TokenVerifier

func (v *TokenVerifier) WithHMACSecret(secret []byte) *TokenVerifier

type ToolPolicy ¶ added in v0.1.160

type ToolPolicy interface {
	// Evaluate runs the policy against the call input. Returns
	// a ResolvedToolPolicy on allow (carrying TTL, MaxUses,
	// caveats to bake into the token) or an error on deny.
	//
	// **Errors are denies, not faults.** A tool policy that
	// returns err means "this call is not allowed by this
	// policy"; the GatewayEvaluator wraps the err with
	// ErrGatewayDeny.
	Evaluate(ctx context.Context, in EvaluationInput) (ResolvedToolPolicy, error)
}

ToolPolicy is the gateway-evaluated rule set per tool. Built-in implementations cover the common cases (manifest declaration check, simple allow-rule); operators implement custom logic for richer policies (Cedar, Rego, business-specific).

**Why an interface rather than a concrete type.** Operators have genuinely different needs — some want declarative YAML, some want Cedar, some want code. The interface hides those choices from GatewayEvaluator; only Evaluate matters for the pipeline.

type VerifyExpectations ¶ added in v0.1.160

type VerifyExpectations struct {
	// Action: the actual call's action. Token must declare
	// the SAME action; mismatch → reject.
	Action string

	// Resource: the actual call's resource. Token's Resource
	// must match exactly OR be empty (token-says-any-resource).
	// Empty Expectations.Resource skips the check.
	Resource string

	// Audience: the verifying plugin's identity. Token's
	// AudienceID must match OR be empty (test tokens). Empty
	// Expectations.Audience skips the check (test fixture).
	Audience string

	// PrincipalID: the principal stamped on the request ctx.
	// Token's PrincipalID must match. Empty skips check.
	PrincipalID string

	// Now: the clock the verifier uses for expiry. Empty →
	// time.Now. Tests pass an explicit clock.
	Now time.Time

	// CaveatVerifiers, when non-empty, are consulted for each
	// caveat key in the token. A caveat key not in this map
	// causes verification to FAIL (unknown caveats are denied
	// — security default; an attacker could try to encode a
	// caveat the verifier doesn't understand).
	CaveatVerifiers map[string]CaveatVerifier
}

VerifyExpectations is what the verifier checks the token's claims against. Empty fields skip the corresponding check.

**The verifier is the contract enforcer.** A token's claims are just JSON until the verifier matches them against runtime reality. Skipping a check (leaving an Expect* field empty) is a security choice the caller makes; document yours.

type YAMLToolPolicies ¶ added in v0.1.160

type YAMLToolPolicies struct {
	Tools []YAMLToolPolicy `yaml:"tools"`
}

YAMLToolPolicies is the top-level YAML structure.

func (y YAMLToolPolicies) Build() (map[string]ToolPolicy, error)

type YAMLToolPolicy ¶ added in v0.1.160

type YAMLToolPolicy struct {
	// ID is the tool key: "<toolbox>:<tool>" or "<toolbox>:*".
	// Examples:
	//   "codefly.dev/github-bot:0.1.0:github.merge_pr"
	//   "codefly.dev/github-bot:0.1.0:*"
	ID string `yaml:"id"`

	// Allow / Deny — exactly one must be true.
	Allow bool `yaml:"allow,omitempty"`
	Deny  bool `yaml:"deny,omitempty"`

	// Reason — required for Deny, optional for Allow.
	Reason string `yaml:"reason,omitempty"`

	// TTL is the token lifetime. Parsed via time.ParseDuration.
	// Examples: "60s", "5m", "1h". Zero/empty uses
	// GatewayEvaluator.DefaultTTL.
	TTL string `yaml:"ttl,omitempty"`

	// MaxUses caps token reuse. Zero/missing → 1 (single-shot).
	MaxUses int `yaml:"max_uses,omitempty"`

	// Caveats maps caveat name → spec. Each name must be
	// registered (built-ins or operator-supplied via
	// RegisterCaveat). Unknown names fail at parse.
	Caveats map[string]CaveatSpec `yaml:"caveats,omitempty"`
}

YAMLToolPolicy is one policy entry. Either Allow or Deny must be true; both true is rejected at parse.