repo

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package repo builds and reads package repository indexes.

A repository is one index file listing every version of every package it offers. Each version is a complete PackageSource spec, so whatever reads the index can install an entry without translating it. The index is served over HTTP like a Helm repository index, or pushed to an OCI registry.

Index

Constants

View Source
const (
	AnnotationDescription = "kubepkg.dev/description"
	AnnotationHome        = "kubepkg.dev/home"
)

Annotations on a PackageSource that describe the package in the index.

View Source
const (
	RoleRoot  = "root"
	RoleIndex = "index"
)

Roles a root delegates.

View Source
const AnnotationSignatures = "kubepkg.dev/signatures"

AnnotationSignatures on a PackageSource carries the signatures of a delegated team over that version, as a JSON list; the index copies them into the version. Annotations are outside the spec digest, so signing changes nothing that is signed.

View Source
const IndexAPIVersion = "kubepkg.dev/v1alpha1"

IndexAPIVersion is the version of the index file format. It is not the version of the cluster API and stays as indexes were first published.

View Source
const IndexKind = "RepositoryIndex"

IndexKind is the kind of an index document.

View Source
const RootFile = "root.yaml"

RootFile is where a repository publishes its current root, next to its index; every version also lives at root/<version>.yaml.

View Source
const SignatureSuffix = ".sig"

SignatureSuffix is appended to an index URL to find its signature.

Variables

View Source
var (
	ErrFetchFailed  = errors.New("index cannot be fetched")
	ErrInvalidIndex = errors.New("index is not valid")
)

Errors of LoadIndex besides ErrBadSignature.

View Source
var ErrBadSignature = errors.New("index is not signed by a trusted key")

ErrBadSignature is returned when no trusted key signed an index.

View Source
var ErrExpired = errors.New("expired")

ErrExpired is returned for a root or an index past its expiry.

View Source
var ErrNewerFormat = errors.New("made for a newer kubepkg")

ErrNewerFormat is returned for repository files made for a newer kubepkg.

View Source
var ErrNoVersion = errors.New("no repository offers an acceptable version")

ErrNoVersion is returned when no repository offers an acceptable version.

Functions

func GenerateKey

func GenerateKey() (private, public []byte, err error)

GenerateKey makes an ed25519 key pair, PEM encoded: the private key as PKCS #8, the public key as PKIX.

func KeyID

func KeyID(publicPEM string) (string, error)

KeyID identifies a public key: the hex sha256 of its PKIX encoding.

func LoadIndexWithRoot

func LoadIndexWithRoot(ctx context.Context, fetchers Fetchers, url string, trust Trust, now time.Time) (*Index, []byte, Trust, error)

LoadIndexWithRoot fetches the root chain and the index next to url, follows the root from version 1 to the current one, checks the index against its index role and both expiries, and returns the index and the root reached, to be passed back as Trust next time.

func LoadRepository

func LoadRepository(ctx context.Context, fetchers Fetchers, spec v1.RepositorySpec, status v1.RepositoryStatus, now time.Time) (*Index, []byte, Trust, error)

LoadRepository loads a Repository's index the way its spec asks: through its pinned root, with plain public keys, or unchecked. It refuses an index older than the one in status and returns the root reached, for status, when the repository has a root.

func Newer

func Newer(a, b Version) bool

Newer orders versions, then builds, highest first.

func ParsePublicKeys

func ParsePublicKeys(pems []string) ([]ed25519.PublicKey, error)

ParsePublicKeys reads PEM encoded ed25519 public keys.

func Sign

func Sign(index, privatePEM []byte) ([]byte, error)

Sign signs the index bytes exactly as published. The signature is base64 text, served next to the index under SignatureSuffix. Because the index pins every chart by digest, it covers the whole repository.

func SignIndex

func SignIndex(index, sigFile, privatePEM []byte) ([]byte, error)

SignIndex adds the key's signature over the index bytes to a signature file, which may be empty or hold signatures by other keys.

