slsa

type BuildTypeParamsUnsetError struct {
	BuildType string
	Controls  []UnconfiguredControl
}

type ControlResult struct {
	ID        string
	Title     string
	SLSALevel int
	Status    Status
	Message   string
}

type Option func(*Verifier) error

type Options struct {
	// Catalog is the set of controls available to the verifier. When nil,
	// the verifier loads the embedded catalog at construction time.
	Catalog *controls.Catalog

	// Builders is the registry binding builders to their signing
	// identities. When nil, the verifier loads the embedded registry at
	// construction time.
	Builders *builders.Registry
}

type Result struct {
	// Status is the aggregate outcome derived from all evaluated controls.
	Status Status

	// SLSALevel is the highest SLSA level whose required core controls all passed.
	SLSALevel int

	// Message explains a failing Status that is not attributable to a
	// single control, such as the computed level falling short of the
	// required minimum. Empty otherwise.
	Message string

	// VerifierID is the identity of the entity that performed the
	// verification, copied from VerificationOptions.VerifierID. It is used
	// as verifier.id when a VSA is emitted from this result.
	VerifierID string

	// SpecVersion is the SLSA spec version whose criteria the statement
	// was evaluated against which is the version the requested SpecVersion
	// resolved to in the catalog (eg "1.2"). It surfaces as
	// slsaVersion when a VSA is emitted from this result.
	SpecVersion string

	// CoreResults holds per-control results for the SLSA spec-defined controls.
	CoreResults []*ControlResult

	// BuildTypeResults holds per-control results for custom buildType controls.
	BuildTypeResults []*ControlResult

	// UserResults holds per-control results for user-supplied controls.
	UserResults []*ControlResult

	// Subjects holds the outcome of binding the statement to the
	// artifacts the caller holds, one entry per expected subject in the
	// order given (see WithSubjects). Empty when no subjects were
	// expected. Any unmatched entry makes Status a FAIL.
	Subjects []subject.Match
}

type Status string

type UnconfiguredControl struct {
	ID                 string
	Title              string
	Parameters         []string
	OptionalParameters []string
}

type VerificationOption func(*VerificationOptions) error

type VerificationOptions struct {
	// RunBuildTypeControls toggles execution of custom buildType controls.
	RunBuildTypeControls bool

	// RunUserControls toggles execution of user supplied controls.
	RunUserControls bool

	// SkipBuildTypeChecks skips buildType controls whose parameters were
	// not set instead of failing the run with ErrBuildTypeParamsUnset.
	// BuildType controls that take no parameters still run.
	SkipBuildTypeChecks bool

	// RequireSignatures, when true, fails verification if the statement
	// does not carry a verified signature (ie loaded as a plain in-toto envelope
	// or failed to verify).
	RequireSignatures bool

	// UserControls is the list of user-supplied controls evaluated when
	// RunUserControls is true.
	UserControls []*controls.Control

	// ExpectedSigners is the set of identities alloed to sign the statement.
	// When set, CheckIdentities will only accept the statement if at
	// least one verified signer matches one of these (OR'ed). An empty list
	// is the default and skips identity matching.
	ExpectedSigners []*sapi.Identity

	// Subjects are the artifacts the caller holds and expects the
	// statement to be about. When non-empty, every one of them must
	// match a subject of the statement or the verification fails. Empty
	// (the default) binds the statement to nothing: it is verified on
	// its content alone.
	Subjects []*subject.Expected

	// NoGitDigestAliases requires exact digest algorithm names when
	// matching Subjects. By default git object digests (gitCommit,
	// gitTree, …) are interchangeable with the sha1 or sha256 hash they
	// are. See subject.WithGitDigestAliases.
	NoGitDigestAliases bool

	// ForceTrack overrides the catalog's predicate-type to track
	// resolution. Empty means "auto" (the catalog must associate the
	// predicate type with exactly one track). When set to a track
	// constant (TrackBuild/TrackSource), the verifier evaluates
	// against that track and errors if the catalog does not classify the
	// predicate type under it.
	ForceTrack controls.Track

	// Params is the parameter map exposed to CEL expressions as `params`.
	// Values are typically string or []string, matching what the --param
	// CLI flag produces.
	Params map[string]any

	// VerifierID identifies the entity performing the verification. It is
	// recorded on the Result and surfaces as verifier.id when a VSA is
	// emitted from the outcome. The CLI sets it from --verifier-id,
	// defaulting to the SLSA verifier project URL; applications embedding
	// the verifier should set their own identity. Empty by default.
	VerifierID string

	// SpecVersion selects the SLSA spec version whose verification
	// criteria (control catalog) the statement is evaluated against,
	// eg "1.2". Criteria carry forward across releases, so the newest
	// catalog at or below the requested version applies. Empty (the
	// default) means the latest version the catalog defines for the
	// resolved track.
	SpecVersion string

	// MinLevel is the SLSA level the attestation is required to reach.
	// When set (> 0), the run fails unless the computed level reaches
	// it, and core controls declared above it are informative: their
	// failure caps the computed level but does not fail the run. Zero
	// (the default) keeps the strict semantics where every applicable
	// control must pass. Controls without a declared level, buildType
	// controls and user controls are always required.
	MinLevel int
}

