agentpkg

package
v1.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package agentpkg defines the signed Agent Package manifest (ADR-010) and its admission verification. A package pins, by digest: the AgentVersion spec, runtime lock, tool lock, permissions, memory schema and SBOM, plus build provenance. v0.3 signs the canonical manifest with ed25519 under a registered key identity; production admission fails closed on any missing or invalid signature, provenance or unknown key. Cosign interop for OCI image signatures is a future projection; the manifest itself is the kernel's trust anchor.

Index

Constants

View Source 
const ManifestSchema = "fenced.agentpkg/v1"

ManifestSchema is the canonical manifest version.

View Source 
const SBOMSpecVersion = "1.5"

SBOMSpecVersion is the CycloneDX version the generator emits (ADR-010: CI produces an SPDX or CycloneDX SBOM for every package).

Variables

View Source 
var (
	ErrSignatureVerificationFailed = errors.New("security pipeline: package signature verification failed")
	ErrDigestMismatch              = errors.New("security pipeline: SBOM or OCI layer digest mismatch")
	ErrABIIncompatible             = errors.New("security pipeline: syscall ABI version incompatible with kernel")
	ErrCapabilityDenied            = errors.New("security pipeline: admission policy denied requested capabilities")
)
View Source 
var ErrPackageBindingMismatch = errors.New("agent package does not bind to this publication")

ErrPackageBindingMismatch reports a package whose signed manifest does not bind to the publication it is attached to (reference or spec mismatch).

View Source 
var ErrPackageManifestInvalid = errors.New("agent package manifest is invalid")

ErrPackageManifestInvalid reports a malformed manifest.

View Source 
var ErrPackageSignatureInvalid = errors.New("agent package signature is invalid")

ErrPackageSignatureInvalid reports a broken signature, an unknown key, or a manifest that does not match the signature.

View Source 
var ErrPackageUnsigned = errors.New("agent package is not signed")

ErrPackageUnsigned reports a package missing its signature.

Functions

func DecodePrivateKey 

func DecodePrivateKey(encoded string) (ed25519.PrivateKey, error)

DecodePrivateKey parses a base64 raw std or standard private key for the signing CLI.

func DecodePublicKey 

func DecodePublicKey(encoded string) (ed25519.PublicKey, error)

DecodePublicKey parses a base64 raw std or standard public key.

func EncodePublicKey 

func EncodePublicKey(key ed25519.PublicKey) string

EncodePublicKey renders a public key for transport (CLI flags, env vars).

func GenerateSBOM 

func GenerateSBOM(manifest Manifest) ([]byte, error)

GenerateSBOM emits a minimal CycloneDX document describing the locked runtime and tool digests of the manifest. The caller pins its digest into the manifest's sbom field.

func GenerateSigningKey 

func GenerateSigningKey(id string) (*SigningKey, *Key, error)

GenerateSigningKey creates a fresh package-signing key pair.

func ManifestDigest 

func ManifestDigest(manifest Manifest) ([sha256.Size]byte, error)

ManifestDigest returns the SHA-256 of the canonical manifest encoding (the exact bytes Sign signed and Verify re-checks).

func Verify 

func Verify(pkg *Package, keys map[string]ed25519.PublicKey) error

Verify checks the signature against the manifest using the trusted key registry. Verification is fail-closed: an unknown key, a malformed signature or a manifest mismatch rejects the package.

func VerifyImageSignature 

func VerifyImageSignature(manifest Manifest, keys map[string]ed25519.PublicKey) error

VerifyImageSignature checks the manifest's image signature fail-closed: when the manifest declares a signed image, the signature must verify over exactly that digest under a trusted key.

func VerifySBOM 

func VerifySBOM(document []byte, expected Digest) error

VerifySBOM checks that the document is a CycloneDX SBOM and that its SHA-256 digest matches the manifest pin.

Types

type CompatibilityRule 

