gate

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package gate decides whether a skill version may be published, held for review, or refused outright. It is pure: no database, no HTTP, no clock.

Index

Constants

View Source
const (
	// ClassExfiltration and ClassSecret are unappealable. No evaluation
	// overrides credential theft: a sandbox observing sixty well-behaved
	// runs does not prove the sixty-first will not post a token somewhere.
	ClassExfiltration = scan.ClassExfiltration
	ClassSecret       = scan.ClassSecret

	// The rest are guesses the scanner makes from shape alone, which is
	// exactly what running the skill in a network-off sandbox measures
	// directly.
	ClassExecution = scan.ClassExecution
	ClassInjection = scan.ClassInjection
	ClassHeuristic = scan.ClassHeuristic
)
View Source
const (
	ReasonScan      = "scan"
	ReasonOwnership = "ownership"
)

Hold reason kinds. These are persisted in skill_versions.hold_reasons and in version_approvals.reason, so they are a wire contract: renaming one makes every in-flight hold unclearable.

Variables

This section is empty.

Functions

This section is empty.

Types

type Class

type Class = scan.Class

Class groups a scan finding by what kind of claim it makes. Severity says how confident the scanner is; class says whether an empirical measurement could ever overturn it.

The vocabulary itself lives in internal/scan (see scan/class.go): scan already needs it to populate Finding.Class as rules fire, and gate needs scan's report types for Decide, so the type must live on the side with no outgoing edge back to the other. Class is a type alias (not a defined type) precisely so gate.Class and scan.Class stay interchangeable and every existing gate.ClassExecution / gate.ClassOf callsite keeps compiling and reading naturally.

func ClassOf

func ClassOf(category string) (Class, bool)

ClassOf maps a scan rule category onto a Class. The bool is false for an unmapped category; callers must not substitute a default, because every plausible default is wrong in one direction or the other. Decide treats an unmapped class as Block, and TestEveryRuleHasAClass keeps that unreachable from the native rule set.

type Decision

type Decision struct {
	Outcome Outcome  `json:"outcome"`
	Reasons []Reason `json:"reasons"`
	// HoldReasons are the reason kinds that must each be cleared before this
	// version may be served. Empty means nothing is holding it. It is a set,
	// not a state, because a scan finding and an unowned publisher are two
	// different questions and neither may be used to launder the other.
	HoldReasons []string `json:"hold_reasons"`
	// Ownership is present only when ownership was evaluated.
	Ownership *OwnershipDetail `json:"ownership,omitempty"`
}

Decision is the whole verdict. It is persisted as an object rather than a bare array of reasons: json.Marshal on a nil slice emits null, and a null in a column declared NOT NULL DEFAULT '[]' makes "no reasons" and "never written" indistinguishable while breaking jsonb_array_length.

func Decide

func Decide(rep scan.Report, q *QualityState, o OwnerState, p Policy) Decision

Decide maps a scan report, an optional quality state, and the publisher's ownership standing onto an outcome. It is pure: no database, no HTTP, no clock, no context.

func (Decision) Held

func (d Decision) Held() bool

Held reports whether this decision keeps the version out of circulation.

type Outcome

type Outcome string

Outcome is what the gate decided.

const (
	Allow            Outcome = "allow"
	AllowWithWarning Outcome = "allow_with_warning"
	NeedsReview      Outcome = "needs_review"
	Block            Outcome = "block"
)

type OwnerRef

type OwnerRef struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
}

OwnerRef identifies one owner well enough for a CLI or a UI to name them. Decide is pure and cannot look users up, so the caller passes them in.

type OwnerState

type OwnerState struct {
	Evaluated   bool
	IsOwner     bool
	Unowned     bool
	RulePattern string
	Owners      []OwnerRef
}

OwnerState is what is known about who owns the skill being published to.

Evaluated is false when ownership was not determined at all — the CLI's local pre-scan, which has no way to ask. An unevaluated state contributes nothing, so local behaviour is byte-for-byte what it was before ownership existed.

IsOwner already folds in instance privilege: an owner or admin is an implicit owner of everything. Resolving that at the HTTP boundary keeps this package free of auth and keeps the privilege check to one call site, exactly as Policy.AdminOverride does.

type OwnershipDetail

type OwnershipDetail struct {
	RulePattern string     `json:"rule_pattern,omitempty"`
	Owners      []OwnerRef `json:"owners"`
	Clears      string     `json:"clears"`
}

OwnershipDetail is the ownership half of a decision, rendered by the CLI and the review screen. Naming the humans who can unblock a publisher is what turns a wall into a next step.

type Policy

type Policy struct {
	// Floor is the minimum headline score a verified report must reach to
	// clear a NeedsReview. 0 means any verified report clears, provided the
	// other conditions hold.
	Floor float64
	// AdminOverride is the already-resolved answer to "may this caller
	// override, and did they ask to". Resolving it at the HTTP boundary and
	// passing the answer keeps Decide pure and keeps the privilege check to
	// exactly one call site, so re-pointing it at an audited authorizer
	// later is a one-function change.
	AdminOverride bool
}

Policy is the deployment's configuration.

type QualityState

type QualityState struct {
	Verified                 bool
	PanelComplete            bool
	Headline                 float64
	CriticalForbidViolations int
}

QualityState is what is known about the version's measured behaviour. A nil *QualityState means no measurement exists — never a zero score. A zero headline means the skill scored nothing, which is the opposite claim.

type Reason

type Reason struct {
	Rule     string `json:"rule"`
	Class    string `json:"class"`
	Severity string `json:"severity"`
	File     string `json:"file"`
	Line     int    `json:"line"`
	Message  string `json:"message"`
	// Clears states in one sentence what would resolve this finding.
	Clears string `json:"clears"`
}

Reason is one finding that drove the decision, together with what would clear it. It is part of the contract, not a debug aid: the CLI renders it and the review UI consumes it.

Jump to

Keyboard shortcuts

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