artifact

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Aug 28, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

README

artifact

import "github.com/agentstation/starmap/pkg/catalogs/artifact"

Package artifact defines the deterministic distribution format for immutable Starmap catalog generations.

Index

Constants

const (
    // FormatVersion is the current catalog distribution archive format.
    FormatVersion uint64 = 1
    // MediaType is the media type of the compressed catalog archive.
    MediaType = "application/vnd.agentstation.starmap.catalog-artifact.v1+tar+gzip"
    // DescriptorMediaType is the media type of artifact.json.
    DescriptorMediaType = "application/vnd.agentstation.starmap.catalog-artifact-descriptor.v1+json"
    // AttestationPredicateType identifies the detached in-toto predicate.
    AttestationPredicateType = "https://agentstation.ai/starmap/catalog-generation/v1"
    // AttestationStatementType is the in-toto statement schema identifier.
    AttestationStatementType = "https://in-toto.io/Statement/v1"
    // Filename is the stable archive filename; generation identity is carried by
    // the descriptor and distribution path rather than interpolated into a path.
    Filename = "starmap-catalog.tar.gz"
    // AttestationFilename is the detached in-toto statement filename.
    AttestationFilename = "starmap-catalog.intoto.json"
    // OCIMirrorArtifactType identifies an OCI manifest that mirrors the exact
    // immutable release assets. The catalog archive remains a layer with
    // MediaType, so its digest can be compared across distribution channels.
    OCIMirrorArtifactType = "application/vnd.agentstation.starmap.catalog-mirror.v1"
    // OCIGenerationAnnotation carries the logical catalog generation ID on an
    // OCI mirror manifest. Consumers must still pin and verify content digests.
    OCIGenerationAnnotation = "ai.agentstation.starmap.generation"
)


const (
    // ChecksumFilename is the detached SHA-256 checksum asset.
    ChecksumFilename = "starmap-catalog.tar.gz.sha256"
)

func Open

func Open(archive, attestation []byte) (catalogs.Generation, error)

Open verifies an archive and detached statement before returning its exact immutable catalog generation.

func VerifyRelease

func VerifyRelease(ctx context.Context, release Release, verifier PublisherVerifier) (catalogs.Generation, error)

VerifyRelease checks the detached checksum, archive statement, generation compatibility, and channel-specific publisher identity before returning the exact immutable generation. It performs no activation or persistence.

type AttestationPredicate

AttestationPredicate records the catalog compatibility identity asserted by the detached statement. Signature and builder provenance are added and verified by the publication boundary.

type AttestationPredicate struct {
    GenerationID          string                         `json:"generation_id"`
    ManifestVersion       uint64                         `json:"manifest_version"`
    SchemaVersion         uint64                         `json:"schema_version"`
    ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
}

type AttestationStatement

AttestationStatement is the deterministic in-toto statement emitted beside an artifact. It is deliberately detached to avoid a self-referential archive digest and to permit signing without changing reproducible artifact bytes.

type AttestationStatement struct {
    Type          string               `json:"_type"`
    Subject       []Subject            `json:"subject"`
    PredicateType string               `json:"predicateType"`
    Predicate     AttestationPredicate `json:"predicate"`
}

type Bundle

Bundle contains one reproducible archive and its detached attestation.

type Bundle struct {
    GenerationID        string
    Filename            string
    MediaType           string
    Data                []byte
    Checksum            string
    AttestationFilename string
    Attestation         []byte
}

func Build
func Build(generation catalogs.Generation) (Bundle, error)

Build validates a generation and deterministically packages it for distribution. Rebuilding identical generation bytes produces identical archive and attestation bytes.

type Descriptor

Descriptor describes the complete logical generation carried by an archive.

type Descriptor struct {
    FormatVersion         uint64                         `json:"format_version"`
    MediaType             string                         `json:"media_type"`
    GenerationID          string                         `json:"generation_id"`
    ManifestVersion       uint64                         `json:"manifest_version"`
    SchemaVersion         uint64                         `json:"schema_version"`
    ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
    Manifest              FileDescriptor                 `json:"manifest"`
    Payload               FileDescriptor                 `json:"payload"`
}

func Inspect
func Inspect(archive, attestation []byte) (Descriptor, error)