type CompatibilityRule struct {
	MinKernelVersion string   `json:"minKernelVersion"`
	MaxKernelVersion string   `json:"maxKernelVersion,omitempty"`
	SupportedABIs    []string `json:"supportedAbis"`
}

CompatibilityRule defines compatibility with Fenced versions.

type Digest 

type Digest struct {
	Algorithm string `json:"algorithm"`
	Hex       string `json:"hex"`
}

Digest is a content digest reference (algorithm + hex).

func ComputeContentDigest 

func ComputeContentDigest(content []byte) Digest

ComputeContentDigest calculates standard sha256:hex digest.

func SBOMDigest 

func SBOMDigest(document []byte) Digest

SBOMDigest returns the sha256 digest of the generated document for pinning into the manifest.

func SpecSHA256 

func SpecSHA256(spec []byte) Digest

SpecSHA256 is a convenience for building a manifest from raw spec bytes.

func (Digest) String 

func (d Digest) String() string

func (Digest) Verify 

func (d Digest) Verify(content []byte) bool

VerifyDigest checks the digest against raw content.

type Key 

type Key struct {
	ID        string
	PublicKey ed25519.PublicKey
}

Key is one registered package-signing identity.

type Manifest 

type Manifest struct {
	Schema          string          `json:"schema"`
	AgentVersionRef string          `json:"agentVersionRef"`
	SpecDigest      Digest          `json:"specDigest"`
	Spec            json.RawMessage `json:"spec"`
	RuntimeLock     []Digest        `json:"runtimeLock"`
	ToolLock        []Digest        `json:"toolLock"`
	Permissions     Digest          `json:"permissions"`
	MemorySchema    Digest          `json:"memorySchema"`
	SBOM            Digest          `json:"sbom"`
	Provenance      Provenance      `json:"provenance"`
	// SignedImageDigest is the digest-pinned OCI image this package ships
	// (ADR-010 cosign-style binding); ImageSignature is its signature. When
	// either is set both must be set and the signature must verify.
	SignedImageDigest Digest     `json:"signedImageDigest,omitempty"`
	ImageSignature    *Signature `json:"imageSignature,omitempty"`
}

Manifest is the canonical, signed package document.

func FromAgentManifest 

func FromAgentManifest(manifest agentversion.Manifest, provenance Provenance) (Manifest, error)

FromAgentManifest builds the unsigned supply-chain manifest from a strict portable Agent Manifest. The returned spec bytes are exactly those accepted by AgentVersion publication, so signing and admission bind the same object.

func (Manifest) Validate 

func (m Manifest) Validate() error

Validate checks shape constraints; digest correctness is verified by the admission inputs at publish time.

type MetadataIndex 

type MetadataIndex struct {
	Manifest            Manifest            `json:"manifest"`
	Version             string              `json:"version"`
	OCIDigest           Digest              `json:"ociDigest"`
	Signature           Signature           `json:"signature"`
	SBOM                Digest              `json:"sbom"`
	SyscallABIVersion   string              `json:"syscallAbiVersion"`
	Capabilities        []string            `json:"capabilities"`
	RuntimeRequirements RuntimeRequirements `json:"runtimeRequirements"`
	Publisher           PublisherInfo       `json:"publisher"`
	Compatibility       CompatibilityRule   `json:"compatibility"`
	PublishedAt         time.Time           `json:"publishedAt"`
}

MetadataIndex defines the complete catalog record for an Agent Package in the registry.

func BuildMetadataIndex 

func BuildMetadataIndex(pkg *Package, publisher PublisherInfo, ociDigest Digest) (*MetadataIndex, error)

BuildMetadataIndex creates the complete registry catalog record from a signed package.

type Package 

type Package struct {
	Manifest  Manifest  `json:"manifest"`
	Signature Signature `json:"signature"`
}

Package is the signed manifest envelope exchanged with admission.

func Sign 

func Sign(manifest Manifest, key *SigningKey) (*Package, error)

Sign produces a package for the manifest under the signing key.

type Provenance 

