diff --git a/internal/domain/storepkg/catalogue.go b/internal/domain/storepkg/catalogue.go index 6dd2b1767..8e4c67c32 100644 --- a/internal/domain/storepkg/catalogue.go +++ b/internal/domain/storepkg/catalogue.go @@ -4,11 +4,18 @@ import ( "context" "errors" "fmt" + "time" ) // ErrCatalogueUnavailable means no catalogue is configured for this instance. var ErrCatalogueUnavailable = errors.New("no package catalogue is configured") +// ErrCatalogueStale means the catalogue is older than the newest one this +// instance has accepted. A registry or a network attacker can serve an older +// validly signed catalogue and pin outdated package digests, so an issue time +// is only ever accepted going forward. +var ErrCatalogueStale = errors.New("catalogue is older than the newest accepted catalogue") + // CatalogueEntry is one package a catalogue offers: where it is and the // digest that pins it. type CatalogueEntry struct { @@ -22,11 +29,21 @@ type CatalogueEntry struct { // Catalogue is a verified list of packages. type Catalogue struct { + // IssuedAt is when the publisher issued this catalogue. The signature + // covers it, so it can be neither stripped nor altered, and it is + // ordered against the newest issue time accepted so far. A catalogue + // without one is refused: accepting it would leave the replay hole open + // for exactly the catalogues published before the field existed. + IssuedAt time.Time `json:"issued_at"` Packages []CatalogueEntry `json:"packages"` } -// Validate refuses an entry an install could not pin. +// Validate refuses a catalogue an install could not trust: one with no signed +// issue time to order it by, or an entry an install could not pin. func (c Catalogue) Validate() error { + if c.IssuedAt.IsZero() { + return errors.New("catalogue has no issue time") + } seen := make(map[string]bool, len(c.Packages)) for _, entry := range c.Packages { switch { @@ -48,6 +65,50 @@ type CatalogueSource interface { Fetch(context.Context) (Catalogue, error) } +// Freshness is the durable high-water mark of accepted catalogue issue +// times: the newest a verified catalogue issued at that this instance has +// accepted. It survives restarts, so a replayed catalogue is refused after +// one too. +type Freshness interface { + // Newest returns the newest accepted issue time, or the zero time when + // no catalogue has been accepted yet. + Newest(context.Context) (time.Time, error) + // Accept records a catalogue issued at issuedAt as accepted. It never + // lowers the mark. + Accept(ctx context.Context, issuedAt time.Time) error +} + +// FreshCatalogueSource refuses a replayed catalogue: one issued before the +// newest issue time Freshness holds. The wrapped source's own verification +// runs first, so a catalogue is refused as stale only once it is known to be +// genuine -- the signature proves an older catalogue is authentic, and the +// issue time is what stops it. +type FreshCatalogueSource struct { + Source CatalogueSource + Freshness Freshness +} + +var _ CatalogueSource = FreshCatalogueSource{} + +func (f FreshCatalogueSource) Fetch(ctx context.Context) (Catalogue, error) { + catalogue, err := f.Source.Fetch(ctx) + if err != nil { + return Catalogue{}, err + } + newest, err := f.Freshness.Newest(ctx) + if err != nil { + return Catalogue{}, fmt.Errorf("read catalogue freshness: %w", err) + } + if !newest.IsZero() && catalogue.IssuedAt.Before(newest) { + return Catalogue{}, fmt.Errorf("%w: issued %s, newest accepted %s", + ErrCatalogueStale, catalogue.IssuedAt.Format(time.RFC3339), newest.Format(time.RFC3339)) + } + if err := f.Freshness.Accept(ctx, catalogue.IssuedAt); err != nil { + return Catalogue{}, fmt.Errorf("record catalogue freshness: %w", err) + } + return catalogue, nil +} + // ListCatalogue returns the verified catalogue. func (s Service) ListCatalogue(ctx context.Context) (Catalogue, error) { if s.Catalogue == nil { diff --git a/internal/domain/storepkg/catalogue_test.go b/internal/domain/storepkg/catalogue_test.go new file mode 100644 index 000000000..08166048a --- /dev/null +++ b/internal/domain/storepkg/catalogue_test.go @@ -0,0 +1,138 @@ +package storepkg + +import ( + "context" + "errors" + "testing" + "time" +) + +type fakeCatalogueSource struct { + catalogue Catalogue + err error +} + +func (f fakeCatalogueSource) Fetch(context.Context) (Catalogue, error) { + return f.catalogue, f.err +} + +type fakeFreshness struct { + newest time.Time + newestErr error + accepted []time.Time + acceptErr error +} + +func (f *fakeFreshness) Newest(context.Context) (time.Time, error) { + return f.newest, f.newestErr +} + +func (f *fakeFreshness) Accept(_ context.Context, issuedAt time.Time) error { + if f.acceptErr != nil { + return f.acceptErr + } + f.accepted = append(f.accepted, issuedAt) + if issuedAt.After(f.newest) { + f.newest = issuedAt + } + return nil +} + +// A verified catalogue is accepted only while its issue time is not older +// than the newest one accepted: an older validly signed catalogue is a +// replay, and the refusal names both times. A freshness failure fails +// closed, so a broken mark never widens what is accepted. +func TestFreshCatalogueSource(t *testing.T) { + jan1 := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + jan2 := time.Date(2026, 1, 2, 0, 0, 0, 0, time.UTC) + errUnverified := errors.New("signature does not verify") + errMarkUnreadable := errors.New("mark unreadable") + errDiskFull := errors.New("disk full") + tests := []struct { + name string + source fakeCatalogueSource + mark fakeFreshness + wantErr error + wantNewest time.Time + }{ + { + name: "no mark yet accepts", + source: fakeCatalogueSource{catalogue: Catalogue{IssuedAt: jan1}}, + wantNewest: jan1, + }, + { + name: "a newer catalogue is accepted and recorded", + source: fakeCatalogueSource{catalogue: Catalogue{IssuedAt: jan2}}, + mark: fakeFreshness{newest: jan1}, + wantNewest: jan2, + }, + { + name: "the same issue time is accepted again", + source: fakeCatalogueSource{catalogue: Catalogue{IssuedAt: jan1}}, + mark: fakeFreshness{newest: jan1}, + wantNewest: jan1, + }, + { + name: "an older catalogue is refused as a replay", + source: fakeCatalogueSource{catalogue: Catalogue{IssuedAt: jan1}}, + mark: fakeFreshness{newest: jan2}, + wantErr: ErrCatalogueStale, + }, + { + name: "an unverified catalogue is refused by its source", + source: fakeCatalogueSource{err: errUnverified}, + wantErr: errUnverified, + }, + { + name: "a freshness read failure fails closed", + source: fakeCatalogueSource{catalogue: Catalogue{IssuedAt: jan2}}, + mark: fakeFreshness{newestErr: errMarkUnreadable}, + wantErr: errMarkUnreadable, + }, + { + name: "a freshness write failure fails closed", + source: fakeCatalogueSource{catalogue: Catalogue{IssuedAt: jan2}}, + mark: fakeFreshness{acceptErr: errDiskFull}, + wantErr: errDiskFull, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + source := FreshCatalogueSource{Source: tt.source, Freshness: &tt.mark} + catalogue, err := source.Fetch(t.Context()) + if !errors.Is(err, tt.wantErr) { + t.Fatalf("err = %v; want %v", err, tt.wantErr) + } + if tt.wantErr == nil { + if catalogue.IssuedAt.IsZero() { + t.Fatal("the accepted catalogue was not returned") + } + if got := tt.mark.newest; !got.Equal(tt.wantNewest) { + t.Fatalf("mark = %s; want %s", got.Format(time.RFC3339), tt.wantNewest.Format(time.RFC3339)) + } + } + }) + } +} + +// A catalogue without an issue time is refused: accepting one would leave +// the replay hole open for catalogues published before the field existed. +func TestCatalogueValidateRequiresIssueTime(t *testing.T) { + entry := CatalogueEntry{Name: "github", Reference: "ghcr.io/x/github", Digest: "sha256:" + "0000000000000000000000000000000000000000000000000000000000000000"} + tests := []struct { + name string + catalogue Catalogue + wantErr bool + }{ + {name: "issued and pinned", catalogue: Catalogue{IssuedAt: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), Packages: []CatalogueEntry{entry}}}, + {name: "no issue time", catalogue: Catalogue{Packages: []CatalogueEntry{entry}}, wantErr: true}, + {name: "no issue time and no packages", catalogue: Catalogue{}, wantErr: true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if err := tt.catalogue.Validate(); (err != nil) != tt.wantErr { + t.Fatalf("err = %v; wantErr %v", err, tt.wantErr) + } + }) + } +} diff --git a/internal/infrastructure/storepkg/catalogue.go b/internal/infrastructure/storepkg/catalogue.go index 15ad4aee9..164168737 100644 --- a/internal/infrastructure/storepkg/catalogue.go +++ b/internal/infrastructure/storepkg/catalogue.go @@ -4,15 +4,24 @@ import ( "bytes" "context" "crypto/ed25519" + "crypto/sha256" "encoding/base64" + "encoding/hex" "encoding/json" "errors" "fmt" + "io/fs" + "os" + "path/filepath" + "sync" + "time" ocispec "github.com/opencontainers/image-spec/specs-go/v1" "oras.land/oras-go/v2/registry/remote" domain "github.com/samcharles93/archie-core/internal/domain/storepkg" + "github.com/samcharles93/archie-core/internal/fsutil" + "github.com/samcharles93/archie-core/internal/infrastructure/configuration" ) // SignatureAnnotation carries the base64 ed25519 signature over the @@ -21,13 +30,18 @@ const SignatureAnnotation = "dev.archie.catalogue.signature.v1" const maxCatalogueBytes = 1 << 20 -// DefaultCatalogue is the archipelago marketplace every instance trusts: -// its reference, and the public half of the key that signs it. -func DefaultCatalogue() OCICatalogue { - return OCICatalogue{ +// DefaultCatalogue is the archipelago marketplace every instance trusts: its +// reference, the public half of the key that signs it, and the durable +// freshness mark that refuses a replayed older catalogue. +func DefaultCatalogue() domain.CatalogueSource { + source := OCICatalogue{ Reference: "ghcr.io/samcharles93/archipelago/catalogue:latest", Key: mustKey("YL4nvn07uq/5mXZOt9cEmLYu/kB6C2+MLTnbHyoX4Pw="), } + return domain.FreshCatalogueSource{ + Source: source, + Freshness: &FileFreshness{Path: defaultFreshnessPath(source.Reference)}, + } } func mustKey(encoded string) ed25519.PublicKey { @@ -105,3 +119,73 @@ func verifyCatalogue(image ocispec.Manifest, layer []byte, key ed25519.PublicKey } return catalogue, nil } + +// FileFreshness is the durable Freshness mark, kept as one small JSON file +// written atomically so a crash never leaves a half-written mark. A missing +// file is no mark yet; a file that exists but does not parse is an error, so +// a corrupt mark fails closed instead of opening a replay window. +type FileFreshness struct { + Path string + + mu sync.Mutex +} + +var _ domain.Freshness = (*FileFreshness)(nil) + +func (f *FileFreshness) Newest(context.Context) (time.Time, error) { + f.mu.Lock() + defer f.mu.Unlock() + return f.read() +} + +func (f *FileFreshness) Accept(_ context.Context, issuedAt time.Time) error { + f.mu.Lock() + defer f.mu.Unlock() + current, err := f.read() + if err != nil { + return err + } + if !issuedAt.After(current) { + return nil + } + encoded, err := json.Marshal(struct { + IssuedAt time.Time `json:"issued_at"` + }{IssuedAt: issuedAt.UTC()}) + if err != nil { + return err + } + return fsutil.WriteFileAtomic(f.Path, encoded, 0o600) +} + +// read returns the mark, or the zero time when no catalogue has been +// accepted yet. +func (f *FileFreshness) read() (time.Time, error) { + raw, err := os.ReadFile(f.Path) + if errors.Is(err, fs.ErrNotExist) { + return time.Time{}, nil + } + if err != nil { + return time.Time{}, err + } + var mark struct { + IssuedAt time.Time `json:"issued_at"` + } + if err := json.Unmarshal(raw, &mark); err != nil { + return time.Time{}, fmt.Errorf("catalogue freshness mark %s: %w", f.Path, err) + } + return mark.IssuedAt, nil +} + +// defaultFreshnessPath is where the default catalogue's freshness mark +// lives: $XDG_STATE_HOME//catalogue/.json, the state home the +// update journal uses too. The key names the catalogue reference, so two +// catalogues never share a mark. +func defaultFreshnessPath(reference string) string { + dir := os.Getenv("XDG_STATE_HOME") + if dir == "" { + home, _ := os.UserHomeDir() + dir = filepath.Join(home, ".local", "state") + } + sum := sha256.Sum256([]byte(reference)) + return filepath.Join(dir, configuration.InstanceName(), "catalogue", hex.EncodeToString(sum[:8])+".json") +} diff --git a/internal/infrastructure/storepkg/catalogue_test.go b/internal/infrastructure/storepkg/catalogue_test.go index 0e06ec82a..dddc7b1b6 100644 --- a/internal/infrastructure/storepkg/catalogue_test.go +++ b/internal/infrastructure/storepkg/catalogue_test.go @@ -1,12 +1,19 @@ package storepkg import ( + "context" "crypto/ed25519" "encoding/base64" + "errors" + "os" + "path/filepath" "testing" + "time" digest "github.com/opencontainers/go-digest" ocispec "github.com/opencontainers/image-spec/specs-go/v1" + + domain "github.com/samcharles93/archie-core/internal/domain/storepkg" ) // A catalogue is trusted only when its layer is the one the manifest names @@ -14,8 +21,9 @@ import ( func TestVerifyCatalogue(t *testing.T) { trusted, signer, _ := ed25519.GenerateKey(nil) _, stranger, _ := ed25519.GenerateKey(nil) - valid := []byte(`{"packages":[{"name":"github","reference":"ghcr.io/x/github","digest":"sha256:` + zeros + `"}]}`) - unpinned := []byte(`{"packages":[{"name":"github","reference":"ghcr.io/x/github","digest":"latest"}]}`) + valid := []byte(`{"issued_at":"2026-01-01T00:00:00Z","packages":[{"name":"github","reference":"ghcr.io/x/github","digest":"sha256:` + zeros + `"}]}`) + untimed := []byte(`{"packages":[{"name":"github","reference":"ghcr.io/x/github","digest":"sha256:` + zeros + `"}]}`) + unpinned := []byte(`{"issued_at":"2026-01-01T00:00:00Z","packages":[{"name":"github","reference":"ghcr.io/x/github","digest":"latest"}]}`) manifest := func(layer []byte, signature string) ocispec.Manifest { return ocispec.Manifest{ @@ -41,6 +49,7 @@ func TestVerifyCatalogue(t *testing.T) { {"signed by another key", manifest(valid, sign(stranger, valid)), valid, false}, {"unsigned", manifest(valid, ""), valid, false}, {"an entry without a digest pin", manifest(unpinned, sign(signer, unpinned)), unpinned, false}, + {"a signed catalogue with no issue time", manifest(untimed, sign(signer, untimed)), untimed, false}, } for _, tc := range cases { _, err := verifyCatalogue(tc.manifest, tc.layer, trusted) @@ -50,4 +59,97 @@ func TestVerifyCatalogue(t *testing.T) { } } +type staticCatalogue struct{ catalogue domain.Catalogue } + +func (s staticCatalogue) Fetch(context.Context) (domain.Catalogue, error) { + return s.catalogue, nil +} + +// verifiedCatalogue signs a catalogue layer issued at issuedAt and returns +// it as verifyCatalogue decoded it, so the test holds a catalogue whose +// signature verifies. +func verifiedCatalogue(t *testing.T, key ed25519.PublicKey, signer ed25519.PrivateKey, issuedAt string) domain.Catalogue { + t.Helper() + layer := []byte(`{"issued_at":"` + issuedAt + `","packages":[{"name":"github","reference":"ghcr.io/x/github","digest":"sha256:` + zeros + `"}]}`) + manifest := ocispec.Manifest{ + Layers: []ocispec.Descriptor{{Digest: digest.FromBytes(layer)}}, + Annotations: map[string]string{SignatureAnnotation: base64.StdEncoding.EncodeToString(ed25519.Sign(signer, layer))}, + } + catalogue, err := verifyCatalogue(manifest, layer, key) + if err != nil { + t.Fatalf("verify catalogue issued %s: %v", issuedAt, err) + } + return catalogue +} + +// A replayed catalogue is refused: the signature proves an older catalogue +// is genuine, so the freshness mark is what stops it, and the mark that +// refuses it survives a restart. +func TestFetchRefusesReplayedCatalogue(t *testing.T) { + trusted, signer, _ := ed25519.GenerateKey(nil) + mark := &FileFreshness{Path: filepath.Join(t.TempDir(), "catalogue", "freshness.json")} + newer := verifiedCatalogue(t, trusted, signer, "2026-01-02T00:00:00Z") + older := verifiedCatalogue(t, trusted, signer, "2026-01-01T00:00:00Z") + + // The newest catalogue is accepted and recorded. + current := domain.FreshCatalogueSource{Source: staticCatalogue{newer}, Freshness: mark} + if _, err := current.Fetch(t.Context()); err != nil { + t.Fatalf("newest catalogue: %v", err) + } + // The older one is validly signed -- the signature alone does not stop a + // replay -- and is refused as stale. + replay := domain.FreshCatalogueSource{Source: staticCatalogue{older}, Freshness: mark} + if _, err := replay.Fetch(t.Context()); !errors.Is(err, domain.ErrCatalogueStale) { + t.Fatalf("replayed catalogue: err = %v, want ErrCatalogueStale", err) + } + // The mark is durable: a fresh reader over the same file, as after a + // restart, still refuses the older catalogue and still accepts the new. + restarted := domain.FreshCatalogueSource{Source: staticCatalogue{older}, Freshness: &FileFreshness{Path: mark.Path}} + if _, err := restarted.Fetch(t.Context()); !errors.Is(err, domain.ErrCatalogueStale) { + t.Fatalf("after restart: err = %v, want ErrCatalogueStale", err) + } + if _, err := (domain.FreshCatalogueSource{Source: staticCatalogue{newer}, Freshness: &FileFreshness{Path: mark.Path}}).Fetch(t.Context()); err != nil { + t.Fatalf("after restart, newest catalogue: %v", err) + } +} + +// The freshness mark never goes backwards, and a mark that exists but does +// not parse fails closed rather than opening a replay window. +func TestFileFreshness(t *testing.T) { + path := filepath.Join(t.TempDir(), "freshness.json") + mark := &FileFreshness{Path: path} + jan1 := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + jan2 := time.Date(2026, 1, 2, 0, 0, 0, 0, time.UTC) + + newest, err := mark.Newest(t.Context()) + if err != nil { + t.Fatalf("Newest with no file: %v", err) + } + if !newest.IsZero() { + t.Fatalf("Newest with no file = %s; want the zero time", newest.Format(time.RFC3339)) + } + if err := mark.Accept(t.Context(), jan1); err != nil { + t.Fatalf("Accept jan1: %v", err) + } + if err := mark.Accept(t.Context(), jan2); err != nil { + t.Fatalf("Accept jan2: %v", err) + } + if err := mark.Accept(t.Context(), jan1); err != nil { + t.Fatalf("Accept jan1 again: %v", err) + } + if newest, err = mark.Newest(t.Context()); err != nil { + t.Fatalf("Newest: %v", err) + } + if !newest.Equal(jan2) { + t.Fatalf("Newest = %s; want %s", newest.Format(time.RFC3339), jan2.Format(time.RFC3339)) + } + + if err := os.WriteFile(path, []byte("{"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := mark.Newest(t.Context()); err == nil { + t.Fatal("Newest over a corrupt mark: err = nil, want an error") + } +} + const zeros = "0000000000000000000000000000000000000000000000000000000000000000"