niko_trust/internal/checkpoint/checkpoint.go

// Package checkpoint defines the relay's signed commitment to its object
// set: the header chain that light nodes follow.
//
// A checkpoint is transport-layer infrastructure. It commits to the Merkle
// root of the objects a relay stores, to the previous checkpoint (forming a
// tamper-evident chain per relay), and to nothing else. It is never a trust
// statement: the relay key that signs it may not sign claims or approvals,
// and consumers derive no authority from it beyond "this relay asserts its
// log looks like this". This is the documented narrowing of INV-1
// (docs/TRUST-MODEL.md): the relay holds one key whose entire power is to
// describe its own storage.
//
// Canonical encoding, reusing TCE primitives so that two implementations
// cannot disagree about byte-exactness:
//
//	MAGIC("trust.n1ko.dev/ckpt/1\0") || version=1 ||
//	epoch || size || root(32) || prev(32) || created_at
//
// All integers are uvarints; timestamps follow the protocol's range rules.
package checkpoint

import (
	"crypto/ed25519"
	"crypto/sha256"
	"errors"
	"fmt"

	"git.n1ko.dev/Niko/niko_trust/internal/tce"
)

// Magic frames a checkpoint and is domain separation at the outermost level:
// a checkpoint can never be reinterpreted as a TCE object or vice versa.
var Magic = []byte("trust.n1ko.dev/ckpt/1\x00")

// Version is the checkpoint format version.
const Version = 1

// Errors returned for malformed checkpoints.
var (
	ErrBadMagic  = errors.New("checkpoint: bad magic")
	ErrVersion   = errors.New("checkpoint: unsupported version")
	ErrSignature = errors.New("checkpoint: signature does not verify")
)

// Checkpoint is one signed head of the relay's log.
type Checkpoint struct {
	// Epoch counts checkpoints this relay has produced, starting at 1.
	Epoch uint64

	// Size is the number of distinct objects committed to by Root.
	Size uint64

	// Root is the sparse Merkle root over the stored object IDs.
	Root [32]byte

	// Prev is SHA-256 of the previous checkpoint's canonical bytes; zeros
	// for epoch 1. Linking heads makes per-relay history tamper-evident
	// without any global consensus.
	Prev [32]byte

	// CreatedAt is the relay's assertion of signing time.
	CreatedAt uint64
}

// Encode returns the canonical bytes.
func (c *Checkpoint) Encode() ([]byte, error) {
	if err := tce.ValidateTimestamp(c.CreatedAt, false); err != nil {
		return nil, fmt.Errorf("checkpoint: created_at: %w", err)
	}
	e := tce.NewEncoder()
	e.Uvarint(Version)
	e.Uvarint(c.Epoch)
	e.Uvarint(c.Size)
	e.FixedBytes("root", c.Root[:], 32)
	e.FixedBytes("prev", c.Prev[:], 32)
	e.Uvarint(c.CreatedAt)
	body, err := e.Bytes()
	if err != nil {
		return nil, err
	}
	out := make([]byte, 0, len(Magic)+len(body))
	out = append(out, Magic...)
	return append(out, body...), nil
}

// Decode strictly parses canonical bytes: exact magic, version, field sizes,
// timestamp range, no trailing bytes.
func Decode(b []byte) (*Checkpoint, error) {
	if len(b) < len(Magic) || string(b[:len(Magic)]) != string(Magic) {
		return nil, ErrBadMagic
	}
	d := tce.NewDecoder(b[len(Magic):])
	version, err := d.Uvarint()
	if err != nil {
		return nil, err
	}
	if version != Version {
		return nil, ErrVersion
	}
	var c Checkpoint
	if c.Epoch, err = d.Uvarint(); err != nil {
		return nil, err
	}
	if c.Size, err = d.Uvarint(); err != nil {
		return nil, err
	}
	root, err := d.FixedBytes(32)
	if err != nil {
		return nil, err
	}
	copy(c.Root[:], root)
	prev, err := d.FixedBytes(32)
	if err != nil {
		return nil, err
	}
	copy(c.Prev[:], prev)
	if c.CreatedAt, err = d.Uvarint(); err != nil {
		return nil, err
	}
	if err := tce.ValidateTimestamp(c.CreatedAt, false); err != nil {
		return nil, fmt.Errorf("checkpoint: created_at: %w", err)
	}
	if err := d.End(); err != nil {
		return nil, err
	}
	return &c, nil
}

// ID is the content address of a checkpoint: SHA-256 of its canonical
// bytes. It is also the value linked by the next checkpoint's Prev.
func ID(b []byte) [32]byte {
	return sha256.Sum256(b)
}

// Sign returns the Ed25519 signature of the relay key over the canonical
// bytes. Only a relay's transport key ever produces this.
func Sign(key ed25519.PrivateKey, b []byte) ([]byte, error) {
	if len(key) != ed25519.PrivateKeySize {
		return nil, errors.New("checkpoint: bad relay key")
	}
	return ed25519.Sign(key, b), nil
}

// Verify checks a checkpoint's signature over its canonical bytes.
func Verify(key ed25519.PublicKey, b, sig []byte) error {
	if len(key) != ed25519.PublicKeySize || len(sig) != ed25519.SignatureSize {
		return ErrSignature
	}
	// ed25519.Verify panics on a mis-sized key, hence the length gate above.
	if !ed25519.Verify(key, b, sig) {
		return ErrSignature
	}
	return nil
}