Inspect verifies the schema-independent artifact envelope and detached statement. It returns compatibility metadata without decoding the catalog payload through the current schema.

func (Descriptor) String
func (d Descriptor) String() string

String returns a concise descriptor useful in logs.

type DigestSet

DigestSet is the SHA-256 digest map used by an in-toto subject.

type DigestSet struct {
    SHA256 string `json:"sha256"`
}

type FileDescriptor

FileDescriptor binds one named artifact member to exact bytes.

type FileDescriptor struct {
    Name      string `json:"name"`
    MediaType string `json:"media_type"`
    Checksum  string `json:"checksum"`
    SizeBytes int64  `json:"size_bytes"`
}

type PublisherVerifier

PublisherVerifier authenticates exact archive bytes to the caller's expected publisher. A GitHub Release implementation, for example, should require the expected repository and signer workflow when verifying build provenance.

VerifyPublisher must return nil only when data is authenticated as the exact contents of name. Implementations own credentials, clients, trust policy, network access, and lifecycle.

type PublisherVerifier interface {
    VerifyPublisher(ctx context.Context, name string, data []byte) error
}

type Release

Release contains the three immutable assets published for one catalog generation. Publisher provenance is channel-specific and is therefore verified through PublisherVerifier rather than encoded as an unsigned field.

type Release struct {
    Archive     []byte
    Checksum    []byte
    Attestation []byte
}

type ReleaseAssets

ReleaseAssets describes one atomically staged immutable publication set.

type ReleaseAssets struct {
    GenerationID    string
    ArchiveChecksum string
    Directory       string
    Files           []string
}

func StageReleaseAssets
func StageReleaseAssets(root string, artifact Bundle) (ReleaseAssets, error)

StageReleaseAssets validates and atomically stages archive, attestation, and checksum assets. An exact retry is idempotent; rebinding the same generation ID to different bytes returns a typed conflict.

type Subject

Subject is one byte object bound by the detached statement.

type Subject struct {
    Name   string    `json:"name"`
    Digest DigestSet `json:"digest"`
}

Generated by gomarkdoc

Documentation

Overview

Package artifact defines the deterministic distribution format for immutable Starmap catalog generations.

Index

Constants

View Source 
const (
	// FormatVersion is the current catalog distribution archive format.
	FormatVersion uint64 = 1
	// MediaType is the media type of the compressed catalog archive.
	MediaType = "application/vnd.agentstation.starmap.catalog-artifact.v1+tar+gzip"
	// DescriptorMediaType is the media type of artifact.json.
	DescriptorMediaType = "application/vnd.agentstation.starmap.catalog-artifact-descriptor.v1+json"
	// AttestationPredicateType identifies the detached in-toto predicate.
	AttestationPredicateType = "https://agentstation.ai/starmap/catalog-generation/v1"
	// AttestationStatementType is the in-toto statement schema identifier.
	AttestationStatementType = "https://in-toto.io/Statement/v1"
	// Filename is the stable archive filename; generation identity is carried by
	// the descriptor and distribution path rather than interpolated into a path.
	Filename = "starmap-catalog.tar.gz"
	// AttestationFilename is the detached in-toto statement filename.
	AttestationFilename = "starmap-catalog.intoto.json"
	// OCIMirrorArtifactType identifies an OCI manifest that mirrors the exact
	// immutable release assets. The catalog archive remains a layer with
	// MediaType, so its digest can be compared across distribution channels.
	OCIMirrorArtifactType = "application/vnd.agentstation.starmap.catalog-mirror.v1"
	// OCIGenerationAnnotation carries the logical catalog generation ID on an
	// OCI mirror manifest. Consumers must still pin and verify content digests.
	OCIGenerationAnnotation = "ai.agentstation.starmap.generation"
)
View Source 
const (
	// ChecksumFilename is the detached SHA-256 checksum asset.
	ChecksumFilename = "starmap-catalog.tar.gz.sha256"
)

Variables

This section is empty.

Functions

func Open 

func Open(archive, attestation []byte) (catalogs.Generation, error)

Open verifies an archive and detached statement before returning its exact immutable catalog generation.

func VerifyRelease 

