signer

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

type Options struct {
	// Key is the path to a cosign PEM-encoded private key file. An
	// encrypted key is decrypted with the COSIGN_PASSWORD environment
	// variable, matching the cosign CLI.
	Key string
	// IdentityToken is a raw OIDC ID token (a JWT, as a plain string)
	// identifying the signer to Fulcio. Setting it selects the keyless
	// flow: a single-use ephemeral key pair is minted, Fulcio issues a
	// short-lived certificate binding it to the token's identity, and the
	// signature is submitted to Rekor. Obtaining the token is the caller's
	// responsibility — see the package doc.
	//
	// This token is sent as a bearer credential to FulcioURL, which is why
	// FulcioURL and RekorURL are validated to be HTTPS (loopback excepted,
	// for tests) before either is contacted — see keylessBundleOptions.
	IdentityToken string
	// FulcioURL overrides the certificate authority for keyless signing.
	// Empty means DefaultFulcioURL. Defaulting happens at signing time and
	// only when IdentityToken selects the keyless flow — a zero Options
	// value alone still errors with ErrKeyRequired, it does not sign
	// against the public-good deployment by default. Once IdentityToken IS
	// set, though, an empty FulcioURL/RekorURL is a deliberate posture
	// change from "no key ⇒ always error": keyless signing then performs
	// outbound network egress to public-good Sigstore services by default.
	FulcioURL string
	// RekorURL overrides the transparency log for keyless signing. Empty
	// means DefaultRekorURL, applied at signing time as with FulcioURL.
	// Only the Rekor v1 API is supported — see rekorAPIVersionV1.
	//
	// A Rekor entry is not optional: the verification policy this project's
	// container/verifier applies to keyless bundles requires a
	// transparency-log entry, so a bundle signed without one would not
	// verify.
	RekorURL string
}

type Result struct {
	// Bundle is the serialized Sigstore bundle, for durable storage and
	// later offline re-verification.
	//
	// Re-verify it against the ARTIFACT digest — the same digest passed to
	// SignOCI — with [verifier.VerifyBundleOffline] or
	// [verifier.VerifyBundleOfflineWithKey]. Bundle is not bare Sigstore
	// bundle JSON: it wraps the bundle together with the simple-signing
	// payload the signature covers, because that payload is the only thing
	// tying a cosign signature to an artifact. See
	// [verifier.StoredBundleMediaType] for the shape, and
	// [verifier.DecodeStoredBundle] to unwrap it.
	//
	// Its JSON shape is not stable across calls for the same identity: a
	// freshly attached signature wraps sign.Bundle's own bundle media type
	// (v0.3), while a signature this call deduped against (see
	// SignOCI's "one signature, two representations" doc) is reconstructed
	// by verifier.RetrieveBundles from the classic cosign annotations —
	// the v0.1 shape, carrying an inclusion promise rather than a proof.
	// Both verify identically; a caller comparing stored bundles byte-for-
	// byte across calls, or inspecting mediaType, will see this difference.
	Bundle []byte
	// PayloadDigest is the "<algorithm>:<hex>" digest of the simple-signing
	// payload the signature covers.
	//
	// It is NOT the artifact digest passed to SignOCI: following the cosign
	// convention, the signature covers a payload that *embeds* the artifact
	// digest rather than the digest itself. Verifying Bundle does not
	// require it — Bundle carries the payload, and the verifier entry points
	// take the artifact digest — so this is informational: it identifies the
	// blob in the attached signature manifest that this signature signs. See
	// [PayloadDigest] to recompute it from a reference and digest alone.
	PayloadDigest string
}

type Signer interface {
	// SignOCI signs the artifact at ref pinned to the given manifest digest
	// ("sha256:..."), attaches the signature as a cosign signature manifest
	// next to the artifact, and returns the bundle together with the digest
	// it signs.
	SignOCI(ctx context.Context, ref, digest string, opts Options) (*Result, error)
}