secrets

Documentation

Overview

Package secrets assembles a namespace's secrets from the objects a backend holds for it: an append-only set of per-write segments over zero or more folded snapshots. Each write appends a new, uniquely named segment, so concurrent writers never overwrite one another. Reads fold the snapshots and segments together by a Lamport clock — last write per key wins, ties between machines are reported as conflicts. Compaction collapses what it reads into a fresh snapshot and deletes the objects it folded.

Every object is one age message sealed under the master key. The layout (segment vs snapshot, ordering, provenance) lives in object names and authenticated payloads, never in plaintext on the wire.

Index

• Constants
• func Exists(ctx context.Context, store backend.Backend, name string) (bool, error)
• type Conflict
• type Namespace
  • func For(store backend.Backend, name string, master *crypto.MasterKey, machine string) *Namespace
  • func (n *Namespace) Append(ctx context.Context, prev *State, seq int, key, value string, deleted bool) (*State, string, error)
  • func (n *Namespace) Compact(ctx context.Context, confirm func() error) error
  • func (n *Namespace) Fold(ctx context.Context) (*State, error)
• type State
  • func (s *State) HasHistory() bool
  • func (s *State) SegmentCount() int

Constants

const DefaultCompactThreshold = 16

DefaultCompactThreshold is the segment count at or above which a write triggers automatic compaction. It bounds the objects a cold read folds, so reads stay fast without anyone running `notenv compact` by hand.

Functions

func Exists

func Exists(ctx context.Context, store backend.Backend, name string) (bool, error)

Exists reports whether a namespace has any stored object yet. It only lists, so it needs no master key.

Types

type Conflict

type Conflict struct {
	Key      string
	Winner   string
	Shadowed []string
}

Conflict reports a key written concurrently on more than one machine (equal Lamport). Winner's value is the one kept; the others are shadowed but remain recoverable from their segments until the next compaction.

type Namespace

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

Namespace reads and writes one namespace's secrets through a backend, sealing every object under master. machine identifies and orders this machine's writes so two machines never produce the same segment.

func For

func For(store backend.Backend, name string, master *crypto.MasterKey, machine string) *Namespace

For binds a namespace to a backend and master key.

func (*Namespace) Append

func (n *Namespace) Append(ctx context.Context, prev *State, seq int, key, value string, deleted bool) (*State, string, error)

Append writes one key change as a new segment and returns the resulting state plus the object key the segment landed under, so the caller can remove the write again if a post-write check (the master-epoch confirm) fails. prev is the fold this write builds on; its Lamport sets the new clock.

func (*Namespace) Compact

func (n *Namespace) Compact(ctx context.Context, confirm func() error) error

Compact folds the namespace into a single fresh snapshot and removes the objects it folded. It writes the new snapshot before deleting anything and only deletes objects it read, so a write that lands concurrently — under a name it never listed — is never lost. Running two compactions against one namespace at the same time is safe but wasteful; coordinate them.

confirm, if non-nil, runs after the snapshot is written and verified but before anything is deleted. If it errors, Compact removes its own snapshot and returns the error with the namespace untouched. The caller uses it to confirm the master it sealed the snapshot with is still the vault's master: without the check, a compaction racing a master rotation could collapse the whole namespace into a snapshot only the superseded key can open.

func (*Namespace) Fold

func (n *Namespace) Fold(ctx context.Context) (*State, error)

Fold reads every object in the namespace and resolves the current secrets.

type State

type State struct {
	Secrets   map[string]string
	Conflicts []Conflict
	// contains filtered or unexported fields
}

State is a folded namespace: the resolved secrets and any same-key conflicts detected during the fold. lamport is the highest Lamport folded, the basis for the next write's clock; segments is how many segment objects it folded.

func (*State) HasHistory

func (s *State) HasHistory() bool

HasHistory reports whether any write has ever been folded into this state; false means the namespace is untouched (distinct from one emptied by deletes).

func (*State) SegmentCount

func (s *State) SegmentCount() int

SegmentCount is how many uncompacted segment objects this fold read, the signal a caller uses to decide whether the next write should compact.