func VerifyRelease(
	ctx context.Context,
	release Release,
	verifier PublisherVerifier,
) (catalogs.Generation, error)

VerifyRelease checks the detached checksum, archive statement, generation compatibility, and channel-specific publisher identity before returning the exact immutable generation. It performs no activation or persistence.

Types

type AttestationPredicate 

type AttestationPredicate struct {
	GenerationID          string                         `json:"generation_id"`
	ManifestVersion       uint64                         `json:"manifest_version"`
	SchemaVersion         uint64                         `json:"schema_version"`
	ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
}

AttestationPredicate records the catalog compatibility identity asserted by the detached statement. Signature and builder provenance are added and verified by the publication boundary.

type AttestationStatement 

type AttestationStatement struct {
	Type          string               `json:"_type"`
	Subject       []Subject            `json:"subject"`
	PredicateType string               `json:"predicateType"`
	Predicate     AttestationPredicate `json:"predicate"`
}

AttestationStatement is the deterministic in-toto statement emitted beside an artifact. It is deliberately detached to avoid a self-referential archive digest and to permit signing without changing reproducible artifact bytes.

type Bundle 

type Bundle struct {
	GenerationID        string
	Filename            string
	MediaType           string
	Data                []byte
	Checksum            string
	AttestationFilename string
	Attestation         []byte
}

Bundle contains one reproducible archive and its detached attestation.

func Build 

func Build(generation catalogs.Generation) (Bundle, error)

Build validates a generation and deterministically packages it for distribution. Rebuilding identical generation bytes produces identical archive and attestation bytes.

type Descriptor 

type Descriptor struct {
	FormatVersion         uint64                         `json:"format_version"`
	MediaType             string                         `json:"media_type"`
	GenerationID          string                         `json:"generation_id"`
	ManifestVersion       uint64                         `json:"manifest_version"`
	SchemaVersion         uint64                         `json:"schema_version"`
	ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
	Manifest              FileDescriptor                 `json:"manifest"`
	Payload               FileDescriptor                 `json:"payload"`
}

Descriptor describes the complete logical generation carried by an archive.

func Inspect 

func Inspect(archive, attestation []byte) (Descriptor, error)

Inspect verifies the schema-independent artifact envelope and detached statement. It returns compatibility metadata without decoding the catalog payload through the current schema.

func (Descriptor) String 

func (d Descriptor) String() string

String returns a concise descriptor useful in logs.

type DigestSet 

type DigestSet struct {
	SHA256 string `json:"sha256"`
}

DigestSet is the SHA-256 digest map used by an in-toto subject.

type FileDescriptor 

type FileDescriptor struct {
	Name      string `json:"name"`
	MediaType string `json:"media_type"`
	Checksum  string `json:"checksum"`
	SizeBytes int64  `json:"size_bytes"`
}

FileDescriptor binds one named artifact member to exact bytes.

type PublisherVerifier 

type PublisherVerifier interface {
	VerifyPublisher(ctx context.Context, name string, data []byte) error
}

PublisherVerifier authenticates exact archive bytes to the caller's expected publisher. A GitHub Release implementation, for example, should require the expected repository and signer workflow when verifying build provenance.

VerifyPublisher must return nil only when data is authenticated as the exact contents of name. Implementations own credentials, clients, trust policy, network access, and lifecycle.

type Release 

type Release struct {
	Archive     []byte
	Checksum    []byte
	Attestation []byte
}

Release contains the three immutable assets published for one catalog generation. Publisher provenance is channel-specific and is therefore verified through PublisherVerifier rather than encoded as an unsigned field.

type ReleaseAssets 

type ReleaseAssets struct {
	GenerationID    string
	ArchiveChecksum string
	Directory       string
	Files           []string
}

ReleaseAssets describes one atomically staged immutable publication set.

func StageReleaseAssets 

func StageReleaseAssets(root string, artifact Bundle) (ReleaseAssets, error)

StageReleaseAssets validates and atomically stages archive, attestation, and checksum assets. An exact retry is idempotent; rebinding the same generation ID to different bytes returns a typed conflict.

type Subject 

type Subject struct {
	Name   string    `json:"name"`
	Digest DigestSet `json:"digest"`
}

Subject is one byte object bound by the detached statement.

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.