type Verifier struct {
	Options Options
	// contains filtered or unexported fields
}

type VerifierImplementation interface {
	// VerifySignatures verifies the integrity of the statement's envelope
	// (layer 1).
	VerifySignatures(ctx context.Context, opts *VerificationOptions, statement attestation.Statement) error

	// CheckIdentities matches the verified identities against the expected
	// signer identities (layer 2). Currently a placeholder; identity-match
	// flags will be added later.
	CheckIdentities(ctx context.Context, opts *VerificationOptions, statement attestation.Statement) error

	// CheckSubjects binds the statement to the artifacts the caller
	// holds: every opts.Subjects entry must match a statement subject.
	// Returns one match per expected subject, in order, so callers can
	// report each; an empty list when nothing was asked.
	CheckSubjects(ctx context.Context, opts *VerificationOptions, statement attestation.Statement) ([]subject.Match, error)

	// CheckBuilder binds the provenance's builder.id to the statement's
	// verified signer using the builder registry and reports the outcome
	// as a core control result; nil for statements without a builder.
	CheckBuilder(ctx context.Context, opts *VerificationOptions, registry *builders.Registry, statement attestation.Statement) (*ControlResult, error)

	// ResolveCategory selects which catalog category to apply by looking
	// up the statement's predicate-type track in the catalog (layer 3
	// split build vs source). Honours opts.ForceTrack when set.
	ResolveCategory(opts *VerificationOptions, catalog *controls.Catalog, statement attestation.Statement) (controls.Category, error)

	// SelectCoreControls chooses the core SLSA controls to evaluate from
	// the catalog given the resolved category (layer 4).
	SelectCoreControls(opts *VerificationOptions, catalog *controls.Catalog, category controls.Category) []*controls.Control

	// SelectBuildTypeControls chooses the custom buildType controls
	// applicable to the given statement (layer 5).
	SelectBuildTypeControls(opts *VerificationOptions, catalog *controls.Catalog, statement attestation.Statement) []*controls.Control

	// SelectUserControls returns the user-supplied controls (layer 6).
	SelectUserControls(opts *VerificationOptions) []*controls.Control

	// RunControls evaluates a list of controls against the statement and
	// returns one result per control.
	RunControls(ctx context.Context, opts *VerificationOptions, ctrls []*controls.Control, statement attestation.Statement) ([]*ControlResult, error)

	// ComputeResult condenses the per-layer outcomes into the final
	// verification result, including the SLSA level (layer 7).
	ComputeResult(opts *VerificationOptions, coreResults, buildTypeResults, userResults []*ControlResult) (*Result, error)
}