trees/checkpoint: Add checkpoint.Checkpoint

go.mod

@@ -38,6 +38,7 @@ require (
 	go.opentelemetry.io/otel/trace v1.43.0
 	go.yaml.in/yaml/v3 v3.0.4
 	golang.org/x/crypto v0.52.0
+	golang.org/x/mod v0.37.0
 	golang.org/x/net v0.55.0
 	golang.org/x/sync v0.20.0
 	golang.org/x/text v0.37.0
@@ -84,9 +85,8 @@ require (
 	go.opentelemetry.io/otel/metric v1.43.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.7.1 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
-	golang.org/x/mod v0.35.0 // indirect
 	golang.org/x/sys v0.45.0 // indirect
-	golang.org/x/tools v0.44.0 // indirect
+	golang.org/x/tools v0.45.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 // indirect
 	gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 // indirect

go.sum

@@ -284,8 +284,8 @@ golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGb
 golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
 golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
-golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
-golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
+golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
 golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20181114220301-adae6a3d119a/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20181220203305-927f97764cc3/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -326,8 +326,8 @@ golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGm
 golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200313205530-4303120df7d8/go.mod h1:Sl4aGygMT6LrqrWclx+PTx3U+LnKx/seiNR+3G19Ar8=
-golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
-golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
+golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
+golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

trees/checkpoint/checkpoint.go

@@ -0,0 +1,164 @@
+package checkpoint
+
+import (
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+
+	"golang.org/x/mod/sumdb/note"
+	"golang.org/x/mod/sumdb/tlog"
+)
+
+// Checkpoint represents a tlog-checkpoint note text.
+//
+// https://c2sp.org/tlog-checkpoint
+type Checkpoint struct {
+	Origin     string
+	Tree       tlog.Tree
+	Extensions []string
+}
+
+// checkNoteText returns an error if text cannot be a signed note's text, nil
+// otherwise. https://c2sp.org/signed-note requires note text to be valid UTF-8
+// with no ASCII control characters (those below U+0020) other than newline.
+func checkNoteText(text string) error {
+	switch {
+	case !utf8.ValidString(text):
+		return errors.New("not valid UTF-8")
+
+	case strings.ContainsFunc(text, func(r rune) bool { return r < 0x20 && r != '\n' }):
+		return errors.New("contains an ASCII control character other than newline")
+
+	default:
+		return nil
+	}
+}
+
+// checkNoteField returns an error if field contains a newline, the note's line
+// delimiter, nil otherwise.
+func checkNoteField(field string) error {
+	if strings.ContainsRune(field, '\n') {
+		return errors.New("contains a newline")
+	}
+	return nil
+}
+
+// validate returns an error if the checkpoint's fields violate the
+// tlog-checkpoint requirements, nil otherwise.
+func (c *Checkpoint) validate() error {
+	if c.Origin == "" {
+		return errors.New("empty checkpoint origin")
+	}
+	err := checkNoteField(c.Origin)
+	if err != nil {
+		return fmt.Errorf("validating checkpoint origin: %w", err)
+	}
+	if c.Tree.N < 0 {
+		return fmt.Errorf("negative checkpoint tree size %d", c.Tree.N)
+	}
+	for _, ext := range c.Extensions {
+		if ext == "" {
+			return errors.New("empty checkpoint extension line")
+		}
+		err := checkNoteField(ext)
+		if err != nil {
+			return fmt.Errorf("validating checkpoint extension line: %w", err)
+		}
+	}
+	return nil
+}
+
+// Marshal returns the note text, first checking the checkpoint against the
+// tlog-checkpoint requirements. It returns an error if the checkpoint is
+// invalid.
+//
+//   - https://c2sp.org/tlog-checkpoint
+//   - https://c2sp.org/signed-note
+func (c *Checkpoint) Marshal() (string, error) {
+	err := c.validate()
+	if err != nil {
+		return "", err
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "%s\n%d\n%s\n", c.Origin, c.Tree.N, c.Tree.Hash)
+	for _, ext := range c.Extensions {
+		b.WriteString(ext)
+		b.WriteByte('\n')
+	}
+	text := b.String()
+	err = checkNoteText(text)
+	if err != nil {
+		return "", fmt.Errorf("validating checkpoint note text: %w", err)
+	}
+	return text, nil
+}
+
+// Unmarshal parses a checkpoint note text. The text must not have any signature
+// lines. For a signed note, use Open.
+//
+//   - https://c2sp.org/tlog-checkpoint
+//   - https://c2sp.org/signed-note
+func Unmarshal(text string) (*Checkpoint, error) {
+	err := checkNoteText(text)
+	if err != nil {
+		return nil, fmt.Errorf("validating checkpoint note text: %w", err)
+	}
+	if !strings.HasSuffix(text, "\n") {
+		return nil, errors.New("checkpoint does not end in newline")
+	}
+	lines := strings.Split(strings.TrimSuffix(text, "\n"), "\n")
+	if len(lines) < 3 {
+		return nil, fmt.Errorf("checkpoint has %d lines, want at least 3", len(lines))
+	}
+
+	size, err := strconv.ParseInt(lines[1], 10, 64)
+	if err != nil {
+		return nil, fmt.Errorf("checkpoint tree size: %w", err)
+	}
+	if size < 0 {
+		return nil, fmt.Errorf("negative checkpoint tree size %d", size)
+	}
+	if strconv.FormatInt(size, 10) != lines[1] {
+		return nil, errors.New("checkpoint tree size has a leading zero or sign")
+	}
+
+	hashBytes, err := base64.StdEncoding.DecodeString(lines[2])
+	if err != nil {
+		return nil, fmt.Errorf("checkpoint root hash: %w", err)
+	}
+	if len(hashBytes) != tlog.HashSize {
+		return nil, fmt.Errorf("checkpoint root hash is %d bytes, want %d", len(hashBytes), tlog.HashSize)
+	}
+	if base64.StdEncoding.EncodeToString(hashBytes) != lines[2] {
+		return nil, errors.New("checkpoint root hash is not canonical base64")
+	}
+	var hash tlog.Hash
+	copy(hash[:], hashBytes)
+
+	c := &Checkpoint{Origin: lines[0], Tree: tlog.Tree{N: size, Hash: hash}, Extensions: lines[3:]}
+	return c, c.validate()
+}
+
+// Open opens a signed checkpoint note and parses its text. An error is returned
+// if signedNote is not a well-formed note, if any of the verifiers rejects a
+// signature (note.InvalidSignatureError), if none of the verifiers has signed
+// the note (note.UnverifiedNoteError), or if the note's text is not a
+// well-formed checkpoint. Signatures from unknown keys are ignored.
+//
+//   - https://c2sp.org/tlog-checkpoint
+//   - https://c2sp.org/signed-note
+func Open(signedNote []byte, verifiers note.Verifiers) (*Checkpoint, *note.Note, error) {
+	n, err := note.Open(signedNote, verifiers)
+	if err != nil {
+		return nil, nil, err
+	}
+	c, err := Unmarshal(n.Text)
+	if err != nil {
+		return nil, nil, err
+	}
+	return c, n, nil
+}