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
- Variables
- func CheckObject(f File, content []byte) error
- func Decode(data []byte, v any) error
- func Encode(v any) ([]byte, error)
- func FormatPublicKey(pub ed25519.PublicKey) string
- func GenerateKey() (privatePEM []byte, public string, err error)
- func KeyID(pub ed25519.PublicKey) string
- func ObjectPath(content []byte) (string, string)
- func ParsePrivateKey(data []byte) (ed25519.PrivateKey, error)
- func Sign(ix Index, priv ed25519.PrivateKey) ([]byte, error)
- type Build
- type Checksum
- type Denial
- type Denylist
- type Dependency
- type Download
- type Envelope
- type File
- type Index
- type Plugin
- type PluginVersion
- type Plugins
- type PublicKey
- type Software
- type SoftwareVersion
- type Template
Constants ¶
const ( IndexFile = "index.json" ObjectsDir = "objects" )
File names within a snapshot directory.
const ( KindSoftware = "software" KindPlugins = "plugins" KindDenylist = "denylist" )
Object kinds.
const ( MaxIndexSize = 1 << 20 MaxObjectSize = 256 << 20 )
Limits readers enforce.
const Version = 1
Version is the format version, and the path prefix snapshots live under.
Variables ¶
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 ¶
CheckObject verifies content against its index entry.
func Decode ¶
Decode reads a snapshot document, ignoring unknown fields (the format grows additively).
func Encode ¶
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 ¶
FormatPublicKey writes a public key the way Shardkeep's trusted key list and -catalog-trust-key take it: "ed25519:<base64>".
func GenerateKey ¶
GenerateKey makes a signing key pair. The private key is PEM (PKCS #8).
func ObjectPath ¶
ObjectPath is where an object with this content lives.
func ParsePrivateKey ¶
func ParsePrivateKey(data []byte) (ed25519.PrivateKey, error)
ParsePrivateKey reads a PEM signing key.
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 ¶
Verify checks index.json against the trusted keys, then decodes and validates the index.
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 ¶
PublicKey is a trusted catalog key.
func ParsePublicKey ¶
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".