actioncontract

package
v1.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package actioncontract is Gait's explicit boundary for consuming Wrkr report-only proposed Action Contract artifacts. A proposal is evidence, never an authorization. Activation is a separate, signed object that can be handed to an execution boundary by an operator or authority.

Index

Constants

View Source 
const (
	ProposedSchemaID         = "https://wrkr.dev/schemas/v1/proposed-action-contract-artifact.schema.json"
	ProposedContractSchemaID = "https://wrkr.dev/schemas/v1/proposed-action-contract-v3.schema.json"
	ProposedSchemaVersion    = "1"
	ProposedContractVersion  = "3"
	ProposedProducer         = "wrkr"

	ActivatedSchemaID        = "https://gait.dev/schemas/v1/activated-action-contract-artifact.schema.json"
	ActivatedSchemaVersion   = "1"
	ActivatedContractVersion = "1"
	ActivatedProducer        = "gait"
)
View Source 
const (
	ReasonMalformedArtifact            = "artifact_malformed"
	ReasonUnsupportedArtifactSchema    = "artifact_schema_unsupported"
	ReasonUnsupportedContractSchema    = "contract_schema_unsupported"
	ReasonUnsupportedProducer          = "producer_unsupported"
	ReasonReportOnlyRequired           = "report_only_required"
	ReasonMissingContractID            = "contract_id_missing"
	ReasonMissingFamilyID              = "contract_family_id_missing"
	ReasonMissingCompositionRef        = "composition_ref_missing"
	ReasonMissingSourceRefs            = "source_refs_missing"
	ReasonMissingEvidenceRefs          = "evidence_refs_missing"
	ReasonRevisionInvalid              = "revision_invalid"
	ReasonRevisionIdentityMismatch     = "revision_identity_mismatch"
	ReasonContractIdentityMismatch     = "contract_identity_mismatch"
	ReasonArtifactIdentityMismatch     = "artifact_identity_mismatch"
	ReasonDigestMismatch               = "canonical_digest_mismatch"
	ReasonContractDigestMismatch       = "contract_digest_mismatch"
	ReasonUnsupportedConstraint        = "constraint_unsupported"
	ReasonStaleProposal                = "proposal_stale"
	ReasonSupersededProposal           = "proposal_superseded"
	ReasonContradictoryProposal        = "proposal_contradictory"
	ReasonActivationModeUnsupported    = "activation_mode_unsupported"
	ReasonPolicyDigestMissing          = "policy_digest_missing"
	ReasonPrincipalMissing             = "activating_principal_missing"
	ReasonAuthorityRefsMissing         = "authority_refs_missing"
	ReasonTargetMissing                = "target_missing"
	ReasonEnvironmentMissing           = "environment_missing"
	ReasonValidityInvalid              = "validity_invalid"
	ReasonRevisionReactivationRequired = "revision_reactivation_required"
	ReasonSelectionRequired            = "explicit_selection_required"
	ReasonAmbiguousSelection           = "ambiguous_selection"
	ReasonAuthorizationRequired        = "authorization_required"
	ReasonSchemaValidationFailed       = "schema_validation_failed"
	ReasonSigningKeyRequired           = "signing_key_required"
	ReasonDevelopmentSigningForbidden  = "development_signing_forbidden"
	ReasonDevelopmentSigningUnverified = "development_signing_unverified"
	ReasonSelectionEvidenceRequired    = "selection_evidence_required"
	ReasonSelectionMismatch            = "selection_mismatch"
	ReasonSelectionNotCurrent          = "selection_not_current"
	ReasonSelectionAmbiguous           = "selection_ambiguous"
	ReasonBindingMismatch              = "proposal_binding_mismatch"
	ReasonEvaluationTimeInvalid        = "evaluation_time_invalid"
	ReasonActivationNotYetValid        = "activation_not_yet_valid"
	ReasonActivationExpired            = "activation_expired"
)

Variables

This section is empty.

Functions

func Activate 

func Activate(artifact Artifact, options ActivationOptions) (ActivatedArtifact, ValidationResult, error)

Activate validates one proposal and emits a deterministic signed activation object. No approval, authority, execution, or effect state is generated.

func DevelopmentPublicKey 

func DevelopmentPublicKey() ed25519.PublicKey

DevelopmentPublicKey exposes the deterministic dev key's public half for local verification tests; production callers should use their configured key.

