artifact

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 23, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ProviderWorkOS              = "workos"
	ProviderClerk               = "clerk"
	ProviderSessionFirst        = "session_first"
	ProviderCustomOIDC          = "custom_oidc"
	ProviderAppleNative         = "apple_native"
	ProviderPostgresGeneric     = "postgres_generic"
	ProviderNeonPostgres        = "neon_postgres"
	ProviderPlanetScalePostgres = "planetscale_postgres"
	ProviderR2S3                = "r2_s3"
	ProviderAWSS3               = "aws_s3"
	ProviderS3Compatible        = "s3_compatible"
	ProviderStripe              = "stripe"
	ProviderGitHub              = "github"

	ControlSecurityBaseline      = "security_baseline"
	ControlPrivacyBaseline       = "privacy_baseline"
	ControlAuditEvidenceBaseline = "audit_evidence_baseline"
	ControlDataSubjectRights     = "data_subject_rights"
	ControlDataRetention         = "data_retention"
	ControlTenantIsolation       = "tenant_isolation"
	ControlWebhookSecurity       = "webhook_security"
	ControlSecretHygiene         = "secret_hygiene"
	ControlSupplyChain           = "supply_chain"
	ControlIncidentResponse      = "incident_response_evidence"
	ControlRegionalResidency     = "regional_data_residency"
)

Variables

This section is empty.

Functions

func BlobProviderProfile 

func BlobProviderProfile(provider string) string

func DBProviderProfile 

func DBProviderProfile(provider, engine string) string

func DigestBytes 

func DigestBytes(data []byte) string

DigestBytes computes a canonical sha256 digest for data.

func DigestFile 

func DigestFile(path string) (string, error)

DigestFile computes a canonical sha256 digest for a file.

func EncodeJSON 

func EncodeJSON(w io.Writer, v any) error

EncodeJSON writes deterministic JSON to w.

func IsSHA256Digest 

func IsSHA256Digest(digest string) bool

func LooksSensitiveValue 

func LooksSensitiveValue(s string) bool

LooksSensitiveValue returns true for obvious secret values. It intentionally does not flag ordinary env var names such as DATABASE_URL.

func MarshalDeterministic 

func MarshalDeterministic(v any) ([]byte, error)

MarshalDeterministic returns indented JSON with a trailing newline.

func MarshalDeterministicJSON 

func MarshalDeterministicJSON(v any) ([]byte, error)

MarshalDeterministicJSON returns deterministic JSON bytes. It is an alias for MarshalDeterministic kept for callers that use protocol terminology.

func NormalizeProjectPath 

func NormalizeProjectPath(root, path string) (string, error)

NormalizeProjectPath converts an absolute or relative path to a normalized project-relative path under root.

func NormalizeRelPath 

func NormalizeRelPath(path string) (string, error)

NormalizeRelPath returns a slash-separated project-relative path safe for artifacts.

func ProviderProfileForEnv 

func ProviderProfileForEnv(name string) string

func RedactProviderError 

func RedactProviderError(err error) string

RedactProviderError returns a secret-safe provider error string.

func RedactSensitive 

func RedactSensitive(s string) string

RedactSensitive redacts obvious secret values while preserving non-secret text.

func RedactSensitiveString 

func RedactSensitiveString(s string) (string, bool)

RedactSensitiveString redacts obvious secret values and reports whether the returned string differs from the input.

func RelPath 

func RelPath(root, absOrRel string) (string, error)

RelPath converts an absolute or relative path to a normalized path under root.

func SHA256Bytes 

func SHA256Bytes(data []byte) string

SHA256Bytes computes a canonical sha256 digest for data.

func SHA256File 

func SHA256File(path string) (string, error)

SHA256File computes a canonical sha256 digest for a file.

func SortDiagnostics 

func SortDiagnostics(diags []Diagnostic)

SortDiagnostics orders diagnostics deterministically for stable artifact output.

func StableArtifactID 

func StableArtifactID(kind, path string) string

StableArtifactID returns a stable artifact node ID.

func StableDatabaseBindingID 

func StableDatabaseBindingID(name string) string

