merge

Documentation

Overview

Package merge combines multiple evidence packs into a single merged pack.

Merged packs include:

• All artifacts from source packs (with path prefixing)
• A provenance object documenting which packs were merged
• Optionally embedded attestations from source packs

Attestation Handling

When IncludeAttestations is true, source pack attestations are embedded as complete Sigstore bundles in the provenance. By default (VerifyAttestations: true), signatures are verified and statement subjects are checked against source pack digests before embedding.

Signer identity is intentionally not verified during merge. The merge operator is untrusted from the receiver's perspective, and identity policy is specific to each receiver. Embedded attestations contain complete certificate chains, so receivers can and should verify identity themselves:

// Receiver verifies with their identity policy
verifier, _ := verify.NewSigstoreVerifier(
    verify.WithIssuer("https://accounts.google.com"),
    verify.WithSubject("trusted-signer@example.com"),
)
results, err := pack.VerifyEmbeddedAttestations(ctx, verifier)

Example

verifier, _ := verify.NewSigstoreVerifier(verify.WithInsecureSkipIdentityCheck())
opts := merge.Options{
    Stream:              "myorg/combined",
    IncludeAttestations: true,
    VerifyAttestations:  true,
    Verifier:            verifier,
}
err := merge.Merge(ctx, sources, "merged.epack", opts)

Package merge provides functionality to combine multiple evidence packs into one.

Index

• func Merge(ctx context.Context, sources []SourcePack, outputPath string, opts Options) error
• type Options
  • func SafeMergeOptions(stream string, verifier verify.Verifier) Options
• type SourcePack

Functions

func Merge

func Merge(ctx context.Context, sources []SourcePack, outputPath string, opts Options) error

Merge combines multiple source packs into a single merged pack.

Artifacts from non-merged source packs are prefixed with their stream identifier to avoid collisions (e.g., artifacts/org/prod/data.json). Artifacts from already-merged packs are preserved as-is (flattened) since they already have stream prefixes.

All source streams must be unique, including streams from nested merged packs. This prevents path collisions and ensures each stream appears exactly once in the final pack.

The output pack's manifest includes a provenance object with type="merged" documenting which packs were combined.

Types

type Options

type Options struct {
	// Stream is the stream identifier for the merged pack.
	Stream string

	// MergedBy is the optional identifier of who performed the merge.
	MergedBy string

	// IncludeAttestations embeds source pack attestations in provenance.
	// When true, attestations from source packs are included as embedded_attestation
	// in the provenance.source_packs array.
	IncludeAttestations bool

	// VerifyAttestations enables verification of source pack attestations before
	// embedding them. Defaults to true when IncludeAttestations is true and a
	// Verifier is provided. When enabled, attestations are cryptographically
	// verified and their statement subjects are checked against the source pack
	// digest.
	//
	// To include attestations without verification (not recommended), set
	// IncludeAttestations=true and do not provide a Verifier.
	VerifyAttestations bool

	// Verifier is used to verify source pack attestations. When provided with
	// IncludeAttestations=true, verification is automatically enabled.
	// If VerifyAttestations is explicitly true but Verifier is nil, an error
	// is returned.
	Verifier verify.Verifier
}

Options configures the merge operation.

func SafeMergeOptions

func SafeMergeOptions(stream string, verifier verify.Verifier) Options

SafeMergeOptions returns Options configured for secure merging. This is the recommended way to configure merge for production use.

Features:

• Includes attestations from source packs
• Verifies attestations before embedding
• Requires a verifier with proper identity policy

Example:

verifier, _ := verify.NewStrictVerifier(issuer, subject)
err := merge.Merge(ctx, sources, "merged.pack", merge.SafeMergeOptions("org/merged", verifier))

type SourcePack

type SourcePack struct {
	// Path is the filesystem path to the pack file.
	Path string

	// Pack is an already-opened pack. If nil, the pack will be opened from Path.
	Pack *pack.Pack
}

SourcePack represents a pack to be merged.