func EncodePrivateKey 

func EncodePrivateKey(privateKey ed25519.PrivateKey) string

EncodePrivateKey is a small helper for test/CLI fixtures and uses Proof's base64-compatible representation without making key material part of an artifact.

func RawDigest 

func RawDigest(raw []byte) string

RawDigest returns the byte SHA-256 used by conformance receipts.

func ValidateArtifactBytes 

func ValidateArtifactBytes(raw []byte, options ValidationOptions) (Artifact, ValidationResult)

func VerifyActivation 

func VerifyActivation(artifact ActivatedArtifact, publicKey ed25519.PublicKey, proposal Artifact) (bool, error)

VerifyActivation checks the signed object against a supplied public key and the actual bound proposal. A signature alone is not a full activation verification result.

func VerifyActivationWithOptions 

func VerifyActivationWithOptions(artifact ActivatedArtifact, publicKey ed25519.PublicKey, options VerificationOptions) (bool, error)

func WriteActivatedArtifact 

func WriteActivatedArtifact(path string, artifact ActivatedArtifact, overwrite bool) error

WriteActivatedArtifact writes deterministic bytes through a same-directory temporary file. Existing targets are refused unless overwrite is explicit; symlink targets and symlinked parent directories are always rejected.

Types

type ActivatedArtifact 

type ActivatedArtifact struct {
	SchemaID            string                `json:"schema_id"`
	SchemaVersion       string                `json:"schema_version"`
	ArtifactID          string                `json:"artifact_id"`
	ContractID          string                `json:"contract_id"`
	ContractFamilyID    string                `json:"contract_family_id"`
	Revision            int                   `json:"revision"`
	Producer            ProducerMetadata      `json:"producer"`
	Proposal            ActivationProposalRef `json:"proposal"`
	PolicyDigest        string                `json:"policy_digest"`
	ActivatingPrincipal string                `json:"activating_principal"`
	AuthorityRefs       []string              `json:"authority_refs"`
	Target              string                `json:"target"`
	Environment         string                `json:"environment"`
	ActivationMode      ActivationMode        `json:"activation_mode"`
	Validity            Validity              `json:"validity"`
	ExplicitExceptions  []string              `json:"explicit_exceptions"`
	ReportOnly          bool                  `json:"report_only"`
	DevelopmentSigning  bool                  `json:"development_signing"`
	Signature           proofsign.Signature   `json:"signature"`
}

func ParseActivatedArtifact 

func ParseActivatedArtifact(raw []byte) (ActivatedArtifact, error)

func ReadActivatedArtifact 

func ReadActivatedArtifact(path string) (ActivatedArtifact, []byte, error)

type ActivationMode 

type ActivationMode string
const (
	ActivationContextOnly  ActivationMode = "context_only"
	ActivationEnforceFloor ActivationMode = "enforce_floor"
	ActivationRequired     ActivationMode = "required"
)

type ActivationOptions 

type ActivationOptions struct {
	PolicyDigest            string
	ActivatingPrincipal     string
	AuthorityRefs           []string
	Target                  string
	Environment             string
	Mode                    ActivationMode
	ValidFrom               string
	ValidUntil              string
	ExplicitExceptions      []string
	SigningPrivateKey       ed25519.PrivateKey
	AllowDevelopmentSigning bool
	Selection               *SelectionEvidence
	EvaluationTime          time.Time
}

type ActivationProposalRef 

type ActivationProposalRef struct {
	ArtifactID             string `json:"artifact_id"`
	CanonicalContentDigest string `json:"canonical_content_digest"`
	ContractID             string `json:"contract_id"`
	ContractFamilyID       string `json:"contract_family_id"`
	Revision               int    `json:"revision"`
	SchemaID               string `json:"schema_id"`
	SchemaVersion          string `json:"schema_version"`
	ContractSchemaVersion  string `json:"contract_schema_version"`
}

type ActivationResult 

type ActivationResult struct {
	Activated  ActivatedArtifact `json:"activated"`
	Validation ValidationResult  `json:"validation"`
}

type Artifact 

