fix(catalogue): sign an issue time and refuse a replayed older catalogue

This commit is contained in:
sam committed 2026-10-30 00:06:38 +11:00
1 parent 1f7a53e951
commit 3d2a41a3a2
4 files changed
+392 -7

No files matched your search

+62 -1
View File
@@ -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 {
+138
View File
@@ -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)
}
})
}
}
+88 -4
View File
@@ -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/<instance>/catalogue/<key>.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")
}
@@ -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"