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
- Variables
- func Fingerprint(facts map[string]MountFact, containerID string) string
- func GenerateKeypair() (string, string, error)
- func Judge(found *Confirmation, live string, now time.Time) string
- func Open(bundle []byte, passphrase, privateKeyHex string) ([]byte, error)
- func Seal(payload []byte, passphrase, recipientHex string, metadata map[string]any) ([]byte, error)
- func SplitArchives(payload []byte) (map[string][]byte, error)
- type Confirmation
- type Header
- type MountFact
- type Row
- type Volume
Constants ¶
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 )
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Seal encrypts payload into a bundle. Exactly one of passphrase or recipientHex (an X25519 public key, 64 hex characters) must be given.
func SplitArchives ¶
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 ¶
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 ¶
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.