type Artifact struct {
	SchemaID               string           `json:"schema_id"`
	SchemaVersion          string           `json:"schema_version"`
	ArtifactID             string           `json:"artifact_id"`
	ContractID             string           `json:"contract_id"`
	ContractFamilyID       string           `json:"contract_family_id"`
	Revision               int              `json:"revision"`
	Producer               ProducerMetadata `json:"producer"`
	SourceScanRefs         []string         `json:"source_scan_refs"`
	CompositionRefs        []string         `json:"composition_refs"`
	ResolutionKey          string           `json:"resolution_key,omitempty"`
	CreationEvidence       []string         `json:"creation_evidence"`
	CanonicalContentDigest string           `json:"canonical_content_digest"`
	Variant                VariantMetadata  `json:"variant"`
	ReportOnly             bool             `json:"report_only"`
	Contract               map[string]any   `json:"contract"`
}

Artifact is intentionally map-backed for the embedded contract. This lets Gait preserve Wrkr's immutable v3 contract without reimplementing Wrkr's risk model or dropping future additive fields.

func ParseArtifact 

func ParseArtifact(raw []byte) (Artifact, error)

ParseArtifact parses one standalone artifact, rejects duplicate keys and trailing JSON, and preserves JSON numbers for JCS digest verification.

func ReadArtifact 

func ReadArtifact(path string) (Artifact, []byte, error)

ReadArtifact reads exactly one artifact from path. The path is a caller selection; no directory scanning or recommendation discovery is performed.

type ProducerMetadata 

type ProducerMetadata struct {
	Name                  string `json:"name"`
	ArtifactSchemaVersion string `json:"artifact_schema_version"`
	ContractSchemaVersion string `json:"contract_schema_version"`
}

ProducerMetadata is the producer declaration carried by a proposal.

type SelectionEvidence 

type SelectionEvidence struct {
	ArtifactID             string `json:"artifact_id"`
	ArtifactSHA256         string `json:"artifact_sha256"`
	CanonicalContentDigest string `json:"canonical_content_digest"`
	ContractID             string `json:"contract_id"`
	ContractFamilyID       string `json:"contract_family_id"`
	Revision               int    `json:"revision"`
	Current                bool   `json:"current"`
}

SelectionEvidence is the Gait-owned current-selection record required before activation or consumer handoff. It binds one explicit artifact to the family/revision currently selected by the caller.

func LoadSelectionEvidence 

func LoadSelectionEvidence(path, artifactPath string, artifact Artifact, raw []byte) (SelectionEvidence, error)

type SupportedConstraintSummary 

type SupportedConstraintSummary struct {
	TargetConstraintKeys []string `json:"target_constraint_keys"`
	PreconditionKinds    []string `json:"precondition_kinds"`
	AuthorityKinds       []string `json:"authority_kinds"`
	Unsupported          []string `json:"unsupported,omitempty"`
}

type ValidationError 

type ValidationError struct{ Reasons []string }

ValidationError is stable and machine-readable. Error() is intentionally compact because CLI JSON exposes Reasons directly.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type ValidationOptions 

type ValidationOptions struct {
	Now                 time.Time
	RequireExplicitPath bool
	ExpectedContractID  string
	ExpectedFamilyID    string
	ExpectedRevision    int
	SchemaRoot          string
}

ValidationOptions controls time-sensitive checks. A zero Now uses the current UTC time; callers that need reproducibility should pass a fixed Now.

type ValidationResult 

type ValidationResult struct {
	Valid                  bool                       `json:"valid"`
	Reasons                []string                   `json:"reason_codes,omitempty"`
	Artifact               *Artifact                  `json:"artifact,omitempty"`
	CanonicalContentDigest string                     `json:"canonical_content_digest,omitempty"`
	SupportedConstraints   SupportedConstraintSummary `json:"supported_constraints"`
}

func ValidateArtifact 

func ValidateArtifact(artifact Artifact, options ValidationOptions) ValidationResult

ValidateArtifact validates an explicit Wrkr v3 proposal and its JCS envelope digest. It does not activate or infer authority.

type Validity 

type Validity struct {
	NotBefore string `json:"not_before"`
	NotAfter  string `json:"not_after,omitempty"`
}

type VariantMetadata 

type VariantMetadata struct {
	ShareProfile string `json:"share_profile"`
	Redacted     bool   `json:"redacted"`
}

type VerificationOptions 

type VerificationOptions struct {
	AllowDevelopmentSigning bool
	Proposal                *Artifact
	// EvaluationTime controls activation and proposal expiry checks. A zero
	// value preserves the library's historical current-time behavior; CLI and
	// deterministic callers should pass an explicit UTC time.
	EvaluationTime time.Time
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.