Documentation
¶
Overview ¶
Package release verifies and installs signed Piglet Binary releases.
pig additive (D18): Piglet releases are product-neutral signed indexes whose per-target binaries can be pulled without contacting a Pi or PiG service.
Index ¶
- Constants
- func AssetName(piglet, target string) string
- func Sign(index Index, key ed25519.PrivateKey) ([]byte, error)
- func ValidGitHubRepository(repository string) bool
- func Validate(index Index) error
- func VerifyAsset(path string, verified VerifiedIndex, target string) error
- type Binary
- type GitHubRelease
- type Index
- type Installed
- type Options
- type Receipt
- type ReceiptArtifact
- type Result
- type VerifiedIndex
Constants ¶
const GitHubURLEnv = "PIG_PIGLET_GITHUB_URL"
GitHubURLEnv names the loopback test server that replaces github.com and api.github.com for Piglet release download and discovery.
const PayloadType = "application/vnd.pig.piglet-release+json"
PayloadType is the DSSE payload type of a Piglet release index.
Variables ¶
This section is empty.
Functions ¶
func AssetName ¶
AssetName is the release asset file name of one target's Piglet Binary: pig-<piglet>-<goos>-<goarch>, with .exe for Windows targets.
func Sign ¶
func Sign(index Index, key ed25519.PrivateKey) ([]byte, error)
Sign signs index with key and returns its DSSE envelope as JSON.
func ValidGitHubRepository ¶
ValidGitHubRepository reports whether repository is an owner/name pair that a github:owner/repo@version release reference accepts.
func VerifyAsset ¶
func VerifyAsset(path string, verified VerifiedIndex, target string) error
VerifyAsset checks a local release asset with the checks Pull applies to a download of it: the complete-file size limit, size and SHA-256 named by the signed index, a valid signature trailer by the index signer, and a signed manifest that names the index's Piglet, version, target, and PiG version.
Types ¶
type Binary ¶
type Binary struct {
URL string `json:"url"`
SHA256 string `json:"sha256"`
Size int64 `json:"size"`
}
Binary is one downloadable signed Piglet Binary. SHA256 covers the complete downloaded file, including its signature trailer.
type GitHubRelease ¶
type GitHubRelease struct {
Repository string `json:"repository"`
TagPrefix string `json:"tagPrefix"`
}
GitHubRelease binds a signed index to its repository and per-Piglet tag namespace. An empty TagPrefix selects the repository's unprefixed v<version> tags.
func (GitHubRelease) Reference ¶
func (g GitHubRelease) Reference(version string) string
Reference returns the explicit pull reference for this namespace and version.
func (GitHubRelease) Tag ¶
func (g GitHubRelease) Tag(version string) string
Tag returns the Git tag for a release version.
type Index ¶
type Index struct {
Piglet string `json:"piglet"`
Version string `json:"version"`
PigVersion string `json:"pigVersion"`
SourceRef string `json:"sourceRef"`
GitHub *GitHubRelease `json:"github,omitempty"`
Signer signature.Signer `json:"signer"`
Binaries map[string]Binary `json:"binaries"`
}
Index names one Piglet release and its available target binaries.
type Installed ¶
type Installed struct {
ReceiptPath string
ArtifactPath string
CurrentPath string
Index Index
Manifest signature.Manifest
Digest string
Size int64
}
Installed is one verified pulled release receipt and managed artifact.
func ListInstalled ¶
ListInstalled verifies every pulled release receipt, its signed artifact, and each Piglet's atomic current pointer.
type Options ¶
type Options struct {
Client *http.Client
Target string
Version string
AcceptSigner string
Now func() time.Time
}
Options selects one release target and applies explicit signer rotation.
type Receipt ¶
type Receipt struct {
IndexURL string `json:"indexUrl"`
IndexEnvelope signature.Envelope `json:"indexEnvelope"`
Manifest signature.Manifest `json:"manifest"`
Artifact ReceiptArtifact `json:"artifact"`
InstalledAt string `json:"installedAt"`
}
Receipt retains the signed release index and signed binary manifest that selected one installed artifact.
type ReceiptArtifact ¶
type ReceiptArtifact struct {
Path string `json:"path"`
Digest string `json:"digest"`
Size int64 `json:"size"`
}
ReceiptArtifact binds a receipt to a path under the managed artifact root.
type Result ¶
type Result struct {
Piglet string
Version string
Target string
SignerKeyID string
Artifact string
Receipt string
}
Result identifies the installed artifact and its durable signed receipt.
func Pull ¶
Pull verifies a signed release index and target binary before publishing any managed file. The current pointer is the atomic commit point and pins the first accepted signer for subsequent pulls. Publication revalidates the signer and release identity under a cross-process store lock, refuses rollback, and refuses symlinked managed paths.
func Update ¶
Update discovers the highest stable version in the installed release's signed GitHub namespace, or selects Options.Version explicitly. It preserves the installed target by default and refuses rollback, identity and unapproved signer changes. A current release returns its existing result without rewriting managed files. pig additive (D18): installed signed identity selects the update namespace and remains pinned across release discovery.
type VerifiedIndex ¶
VerifiedIndex is an index whose embedded public key verified its DSSE envelope. The key is still subject to the caller's trust and continuity policy.
func FetchIndex ¶
FetchIndex downloads the signed release index that ref names and verifies its signature and that it describes the requested release. It downloads no Binary and applies no trust or continuity policy, so a publisher can read the identity of a release it made and a catalog entry can name its signer without installing anything.
pig additive (D18): npm Piglet source publication records the signed Binary release that matches it.
func Verify ¶
func Verify(data []byte) (VerifiedIndex, error)
Verify strictly decodes a release envelope, validates its index, and checks the DSSE signature with the public key named by the signed index.