format

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: AGPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package format is version 1 of the Shardkeep catalog snapshot format: the types, their encoding, and Ed25519 signing and verification. The builder writes snapshots with it; Shardkeep Controllers read and verify them with it. FORMAT.md describes the same contract in prose.

A snapshot is a signed index (index.json: the index with its signature, in one file so it is replaced atomically) listing content-addressed objects (objects/<sha256>.json). Readers verify the signature, then each object's SHA-256 and size against the index. Within version 1, changes are additive: readers ignore fields and object kinds they do not know.

Index

Constants

View Source
const (
	IndexFile  = "index.json"
	ObjectsDir = "objects"
)

File names within a snapshot directory.

View Source
const (
	KindSoftware = "software"
	KindPlugins  = "plugins"
	KindDenylist = "denylist"
)

Object kinds.

View Source
const (
	MaxIndexSize  = 1 << 20
	MaxObjectSize = 256 << 20
)

Limits readers enforce.

View Source
const Version = 1

Version is the format version, and the path prefix snapshots live under.

Variables

View Source
var ErrUntrusted = errors.New("the catalog index is not signed by a trusted key")

ErrUntrusted is returned when an index is not signed by a trusted key.

Functions

func CheckObject

func CheckObject(f File, content []byte) error

CheckObject verifies content against its index entry.

func Decode

func Decode(data []byte, v any) error

Decode reads a snapshot document, ignoring unknown fields (the format grows additively).

func Encode

func Encode(v any) ([]byte, error)

Encode is the one encoding snapshots use: compact JSON with a trailing newline. Go encodes struct fields in declaration order and map keys sorted, so the same value always gives the same bytes.

func FormatPublicKey

func FormatPublicKey(pub ed25519.PublicKey) string

FormatPublicKey writes a public key the way Shardkeep's trusted key list and -catalog-trust-key take it: "ed25519:<base64>".

func GenerateKey

func GenerateKey() (privatePEM []byte, public string, err error)