func StableDiagnosticID 

func StableDiagnosticID(code, entityID string) string

StableDiagnosticID returns a stable diagnostic ID.

func StableEnvID 

func StableEnvID(name string) string

func StableRouteID 

func StableRouteID(path, method string) string

StableRouteID returns a stable route ID matching artifact route references.

func StableServiceID 

func StableServiceID(name string) string

func StableStateID 

func StableStateID(stableID string) string

func ValidateArtifactRef 

func ValidateArtifactRef(ref ArtifactRef) error

func ValidateSHA256Digest 

func ValidateSHA256Digest(digest string) error

func ValidateSourceRef 

func ValidateSourceRef(ref SourceRef) error

func WriteDeterministicJSON 

func WriteDeterministicJSON(path string, v any) error

WriteDeterministicJSON writes deterministic JSON to path, creating parent directories. It is an alias for WriteJSON kept for protocol-facing callers.

func WriteJSON 

func WriteJSON(path string, v any) error

WriteJSON writes deterministic JSON to path, creating parent directories.

Types

type Analysis 

type Analysis struct {
	Mode              string          `json:"mode"`
	Status            AnalysisStatus  `json:"status"`
	SupportLevel      SupportLevel    `json:"support_level"`
	ProofLevel        ProofLevel      `json:"proof_level"`
	RedactionStatus   RedactionStatus `json:"redaction_status,omitempty"`
	UnsupportedReason string          `json:"unsupported_reason,omitempty"`
}

Analysis describes how an artifact was produced and how strongly it is known.

type AnalysisStatus 

type AnalysisStatus string

AnalysisStatus describes the outcome of producing an artifact. 

const (
	AnalysisStatusSucceeded             AnalysisStatus = "succeeded"
	AnalysisStatusSucceededWithWarnings AnalysisStatus = "succeeded_with_warnings"
	AnalysisStatusFailed                AnalysisStatus = "failed"
	AnalysisStatusNotApplicable         AnalysisStatus = "not_applicable"
	AnalysisStatusManualRequired        AnalysisStatus = "manual_required"
	AnalysisStatusUnsupported           AnalysisStatus = "unsupported"
)

type App 

type App struct {
	ID     string `json:"id,omitempty"`
	Name   string `json:"name,omitempty"`
	Module string `json:"module,omitempty"`
	Root   string `json:"root,omitempty"`
}

App identifies the repository-owned app described by an artifact.

func NewApp 

func NewApp(name, module, root string) App

NewApp returns normalized app metadata for artifact envelopes.

type ArtifactRef 

type ArtifactRef struct {
	ID            string            `json:"id"`
	Kind          string            `json:"kind"`
	Path          string            `json:"path,omitempty"`
	Digest        string            `json:"digest,omitempty"`
	SchemaVersion string            `json:"schema_version,omitempty"`
	Status        ArtifactRefStatus `json:"status"`
	ProofLevel    ProofLevel        `json:"proof_level,omitempty"`
	Required      bool              `json:"required"`
}

ArtifactRef points at another versioned artifact.

func FileArtifactRef 

func FileArtifactRef(root, kind, relPath, schemaVersion string, required bool, proof ProofLevel) (ArtifactRef, error)

FileArtifactRef creates a ref for a workspace-relative file, including digest when present.

func NewArtifactRef 

func NewArtifactRef(kind, path, digest, schemaVersion string, required bool) (ArtifactRef, error)

NewArtifactRef creates a normalized current artifact reference.

func NewMissingArtifactRef 

func NewMissingArtifactRef(kind, path, schemaVersion string, required bool) (ArtifactRef, error)

NewMissingArtifactRef creates a normalized missing artifact reference.

type ArtifactRefStatus 

type ArtifactRefStatus string

ArtifactRefStatus describes the freshness or availability of a referenced artifact. 

