Documentation
¶
Index ¶
- func AuthCheckEvent(configDir string, cfg config.ConfigReader, event *normevent.Event) normevent.Event
- func IsAuthorized(event *normevent.Event) bool
- func IsEventAuthorized(event *normevent.Event) bool
- func IsEventAuthorizedWith(event *normevent.Event, opts AuthOptions) bool
- func IsHarnessAuthorized(event *normevent.Event, harnessRole string) bool
- func IsHarnessAuthorizedWith(event *normevent.Event, harnessRole string, opts AuthOptions) bool
- func IsRecognizedBot(actor normevent.Actor) bool
- func KillSwitchActive(configDir string) (bool, error)
- func MergedConfigAgents(configDir string) ([]config.AgentEntry, error)
- func RequiredActorRole(harnessRole string) normevent.ActorRole
- type AuthOptions
- type EntityDecision
- type EntityEvaluation
- type EntityOutcome
- type ExecutionRef
- type Options
- type TriggeredHarness
- func FilterAuthorizedHarnesses(harnesses []TriggeredHarness, event *normevent.Event) []TriggeredHarness
- func FilterAuthorizedHarnessesWith(harnesses []TriggeredHarness, event *normevent.Event, opts AuthOptions) []TriggeredHarness
- func ListTriggeredHarnesses(ctx context.Context, configDir string, cfg config.ConfigReader, ...) ([]TriggeredHarness, error)
- func MatchHarnesses(candidates []TriggeredHarness, event *normevent.Event) ([]TriggeredHarness, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AuthCheckEvent ¶ added in v0.50.0
func AuthCheckEvent(configDir string, cfg config.ConfigReader, event *normevent.Event) normevent.Event
AuthCheckEvent returns a copy of event to pass to the authorization gate (IsEventAuthorized, IsHarnessAuthorized, FilterAuthorizedHarnesses). When the per-repo config enables OWNERS-file authorization, the copy's actor role is upgraded from the OWNERS and OWNERS_ALIASES files in the parent of configDir. The caller's event is not mutated: the upgraded role is used only for the gate, and CEL evaluation keeps seeing the collaborator-API role.
func IsAuthorized ¶
IsAuthorized reports whether event may dispatch a mutation harness (write threshold). It is equivalent to IsHarnessAuthorized with an empty harness role, which fails closed to write.
func IsEventAuthorized ¶ added in v0.50.0
IsEventAuthorized is the event-level dispatch gate, run once per event before harness enumeration. It returns false when the event is denied for every harness: a nil event, a bot whose ADR 0107 lookup did not recognize a registered role, a human whose role lookup failed, or an actor.role below the lowest per-harness threshold (triage). A true result means at least one harness may be authorized; callers must still filter harnesses with IsHarnessAuthorized or FilterAuthorizedHarnesses.
func IsEventAuthorizedWith ¶ added in v0.54.0
func IsEventAuthorizedWith(event *normevent.Event, opts AuthOptions) bool
IsEventAuthorizedWith is IsEventAuthorized under the policy in opts.
func IsHarnessAuthorized ¶ added in v0.50.0
IsHarnessAuthorized reports whether event may dispatch a harness whose role: field is harnessRole. Event-level exceptions (GitHub label-added, recognized bots, GitHub bot review_submitted) authorize every harness; Jira label-added is such an exception only under IsHarnessAuthorizedWith with AuthOptions.JiraLabelsByEditPermission set. Event-level denials deny every harness; the remaining path requires actor.role to satisfy RequiredActorRole(harnessRole).
func IsHarnessAuthorizedWith ¶ added in v0.54.0
func IsHarnessAuthorizedWith(event *normevent.Event, harnessRole string, opts AuthOptions) bool
IsHarnessAuthorizedWith is IsHarnessAuthorized under the policy in opts.
func IsRecognizedBot ¶ added in v0.50.0
IsRecognizedBot reports whether actor is a bot whose bot-role lookup completed and resolved a registered canonical role (ADR 0107).
func KillSwitchActive ¶
KillSwitchActive reads kill_switch from config in configDir.
func MergedConfigAgents ¶
func MergedConfigAgents(configDir string) ([]config.AgentEntry, error)
MergedConfigAgents loads agent entries from per-repo config directory.
func RequiredActorRole ¶ added in v0.50.0
RequiredActorRole returns the minimum actor.role a harness requires, derived from its role: field per the authorization contract's default thresholds. Observation roles (triage, review) require triage; every other role, including an empty, unknown, or custom role, requires write (fail closed).
Types ¶
type AuthOptions ¶ added in v0.54.0
type AuthOptions struct {
// JiraLabelsByEditPermission turns on the Jira label-added exception:
// a Jira label-added event is authorized without a role threshold,
// because Jira requires the Edit Issues permission to change labels.
// Set it only when a jira authorization provider entry is present and
// selects labels: jira_editors (its default); under allowlist or
// project_roles the poller resolves the label author's actor.role from
// that source and the threshold applies.
JiraLabelsByEditPermission bool
}
AuthOptions carries the configuration-derived inputs to the dispatch gate. The zero value is the default policy: a Jira label-added event takes the per-harness role threshold like any other event.
func AuthOptionsFor ¶ added in v0.54.0
func AuthOptionsFor(cfg config.ConfigReader) AuthOptions
AuthOptionsFor derives the dispatch gate policy from the loaded config's jira authorization provider: Jira label-added events get the Edit Issues exception only when a jira provider entry is present and selects labels: jira_editors (the default for an entry). With no jira entry, or under allowlist or project_roles, they take the role threshold.
type EntityDecision ¶ added in v0.57.0
type EntityDecision struct {
Outcome EntityOutcome
Reason string
}
EntityDecision is an entity-source evaluation's outcome and its reason.
func DecideEntityEligibility ¶ added in v0.57.0
func DecideEntityEligibility(ctx context.Context, ev EntityEvaluation) EntityDecision
DecideEntityEligibility evaluates an entity-source harness predicate and returns exactly one of eligible, non-match, deferred, or denied.
It never converts unresolved data to a non-match: an entity read failure, a malformed entity, or a predicate that the known data does not settle defers the candidate, while a missing gate, a failed authorization, or a predicate that is invalid or fails to evaluate denies it.
type EntityEvaluation ¶ added in v0.57.0
type EntityEvaluation struct {
// Harness names the harness in decision reasons.
Harness string
// Trigger is the harness CEL predicate over entity and event.
Trigger string
// EntitySources reports whether the harness declares valid entity
// sources. Without them the harness is event-only and is denied here.
EntitySources bool
// Event is the prompting event, or nil for an eventless evaluation
// (scheduled discovery or a bound run's recheck), which binds event to
// CEL null.
Event *normevent.Event
// Authorize runs the gate that precedes CEL: the selected harness's
// event-actor gate when Event is set, or the trusted-origin and platform
// eligibility gate when Event is nil. A nil Authorize or an error denies.
Authorize func(context.Context) error
// ResolveEntity resolves the candidate's current normalized entity after
// authorization. An error defers the candidate; it is never a non-match.
ResolveEntity func(context.Context) (*normentity.Entity, error)
}
EntityEvaluation is one entity-source harness predicate check: a required normalized entity and an optional prompting event.
Harnesses without entity sources are not evaluated here; they stay on the unchanged event-only path (MatchHarnesses).
type EntityOutcome ¶ added in v0.57.0
type EntityOutcome int
EntityOutcome is the final decision of one entity-source harness evaluation (ADR 0098, ADR 0147). Only EntityEligible may start a sandbox.
const ( // EntityDenied: the evaluation is not permitted or cannot be performed — // no entity sources, an invalid or failing predicate, or a failed // authorization gate. Retrying with more data does not change it. EntityDenied EntityOutcome = iota // EntityDeferred: the entity data does not settle the predicate (unknown // fields, non-complete collection coverage, or a failed read). The // candidate stays retryable and is never recorded as a non-match. EntityDeferred // EntityNonMatch: the predicate is false for every completion of the // evidence. EntityNonMatch // EntityEligible: the predicate is true for every completion of the // evidence. EntityEligible )
Entity-source evaluation outcomes. The zero value is EntityDenied so an unset decision fails closed.
func (EntityOutcome) MayStartSandbox ¶ added in v0.57.0
func (o EntityOutcome) MayStartSandbox() bool
MayStartSandbox reports whether the outcome permits sandbox launch. Only EntityEligible does.
func (EntityOutcome) String ¶ added in v0.57.0
func (o EntityOutcome) String() string
type ExecutionRef ¶
type ExecutionRef struct {
Agent string `json:"agent"`
Role string `json:"role"`
SourceRepo string `json:"source_repo"`
EventType string `json:"event_type"`
EventPayload json.RawMessage `json:"event_payload"`
TriggerSource string `json:"trigger_source,omitempty"`
StatusRepo string `json:"status_repo"`
StatusNumber string `json:"status_number"`
}
ExecutionRef is the matrix payload consumed by harness-run and fullsend run.
func Dispatch ¶
func Dispatch(ctx context.Context, opts Options) ([]ExecutionRef, error)
Dispatch evaluates authorization, kill switch, harness triggers, and returns execution refs. Returns empty slice (not error) when denied, kill-switched, or no triggers match. Returns an error when every registered harness fails to resolve or load.
func ProjectExecutionRef ¶
func ProjectExecutionRef(agentName string, role string, event *normevent.Event) (ExecutionRef, error)
ProjectExecutionRef maps a matched harness and event to an execution ref. Harness role values must be registered in the mint service ALLOWED_ROLES policy; custom role names pass harness validation but fail token minting with HTTP 403 until mint enrollment is extended for the repo.
type Options ¶
type Options struct {
// ConfigDir is the fullsend config directory (e.g. ".fullsend").
// Must be a direct child of the repo root; filepath.Dir is used
// to locate OWNERS and OWNERS_ALIASES for authorization.
ConfigDir string
Event *normevent.Event
// FetchPolicy controls SSRF protection for URL-sourced agent harnesses.
// When nil, fetch.DefaultPolicy is used (allows github.com and
// raw.githubusercontent.com). Set this in tests to allow httptest domains.
FetchPolicy *fetch.FetchPolicy
}
Options configures a dispatch run.
type TriggeredHarness ¶
TriggeredHarness pairs a registered agent with its loaded harness.
func FilterAuthorizedHarnesses ¶ added in v0.50.0
func FilterAuthorizedHarnesses(harnesses []TriggeredHarness, event *normevent.Event) []TriggeredHarness
FilterAuthorizedHarnesses returns the subset of harnesses that event is authorized to dispatch, keyed on each harness role: field. Run it before MatchHarnesses so CEL only evaluates authorized harnesses.
func FilterAuthorizedHarnessesWith ¶ added in v0.54.0
func FilterAuthorizedHarnessesWith(harnesses []TriggeredHarness, event *normevent.Event, opts AuthOptions) []TriggeredHarness
FilterAuthorizedHarnessesWith is FilterAuthorizedHarnesses under the policy in opts.
func ListTriggeredHarnesses ¶
func ListTriggeredHarnesses(ctx context.Context, configDir string, cfg config.ConfigReader, fetchPolicy *fetch.FetchPolicy) ([]TriggeredHarness, error)
ListTriggeredHarnesses returns config-registered agents whose harness has a non-empty trigger. fetchPolicy controls SSRF protection for URL-sourced agents. When nil, fetch.DefaultPolicy is used. Callers that need custom domain lists (e.g. tests using httptest) can pass a policy with the test server's domain.
Per-agent resolve/load failures are logged as GitHub Actions error annotations and skipped so a single broken harness does not block the rest. If every registered agent fails to resolve or load, an error is returned so a fully-unreadable harness set is not indistinguishable from "no trigger matched".
func MatchHarnesses ¶
func MatchHarnesses(candidates []TriggeredHarness, event *normevent.Event) ([]TriggeredHarness, error)
MatchHarnesses evaluates CEL triggers and returns matching harnesses.