GenerateKey makes a signing key pair. The private key is PEM (PKCS #8).

func KeyID

func KeyID(pub ed25519.PublicKey) string

KeyID names an Ed25519 public key.

func ObjectPath

func ObjectPath(content []byte) (string, string)

ObjectPath is where an object with this content lives.

func ParsePrivateKey

func ParsePrivateKey(data []byte) (ed25519.PrivateKey, error)

ParsePrivateKey reads a PEM signing key.

func Sign

func Sign(ix Index, priv ed25519.PrivateKey) ([]byte, error)

Sign encodes and signs an index, returning the content of index.json.

Types

type Build

type Build struct {
	Build string `json:"build"`
	// Channel is "stable", "beta" or "alpha".
	Channel  string   `json:"channel"`
	URL      string   `json:"url"`
	Checksum Checksum `json:"checksum"`
	// Size is zero when the publisher does not state it.
	Size int64 `json:"size,omitempty"`
}

Build is one downloadable server jar.

type Checksum

type Checksum struct {
	// Algorithm is "sha512", "sha256", "sha1" or "md5".
	Algorithm string `json:"algorithm"`
	Hex       string `json:"hex"`
}

Checksum is a published digest of a file.

type Denial

type Denial struct {
	PluginID string `json:"pluginId"`
	// Versions are version IDs; empty means every version.
	Versions []string `json:"versions,omitempty"`
	Reason   string   `json:"reason"`
	Link     string   `json:"link,omitempty"`
}

Denial is one denylist entry.

type Denylist

type Denylist struct {
	Entries []Denial `json:"entries"`
}

Denylist lists plugins or versions Shardkeep recommends against (kind "denylist").

type Dependency

type Dependency struct {
	// PluginID is the catalog ID when the dependency is in the catalog.
	PluginID string `json:"pluginId,omitempty"`
	// Name is the dependency as its source names it.
	Name     string `json:"name"`
	Required bool   `json:"required"`
}

Dependency is another plugin a version needs or works with.

type Download

type Download struct {
	URL       string     `json:"url"`
	Name      string     `json:"name,omitempty"`
	Size      int64      `json:"size,omitempty"`
	Checksums []Checksum `json:"checksums"`
}

Download is a file at its official location.

type Envelope

type Envelope struct {
	// Payload is the encoded Index (base64 in JSON).
	Payload []byte `json:"payload"`
	// KeyID names the public key: the first 16 hex characters of the
	// SHA-256 of the raw public key.
	KeyID     string `json:"keyId"`
	Algorithm string `json:"algorithm"`
	Signature []byte `json:"signature"`
}

Envelope is the content of index.json: the encoded index and an Ed25519 signature over exactly those bytes. Keeping both in one file means a reader never sees a new index with an old signature.

type File

type File struct {
	Kind string `json:"kind"`
	// Path is relative to the snapshot directory: objects/<sha256>.json.
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

File is one object of a snapshot.

type Index

type Index struct {
	Format int `json:"format"`
	// Sequence grows with every published snapshot. Readers refuse one
	// that is not newer than what they have, so an old snapshot cannot be
	// replayed.
	Sequence    int64     `json:"sequence"`
	GeneratedAt time.Time `json:"generatedAt"`
	Files       []File    `json:"files"`
}

Index is a snapshot's table of contents; it is what gets signed.

func Verify

func Verify(envelope []byte, trusted []PublicKey) (Index, error)

Verify checks index.json against the trusted keys, then decodes and validates the index.

func (Index) Object

func (ix Index) Object(kind string) (File, bool)

Object returns the index entry of a kind.

func (Index) Validate

func (ix Index) Validate() error

Validate checks an index is well formed for this version: format 1, a positive sequence, and objects that are content-addressed under objects/ with a size within limits. Unknown kinds are allowed (and skipped by readers).

type Plugin

type Plugin struct {
	// ID is "<source>:<project>", e.g. "modrinth:luckperms".
	ID        string `json:"id"`
	Source    string `json:"source"`
	Slug      string `json:"slug"`
	Name      string `json:"name"`
	Summary   string `json:"summary,omitempty"`
	License   string `json:"license,omitempty"`
	Downloads int64  `json:"downloads"`
	// URL is the project's page at its source.
	URL string `json:"url"`
	// Updated is when the project last changed at its source.
	Updated time.Time `json:"updated"`
	// Versions are newest first.
	Versions []PluginVersion `json:"versions"`
}

Plugin is one plugin project.

type PluginVersion

type PluginVersion struct {
	// ID is the version's identifier at its source.
	ID      string `json:"id"`
	Version string `json:"version"`
	// Channel is "release", "beta" or "alpha".
	Channel string `json:"channel"`
	// Platforms are the server software it runs on: "paper", "purpur",
	// "velocity", ...
	Platforms    []string     `json:"platforms"`
	GameVersions []string     `json:"gameVersions"`
	Published    time.Time    `json:"published"`
	File         Download     `json:"file"`
	Dependencies []Dependency `json:"dependencies,omitempty"`
}

PluginVersion is one release of a plugin.

type Plugins

type Plugins struct {
	Plugins []Plugin `json:"plugins"`
}

Plugins lists plugins (kind "plugins").

type PublicKey

type PublicKey struct {
	ID  string
	Key ed25519.PublicKey
}

PublicKey is a trusted catalog key.

func ParsePublicKey

func ParsePublicKey(s string) (PublicKey, error)

ParsePublicKey reads "ed25519:<base64>".

type Software

type Software struct {
	Templates []Template `json:"templates"`
}

Software lists server software (kind "software").

type SoftwareVersion

type SoftwareVersion struct {
	Version string `json:"version"`
	// JavaVersion is the Java feature release Mojang says the version needs.
	JavaVersion int `json:"javaVersion"`
	// Builds are newest first. Software without builds (Vanilla) has one
	// build with an empty name.
	Builds []Build `json:"builds"`
}

SoftwareVersion is one Minecraft version of a template.

type Template

type Template struct {
	Name string `json:"name"`
	// Versions are newest first.
	Versions []SoftwareVersion `json:"versions"`
}

Template is one kind of server software, e.g. "paper".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL