statebackup

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package statebackup exports a service's irreplaceable state (a node identity, a keystore, a wallet) as an encrypted file, and decides whether the user still has a backup of it.

The bundle format is the web app's (GeiserX/CashPilot app/state_backup.py), byte for byte, so one decrypt tool opens a backup from either app:

4-byte big-endian header length | header JSON | ChaCha20-Poly1305 ciphertext

The header carries magic "CASHPILOT-BACKUP", version 1, salt, nonce, mode, metadata and the payload's sha256. It is not encrypted but it is the AEAD's associated data, so changing which service a bundle says it belongs to breaks it. The key comes from scrypt (N=2^15, r=8, p=1) over a passphrase, or from HKDF-SHA256 (info "cashpilot-backup-v1") over an X25519 exchange with the recipient's public key.

CashPilot keeps nothing that could open what it exported: the passphrase is used once and dropped, and in recipient mode no secret enters the app at all. There is no upload and no schedule; a timer would need a stored key.

Index

Constants

View Source
const (
	Magic   = "CASHPILOT-BACKUP"
	Version = 1

	ModePassphrase = "passphrase"
	ModeRecipient  = "recipient"

	// MinPassphraseLength: shorter than this can be brute-forced offline, and
	// nothing rate-limits a guess at a stolen file.
	MinPassphraseLength = 12

	// MaxStateBytes is the most state an export reads. Identities and wallets are
	// kilobytes; anything near this is a storage folder (Storj, Sia), which belongs
	// in a disk-level backup, not in one file held in memory with the node paused.
	MaxStateBytes = 256 << 20
)
View Source
const (
	StateNone      = "none"      // never confirmed
	StateConfirmed = "confirmed" // confirmed, same state, under six months old
	StateChanged   = "changed"   // the state moved or was recreated since
	StateRecheck   = "recheck"   // confirmed when the fingerprint was unknown
	StateExpired   = "expired"   // older than MaxAge
)

The states a service's backup can be in.

View Source
const MaxAge = 183 * 24 * time.Hour

MaxAge is how long a confirmed backup counts before the app asks again. The fingerprint catches a new volume or a moved folder; this catches what it cannot see, such as an identity regenerated inside the same volume. Same as the web.

View Source
const MaxArchiveBytes = MaxStateBytes

MaxArchiveBytes is the most file data a restore unpacks. An export never reads more than MaxStateBytes, tar headers included, so every bundle Desktop made fits. The web caps its own exports at 64 MB, so its bundles fit too.

View Source
const MaxArchiveEntries = 20_000

MaxArchiveEntries is the most entries a restore accepts. An identity, keystore or wallet folder holds tens of files, a relay folder a few hundred. Past this it is a data folder, which belongs in a disk-level backup. Same number as the web.

Variables

View Source
var ErrBackup = errors.New("backup")

ErrBackup marks every error this package returns about a bundle or its inputs. The messages never contain a passphrase or key.

Functions

func Fingerprint

func Fingerprint(facts map[string]MountFact, containerID string) string

Fingerprint is a short hash of WHERE a service's irreplaceable state lives: each critical mount's type and source, plus a named volume's creation time, or the container id when the state is not on a mount. It changes when a volume is removed and made again or the service points somewhere else; it does not change when the container is recreated over the same volume (every image update). It never reads the files. Same recipe as the web's orchestrator.state_id.

func GenerateKeypair

func GenerateKeypair() (string, string, error)

GenerateKeypair returns a fresh X25519 pair as (private hex, public hex). The private half is for the user to keep; nothing in the app stores it.

func Judge

func Judge(found *Confirmation, live string, now time.Time) string

Judge decides a service's backup state from its confirmation (nil when there is none) and the fingerprint it has now ("" when unknown).

func Open

func Open(bundle []byte, passphrase, privateKeyHex string) ([]byte, error)

Open decrypts a bundle with the passphrase or the recipient's private key (hex), whichever its header asks for, and checks the payload against the recorded sha256. A wrong secret and an altered file fail the same way.

func Seal

func Seal(payload []byte, passphrase, recipientHex string, metadata map[string]any) ([]byte, error)

Seal encrypts payload into a bundle. Exactly one of passphrase or recipientHex (an X25519 public key, 64 hex characters) must be given.

func SplitArchives

func SplitArchives(payload []byte) (map[string][]byte, error)

SplitArchives turns a decrypted payload into one tar per backed-up mount.

The payload is Docker's archive of each critical mount, one after another, so each archive's entries sit under the mount's last path component (/var/lib/mysterium-node becomes mysterium-node/...). They are regrouped by that name.

Every entry is rebuilt from a short list of fields: name, type, permission bits, owner ids, modification time, size and link target. Owners, modes and times are what `docker cp` and `tar -x` need to put the files back the way the service expects; nothing else from the input reaches the output.

The archives get extracted as root into a volume, and in recipient mode anyone holding the public key can build a bundle that opens cleanly. So every entry is checked on its own and one refused entry fails the whole restore, with an error that names the rule: an absolute name, "..", a link that points out of its folder, a path through a link, a path given twice, a device or pipe, a sparse file, a PAX global header, any extended record such as a file capability, a control character in a name or link target, or an invalid time. Setuid, setgid and sticky bits are dropped. More than MaxArchiveBytes of file data or MaxArchiveEntries entries is refused before the data is read. Same rules as the web's split_archives.

Types

type Confirmation

type Confirmation struct {
	Slug string `json:"slug"`
	// StateID is the fingerprint when it was confirmed; "" when it could not be read.
	StateID string `json:"stateId"`
	// Method is "manual" (the button) or "export" (a backup saved from the app).
	Method      string    `json:"method"`
	ConfirmedAt time.Time `json:"confirmedAt"`
}

Confirmation is the user's word that a service's state is backed up.

type Header struct {
	Magic              string         `json:"magic"`
	Version            int            `json:"version"`
	Mode               string         `json:"mode"`
	Salt               string         `json:"salt"`
	Nonce              string         `json:"nonce"`
	EphemeralPublicKey string         `json:"ephemeral_public_key"`
	SHA256             string         `json:"sha256"`
	Metadata           map[string]any `json:"metadata"`
}

Header is the bundle's unencrypted, authenticated header. It never holds key material.

func ReadHeader

func ReadHeader(bundle []byte) (Header, error)

ReadHeader returns the header without decrypting anything.

type MountFact

type MountFact struct {
	// Mounted is false when nothing is mounted there: the state lives in the
	// container's own layer and dies with the container.
	Mounted bool
	Type    string // "volume", "bind", ...
	Name    string // a named volume's name
	Source  string // a bind mount's host path
	// Created is a named volume's CreatedAt.
	Created string
}

MountFact is what Docker says about the mount at one critical target.

type Row

type Row struct {
	Slug        string   `json:"slug"`
	Name        string   `json:"name"`
	Volumes     []Volume `json:"volumes"`
	State       string   `json:"state"`
	ConfirmedAt string   `json:"confirmedAt"`
	Method      string   `json:"method"`
	// TracksChanges is false when the fingerprint could not be read (the
	// container is gone, Docker is down), so only the time limit re-arms it.
	TracksChanges bool `json:"tracksChanges"`
}

Row is one deployed service with irreplaceable state, as the card shows it.

type Volume

type Volume struct {
	Target string `json:"target"`
	Holds  string `json:"holds"`
}

Volume is one mount the catalog marks irreplaceable, with the catalog's words.

Jump to

Keyboard shortcuts

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