const (
	ArtifactRefStatusCurrent       ArtifactRefStatus = "current"
	ArtifactRefStatusStale         ArtifactRefStatus = "stale"
	ArtifactRefStatusMissing       ArtifactRefStatus = "missing"
	ArtifactRefStatusInvalid       ArtifactRefStatus = "invalid"
	ArtifactRefStatusNotGenerated  ArtifactRefStatus = "not_generated"
	ArtifactRefStatusNotApplicable ArtifactRefStatus = "not_applicable"
	ArtifactRefStatusUnsupported   ArtifactRefStatus = "unsupported"
	ArtifactRefStatusUnknown       ArtifactRefStatus = "unknown"
)

type Diagnostic 

type Diagnostic struct {
	Code       string     `json:"code"`
	Severity   Severity   `json:"severity"`
	Message    string     `json:"message"`
	EntityID   string     `json:"entity_id,omitempty"`
	FieldPath  string     `json:"field_path,omitempty"`
	SourceRef  SourceRef  `json:"source_ref,omitempty"`
	ProofLevel ProofLevel `json:"proof_level,omitempty"`
	Repair     Repair     `json:"repair,omitempty"`
}

Diagnostic is a stable machine-readable Vango artifact finding.

func NormalizeDiagnostics 

func NormalizeDiagnostics(diags []Diagnostic) []Diagnostic

NormalizeDiagnostics trims stable fields and normalizes source refs.

func ValidateArtifactRefsForPersistence 

func ValidateArtifactRefsForPersistence(refs []ArtifactRef, opts RefValidationOptions) []Diagnostic

ValidateArtifactRefsForPersistence validates artifact reference path shape, digest shape, and optional file freshness.

func ValidateDiagnosticShape 

func ValidateDiagnosticShape(diagnostics []Diagnostic, codePrefix string) []Diagnostic

func ValidateEnvelope 

func ValidateEnvelope(e Envelope) []Diagnostic

ValidateEnvelope reports protocol-shape diagnostics for an envelope.

func ValidateNoAbsolutePaths 

func ValidateNoAbsolutePaths(v any) []Diagnostic

ValidateNoAbsolutePaths reports diagnostics for artifact path fields that contain absolute paths or path traversal.

func ValidateNoSecretValues 

func ValidateNoSecretValues(v any) []Diagnostic

ValidateNoSecretValues reports diagnostics for obvious plaintext secret values in an artifact payload.

func ValidatePersistableRedactionStatus 

func ValidatePersistableRedactionStatus(status RedactionStatus, codePrefix, fieldPath, artifactName string) []Diagnostic

ValidatePersistableRedactionStatus enforces that persisted artifact evidence is either known secret-safe or already redacted.

func ValidateReferenceMapForPersistence 

func ValidateReferenceMapForPersistence(references map[string]ArtifactRef, canonical []ArtifactRef, opts RefValidationOptions) []Diagnostic

ValidateReferenceMapForPersistence validates a stable references map and ensures it mirrors the canonical refs exposed elsewhere in the artifact.

type Envelope 

type Envelope struct {
	SchemaVersion string                 `json:"schema_version"`
	ArtifactID    string                 `json:"artifact_id"`
	ArtifactKind  string                 `json:"artifact_kind"`
	Producer      Producer               `json:"producer"`
	App           App                    `json:"app"`
	Analysis      Analysis               `json:"analysis"`
	Inputs        []ArtifactRef          `json:"inputs"`
	Outputs       []ArtifactRef          `json:"outputs"`
	References    map[string]ArtifactRef `json:"references,omitempty"`
	Diagnostics   []Diagnostic           `json:"diagnostics"`
}

Envelope is the shared top-level artifact shape embedded by companion artifacts.

func NewEnvelope 

func NewEnvelope(schemaVersion, artifactKind string, producer Producer, app App, analysis Analysis) Envelope

NewEnvelope returns a normalized shared envelope with empty slices initialized.

func NormalizeEnvelope 

func NormalizeEnvelope(e Envelope) Envelope

NormalizeEnvelope returns a copy with required slices initialized and sorted diagnostics.

type Operation 

type Operation string

Operation is the shared host/runtime operation vocabulary. 