func SignRoot

func SignRoot(sr *SignedRoot, privatePEM []byte) error

SignRoot adds the key's signature to a root. Signers can sign one after another, on different machines.

func SignSources

func SignSources(file, privatePEM []byte) ([]byte, []string, error)

SignSources adds the key's signature to every PackageSource in a YAML file, in its signatures annotation, and returns the file and what was signed. Charts must be pinned by digest already, as the index will publish them, or the signature would not match.

func SpecDigest

func SpecDigest(spec v1.PackageSourceSpec) (string, error)

SpecDigest is the sha256 of a spec in canonical JSON.

func Verify

func Verify(index, signature []byte, keys []ed25519.PublicKey) error

Verify checks that one of the keys signed the index bytes. Several keys let a repository rotate: trust the new key, then sign with it.

Types

type AllowAll

type AllowAll struct{}

AllowAll is the default policy.

func (AllowAll) AdmitIndex

func (AllowAll) AdmitIndex(context.Context, string, []byte, *Index) error

AdmitIndex implements Policy.

func (AllowAll) AdmitVersion

func (AllowAll) AdmitVersion(context.Context, string, string, Version) error

AdmitVersion implements Policy.

type BuildOptions

type BuildOptions struct {
	// Verify downloads charts that are already pinned and checks their
	// digests too. Charts without a digest are always downloaded and
	// pinned.
	Verify bool
	// Base is the index already published. Its versions are kept, and a
	// version rebuilt with the same number must not change: published
	// versions are immutable, a changed recipe needs a new build.
	Base *Index
	// Relocate moves the charts and package trees of published versions
	// from one registry path to another, oci://old=oci://new by prefix,
	// when a repository moves registries. Only the location changes: each
	// relocated chart is fetched from its new place and must have the
	// digest it was published with, so what a version installs stays the
	// same; its spec digest changes with the location.
	Relocate map[string]string
}

BuildOptions control Build.

type ChartFetcher

type ChartFetcher interface {
	FetchChart(ctx context.Context, c source.Chart) (dir, digest string, err error)
}

ChartFetcher resolves chart digests; source.Fetcher implements it.

type Delegation

type Delegation struct {
	Name string `json:"name"`
	// Packages are name patterns, as path.Match takes them: "cdi", "kubevirt-*".
	Packages  []string `json:"packages"`
	KeyIDs    []string `json:"keyids"`
	Threshold int      `json:"threshold"`
}

Delegation hands the packages whose names match its patterns to other keys: versions of those packages are trusted only with enough of these keys' signatures, whoever signs the index. A team then publishes through the repository's CI without the CI's key being able to forge its packages.

type Fetchers

type Fetchers map[string]IndexFetcher

Fetchers pick an IndexFetcher by URL scheme. A distribution adds its own schemes, e.g. for an internal artifact store.

func DefaultFetchers

func DefaultFetchers() Fetchers

DefaultFetchers handle http:// and https://.

func (Fetchers) Fetch

func (f Fetchers) Fetch(ctx context.Context, u string) ([]byte, error)

Fetch downloads the index at u with the fetcher for its scheme.

type HTTPFetcher

type HTTPFetcher struct{}

HTTPFetcher fetches indexes over HTTP(S).

func (HTTPFetcher) FetchIndex

func (HTTPFetcher) FetchIndex(ctx context.Context, u string) ([]byte, error)

FetchIndex implements IndexFetcher.

type Index

type Index struct {
	APIVersion string `json:"apiVersion"`
	Kind       string `json:"kind"`
	// Generated is when the index was built. Clusters refuse an index
	// older than one they accepted, so an old signed index cannot be
	// replayed to roll them back to versions since withdrawn.
	Generated *metav1.Time `json:"generated,omitempty"`
	// Expires bounds how long clients accept the index: a mirror that
	// keeps serving an old one is refused once it expires. Repositories
	// with a root must set it.
	Expires  *metav1.Time       `json:"expires,omitempty"`
	Packages map[string]Package `json:"packages"`

	// Unknown lists versions this kubepkg left out because their specs
	// have fields it does not know: built for a newer kubepkg.
	Unknown []string `json:"-"`
	// Untrusted lists versions left out because their delegation did not
	// sign them.
	Untrusted []string `json:"-"`
}

Index is a repository index.

func Build

func Build(ctx context.Context, dir string, charts ChartFetcher, opts BuildOptions) (*Index, error)

Build reads every PackageSource in the YAML files under dir and returns the index. Charts without a digest are downloaded and pinned in the index, so a published version always installs the same bytes; the source files are left as they are.

func LoadIndex

func LoadIndex(ctx context.Context, fetchers Fetchers, url string, publicKeys []string) (*Index, []byte, error)

LoadIndex fetches the index at url, checks its signature when public keys are given, and parses it. Errors are ErrFetchFailed, ErrBadSignature or ErrInvalidIndex.

func Parse

func Parse(raw []byte) (*Index, error)

Parse decodes an index and checks its kind.

func (*Index) LeftOut

func (idx *Index) LeftOut() []string

LeftOut describes the versions a client left out of the index, for warnings.

func (*Index) Write

func (idx *Index) Write(w io.Writer) error

Write encodes the index as YAML with packages sorted by name.

type IndexFetcher

type IndexFetcher interface {
	FetchIndex(ctx context.Context, url string) ([]byte, error)
}

IndexFetcher downloads a repository index.

type Package

type Package struct {
	Description string `json:"description,omitempty"`
	Home        string `json:"home,omitempty"`
	// Versions are sorted newest first, by version and then build.
	Versions []Version `json:"versions"`
}

Package is every published version of one package.

type Policy

type Policy interface {
	// AdmitIndex runs on every fetched index before it is used; raw is the
	// index as fetched.
	AdmitIndex(ctx context.Context, repository string, raw []byte, idx *Index) error
	// AdmitVersion runs on a version before it is selected for install.
	AdmitVersion(ctx context.Context, repository, pkg string, v Version) error
}

Policy decides which indexes and versions the operator accepts. It is where a distribution checks signatures, allowed registries and the like.

type Role

type Role struct {
	KeyIDs    []string `json:"keyids"`
	Threshold int      `json:"threshold"`
}

Role is the keys that sign for a role and how many signatures it takes.

type Root

type Root struct {
	Version int       `json:"version"`
	Expires time.Time `json:"expires"`
	// Keys are PEM encoded ed25519 public keys by key ID.
	Keys  map[string]string `json:"keys"`
	Roles map[string]Role   `json:"roles"`
	// Delegations hand packages to other keys. A kubepkg that does not
	// know them cannot reproduce what was signed and refuses the root,
	// rather than install delegated packages unchecked.
	Delegations []Delegation `json:"delegations,omitempty"`
}

Root says which keys may sign for which role, and how many must. It is the repository's trust anchor, after TUF: clients pin the first root's keys and follow later versions, each signed by enough keys of the root before it and of itself.

func (*Root) Delegate

func (r *Root) Delegate(name string, packages, keys []string, threshold int) error

Delegate adds a delegation, putting its keys among the root's keys.

func (Root) Digest

func (r Root) Digest() (string, error)

Digest identifies a root's content.

type Selection

type Selection struct {
	Repository string
	Version    Version
}

Selection is the version chosen for a package.

type Signature

type Signature struct {
	KeyID string `json:"keyid"`
	Sig   string `json:"sig"`
}

Signature is one key's signature.

func SignVersion

func SignVersion(pkg string, v Version, privatePEM []byte) (Signature, error)

SignVersion signs a version of a package with a delegated key.

type Signatures

type Signatures struct {
	Signatures []Signature `json:"signatures"`
}

Signatures is the signature file of an index: several keys may sign.

type SignedRoot

