Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
4b3ed0d
feat(artifacts): add domain contracts, canonical records, and compati…
osterman Oct 31, 2026
bb356a2
feat(artifacts): add artifacts configuration, validation, and reposit…
osterman Oct 31, 2026
faa07ae
fix(artifacts): repair L2 CI failures in snapshots, fixtures, and Win…
osterman Nov 8, 2026
e29bc8d
fix(artifacts): address foundation review findings
osterman Nov 11, 2026
f9f26cf
fix(artifacts): preserve evaluated configuration origins
osterman Nov 11, 2026
89c529d
refactor(config): simplify artifact source replay
osterman Nov 11, 2026
998183d
test(artifacts): handle Windows trusted key paths
osterman Nov 12, 2026
d07011e
fix(artifacts): carry static sentinels on stream and kind-data failures
osterman Nov 15, 2026
3e73225
fix(artifacts): never echo credentials from rejected URLs and identities
osterman Nov 15, 2026
978c86c
fix(artifacts): validate default packaging against the capability matrix
osterman Nov 15, 2026
aa89526
fix(artifacts): measure S3 tag and identity limits in characters
osterman Nov 15, 2026
515cd74
fix(artifacts): resolve symlink targets through in-package links
osterman Nov 15, 2026
8f3c058
fix(config): evaluate YAML aliases and merge keys and keep include or…
osterman Nov 15, 2026
4016693
test(artifacts): require the trusted key to anchor to its declaring d…
osterman Nov 15, 2026
94d24dc
fix(config): redact credentials from include errors
osterman Nov 15, 2026
581fb88
fix(config): report merge-key origins only for the keys a merge copies
osterman Nov 15, 2026
ee2bff0
fix(config): keep remote provenance when a local include wraps a remo…
osterman Nov 15, 2026
9e0a6ff
fix(config): redact credentials from every include error path
osterman Nov 15, 2026
51146ff
fix(config): bound alias expansion while decoding YAML
osterman Nov 15, 2026
e496f03
test(config): cover include fetch-error redaction and decoded passwords
osterman Nov 15, 2026
586e100
refactor(config): flatten the include evaluation and origin recording
osterman Nov 15, 2026
b0291bf
fix(artifact): find URL userinfo structurally in every redaction helper
osterman Nov 15, 2026
6eafe82
fix(config): group merge-source origins by key before replaying them
osterman Nov 15, 2026
18ef7a3
fix(artifact): redact credentials fail-closed through one shared grammar
osterman Nov 15, 2026
f2afb4d
fix(artifact): route every echoed registry, prefix, key pattern, refe…
osterman Nov 15, 2026
5f8155d
fix(artifact): withhold the unknown key_pattern field name when the p…
osterman Nov 15, 2026
f1ba0bf
fix(artifact): withhold an address with too many boundaries before ex…
osterman Nov 15, 2026
1003fca
fix(utils): redact scheme-less include userinfo and scrub the OCI inc…
osterman Nov 15, 2026
cb3cb6f
fix(artifact): redact every configured name and value an error still …
osterman Nov 15, 2026
53f416d
refactor(artifact): split the address bounds check and boundary scan …
osterman Nov 15, 2026
342bde4
fix(artifact): keep credentials out of decode and factory error text
osterman Nov 16, 2026
b2d2f2a
fix(config): satisfy include key comment lint after integration
osterman Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .atmos-git-hooks.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ checks:
- id: go-fumpt
handler: gofumpt
files: '\.go$'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/)'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|pkg/artifact/compat/testdata/)'
fix: true

- id: go-mod-tidy
Expand All @@ -37,7 +37,7 @@ checks:
- id: golangci-lint
handler: custom_lint
files: '\.go$'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/)'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|pkg/artifact/compat/testdata/)'

- id: gomodcheck
handler: module_compatibility
Expand All @@ -57,18 +57,18 @@ checks:

- id: trailing-whitespace
handler: trailing_whitespace
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|.*\.svg|website/src/components/Screengrabs/)'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|pkg/artifact/compat/testdata/|.*\.svg|website/src/components/Screengrabs/)'
fix: true

- id: end-of-file-fixer
handler: end_of_file
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|.*\.svg|website/src/components/Screengrabs/)'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|pkg/artifact/compat/testdata/|.*\.svg|website/src/components/Screengrabs/)'
fix: true

- id: check-yaml
handler: yaml_syntax
files: '\.(yaml|yml)$'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|tests/fixtures/)'
exclude: '^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|pkg/artifact/compat/testdata/|tests/fixtures/)'

- id: check-added-large-files
handler: large_files
Expand Down
4 changes: 3 additions & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,9 @@ jobs:
# builds silently drop that list in the aggregate `validate --affected` path.
# Exclude README.md: it's machine-generated by cloudposse/build-harness, so its
# formatting isn't ours to enforce.
run: atmos validate --affected --exclude 'tests/fixtures/**' --exclude '**/*.go' --exclude 'specs/**' --exclude 'README.md' --format rich
# pkg/artifact/compat/testdata/** holds frozen, digest-pinned fixtures that must stay
# byte-exact (no trailing newline); this mirrors scripts/checks/checks.star.
run: atmos validate --affected --exclude 'tests/fixtures/**' --exclude 'pkg/artifact/compat/testdata/**' --exclude '**/*.go' --exclude 'specs/**' --exclude 'README.md' --format rich

# Committed website casts and screengrabs are generated artifacts, but a
# change can also edit or hand-record them directly, bypassing the pipeline
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ tools/gomodcheck/.gomodcheck
.DS_Store
/variant
*.tar
# Frozen compatibility fixtures must be committed even when they are archives.
!pkg/artifact/compat/testdata/**/*.tar
*.gz
/bin

