backup

Documentation

Overview

Package backup packs what the user set up in magpie into one file, sealed with a passphrase, to carry to another machine: the providers (their keys too, unless left out), the pictures picked for them, the settings, the profiles, every agent's model and the library (the instructions, MCP servers and skills magpie gives the agents). Subscriptions are not in it: each is the sign-in of an agent on this machine, so each machine signs in on its own.

The file is JSON: a header naming how it is sealed, and the bundle encrypted with AES-256-GCM under a key derived from the passphrase with PBKDF2-SHA256. Nothing in it can be read without the passphrase.

Index

• Constants
• Variables
• func Flag(keys bool) *bool
• func OpenData(sealed []byte, pass string) ([]byte, error)
• func Seal(b Bundle, pass string) ([]byte, error)
• func SealData(data []byte, pass string) ([]byte, error)
• func Secret(name string) bool
• type Bundle
  • func Collect(keys bool, app string) (Bundle, error)
  • func Open(data []byte, pass string) (Bundle, error)
• type Parts
• type Result
  • func Restore(b Bundle, parts Parts) (Result, error)

Constants

const BundleVersion = 2

BundleVersion is the bundle's structure: 2 carries the per-part credential markers (ProvidersKeys, SettingsKeys, LibraryKeys) as their own three-state flags; 1 and before had the whole-bundle Keys alone.

const Ext = ".magpie-backup"

Ext is the extension backups are saved with.

Variables

var All = Parts{true, true, true, true, true}

All is every part.

var ErrCorrupt = errors.New("not a magpie backup")

ErrCorrupt is a file that isn't a backup at all, or one cut short: its JSON, format, or key-derivation fields don't read. It is told from a wrong passphrase and from a newer magpie's file, so a sync can rebuild the damaged one from this computer rather than fail on it forever.

var ErrPassphrase = errors.New("wrong passphrase, or the file was changed")

ErrPassphrase is a passphrase that does not open the backup.

Functions

func Flag

func Flag(keys bool) *bool

Flag is a per-part credential marker as a bundle field takes one: the part's own, written when a sync merged it. Absent (nil) is a whole collect's or an older magpie's.

func OpenData

func OpenData(sealed []byte, pass string) ([]byte, error)

OpenData opens what SealData sealed.

func Seal

func Seal(b Bundle, pass string) ([]byte, error)

Seal encrypts the bundle under the passphrase.

func SealData

func SealData(data []byte, pass string) ([]byte, error)

SealData seals data under the passphrase, as Seal does a bundle.

func Secret

func Secret(name string) bool

Secret reports whether a header or an environment variable by that name looks like it holds a key: what a backup without keys leaves empty.

Types

type Bundle

type Bundle struct {
	Version     int                        `json:"version"`
	Created     time.Time                  `json:"created"`
	App         string                     `json:"app,omitempty"` // the magpie that made it
	Keys        bool                       `json:"keys"`          // whole-backup credential policy
	Providers   []provider.Provider        `json:"providers"`
	Icons       map[string][]byte          `json:"icons,omitempty"`  // pictures picked for providers, by file name
	Groups      []provider.Group           `json:"groups,omitempty"` // the user's model groups
	Settings    *settings.Settings         `json:"settings,omitempty"`
	GatewayKeys *[]access.Key              `json:"gatewayKeys,omitempty"`
	Profiles    map[string]profile.Profile `json:"profiles,omitempty"`
	Agents      map[string]string          `json:"agents,omitempty"`  // every agent's fields as they are now
	Library     *library.Bundle            `json:"library,omitempty"` // nil from a magpie before it, or with none
	// Searches are the web search APIs (#419), their keys with the
	// providers'; nil from a magpie before them.
	Searches *[]provider.SearchAPI `json:"searches,omitempty"`
	// Order is the order the user put the providers in (#499), by id;
	// none from a magpie before it went, or when they were never arranged.
	Order []string `json:"order,omitempty"`
	// GroupOrder is the order the user put the routing groups in (#779),
	// by id; none from a magpie before it, or when never arranged.
	GroupOrder []string `json:"groupOrder,omitempty"`
	// Sync can carry one part's credentials without changing the others'
	// Keys policy; these are absent from older backups and whole collects.
	ProvidersKeys *bool `json:"providersKeys,omitempty"`
	SettingsKeys  *bool `json:"settingsKeys,omitempty"`
	LibraryKeys   *bool `json:"libraryKeys,omitempty"`
}

Bundle is what a backup holds.

func Collect

func Collect(keys bool, app string) (Bundle, error)

Collect gathers the bundle; without keys, providers carry none, nor any header that looks like one, and the library's servers no environment variable or header that looks like one (their names stay).

func Open

func Open(data []byte, pass string) (Bundle, error)

Open decrypts a backup.

type Parts

type Parts struct {
	Providers, Settings, Profiles, Agents, Library bool
}

Parts picks what a restore puts back.

type Result

type Result struct {
	Added, Replaced int      // providers
	NeedKey         []string // providers that came without a key and have none here
	Settings        bool
	Profiles        int
	Agents          int               // agent fields changed
	Skipped         []string          // agent fields left alone: the agent is not on this machine, or the value failed
	Library         bool              // the library was put in
	LibraryProblems []library.Problem `json:",omitempty"` // what of it couldn't be given to an agent
}

Result says what a restore did.

func Restore

func Restore(b Bundle, parts Parts) (Result, error)

Restore puts the chosen parts of the bundle in. Providers come first, so the agents' models that go through them resolve. Only agents on this machine are set.