imagepolicy

type CosignVerifier struct {
	// Binary overrides the executable path. Tests set it; deployments do not.
	Binary string
	// contains filtered or unexported fields
}

type Decision struct {
	// Ref is the parsed, normalized reference. Zero when parsing failed.
	Ref Reference `json:"ref"`
	// Allowed is the verdict.
	Allowed bool `json:"allowed"`
	// Rule names the rule that decided. On an allow it is empty; on a denial
	// it is one of the Rule* constants.
	Rule string `json:"rule,omitempty"`
	// Reason states what was observed, in the operator's terms.
	Reason string `json:"reason,omitempty"`
	// Remediation states what to do about it.
	Remediation string `json:"remediation,omitempty"`
	// NeedsPin is true for an allowed reference that is not digest-pinned.
	// The executor must resolve and pin it before running; see Enforcer.
	NeedsPin bool `json:"needs_pin,omitempty"`
	// NeedsSignature is true when the policy requires cosign verification of
	// this image. Evaluate does not perform it — it is impure.
	NeedsSignature bool `json:"needs_signature,omitempty"`
	// PolicyActive reports whether any rule was applied at all.
	PolicyActive bool `json:"policy_active"`
}

type DenyError struct {
	Ref         string
	Rule        string
	Reason      string
	Remediation string
}

type Enforcer struct {
	Policy   Policy
	Resolver Resolver
	Verifier Verifier
}

type Identity struct {
	// Issuer is the exact OIDC issuer URL, e.g.
	// "https://token.actions.githubusercontent.com".
	Issuer string `json:"issuer" yaml:"issuer"`
	// SubjectRegexp is a regular expression the certificate subject must
	// match, e.g. "^https://github\\.com/acme/.+".
	SubjectRegexp string `json:"subject_regexp" yaml:"subject_regexp"`
}

type Policy struct {
	// AllowedRegistries are the registry hosts a project may pull from.
	// Matching is on the parsed host, whole-string and case-insensitive. Two
	// forms beyond an exact host are accepted:
	//
	//	*.example.com   any subdomain of example.com, at a label boundary
	//	*               any registry (use with require_digest to constrain
	//	                provenance without constraining the source)
	//
	// Empty means this dimension is not constrained — a policy of nothing but
	// require_digest is a legitimate one ("I do not care where images come
	// from, but they must be immutable"), and reading an empty list as
	// deny-all would make it a hub that refuses every image. Validate refuses
	// the one combination where that reading would be a hole: a registry-less
	// allowed_repos entry with no allowed_registries constrains the path and
	// not the source.
	AllowedRegistries []string `json:"allowed_registries,omitempty" yaml:"allowed_registries,omitempty"`

	// AllowedRepos further narrows which repositories within those registries
	// are permitted. Empty means "any repository on an allowed registry".
	//
	// An entry may name a registry ("ghcr.io/acme/tools") or not
	// ("acme/tools"), in which case it applies within whichever registry
	// already passed AllowedRegistries. A trailing "/*" matches the prefix at
	// a path-component boundary.
	AllowedRepos []string `json:"allowed_repos,omitempty" yaml:"allowed_repos,omitempty"`

	// RequireDigest refuses any reference that is not already pinned to a
	// digest. Without it, a tag reference is still resolved and pinned where
	// the executor can do so — RequireDigest is what makes the *reference*
	// carry the pin, which is the only form that survives an executor with no
	// local image store to resolve against.
	RequireDigest bool `json:"require_digest,omitempty" yaml:"require_digest,omitempty"`

	// RequireSignature refuses any image whose signature cosign cannot verify
	// against CosignPublicKeys or CosignIdentities. Verification is on the
	// digest, never on a tag.
	RequireSignature bool `json:"require_signature,omitempty" yaml:"require_signature,omitempty"`

	// CosignPublicKeys are paths to public keys any one of which may carry the
	// signature (`cosign verify --key`).
	CosignPublicKeys []string `json:"cosign_public_keys,omitempty" yaml:"cosign_public_keys,omitempty"`

	// CosignIdentities are keyless identities any one of which may carry the
	// signature (`cosign verify --certificate-oidc-issuer …`).
	CosignIdentities []Identity `json:"cosign_identities,omitempty" yaml:"cosign_identities,omitempty"`

	// DefaultRegistry qualifies a reference that names no registry.
	//
	// Absent it, "alpine:3.20" is *denied* rather than assumed to be Docker
	// Hub. That is not pedantry: podman resolves an unqualified name against
	// unqualified-search-registries, which is host configuration the policy
	// cannot see, so the same reference can legitimately pull from different
	// registries on two executors in the same fleet. An operator who wants the
	// Docker convention writes it down here.
	DefaultRegistry string `json:"default_registry,omitempty" yaml:"default_registry,omitempty"`
}

type Reference struct {
	// Original is the reference exactly as supplied.
	Original string `json:"original"`
	// Registry is the normalized host[:port]. Empty when the reference named
	// no registry and no default was applied — see Qualified.
	Registry string `json:"registry,omitempty"`
	// Repository is the path below the registry, e.g. "library/alpine".
	Repository string `json:"repository"`
	// Tag is the tag, empty for a digest-only reference.
	Tag string `json:"tag,omitempty"`
	// Digest is the "sha256:…" content digest, empty when the reference is
	// tag-only.
	Digest string `json:"digest,omitempty"`
	// Qualified reports whether the *reference itself* named a registry.
	// False means the registry, if any, came from Policy.DefaultRegistry.
	Qualified bool `json:"qualified"`
}

type RegistryCredential struct {
	Username string
	Password string
}

type RegistryResolver struct {
	// Client performs the requests. Nil uses one bounded by
	// registryRequestTimeout that honours the proxy environment.
	Client *http.Client
	// Credentials returns the login for a registry host, false when there is
	// none. Nil reads DockerConfigCredential.
	Credentials func(registry string) (RegistryCredential, bool)
	// Endpoint returns the base URL a registry's API is served at. Nil serves
	// every registry over https at its own host and Docker Hub at
	// registry-1.docker.io. Tests point it at a local server.
	Endpoint func(registry string) string
}

type Resolver interface {
	// ResolveDigest returns the "sha256:…" digest for ref, or ErrNoDigest when
	// the image exists but carries none.
	ResolveDigest(ctx context.Context, ref string) (string, error)
}

type Result struct {
	// Ref is what the caller must actually run. It is the digest-pinned
	// canonical form whenever one could be obtained.
	Ref string `json:"ref"`
	// Digest is the pinned digest, empty when the reference could not be
	// pinned and the policy did not require it.
	Digest string `json:"digest,omitempty"`
	// Decision is the verdict Evaluate reached on the original reference.
	Decision Decision `json:"decision"`
	// Verified reports that a signature was checked and accepted.
	Verified bool `json:"verified,omitempty"`
	// Warnings describe an accepted-but-weaker outcome, e.g. an image that
	// could not be pinned on a hub that does not require pinning.
	Warnings []string `json:"warnings,omitempty"`
}

type Verifier interface {
	Verify(ctx context.Context, ref string, p Policy) error
}