const (
	OperationSetupAnalysis       Operation = "setup_analysis"
	OperationBuild               Operation = "build"
	OperationPreviewDeploy       Operation = "preview_deploy"
	OperationProductionPromotion Operation = "production_promotion"
	OperationRollback            Operation = "rollback"
	OperationScaleToZero         Operation = "scale_to_zero"
	OperationHorizontalScale     Operation = "horizontal_scale"
	OperationNewRegionEnablement Operation = "new_region_enablement"
	OperationNewCellEnablement   Operation = "new_cell_enablement"
	OperationMigrationOperation  Operation = "migration_operation"
	OperationNativeRelease       Operation = "native_release"
	OperationDomainAttach        Operation = "domain_attach"
)

type OperationReadiness 

type OperationReadiness struct {
	Operation         Operation       `json:"operation"`
	Status            ReadinessStatus `json:"status"`
	ProofLevel        ProofLevel      `json:"proof_level"`
	RequiredArtifacts []string        `json:"required_artifacts,omitempty"`
	BlockingFacts     []string        `json:"blocking_facts,omitempty"`
	ManualReviewFacts []string        `json:"manual_review_facts,omitempty"`
	UnsupportedFacts  []string        `json:"unsupported_facts,omitempty"`
	NotProvenFacts    []string        `json:"not_proven_facts,omitempty"`
	Diagnostics       []Diagnostic    `json:"diagnostics,omitempty"`
	Repair            Repair          `json:"repair,omitempty"`
}

OperationReadiness is a domain-local readiness projection.

type Origin 

type Origin string

Origin describes where an artifact fact came from. 

const (
	OriginDeclared              Origin = "declared"
	OriginGeneratedArtifact     Origin = "generated_artifact"
	OriginDiscovered            Origin = "discovered"
	OriginInferredLowConfidence Origin = "inferred_low_confidence"
	OriginHostAttached          Origin = "host_attached"
)

type Producer 

type Producer struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Tool        string `json:"tool"`
	ToolVersion string `json:"tool_version"`
	Commit      string `json:"commit,omitempty"`
}

Producer identifies the Vango toolchain that emitted an artifact.

func NewProducer 

func NewProducer(version, commit string) Producer

NewProducer returns standard Vango producer metadata.

type ProfileFact 

type ProfileFact struct {
	ID                  string       `json:"id"`
	Kind                string       `json:"kind"`
	Family              string       `json:"family,omitempty"`
	Profile             string       `json:"profile,omitempty"`
	Status              string       `json:"status"`
	SupportLevel        SupportLevel `json:"support_level"`
	ProofLevel          ProofLevel   `json:"proof_level"`
	Facts               []string     `json:"facts"`
	RequiredArtifacts   []string     `json:"required_artifacts"`
	HostBindingRequired bool         `json:"host_binding_required,omitempty"`
	CoveredFacts        []string     `json:"covered_facts"`
	ManualReviewFacts   []string     `json:"manual_review_facts"`
	UnsupportedFacts    []string     `json:"unsupported_facts"`
}

ProfileFact is the shared compact fact shape for provider/control profiles. Domain companion artifacts remain authoritative for detailed semantics.

func NewControlProfileFact 

func NewControlProfileFact(profile, family, status string, requiredArtifacts []string, coveredFacts []string, manualReviewFacts []string) ProfileFact

func NewProviderProfileFact 

func NewProviderProfileFact(profile, family, status string, requiredArtifacts []string, manualReviewFacts []string) ProfileFact

type ProofLevel 

type ProofLevel string

ProofLevel describes how strongly an artifact fact is known. 

const (
	ProofLevelNone                  ProofLevel = "none"
	ProofLevelDeclared              ProofLevel = "declared"
	ProofLevelDiscovered            ProofLevel = "discovered"
	ProofLevelInferredLowConfidence ProofLevel = "inferred_low_confidence"
	ProofLevelGeneratedArtifact     ProofLevel = "generated_artifact"
	ProofLevelSourceValidated       ProofLevel = "source_validated"
	ProofLevelBuildValidated        ProofLevel = "build_validated"
	ProofLevelFreshValidated        ProofLevel = "fresh_validated"
	ProofLevelShadowValidated       ProofLevel = "shadow_validated"
	ProofLevelLiveReadOnlyValidated ProofLevel = "live_read_only_validated"
	ProofLevelHostAttached          ProofLevel = "host_attached"
	ProofLevelOperatorAcknowledged  ProofLevel = "operator_acknowledged"
	ProofLevelOperationExecuted     ProofLevel = "operation_executed"
	ProofLevelManualRequired        ProofLevel = "manual_required"
	ProofLevelNotSupportedYet       ProofLevel = "not_supported_yet"
	ProofLevelNotApplicable         ProofLevel = "not_applicable"
	ProofLevelUnknown               ProofLevel = "unknown"
)

