artifact

Documentation

Overview

Package artifact provides deterministic artifact records and manifests.

Index

• Constants
• func CanonicalAssessmentJSON(value Assessment) ([]byte, error)
• func CanonicalDescriptorJSON(value Descriptor) ([]byte, error)
• func CleanRelativePath(inputPath string, opts ...Options) (string, error)
• func DigestAssessment(value Assessment) (digest.Record, error)
• func DigestDescriptor(value Descriptor) (digest.Record, error)
• func ValidateAssessment(value Assessment) error
• func ValidateDescriptor(value Descriptor) error
• func ValidateRegularFiles(root string, paths []string, opts ...Options) error
• func ValidateRoot(root string, opts ...Options) error
• type Assessment
  • func NormalizeAssessment(value Assessment) Assessment
• type Descriptor
  • func NormalizeDescriptor(value Descriptor) Descriptor
• type FileOptions
• type LifecycleStatus
  • func EffectiveStatus(value Assessment, at time.Time) LifecycleStatus
• type Manifest
  • func DirectoryManifest(root string, version ...string) (Manifest, error)
  • func NewManifest(opts ManifestOptions) (Manifest, error)
  • func (m Manifest) Digest() (digest.Record, error)
• type ManifestOptions
• type Options
• type Record
  • func FileRecord(root string, opts FileOptions) (Record, error)

Constants

const (
	// DescriptorVersion is the wire version for content-addressed artifact
	// descriptors.
	DescriptorVersion = "evidence.artifact-descriptor.v1"
	// AssessmentVersion is the wire version for artifact lifecycle assessments.
	AssessmentVersion = "evidence.artifact-assessment.v1"
)

const (
	// ManifestVersion is the default artifact manifest schema version.
	ManifestVersion = "evidence.artifact-manifest.v1"
)

Functions

func CanonicalAssessmentJSON

func CanonicalAssessmentJSON(value Assessment) ([]byte, error)

CanonicalAssessmentJSON returns deterministic normalized JSON.

func CanonicalDescriptorJSON

func CanonicalDescriptorJSON(value Descriptor) ([]byte, error)

CanonicalDescriptorJSON returns deterministic normalized JSON.

func CleanRelativePath

func CleanRelativePath(inputPath string, opts ...Options) (string, error)

CleanRelativePath returns a canonical slash-separated relative artifact path.

func DigestAssessment

func DigestAssessment(value Assessment) (digest.Record, error)

DigestAssessment returns the SHA-256 digest of canonical assessment JSON.

func DigestDescriptor

func DigestDescriptor(value Descriptor) (digest.Record, error)

DigestDescriptor returns the SHA-256 digest of canonical descriptor JSON.

func ValidateAssessment

func ValidateAssessment(value Assessment) error

ValidateAssessment rejects malformed or internally inconsistent lifecycle evidence. Trust in the caller that supplied the assessment remains external.

func ValidateDescriptor

func ValidateDescriptor(value Descriptor) error

ValidateDescriptor rejects malformed descriptor fields. Only SHA-256 is currently supported so content identity stays unambiguous across consumers.

func ValidateRegularFiles

func ValidateRegularFiles(root string, paths []string, opts ...Options) error

ValidateRegularFiles rejects missing, symlinked, directory, and special-file artifact inputs.

func ValidateRoot

func ValidateRoot(root string, opts ...Options) error

ValidateRoot rejects missing, non-directory, and symlink artifact roots.

Types

type Assessment

type Assessment struct {
	Version    string          `json:"version"`
	Subject    Descriptor      `json:"subject"`
	Status     LifecycleStatus `json:"status"`
	AssessedAt time.Time       `json:"assessed_at"`
	ExpiresAt  time.Time       `json:"expires_at,omitzero"`
	Successor  digest.Record   `json:"successor,omitzero"`
	Supporting []Descriptor    `json:"supporting,omitempty"`
}

Assessment binds lifecycle evidence to exact subject bytes. Successor is required only for superseded subjects. Supporting descriptors are inert evidence references selected by the caller.

func NormalizeAssessment

func NormalizeAssessment(value Assessment) Assessment

NormalizeAssessment returns a deterministic copy without mutating input.

type Descriptor

type Descriptor struct {
	Version     string            `json:"version"`
	MediaType   string            `json:"media_type"`
	SizeBytes   int64             `json:"size_bytes"`
	Digest      digest.Record     `json:"digest"`
	Annotations map[string]string `json:"annotations,omitempty"`
}

Descriptor identifies exact artifact bytes without naming a product, storage location, registry, or trust policy.

func NormalizeDescriptor

func NormalizeDescriptor(value Descriptor) Descriptor

NormalizeDescriptor returns a deterministic copy without mutating input.

type FileOptions

type FileOptions struct {
	Path           string
	Kind           string
	MediaType      string
	Classification string
	Required       bool
}

FileOptions supplies caller-owned metadata for a file artifact record.

type LifecycleStatus

type LifecycleStatus string

LifecycleStatus is a caller-supplied assessment of an artifact's current distribution lifecycle. It describes evidence and does not grant trust.

const (
	LifecycleActive     LifecycleStatus = "active"
	LifecycleStale      LifecycleStatus = "stale"
	LifecycleRevoked    LifecycleStatus = "revoked"
	LifecycleSuperseded LifecycleStatus = "superseded"
)

func EffectiveStatus

func EffectiveStatus(value Assessment, at time.Time) LifecycleStatus

EffectiveStatus returns stale when an otherwise active assessment has expired at the caller-supplied time. The zero time leaves explicit status unchanged; callers must supply their own clock value when expiry matters.

type Manifest

type Manifest struct {
	Version   string   `json:"version"`
	Root      string   `json:"root,omitempty"`
	Artifacts []Record `json:"artifacts"`
}

Manifest describes a deterministic set of artifacts.

func DirectoryManifest

func DirectoryManifest(root string, version ...string) (Manifest, error)

DirectoryManifest returns a deterministic manifest of every regular file below root. Symlinked files or directories are rejected.

func NewManifest

func NewManifest(opts ManifestOptions) (Manifest, error)

NewManifest returns a deterministic manifest for caller-supplied files.

func (Manifest) Digest

func (m Manifest) Digest() (digest.Record, error)

Digest returns a digest over the canonical JSON manifest.

type ManifestOptions

type ManifestOptions struct {
	Version string
	Root    string
	Files   []FileOptions
}

ManifestOptions configures manifest generation.

type Options

type Options struct {
	// RootLabel names the root directory; default "artifact root".
	RootLabel string
	// PathLabel names a relative path; default "artifact path".
	PathLabel string
	// InputLabel names a validated file; default "artifact input".
	InputLabel string
}

Options customizes the nouns used in artifact validation error messages so a downstream product can surface domain-specific wording (for example "package root" or "required handoff input") while sharing one validation implementation. The zero value reproduces the default "artifact" wording.

type Record

type Record struct {
	Path           string        `json:"path"`
	Kind           string        `json:"kind,omitempty"`
	MediaType      string        `json:"media_type,omitempty"`
	Classification string        `json:"classification,omitempty"`
	Required       bool          `json:"required,omitempty"`
	SizeBytes      int64         `json:"size_bytes"`
	Digest         digest.Record `json:"digest"`
}

Record describes one artifact without embedding artifact content.

func FileRecord

func FileRecord(root string, opts FileOptions) (Record, error)

FileRecord returns a record for one safe relative file under root.