amadan

carlos / platform Public

settings-1 task 3: channel pointers carry manifest digests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
claude b56d038c799308058b4a954e2b69cda780260b35 parent b83486b
3 files changed, +199 −0
  • internal/release/digests.go +44 −0
  • internal/release/pointerdigests_test.go +129 −0
  • internal/release/release.go +26 −0
diff --git a/internal/release/digests.go b/internal/release/digests.go
index 81944efc9..0ce445317 100644
--- a/internal/release/digests.go
+++ b/internal/release/digests.go
@@ -57,3 +57,47 @@ func digestShort(d string) string {
}
return d
}
+
+// DigestOf is the signed digest of version as this pointer names it: the
+// head's when version is the head, else the History entry's. "" when the
+// pointer signs none for it, or does not name it.
+func (p *ChannelPointer) DigestOf(version string) string {
+ if p == nil {
+ return ""
+ }
+ if version == p.Version {
+ return p.Digest
+ }
+ for i, v := range p.History {
+ if v == version && i < len(p.HistoryDigests) {
+ return p.HistoryDigests[i]
+ }
+ }
+ return ""
+}
+
+// CarriesDigests is the test the ratchet and CARLOS_REQUIRE_POINTER_DIGEST
+// apply: a pointer "with digests" signs one for its head.
+func (p *ChannelPointer) CarriesDigests() bool { return p != nil && p.Digest != "" }
+
+// ChannelHasDigests reports whether any entry carries a digest: the rollback
+// rule's test (spec §4.6, "once its channel has any digest").
+func (p *ChannelPointer) ChannelHasDigests() bool {
+ if p.CarriesDigests() {
+ return true
+ }
+ for _, d := range p.HistoryDigests {
+ if d != "" {
+ return true
+ }
+ }
+ return false
+}
+
+// alignedHistoryDigests is p.HistoryDigests at History's length: an absent
+// list is all "". The copy is the writer's to change.
+func alignedHistoryDigests(p *ChannelPointer) []string {
+ out := make([]string, len(p.History))
+ copy(out, p.HistoryDigests)
+ return out
+}
diff --git a/internal/release/pointerdigests_test.go b/internal/release/pointerdigests_test.go
new file mode 100644
index 000000000..c56a891b2
--- /dev/null
+++ b/internal/release/pointerdigests_test.go
@@ -0,0 +1,129 @@
+package release
+
+import (
+ "crypto/ed25519"
+ "encoding/base64"
+ "encoding/json"
+ "strings"
+ "testing"
+ "time"
+)
+
+// legacyPointer is ChannelPointer exactly as every binary before #253 knows
+// it. An old binary decodes into this and nothing else.
+type legacyPointer struct {
+ Schema int `json:"schema"`
+ Account string `json:"account,omitempty"`
+ App string `json:"app"`
+ Channel string `json:"channel"`
+ Version string `json:"version"`
+ PromotedAt time.Time `json:"promoted_at"`
+ History []string `json:"history,omitempty"`
+ Audit []Promotion `json:"audit,omitempty"`
+ FastTrack bool `json:"fast_track,omitempty"`
+}
+
+func signedPointerBytes(t *testing.T, priv ed25519.PrivateKey, p *ChannelPointer) []byte {
+ t.Helper()
+ b, err := signPointer(RootSigner(priv), p)
+ if err != nil {
+ t.Fatalf("signPointer: %v", err)
+ }
+ return b
+}
+
+var (
+ dA = ManifestDigest([]byte("manifest a"))
+ dB = ManifestDigest([]byte("manifest b"))
+)
+
+func TestDigestOf(t *testing.T) {
+ p := &ChannelPointer{Version: "v3", Digest: dA, History: []string{"v2", "v1"}, HistoryDigests: []string{"", dB}}
+ for v, want := range map[string]string{"v3": dA, "v2": "", "v1": dB, "v9": ""} {
+ if got := p.DigestOf(v); got != want {
+ t.Errorf("DigestOf(%s) = %q, want %q", v, got, want)
+ }
+ }
+ if !p.CarriesDigests() || !p.ChannelHasDigests() {
+ t.Fatal("a pointer with a head digest carries digests")
+ }
+ tail := &ChannelPointer{Version: "v3", History: []string{"v2"}, HistoryDigests: []string{dB}}
+ if tail.CarriesDigests() || !tail.ChannelHasDigests() {
+ t.Fatal("history digests alone: the channel has digests, the pointer carries none")
+ }
+ if (&ChannelPointer{Version: "v1"}).ChannelHasDigests() {
+ t.Fatal("a legacy pointer has no digests")
+ }
+ var nilp *ChannelPointer
+ if nilp.DigestOf("v1") != "" {
+ t.Fatal("a nil pointer has no digests")
+ }
+}
+
+// Spec §8: an old binary verifies a pointer with digests.
+func TestAnOldBinaryVerifiesAPointerWithDigests(t *testing.T) {
+ priv, pub := testKeys(t)
+ wire := signedPointerBytes(t, priv, &ChannelPointer{Account: "bab", App: "km", Channel: "stable", Version: "v2",
+ Digest: dA, History: []string{"v1"}, HistoryDigests: []string{dB}})
+ var sw signedWrapper
+ if err := json.Unmarshal(wire, &sw); err != nil {
+ t.Fatal(err)
+ }
+ sig, _ := base64.StdEncoding.DecodeString(sw.Sig)
+ if !ed25519.Verify(pub, []byte(sw.Payload), sig) {
+ t.Fatal("the signature does not cover the payload as an old binary reads it")
+ }
+ payload, _ := base64.StdEncoding.DecodeString(sw.Payload)
+ var old legacyPointer
+ if err := json.Unmarshal(payload, &old); err != nil || old.Version != "v2" || len(old.History) != 1 {
+ t.Fatalf("old decode = %+v, %v", old, err)
+ }
+}
+
+func TestAPointerWithoutDigestsMarshalsAsBefore(t *testing.T) {
+ b, err := json.Marshal(&ChannelPointer{Schema: 1, App: "km", Channel: "stable", Version: "v1", History: []string{"v0"}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if strings.Contains(string(b), "digest") {
+ t.Fatalf("an empty digest leaked into the payload: %s", b)
+ }
+}
+
+// Review Focus 1.
+func TestValidatePointerRefusesMisalignedHistoryDigests(t *testing.T) {
+ base := func() *ChannelPointer {
+ return &ChannelPointer{Schema: 1, Account: "bab", App: "km", Channel: "stable", Version: "v3",
+ PromotedAt: time.Now().UTC().Truncate(time.Second), History: []string{"v2", "v1"}}
+ }
+ ok := base()
+ ok.Digest, ok.HistoryDigests = dA, []string{"", dB}
+ if err := validatePointer(ok, "bab", "km", "stable"); err != nil {
+ t.Fatalf("aligned: %v", err)
+ }
+ short := base()
+ short.Digest, short.HistoryDigests = dA, []string{dB}
+ if err := validatePointer(short, "bab", "km", "stable"); err == nil {
+ t.Fatal("history_digests shorter than history was accepted")
+ }
+ bad := base()
+ bad.Digest = "not-a-digest"
+ if err := validatePointer(bad, "bab", "km", "stable"); err == nil {
+ t.Fatal("a malformed head digest was accepted")
+ }
+ badHist := base()
+ badHist.HistoryDigests = []string{"", strings.ToUpper(dB)}
+ if err := validatePointer(badHist, "bab", "km", "stable"); err == nil {
+ t.Fatal("a malformed history digest was accepted")
+ }
+}
+
+func TestVerifyPointerRoundTripsDigests(t *testing.T) {
+ priv, pub := testKeys(t)
+ wire := signedPointerBytes(t, priv, &ChannelPointer{Account: "bab", App: "km", Channel: "stable", Version: "v2",
+ Digest: dA, History: []string{"v1"}, HistoryDigests: []string{""}})
+ p, err := verifyPointer(pub, wire, "bab", "km", "stable")
+ if err != nil || p.Digest != dA || len(p.HistoryDigests) != 1 || p.HistoryDigests[0] != "" {
+ t.Fatalf("verifyPointer = %+v, %v", p, err)
+ }
+}
diff --git a/internal/release/release.go b/internal/release/release.go
index cf90d48ee..b86e5cf97 100644
--- a/internal/release/release.go
+++ b/internal/release/release.go
@@ -130,6 +130,18 @@ type ChannelPointer struct {
// rollback returns to where you were (Eleven versions.go's
// current<->previous swap, generalised).
History []string `json:"history,omitempty"`
+ // Digest is the sha256 of Version's canonical manifest bytes
+ // (ManifestDigest), and HistoryDigests holds one per History entry in the
+ // same order, "" where the writer had none to copy (#253, spec §4.6).
+ // ADDITIVE and inside the signed payload: absent from every pointer
+ // written before them and from every pointer written while the digest
+ // marker is off, so those marshal byte-identically to before; old
+ // binaries ignore both keys and verify as they always have. A digest is
+ // either computed at promotion from the bytes the publisher shipped, or
+ // copied verbatim from the verified predecessor: never computed for an
+ // entry a writer inherits (inheritedDigests).
+ Digest string `json:"digest,omitempty"`
+ HistoryDigests []string `json:"history_digests,omitempty"`
// Audit is the promotion trail, newest first, max auditMax: how this
// channel came to point where it does, and who said so. ADDITIVE — a
// pointer written before the trail existed has no "audit" key, parses
@@ -524,6 +536,20 @@ func validatePointer(p *ChannelPointer, wantAcct, wantApp, wantChannel string) e
return fmt.Errorf("pointer history has invalid version %q", v)
}
}
+ // Digests (#253): absent, or well-formed and aligned with History. A
+ // short list is malformed, never "the rest have none": a writer that
+ // meant "none" writes "" at the position.
+ if p.Digest != "" && !validDigest(p.Digest) {
+ return fmt.Errorf("pointer has an invalid digest")
+ }
+ if len(p.HistoryDigests) != 0 && len(p.HistoryDigests) != len(p.History) {
+ return fmt.Errorf("pointer history_digests has %d entries for %d history entries", len(p.HistoryDigests), len(p.History))
+ }
+ for _, d := range p.HistoryDigests {
+ if d != "" && !validDigest(d) {
+ return fmt.Errorf("pointer history has an invalid digest")
+ }
+ }
// The audit trail is checked loosely and only for shape: an old pointer
// carries none, and a trail is a record of what happened, not an
// instruction — refusing a pointer the fleet needs over a malformed