effects

Documentation

Overview

Package effects models bounded, reference-first effect evidence and grades typed effect contracts without executing or mutating external systems.

Index

• Constants
• func LoadPublicKey(path string) (ed25519.PublicKey, error)
• func WriteJUnit(path string, result GradeResult) error
• type Capture
• type Collector
• type Contract
  • func LoadContract(path string) (Contract, error)
• type Correlation
• type CorrelationExpectation
• type GradeOptions
• type GradeResult
  • func Grade(snapshot Snapshot, contract Contract) GradeResult
  • func GradeWithOptions(snapshot Snapshot, contract Contract, options GradeOptions) GradeResult
• type Observation
• type Predicate
• type PredicateEvaluation
• type Provenance
• type Redaction
• type Selector
• type Snapshot
  • func LoadSnapshot(path string) (Snapshot, error)
  • func (s Snapshot) CanonicalDigest() (string, error)
  • func (s Snapshot) Sign(privateKey ed25519.PrivateKey, mode string) (Snapshot, error)
  • func (s Snapshot) VerifyProvenance() error
  • func (s Snapshot) VerifyProvenanceAgainst(publicKey ed25519.PublicKey) error
• type ValidationResult
  • func ValidateContract(c Contract) ValidationResult
  • func ValidateSnapshot(s Snapshot) ValidationResult

Constants

const (
	SnapshotSchemaID = "https://gait.dev/schemas/v1/effects/effect-snapshot.schema.json"
	ContractSchemaID = "https://gait.dev/schemas/v1/effects/effect-contract.schema.json"
	GradeSchemaID    = "https://gait.dev/schemas/v1/effects/effect-grading-result.schema.json"
	SchemaVersion    = "1.0.0"
)

const (
	ResourcePostgres   = "postgres"
	ResourceFilesystem = "filesystem"
	ResourceHTTP       = "http"
	ResourceGeneric    = "resource"

	ObservationPresent = "present"
	ObservationAbsent  = "absent"
	ObservationUnknown = "unknown"

	CompletenessComplete = "complete"
	CompletenessPartial  = "partial"
	CompletenessUnknown  = "unknown"

	EnforcementVerified     = "verified"
	EnforcementObservedOnly = "observed_only"
	EnforcementPartial      = "partial"
	EnforcementUnknown      = "unknown"

	GradePass         = "pass"
	GradeFail         = "fail"
	GradeInconclusive = "inconclusive"

	PredicateExpect    = "expect"
	PredicateForbid    = "forbid"
	PredicateInvariant = "invariant"
)

const (
	ReasonSchemaUnsupported      = "effect_schema_unsupported"
	ReasonSnapshotIDMissing      = "effect_snapshot_id_missing"
	ReasonResourceKindInvalid    = "effect_resource_kind_invalid"
	ReasonSelectorMissing        = "effect_selector_missing"
	ReasonObservationInvalid     = "effect_observation_invalid"
	ReasonDigestInvalid          = "effect_digest_invalid"
	ReasonDigestMismatch         = "effect_digest_mismatch"
	ReasonCollectorMissing       = "effect_collector_missing"
	ReasonCaptureInvalid         = "effect_capture_invalid"
	ReasonRedactionInvalid       = "effect_redaction_invalid"
	ReasonCompletenessInvalid    = "effect_completeness_invalid"
	ReasonEnforcementInvalid     = "effect_enforcement_invalid"
	ReasonEvidenceMissing        = "effect_evidence_missing"
	ReasonContractIDMissing      = "effect_contract_id_missing"
	ReasonPredicateInvalid       = "effect_predicate_invalid"
	ReasonContractInvalid        = "effect_contract_invalid"
	ReasonSnapshotInvalid        = "effect_snapshot_invalid"
	ReasonContractMismatch       = "effect_contract_mismatch"
	ReasonPredicateFailed        = "effect_predicate_failed"
	ReasonPredicateInconclusive  = "effect_predicate_inconclusive"
	ReasonEvidenceIncomplete     = "effect_evidence_incomplete"
	ReasonObservedOnly           = "effect_observed_only"
	ReasonFieldUnavailable       = "effect_field_unavailable"
	ReasonWhitespaceInvalid      = "effect_whitespace_invalid"
	ReasonSchemaValidationFailed = "effect_schema_validation_failed"
	ReasonProvenanceMissing      = "effect_provenance_missing"
	ReasonProvenanceInvalid      = "effect_provenance_invalid"
	ReasonNonAuthoritative       = "effect_non_authoritative_provenance"
	ReasonTrustedKeyMissing      = "effect_trusted_collector_key_missing"
	ReasonTrustedKeyMismatch     = "effect_trusted_collector_key_mismatch"
	ReasonCorrelationMissing     = "effect_correlation_missing"
	ReasonCorrelationMismatch    = "effect_correlation_mismatch"
	ReasonTemporalOrderInvalid   = "effect_temporal_order_invalid"
)

Functions

func LoadPublicKey

func LoadPublicKey(path string) (ed25519.PublicKey, error)

func WriteJUnit

func WriteJUnit(path string, result GradeResult) error

Types

type Capture

type Capture struct {
	Mode       string `json:"mode"`
	SourceRef  string `json:"source_ref,omitempty"`
	CapturedAt string `json:"captured_at"`
}

type Collector

type Collector struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	Mode    string `json:"mode"`
}

type Contract