type Provenance struct {
	Builder       string    `json:"builder"`
	BuildWorkflow string    `json:"buildWorkflow"`
	GitCommit     string    `json:"gitCommit"`
	BuiltAt       time.Time `json:"builtAt"`
}

Provenance records who built the package and from what (in-toto/SLSA shape, v0.3 subset): the build workflow identity, the git commit, and the builder. Production admission checks workflow allow-listing on this field.

type PublisherInfo 

type PublisherInfo struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Email        string `json:"email,omitempty"`
	Organization string `json:"organization,omitempty"`
	Verified     bool   `json:"verified"`
}

PublisherInfo identifies the signing organization or author.

type Registry 

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

Registry is the trusted package-signing key set used by publish admission (ADR-010). Lookup is fail-closed: a package signed by a key that is not in the registry is rejected before any other check.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry returns an empty trusted-key registry.

func (*Registry) Add 

func (r *Registry) Add(key Key) error

Add trusts the given key identity. Re-adding an identity with a different key is an error: key IDs must be unique within the trust root.

func (*Registry) Len 

func (r *Registry) Len() int

Len reports the number of trusted key identities.

func (*Registry) Trusted 

func (r *Registry) Trusted() map[string]ed25519.PublicKey

Trusted returns a copy of the trusted key set.

func (*Registry) Verify 

func (r *Registry) Verify(pkg *Package) error

Verify checks the package signature against the trusted registry, fail-closed: an unsigned package, an untrusted key, a malformed signature or a manifest mismatch rejects the package.

type RuntimeRequirements 

type RuntimeRequirements struct {
	CPU       string   `json:"cpu,omitempty"`
	Memory    string   `json:"memory,omitempty"`
	Isolation string   `json:"isolation,omitempty"` // wasm, oci, gvisor
	Features  []string `json:"features,omitempty"`
}

RuntimeRequirements defines hardware and isolation constraints.

type SecurityInstallRequest 

type SecurityInstallRequest struct {
	Package             *Package
	ExpectedKeyID       string
	AllowedCapabilities map[string]bool
	TenantID            string
	DryRun              bool
}

SecurityInstallRequest carries inputs for the 6-stage security gate.

type SecurityInstallResult 

type SecurityInstallResult struct {
	VerifiedSignature bool      `json:"verifiedSignature"`
	VerifiedSBOM      bool      `json:"verifiedSbom"`
	VerifiedDigest    bool      `json:"verifiedDigest"`
	VerifiedABI       bool      `json:"verifiedAbi"`
	VerifiedPolicy    bool      `json:"verifiedPolicy"`
	AgentVersionRef   string    `json:"agentVersionRef"`
	RegisteredAt      time.Time `json:"registeredAt"`
}

SecurityInstallResult details the outcome of every security verification stage.

func ExecuteSecurityPipeline 

func ExecuteSecurityPipeline(
	ctx context.Context,
	req SecurityInstallRequest,
	keyRegistry *Registry,
) (*SecurityInstallResult, error)

ExecuteSecurityPipeline enforces the mandatory 6-stage security gate: Registry Fetch -> Verify Signature -> Verify SBOM/Digest -> Check ABI Compatibility -> Check Capability -> Create AgentVersion. It is physically impossible to bypass Admission, Capability grants, or Policy rules.

type Signature 

type Signature struct {
	KeyID     string    `json:"keyId"`
	Ed25519   string    `json:"ed25519"` // base64 raw std encoding
	CreatedAt time.Time `json:"createdAt"`
}

Signature binds the manifest hash to a registered key identity.

func SignImage 

func SignImage(digest Digest, key *SigningKey) (*Signature, error)

SignImage signs the digest-pinned OCI image the package ships. The signature is embedded in the manifest (SignedImageDigest + ImageSignature) before the manifest itself is signed, so the manifest signature covers it.

type SigningKey 

type SigningKey struct {
	ID         string
	PrivateKey ed25519.PrivateKey
}

SigningKey is the private half; only the signer holds it.

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.