type ReadinessStatus 

type ReadinessStatus string

ReadinessStatus is the shared operation readiness status vocabulary. 

const (
	ReadinessReady             ReadinessStatus = "ready"
	ReadinessReadyWithWarnings ReadinessStatus = "ready_with_warnings"
	ReadinessDegradedReady     ReadinessStatus = "degraded_ready"
	ReadinessManualRequired    ReadinessStatus = "manual_required"
	ReadinessBlocked           ReadinessStatus = "blocked"
	ReadinessNotApplicable     ReadinessStatus = "not_applicable"
	ReadinessNotSupportedYet   ReadinessStatus = "not_supported_yet"
	ReadinessUnknown           ReadinessStatus = "unknown"
)

type RedactionStatus 

type RedactionStatus string

RedactionStatus describes whether evidence is safe to persist or display. 

const (
	RedactionStatusSecretSafe           RedactionStatus = "secret_safe"
	RedactionStatusRedacted             RedactionStatus = "redacted"
	RedactionStatusUnsafeForPersistence RedactionStatus = "unsafe_for_persistence"
	RedactionStatusUnknown              RedactionStatus = "unknown"
)

type RefValidationOptions 

type RefValidationOptions struct {
	ProjectRoot      string
	RequireArtifacts bool
	CodePrefix       string
	FieldPrefix      string
}

type Repair 

type Repair struct {
	Summary                  string   `json:"summary,omitempty"`
	Commands                 []string `json:"commands,omitempty"`
	SafeToApplyAutomatically bool     `json:"safe_to_apply_automatically,omitempty"`
	AffectedPaths            []string `json:"affected_paths,omitempty"`
}

Repair describes a suggested manual or automated repair action.

type Severity 

type Severity string

Severity is the Vango artifact diagnostic severity vocabulary. 

const (
	SeverityInfo     Severity = "info"
	SeverityWarning  Severity = "warning"
	SeverityError    Severity = "error"
	SeverityCritical Severity = "critical"
)

type SourceRef 

type SourceRef struct {
	Path      string `json:"path,omitempty"`
	FieldPath string `json:"field_path,omitempty"`
	Line      int    `json:"line,omitempty"`
	LineStart int    `json:"line_start,omitempty"`
	LineEnd   int    `json:"line_end,omitempty"`
	Symbol    string `json:"symbol,omitempty"`
	Anchor    string `json:"anchor,omitempty"`
}

SourceRef points back to source/config/artifact input fields.

func NormalizeSourceRef 

func NormalizeSourceRef(ref SourceRef) (SourceRef, error)

NormalizeSourceRef validates and normalizes a source reference.

func (SourceRef) IsZero 

func (ref SourceRef) IsZero() bool

type SupportLevel 

type SupportLevel string

SupportLevel describes whether Vango can analyze a fact directly. 

const (
	SupportLevelSupported             SupportLevel = "supported"
	SupportLevelSupportedConservative SupportLevel = "supported_conservative"
	SupportLevelHostControlled        SupportLevel = "host_controlled"
	SupportLevelAdapterControlled     SupportLevel = "adapter_controlled"
	SupportLevelManaged               SupportLevel = "managed"
	SupportLevelNotSupportedYet       SupportLevel = "not_supported_yet"
	SupportLevelNotApplicable         SupportLevel = "not_applicable"
	SupportLevelUnsupported           SupportLevel = "unsupported"
	SupportLevelUnknown               SupportLevel = "unknown"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.