type SignedRoot struct {
	Signed     Root        `json:"signed"`
	Signatures []Signature `json:"signatures"`
}

SignedRoot is a root with the signatures over its canonical form.

func NewRoot

func NewRoot(rootKeys []string, rootThreshold int, indexKeys []string, indexThreshold int, expires time.Time) (*SignedRoot, error)

NewRoot makes version 1 of a root from public keys per role.

func ParseRoot

func ParseRoot(raw []byte) (*SignedRoot, error)

ParseRoot reads a signed root.

type Store

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

Store holds the accepted index of each repository.

func NewStore

func NewStore() *Store

NewStore returns an empty store.

func (*Store) Attempted

func (s *Store) Attempted(name string) bool

Attempted reports whether a repository was fetched at least once.

func (*Store) Catalog

func (s *Store) Catalog(ctx context.Context, variant string, policy Policy) resolve.Catalog

Catalog lists, for every package, the releases of the given variant from the repository it is taken from and that policy admits, so the resolver sees exactly the versions the operator will select from. Of several builds of one version only the newest admitted one is listed.

func (*Store) Delete

func (s *Store) Delete(name string)

Delete forgets a repository.

func (*Store) Describe

func (s *Store) Describe(pkg string) (description, home string)

Describe returns the description and home of a package from the repository it is taken from.

func (*Store) Failed

func (s *Store) Failed(name string)

Failed records a failed fetch. An index loaded earlier stays in use.

func (*Store) Offered

func (s *Store) Offered(pkg, only string) (string, []Version, bool)

Offered returns the repository a package is taken from and its versions, newest first. The highest priority repository that has the package at all shadows the others (ties by name): a package a vendor repository carries never silently comes from a community one. only restricts the choice to one repository.

func (*Store) Packages

func (s *Store) Packages() []string

Packages lists every package name in the store, sorted.

func (*Store) Select

func (s *Store) Select(ctx context.Context, pkg, constraint, only string, policy Policy) (Selection, error)

Select picks the newest version and build of pkg matching constraint from the repository Offered names. policy may refuse a version, and the next one is tried.

func (*Store) Set

func (s *Store) Set(name string, priority int32, idx *Index)

Set records the index of a repository.

type Trust

type Trust struct {
	RootKeys      []string
	RootThreshold int
	// RootVersion and RootDigest are the root accepted before; 0 starts
	// from version 1. A different root under an accepted version number is
	// a forked chain, as made with stolen old keys, and is refused.
	RootVersion int
	RootDigest  string
}

Trust is what a client pins: the first root's keys and threshold, and the root version it accepted last, so a root cannot be rolled back.

type TrustedRoot

type TrustedRoot struct {
	Root Root
}

TrustedRoot is where a client stands: the root it last accepted.

func Bootstrap

func Bootstrap(sr *SignedRoot, pinned []string, threshold int) (*TrustedRoot, error)

Bootstrap verifies version 1 of a root against keys the client pinned out of band and the threshold it expects.

func (*TrustedRoot) Update

func (t *TrustedRoot) Update(next *SignedRoot) error

Update accepts the next root version: it must be exactly one version on, signed by enough root keys of the current root and of itself.

func (*TrustedRoot) VerifyIndex

func (t *TrustedRoot) VerifyIndex(index, sigFile []byte, idx *Index, now time.Time) error

VerifyIndex checks an index against the index role of the root and the expiry of both, and leaves out versions of delegated packages their delegation did not sign.

type Version

type Version struct {
	Version string `json:"version"`
	Build   int32  `json:"build,omitempty"`
	// Digest is the sha256 of the spec in canonical JSON. It identifies
	// exactly what this version installs, charts included, because every
	// chart in the spec is pinned by digest.
	Digest string               `json:"digest"`
	Spec   v1.PackageSourceSpec `json:"spec"`
	// Signatures are by keys a root delegates the package to.
	Signatures []Signature `json:"signatures,omitempty"`
}

Version is one published build of a version.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL