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.
	//
	// Its JSON shape is not stable across calls for the same identity: a
	// freshly attached signature serializes as 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 bundle actually signs.
	//
	// This is deliberately surfaced because 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, so verifying Bundle offline requires this value —
	// passing the artifact digest to a bundle verifier will always fail.
	// 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)
}