Expand Down
42 changes: 42 additions & 0 deletions errors/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ var (
ErrYamlFuncInvalidArguments = errors.New("invalid number of arguments in the Atmos YAML function")
ErrYamlFuncTemplateEmbedding = errors.New("a YAML function value cannot be used in this template expression")
ErrYamlFuncMaxResolutionDepth = errors.New("Atmos YAML function resolution exceeded the maximum dependency depth (likely an undetected circular dependency)")
ErrYamlAliasExpansionLimit = errors.New("YAML aliases expand to more values than the configuration loader allows")
ErrComponentFuncDuringManifestLoad = errors.New("atmos.Component cannot be evaluated while stack manifests are being loaded")
ErrDeferredTemplateContextMissing = errors.New("cannot resolve deferred !template value: template context is unavailable because template processing was disabled for this invocation")
ErrAwsGetCallerIdentity = errors.New("failed to get AWS caller identity")
Expand Down Expand Up @@ -2080,6 +2081,47 @@ var (
ErrPolicyPlan = errors.New("saved plan policy enforcement failed")
)

// Generic artifact domain sentinels. They describe repository-independent outcomes of the
// pkg/artifact contracts; backend adapters wrap them and keep their SDK causes for diagnostics.
// Missing artifacts use ErrArtifactNotFound and integrity mismatches use ErrArtifactIntegrityFailed.
var (
// ErrArtifactConfigInvalid is returned when artifact repository or verification configuration is invalid.
ErrArtifactConfigInvalid = errors.New("invalid artifact configuration")

// ErrArtifactRefInvalid is returned when an artifact name, version, digest, or reference is malformed.
ErrArtifactRefInvalid = errors.New("invalid artifact reference")

// ErrArtifactConflict is returned when a publication, copy, or delete conflicts with existing state.
ErrArtifactConflict = errors.New("artifact conflict")

// ErrArtifactPublicationUnavailable is returned when a reference exists but cannot currently be
// published to or read, for example while another operation is pending or after an interrupted replacement.
ErrArtifactPublicationUnavailable = errors.New("artifact publication is unavailable")

// ErrArtifactUnsupportedCapability is returned when a repository does not provide a requested
// guarantee. It is never a successful no-op.
ErrArtifactUnsupportedCapability = errors.New("artifact repository capability is not supported")

// ErrArtifactDocumentMissing is returned when a requested package document (README or CHANGELOG) does not exist.
ErrArtifactDocumentMissing = errors.New("artifact document not found")

// ErrArtifactPackagingInvalid is returned when source content cannot be packaged as an artifact.
ErrArtifactPackagingInvalid = errors.New("invalid artifact packaging")

// ErrArtifactUnsafePath is returned for absolute, escaping, empty-segment, or reserved paths.
ErrArtifactUnsafePath = errors.New("unsafe artifact path")

// ErrArtifactRecordInvalid is returned when an artifact record fails validation or is not canonical.
ErrArtifactRecordInvalid = errors.New("invalid artifact record")

// ErrArtifactTooLarge is returned when a record, document, or evidence blob exceeds its bounded-read limit.
ErrArtifactTooLarge = errors.New("artifact data exceeds the size limit")

// ErrArtifactStreamFailed is returned when reading or closing an artifact stream fails. The
// underlying I/O error is wrapped alongside it for diagnostics.
ErrArtifactStreamFailed = errors.New("artifact stream failed")
)

// ExitCodeError is a typed error that preserves subcommand exit codes.
// This allows the root command to exit with the same code as the subcommand.
// When Code is 0, it indicates successful completion that should exit cleanly without printing errors.
Expand Down
47 changes: 47 additions & 0 deletions pkg/artifact/boundary_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
package artifact

import (
"go/parser"
"go/token"
"path/filepath"
"strconv"
"strings"
"testing"

"github.com/stretchr/testify/require"
)

// TestPackageDependencyBoundary keeps the domain package free of CLI, runner, hook, plugin, and CI
// dependencies, as required by the package boundary contract.
func TestPackageDependencyBoundary(t *testing.T) {
forbidden := []string{
"github.com/cloudposse/atmos/cmd",
"github.com/cloudposse/atmos/pkg/ci",
"github.com/cloudposse/atmos/pkg/plugin",
"github.com/cloudposse/atmos/pkg/runner",
"github.com/cloudposse/atmos/pkg/hooks",
"github.com/cloudposse/atmos/internal/exec",
"github.com/google/go-containerregistry",
"oras.land/oras-go",
"github.com/aws/aws-sdk-go-v2",
}
files, err := filepath.Glob("*.go")
require.NoError(t, err)
checked := 0
for _, file := range files {
if strings.HasSuffix(file, "_test.go") {
continue
}
parsed, err := parser.ParseFile(token.NewFileSet(), file, nil, parser.ImportsOnly)
require.NoError(t, err)
checked++
for _, spec := range parsed.Imports {
path, err := strconv.Unquote(spec.Path.Value)
require.NoError(t, err)
for _, prefix := range forbidden {
require.Falsef(t, path == prefix || strings.HasPrefix(path, prefix+"/"), "%s imports forbidden package %s", file, path)
}
}
}
require.Positive(t, checked, "no source files were checked")
}
188 changes: 188 additions & 0 deletions pkg/artifact/canonical.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
package artifact

import (
"bytes"
"encoding/json"
"fmt"
"io"

"github.com/opencontainers/go-digest"

errUtils "github.com/cloudposse/atmos/errors"
"github.com/cloudposse/atmos/pkg/perf"
)

// Validate checks the Record against the V1 schema, including that ContentDigest matches the
// inventory and documents. It does not check size limits of the serialized form; Canonical does.
func (r *Record) Validate() error {
defer perf.Track(nil, "artifact.Record.Validate")()

if r.SchemaVersion != SchemaVersion {
return fmt.Errorf("%w: unsupported schema_version %d (want %d)", errUtils.ErrArtifactRecordInvalid, r.SchemaVersion, SchemaVersion)
}
if err := ValidateName(r.Name); err != nil {
return err
}
if err := ValidateVersion(r.Version); err != nil {
return err
}
if err := ValidateKind(r.Kind); err != nil {
return err
}
if r.CreatedAt.IsZero() {
return fmt.Errorf("%w: created_at is required", errUtils.ErrArtifactRecordInvalid)
}
if err := r.Metadata.validate(); err != nil {
return err
}
expected, err := ComputeContentDigest(r.Inventory, r.Documents)
if err != nil {
return err
}
if r.ContentDigest != expected {
return fmt.Errorf("%w: content_digest %q does not match the inventory and documents (%s)", errUtils.ErrArtifactRecordInvalid, r.ContentDigest, expected)
}
return nil
}

func (m Metadata) validate() error {
for key := range m.Labels {
if key == "" {
return fmt.Errorf("%w: label keys must not be empty", errUtils.ErrArtifactRecordInvalid)
}
}
return nil
}

// Seal sets SchemaVersion (when unset) and ContentDigest from the inventory and documents, then
// validates the Record. Call it after assembling a Record from scratch.
func (r *Record) Seal() error {
defer perf.Track(nil, "artifact.Record.Seal")()

if r.SchemaVersion == 0 {
r.SchemaVersion = SchemaVersion
}
computed, err := ComputeContentDigest(r.Inventory, r.Documents)
if err != nil {
return err
}
r.ContentDigest = computed
return r.Validate()
}

// normalized returns a deep-enough copy with sorted arrays, non-nil arrays, normalized time, and
// empty provenance dropped, ready for serialization. The receiver is never mutated.
func (r *Record) normalized() Record {
out := *r
out.CreatedAt = NewTimestamp(r.CreatedAt.Time())
out.Inventory = sortedInventory(r.Inventory)
out.Documents = sortedDocuments(r.Documents)
out.Metadata.Provenance = r.Metadata.Provenance.normalized()
if len(r.Metadata.Labels) == 0 {
out.Metadata.Labels = nil
}
return out
}

func (p *Provenance) normalized() *Provenance {
if p == nil {
return nil
}
out := Provenance{}
if p.CI != nil && *p.CI != (CIProvenance{}) {
ci := *p.CI
out.CI = &ci
}
if p.Source != nil && *p.Source != (SourceProvenance{}) {
source := *p.Source
out.Source = &source
}
if out.CI == nil && out.Source == nil {
return nil
}
return &out
}

// Canonical returns the canonical Record bytes: sorted keys and arrays, UTF-8, integer sizes and
// modes, UTC RFC3339 seconds, no insignificant whitespace, and no trailing newline. The same bytes
// are stored as the OCI config blob and in local and S3 record files. The Record is validated
// first, and records larger than [MaxRecordSize] are rejected.
func (r *Record) Canonical() ([]byte, error) {
defer perf.Track(nil, "artifact.Record.Canonical")()

if err := r.Validate(); err != nil {
return nil, err
}
canonical, err := canonicalJSON(r.normalized())
if err != nil {
return nil, err
}
if int64(len(canonical)) > MaxRecordSize {
return nil, fmt.Errorf("%w: record is %d bytes; the limit is %d", errUtils.ErrArtifactTooLarge, len(canonical), MaxRecordSize)
}
return canonical, nil
}

// canonicalJSON marshals v with encoding/json and re-encodes the result canonically.
func canonicalJSON(v any) ([]byte, error) {
var buf bytes.Buffer
encoder := json.NewEncoder(&buf)
encoder.SetEscapeHTML(false)
if err := encoder.Encode(v); err != nil {
return nil, fmt.Errorf("%w: %w", errUtils.ErrArtifactRecordInvalid, err)
}
return CanonicalizeJSON(buf.Bytes())
}

// RecordDigest returns the SHA-256 of the full canonical Record bytes, including created_at.
func (r *Record) RecordDigest() (digest.Digest, error) {
defer perf.Track(nil, "artifact.Record.RecordDigest")()

canonical, err := r.Canonical()
if err != nil {
return "", err
}
return digest.FromBytes(canonical), nil
}

// DecodeRecord strictly parses canonical Record bytes. It rejects oversize input, unknown fields,
// invalid records, and any bytes that are not exactly the canonical serialization of the decoded
// Record, so the record digest of the stored bytes is always the digest of the decoded value.
func DecodeRecord(raw []byte) (*Record, error) {
defer perf.Track(nil, "artifact.DecodeRecord")()

if int64(len(raw)) > MaxRecordSize {
return nil, fmt.Errorf("%w: record is %d bytes; the limit is %d", errUtils.ErrArtifactTooLarge, len(raw), MaxRecordSize)
}
decoder := json.NewDecoder(bytes.NewReader(raw))
decoder.DisallowUnknownFields()
var record Record
if err := decoder.Decode(&record); err != nil {
return nil, fmt.Errorf("%w: %w", errUtils.ErrArtifactRecordInvalid, err)
}
canonical, err := record.Canonical()
if err != nil {
return nil, err
}
if !bytes.Equal(canonical, raw) {
return nil, fmt.Errorf("%w: bytes are not the canonical serialization", errUtils.ErrArtifactRecordInvalid)
}
return &record, nil
}

// ReadRecord reads and strictly decodes a Record from r, buffering at most [MaxRecordSize] bytes.
// It returns the canonical bytes alongside the Record so callers can compute the record digest
// of exactly what was stored.
func ReadRecord(r io.Reader) (*Record, []byte, error) {
defer perf.Track(nil, "artifact.ReadRecord")()

raw, err := ReadBounded(r, MaxRecordSize)
if err != nil {
return nil, nil, err
}
record, err := DecodeRecord(raw)
if err != nil {
return nil, nil, err
}
return record, raw, nil
}
Loading
Loading