catalog

Documentation

Overview

Package catalog provides fail-closed helpers for the sovereign artifact catalog. It deliberately separates local source validation from signing, upload, and relay publication.

Index

• Constants
• type Asset
• type CheckedAsset
  • func Preflight(manifest Manifest) ([]CheckedAsset, error)
• type EventPublisher
• type Manifest
• type PublishError
  • func (e *PublishError) Error() string
  • func (e *PublishError) Unwrap() error
• type PublishReceipt
  • func PublishBundle(ctx context.Context, publisher EventPublisher, bundle *SignedBundle) (*PublishReceipt, error)
• type RelayPublisher
  • func NewRelayPublisher(config RelayPublisherConfig) (*RelayPublisher, error)
  • func (p *RelayPublisher) Publish(ctx context.Context, event casnostr.Event) error
• type RelayPublisherConfig
• type SignedBundle
  • func SignBundle(ctx context.Context, manifest Manifest, checked []CheckedAsset, ...) (*SignedBundle, error)

Constants

const (
	KindFileMetadata        = 1063
	KindReleaseArtifactSet  = 30063
	KindAppCurationSet      = 30267
	KindSoftwareApplication = 32267
)

Types

type Asset

type Asset struct {
	SourcePath string
	SHA256     string
	MIMEType   string
	Format     string
	Platform   string
	Arch       string
}

Asset describes one local artifact before it is uploaded to Blossom.

type CheckedAsset

type CheckedAsset struct {
	SourcePath string
	SHA256     string
	Size       int64
	MIMEType   string
	Format     string
	Platform   string
	Arch       string
}

CheckedAsset is immutable source evidence suitable for constructing a kind 1063 event after preflight succeeds.

func Preflight

func Preflight(manifest Manifest) ([]CheckedAsset, error)

Preflight validates identities and release metadata, then hashes every local artifact. It performs no network access, signing, upload, or publication.

type EventPublisher

type EventPublisher interface {
	Publish(context.Context, casnostr.Event) error
}

EventPublisher publishes one already-signed event. Implementations should treat replay of the same event ID as success, making PublishBundle retryable.

type Manifest

type Manifest struct {
	ApplicationID string
	Name          string
	Summary       string
	Description   string
	Repository    string
	Version       string
	ReleaseNotes  string
	ProjectPubKey string
	CuratorPubKey string
	Audience      string
	// CatalogEntries is the curator's complete existing audience-catalog
	// snapshot. SignBundle preserves these entries and appends this application.
	CatalogEntries []string
	Assets         []Asset
}

Manifest is the source-side contract for one software release. Public keys are hex-encoded Nostr public keys; private signing material is intentionally not part of this type.

type PublishError

type PublishError struct {
	Stage     string
	EventID   casnostr.ID
	Published []casnostr.ID
	Err       error
}

PublishError reports a stopped publication without hiding the accepted prefix. Retrying the same signed bundle is safe because Nostr event IDs are content-addressed.

func (*PublishError) Error

func (e *PublishError) Error() string

func (*PublishError) Unwrap

func (e *PublishError) Unwrap() error

type PublishReceipt

type PublishReceipt struct {
	Published []casnostr.ID
}

PublishReceipt identifies the exact prefix accepted before completion or a partial failure.

func PublishBundle

func PublishBundle(ctx context.Context, publisher EventPublisher, bundle *SignedBundle) (*PublishReceipt, error)

PublishBundle verifies the complete signed graph before publishing in dependency order: assets, application, release, then curator catalog. It stops on the first failure so no release or catalog can advertise an incomplete dependency prefix.

type RelayPublisher

type RelayPublisher struct {
	// contains filtered or unexported fields
}

RelayPublisher publishes signed events to Nostr relays and fails unless the configured acknowledgement quorum is met.

func NewRelayPublisher

func NewRelayPublisher(config RelayPublisherConfig) (*RelayPublisher, error)

func (*RelayPublisher) Publish

func (p *RelayPublisher) Publish(ctx context.Context, event casnostr.Event) error

type RelayPublisherConfig

type RelayPublisherConfig struct {
	RelayURLs          []string
	MinimumAcceptances int
}

RelayPublisherConfig defines the relay acknowledgement threshold for every event in a bundle.

type SignedBundle

type SignedBundle struct {
	Application *casnostr.Event
	Assets      []*casnostr.Event
	Release     *casnostr.Event
	Catalog     *casnostr.Event
}

SignedBundle is the complete event graph for one curated release. Project events are signed by the per-project identity; Catalog is signed separately by the fleet curator.

func SignBundle

func SignBundle(
	ctx context.Context,
	manifest Manifest,
	checked []CheckedAsset,
	artifactURLs map[string]string,
	projectSigner casnostr.Signer,
	curatorSigner casnostr.Signer,
	createdAt time.Time,
) (*SignedBundle, error)

SignBundle constructs and signs the canonical sovereign catalog event graph. It has no network side effects. artifactURLs must point to the content whose digest was established by Preflight.