attest

type Check struct {
	// Name identifies the check, e.g. "signature", "certificate-chain".
	Name string `json:"name"`
	// Status is what happened.
	Status CheckStatus `json:"status"`
	// Detail explains a failure, or why a check was skipped.
	Detail string `json:"detail,omitempty"`
}

type CheckStatus string

type Identity struct {
	// Subject is the SAN — a workflow reference in CI, an email for a person,
	// a SPIFFE ID for a workload.
	Subject string `json:"subject,omitempty"`
	// Issuer is the OIDC issuer that authenticated them.
	Issuer string `json:"issuer,omitempty"`
	// NotBefore and NotAfter are the certificate's validity window. Fulcio
	// certificates live for ten minutes, so this is also roughly when the
	// signature was made.
	NotBefore time.Time `json:"notBefore,omitzero"`
	NotAfter  time.Time `json:"notAfter,omitzero"`
	// BuildTrigger, SourceRepository and SourceRevision are the Fulcio CI
	// extensions, present when the signer was a pipeline rather than a person.
	BuildTrigger     string `json:"buildTrigger,omitempty"`
	SourceRepository string `json:"sourceRepository,omitempty"`
	SourceRevision   string `json:"sourceRevision,omitempty"`
}

type Options struct {
	// ArtifactPath is the file being verified, for labelling.
	ArtifactPath string
	// Artifact is the bytes the signature should cover. Required for a cosign
	// detached signature; for DSSE the payload is inside the envelope.
	Artifact []byte
	// SignaturePath and CertificatePath are the cosign detached sidecars.
	SignaturePath, CertificatePath string
	// EnvelopePath is a DSSE envelope (.intoto.jsonl).
	EnvelopePath string
	// Identity, when set, is the exact certificate subject required.
	//
	// Exact, not a pattern. Every keyless subject is a URL, so a pattern is
	// full of dots, and a user pasting "https://github.com/acme/repo" as a
	// regex gets a match on "https://githubXcom/acme/repo" too. The safe
	// comparison is the default and the pattern is opt-in, which is also the
	// split cosign uses (--certificate-identity vs -regexp).
	Identity string
	// IdentityRegex, when set, is a pattern the subject must match. For
	// deliberately matching a set — every workflow in one repository, say.
	IdentityRegex string
	// Issuer, when set, is the OIDC issuer the certificate must name. Accepts a
	// shortcut name (github, gitlab, google, microsoft) as well as a URL.
	Issuer string
	// TrustedRootPath is a PEM bundle to validate the certificate chain
	// against. Empty resolves through SIGSTORE_ROOT_FILE, then the project's
	// own root, then the embedded public-good one — see resolveAnchor.
	TrustedRootPath string
	// ProjectRoot is the repository the artefact belongs to. Used to discover
	// .vulnetix/trusted-root.pem, and to notice when the signer is that
	// repository's own CI.
	ProjectRoot string
	// RepoFullName is the "owner/repo" of ProjectRoot, when it is known.
	// Purely informational: a signature from the repository being scanned is
	// worth pointing out, and one from somewhere else is worth pointing out
	// more.
	RepoFullName string
	// Strict requires the verification to be fully pinned: an identity and an
	// issuer expectation, and a chain that verified. It fails with the exact
	// flags to add rather than a lecture about what strict means.
	Strict bool
	// Require names checks that must have been performed. A required check that
	// was skipped becomes a failure.
	Require []string
	// Now overrides the clock, for tests.
	Now time.Time
}

type Predicate struct {
	// Type is the predicateType URI, verbatim.
	Type string `json:"type"`
	// Kind is what this CLI made of it.
	Kind PredicateKind `json:"kind"`
	// Subjects are the artefacts the statement is about.
	Subjects []Subject `json:"subjects,omitempty"`

	// Builder is who claims to have built the artefact, e.g. a GitHub Actions
	// workflow reference. Provenance only.
	Builder string `json:"builder,omitempty"`
	// BuildType is the build definition the builder followed.
	BuildType string `json:"buildType,omitempty"`
	// SourceURI and SourceRevision are where the inputs came from.
	SourceURI      string `json:"sourceUri,omitempty"`
	SourceRevision string `json:"sourceRevision,omitempty"`
	// Invocation is the entry point the build was started at.
	Invocation string `json:"invocation,omitempty"`

	// SLSAVersion is the provenance schema version: "v0.2" or "v1".
	SLSAVersion string `json:"slsaVersion,omitempty"`
}

type PredicateKind string

type Result struct {
	// Artifact is the file that was verified.
	Artifact string `json:"artifact"`
	// Digest is the SHA-256 of the artefact's bytes.
	Digest string `json:"digest"`
	// Envelope is the signature form that was read: "dsse" or "cosign".
	Envelope string `json:"envelope,omitempty"`
	// Identity is who the certificate says signed it.
	Identity Identity `json:"identity,omitzero"`
	// TrustAnchor names what the chain was verified against.
	TrustAnchor string `json:"trustAnchor,omitempty"`
	// SignerIsThisRepo reports that the signer is the repository being scanned.
	SignerIsThisRepo bool `json:"signerIsThisRepo,omitempty"`
	// SignerRepo names the signer's repository when it is NOT this one.
	SignerRepo string `json:"signerRepo,omitempty"`
	// Checks is every verification step and its outcome. This, not a boolean,
	// is the honest answer.
	Checks []Check `json:"checks"`
	// Suggestions are the ways this verification could be made stricter, each
	// with the exact command to do it.
	//
	// This is the difference between a report that is honest and one that is
	// useful. Telling a reader that nothing pinned the signer's identity is
	// only half an answer; the other half is the flag that would pin it, filled
	// in with the identity actually found.
	Suggestions []Suggestion `json:"suggestions,omitempty"`
	// Predicate is the in-toto predicate when one was found.
	Predicate *Predicate `json:"predicate,omitempty"`
}

type SLSALevelClaim struct {
	// HasProvenance reports whether a provenance predicate was found at all.
	HasProvenance bool `json:"hasProvenance"`
	// HasBuilder, HasSource and HasSubjectDigest report the fields that make
	// provenance actionable.
	HasBuilder       bool `json:"hasBuilder"`
	HasSource        bool `json:"hasSource"`
	HasSubjectDigest bool `json:"hasSubjectDigest"`
	// Missing names the absent fields, so a shortfall is actionable.
	Missing []string `json:"missing,omitempty"`
}

type Subject struct {
	Name   string            `json:"name,omitempty"`
	Digest map[string]string `json:"digest,omitempty"`
}

type Suggestion struct {
	// Why says what is currently unconstrained, in plain terms.
	Why string `json:"why"`
	// Flags is the argument to add to this command, ready to paste. Empty when
	// the suggestion is to run a different tool entirely.
	Flags string `json:"flags,omitempty"`
	// Command is a complete command line, for a suggestion this CLI cannot
	// satisfy itself. Never a fragment with an ellipsis in it: a suggestion the
	// reader has to fill in is one they have to already know the answer to,
	// which defeats the point of suggesting it.
	Command string `json:"command,omitempty"`
}

type TrustAnchor struct {
	// Name identifies the anchor in output, e.g. "Sigstore public-good".
	Name string
	// Pool is what certificates chain to.
	Pool *x509.CertPool
	// Roots are the parsed certificates, for reporting expiry.
	Roots []*x509.Certificate
}