backup

type Archive struct {
	Manifest *Manifest
	// Sidecar describes the encrypted file; [Publish] writes it after it.
	Sidecar *Sidecar
	// Path is the encrypted file.
	Path string
	// SidecarSHA256 is the SHA-256 (hex) of the sidecar exactly as [Publish]
	// wrote it; empty until it has.
	SidecarSHA256 string
}

type Attestor interface {
	// Attest returns every record of the backup, none when there is none. It
	// returns an [ErrAttestUnavailable] when it cannot tell.
	Attest(ctx context.Context, instance, id string) ([]Claim, error)
}

type AttestorFunc func(ctx context.Context, instance, id string) ([]Claim, error)

type BlobsEntry struct {
	Count int64 `json:"count"`
	Bytes int64 `json:"bytes"`
}

type Claim struct {
	// RecordID is the record's id in the trail, for the log.
	RecordID string
	// Instance is the installation the record says the backup is of.
	Instance string
	// ObjectKey, ObjectSize and ObjectSHA256 describe the encrypted object;
	// SidecarSHA256 is the hash of the sidecar as written.
	ObjectKey     string
	ObjectSize    int64
	ObjectSHA256  string
	SidecarSHA256 string
	// Recipients are the [Fingerprints] of the recipients it was encrypted to.
	Recipients []string
	// Sealed is whether the hour holding the record is sealed, and SealKey the
	// seal that covers it.
	Sealed  bool
	SealKey string
}

type Fetched struct {
	Sidecar       *Sidecar
	SidecarSHA256 string
	Body          []byte
}

type Hashes struct{ Object, Sidecar string }

type Identities func(ctx context.Context) ([]age.Identity, error)

type Layout string

type Lines struct {
	Records int64  `json:"records"`
	SHA256  string `json:"sha256"`
}

type Manifest struct {
	// Format is the archive format version (see [Version]).
	Format int `json:"format"`
	// Instance and ID name the backup; they are also in its object key.
	Instance string `json:"instance"`
	ID       string `json:"id"`
	// Layout is the storage layout of the source installation.
	Layout Layout `json:"layout"`
	// Created is the start of the backup, UTC, RFC 3339.
	Created string `json:"created"`
	// Creator names what wrote it, for example "sluis-backup 1.76.1".
	Creator string `json:"creator"`
	// Modules lists the modules in the backup in [port.Modules] order, each
	// once.
	Modules []ModuleEntry `json:"modules"`
	// Files is the SHA-256 (hex) of every other member, by member name.
	Files map[string]string `json:"files"`
}

type ModuleEntry struct {
	Module  port.Module `json:"module"`
	State   Lines       `json:"state"`
	Secrets Lines       `json:"secrets"`
	Blobs   BlobsEntry  `json:"blobs"`
}

type NoAttestor struct{}

type ObjectInfo struct {
	Key    string `json:"key"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

type Params struct {
	Instance string
	ID       string
	Layout   Layout
	// Creator names what writes it, for example "sluis-backup 1.76.1".
	Creator string
	// Recipients are the age X25519 public keys (age1...) the backup is
	// encrypted to; at least one.
	Recipients []string
	// Now is the clock; time.Now when nil.
	Now func() time.Time
	// TempDir holds the spool and the encrypted file while they are written;
	// os.TempDir() (/tmp on Lambda) when empty.
	TempDir string
}

type Reader struct {
	// contains filtered or unexported fields
}

type Section string

type Sidecar struct {
	Format     int             `json:"format"`
	Instance   string          `json:"instance"`
	ID         string          `json:"id"`
	Created    string          `json:"created"`
	Creator    string          `json:"creator"`
	Layout     Layout          `json:"layout"`
	Object     ObjectInfo      `json:"object"`
	Recipients []string        `json:"recipients"`
	Modules    []SidecarModule `json:"modules"`
}

type SidecarModule struct {
	Module        port.Module `json:"module"`
	StateRecords  int64       `json:"stateRecords"`
	SecretRecords int64       `json:"secretRecords"`
	Blobs         int64       `json:"blobs"`
	BlobBytes     int64       `json:"blobBytes"`
}

type Verification struct {
	// Unverified is set when the backup went ahead without a sealed record of
	// it, and Reason says why (the Reason... words).
	Unverified bool
	Reason     string
	// Hashes are those of the backup that was checked.
	Hashes Hashes
	// RecordID and SealKey name the record and seal that vouched for it.
	RecordID, SealKey string
}

type Verifier struct {
	// Attestor asks the trail. Nil is [NoAttestor].
	Attestor Attestor
	// Recipients are the age recipients (age1...) the restore is configured
	// with. When set the sidecar must list exactly these, verified or not.
	Recipients []string
	// AllowUnverified lets a backup the trail says nothing of go ahead (no
	// record, an hour not sealed, a trail that cannot be asked), with
	// [Verification.Unverified] set. It needs Recipients, so that a backup of
	// an earlier set is still refused. It does not override [ErrMismatch] or
	// [ErrRecipients].
	AllowUnverified bool
	// Pinned, when set, is the hashes an earlier slice of a restore checked.
	// The trail is not asked again: the fetched backup must be those bytes,
	// and Was is the verification that slice reached.
	Pinned *Hashes
	Was    Verification
}

type Writer struct {
	// contains filtered or unexported fields
}