type Contract struct {
	SchemaID      string      `json:"schema_id"`
	SchemaVersion string      `json:"schema_version"`
	ContractID    string      `json:"contract_id"`
	Name          string      `json:"name"`
	Predicates    []Predicate `json:"predicates"`
}

func LoadContract

func LoadContract(path string) (Contract, error)

type Correlation

type Correlation struct {
	ActionDigest     string   `json:"action_digest,omitempty"`
	ActivationDigest string   `json:"activation_digest,omitempty"`
	ProofDigest      string   `json:"proof_digest,omitempty"`
	RunID            string   `json:"run_id,omitempty"`
	LifecycleID      string   `json:"lifecycle_id,omitempty"`
	ProofRefs        []string `json:"proof_refs,omitempty"`
}

type CorrelationExpectation

type CorrelationExpectation struct {
	ActionDigest     string
	ActivationDigest string
	ProofDigest      string
}

CorrelationExpectation is the caller-owned identity binding for an effect grade. At least one digest must be supplied before a pass is authoritative.

type GradeOptions

type GradeOptions struct {
	TrustedCollectorPublicKey ed25519.PublicKey
	// AllowFixtureTestProvenance is reserved for the committed fixture generator
	// and package tests; the production CLI does not expose this bypass.
	AllowFixtureTestProvenance bool
	ExpectedCorrelation        *CorrelationExpectation
}

type GradeResult

type GradeResult struct {
	SchemaID       string                `json:"schema_id"`
	SchemaVersion  string                `json:"schema_version"`
	ContractID     string                `json:"contract_id"`
	SnapshotID     string                `json:"snapshot_id"`
	Status         string                `json:"status"`
	EvidenceStatus string                `json:"evidence_status"`
	ReasonCodes    []string              `json:"reason_codes"`
	Evaluations    []PredicateEvaluation `json:"evaluations"`
}

func Grade

func Grade(snapshot Snapshot, contract Contract) GradeResult

func GradeWithOptions

func GradeWithOptions(snapshot Snapshot, contract Contract, options GradeOptions) GradeResult

type Observation

type Observation struct {
	State        string   `json:"state"`
	Digest       string   `json:"digest,omitempty"`
	Count        *int64   `json:"count,omitempty"`
	Identity     string   `json:"identity,omitempty"`
	Owner        string   `json:"owner,omitempty"`
	TTLSeconds   *int64   `json:"ttl_seconds,omitempty"`
	ObservedAt   string   `json:"observed_at"`
	EvidenceRefs []string `json:"evidence_refs,omitempty"`
}

type Predicate

type Predicate struct {
	ID       string `json:"id"`
	Kind     string `json:"kind"`
	Field    string `json:"field"`
	Operator string `json:"operator,omitempty"`
	Expected any    `json:"expected,omitempty"`
}

type PredicateEvaluation

type PredicateEvaluation struct {
	ID          string   `json:"id"`
	Kind        string   `json:"kind"`
	Field       string   `json:"field"`
	Status      string   `json:"status"`
	ReasonCodes []string `json:"reason_codes,omitempty"`
	Observed    any      `json:"observed,omitempty"`
	Expected    any      `json:"expected,omitempty"`
}

type Provenance

type Provenance struct {
	Mode      string              `json:"mode"`
	PublicKey string              `json:"public_key"`
	Signature proofsign.Signature `json:"signature"`
}

type Redaction

type Redaction struct {
	Mode   string   `json:"mode"`
	Fields []string `json:"fields,omitempty"`
}

type Selector

type Selector struct {
	Resource string            `json:"resource"`
	Scope    string            `json:"scope,omitempty"`
	Name     string            `json:"name,omitempty"`
	Path     string            `json:"path,omitempty"`
	URL      string            `json:"url,omitempty"`
	Labels   map[string]string `json:"labels,omitempty"`
}

type Snapshot

type Snapshot struct {
	SchemaID               string      `json:"schema_id"`
	SchemaVersion          string      `json:"schema_version"`
	SnapshotID             string      `json:"snapshot_id"`
	ResourceKind           string      `json:"resource_kind"`
	Selector               Selector    `json:"selector"`
	Before                 Observation `json:"before"`
	After                  Observation `json:"after"`
	Collector              Collector   `json:"collector"`
	Capture                Capture     `json:"capture"`
	Redaction              Redaction   `json:"redaction"`
	Correlation            Correlation `json:"correlation"`
	Provenance             Provenance  `json:"provenance"`
	Completeness           string      `json:"completeness"`
	Enforcement            string      `json:"enforcement"`
	EvidenceRefs           []string    `json:"evidence_refs,omitempty"`
	CanonicalContentDigest string      `json:"canonical_content_digest"`
}

func LoadSnapshot

func LoadSnapshot(path string) (Snapshot, error)

func (Snapshot) CanonicalDigest

func (s Snapshot) CanonicalDigest() (string, error)

func (Snapshot) Sign

func (s Snapshot) Sign(privateKey ed25519.PrivateKey, mode string) (Snapshot, error)

func (Snapshot) VerifyProvenance

func (s Snapshot) VerifyProvenance() error

func (Snapshot) VerifyProvenanceAgainst

func (s Snapshot) VerifyProvenanceAgainst(publicKey ed25519.PublicKey) error

type ValidationResult

type ValidationResult struct {
	Valid       bool     `json:"valid"`
	ReasonCodes []string `json:"reason_codes,omitempty"`
}

func ValidateContract

func ValidateContract(c Contract) ValidationResult

func ValidateSnapshot

func ValidateSnapshot(s Snapshot) ValidationResult