statebackup

package
v1.0.4 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 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.

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. Owners, modes and times are kept, which is what `docker cp` needs to put the files back the way the service expects.

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 unsafe entry fails the whole restore: an absolute name, "..", a link that points out of its folder, a path through a link, a device or a pipe. Setuid and setgid bits are dropped. 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