verifier

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

type Result struct {
	// Signed is true when a signature was found and verified.
	Signed bool
	// SignerIdentity is the certificate's subject identity (workflow path
	// for GitHub-Actions-issued certificates, SAN otherwise). Empty for
	// key-signed artifacts, which carry no certificate.
	SignerIdentity string
	// CertIssuer is the OIDC issuer that authenticated the signer. Empty
	// for key-signed artifacts.
	CertIssuer string
	// RepositoryURI is the source repository from the certificate, if any.
	RepositoryURI string
	// RepositoryRef is the git ref the signing workflow ran on, from the
	// certificate's Fulcio extensions. Empty when the certificate carries no
	// such extension (signers outside CI, or gitsign from a personal OIDC
	// identity).
	RepositoryRef string
	// RunnerEnvironment is the runner class the signing workflow executed in
	// (e.g. "github-hosted"), from the certificate's Fulcio extensions.
	// Empty when the certificate carries no such extension.
	RunnerEnvironment string
	// SigstoreURL is the transparency log instance used for verification.
	SigstoreURL string
	// Provisional marks a verification with a documented assurance gap
	// (git signatures until Rekor proof validation lands).
	Provisional bool
	// Bundle is the serialized Sigstore bundle for offline re-verification.
	Bundle []byte
}

type Verifier interface {
	// VerifyOCI discovers the Sigstore signature material attached to the
	// OCI artifact and verifies it (keyless/Fulcio flow). A non-nil
	// expected identity is enforced inside the Sigstore verification
	// policy, and its recorded repository ref and runner environment
	// against the verified certificate; nil expected is the
	// trust-on-first-use case and verifies the chain of trust only.
	// Returns ErrUnsigned when the artifact carries no signature material.
	VerifyOCI(ctx context.Context, imageRef, digest string, expected *lockfile.Provenance) (*Result, error)

	// VerifyOCIWithKey discovers the signature material and verifies it
	// against the given PEM public key (the cosign key-pair flow).
	// Key-signed bundles carry no certificate identity: trust is the key.
	VerifyOCIWithKey(ctx context.Context, imageRef, digest string, pubKeyPEM []byte) (*Result, error)

	// VerifyGit cryptographically verifies a gitsign commit signature over
	// the commit payload against the embedded Fulcio roots. A non-nil
	// expected identity must match the certificate identity; nil expected
	// is the trust-on-first-use case. Returns ErrUnsigned for an empty
	// signature.
	VerifyGit(ctx context.Context, payload, signature []byte, expected *lockfile.Provenance) (*Result, error)

	// VerifyBundleOffline re-verifies a stored bundle against the artifact
	// digest ("sha256:<hex>") without network access, enforcing expected
	// like VerifyOCI.
	VerifyBundleOffline(bundle []byte, digest string, expected *lockfile.Provenance) error

	// VerifyBundleOfflineWithKey re-verifies a stored key-signed bundle
	// against the signer's PEM public key without network access — the
	// offline counterpart of VerifyOCIWithKey. imageRef and digest
	// reconstruct the signed payload, binding the check to the artifact.
	VerifyBundleOfflineWithKey(bundle []byte, imageRef, digest string, pubKeyPEM []byte) error

	// ResultFromBundle verifies a stored bundle offline (chain of trust
	// only) and returns the observed identity — used to back-fill
	// provenance for adopted skills.
	ResultFromBundle(bundle []byte, digest string) (*Result, error)
}