mesh-catalog/modules/mesh-vault/cmd/mesh-vault/ledger.go

package main

// The custody ledger (novox/hq ADR 0085, design 24), carried over from the TypeScript vault: for each pair
// credential the controller delivers to this vault as the `secret` provider, who holds it, since when, its
// fingerprint and every rotation — and never the value. The controller still mints and seals those until
// the secrets move to the vault (design 57's V3, V4); the pass records what it delivered, so
// `secret_holders` and `secret_verify` answer as before. Its files are the same JSON, read as they are.
//
// **A holder the mesh stops asking for is retired, never deleted by a pass** (novox/hq ADR 0230). The vault
// is a mark-only provider: it has no access to switch off, so retiring writes the mark — when and why — into
// the holder's own ledger file, which keeps its rotation history. A holder is retired only once the same set
// has gone unasked in five consecutive passes that read the contributions file and for ten minutes; a set
// over the bound (more than three, or more than half of those held) waits for a person; asked for again, a
// retired holder is re-enabled at once; a holder is deleted only by `provisioner_delete`, a person's act
// with a why. Because the mark is in the ledger file, a restart forgets nothing.

import (
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
	"time"
)

// isoMillis is JavaScript's toISOString, the form the ledger's times were first written in.
const isoMillis = "2006-01-02T15:04:05.000Z"

// Held is one holder of a secret this vault provides: everything the vault knows of it, and no value.
type Held struct {
	As          string    `json:"as"`
	Consumer    string    `json:"consumer"`
	Fingerprint string    `json:"fingerprint"`
	Length      int       `json:"length"`
	Since       string    `json:"since"`
	Changed     string    `json:"changed"`
	Rotations   int       `json:"rotations"`
	History     []Earlier `json:"history"`
	// Retired is the mark a retirement writes; nil while the holder is active.
	Retired *RetiredMark `json:"retired,omitempty"`
}

// RetiredMark is when and why a holder was retired.
type RetiredMark struct {
	At  string `json:"at"`
	Why string `json:"why"`
}

// Earlier is a fingerprint a rotation replaced, and when.
type Earlier struct {
	Fingerprint string `json:"fingerprint"`
	Until       string `json:"until"`
}

// Outcome is what recording a delivery found.
type Outcome string

const (
	Granted   Outcome = "granted"
	Rotated   Outcome = "rotated"
	Unchanged Outcome = "unchanged"
)

// Fingerprint is sha256 of a value, as `sha256:<hex>`: the one thing about a secret that may be said.
func Fingerprint(value string) string {
	sum := sha256.Sum256([]byte(value))
	return "sha256:" + hex.EncodeToString(sum[:])
}

// Ledger is the directory of holders.
type Ledger struct{ dir string }

// NewLedger opens (and makes) the ledger at dir.
func NewLedger(dir string) (*Ledger, error) {
	if dir == "" {
		return nil, errors.New("MESH_VAULT_LEDGER is not set: the vault has nowhere to keep its ledger")
	}
	if err := os.MkdirAll(dir, 0o700); err != nil {
		return nil, err
	}
	return &Ledger{dir: dir}, nil
}

var login = regexp.MustCompile(`^[a-z0-9][a-z0-9_.-]*$`)

func (l *Ledger) pathOf(as string) (string, error) {
	if !login.MatchString(as) || strings.Contains(as, "..") {
		return "", fmt.Errorf("a login is a name, not a path: %q", as)
	}
	return filepath.Join(l.dir, as+".json"), nil
}

// Record says the mesh delivered value for as: the same value again changes nothing, another is a rotation.
// The value is fingerprinted here and goes no further. A retirement mark is left as it is.
func (l *Ledger) Record(as, consumer, value string, now time.Time) (Held, Outcome, error) {
	path, err := l.pathOf(as)
	if err != nil {
		return Held{}, "", err
	}
	fp, at := Fingerprint(value), now.UTC().Format(isoMillis)
	before, ok := l.Get(as)
	if !ok {
		h := Held{As: as, Consumer: consumer, Fingerprint: fp, Length: len(value), Since: at, Changed: at, History: []Earlier{}}
		return h, Granted, l.write(path, h)
	}
	if before.Fingerprint == fp && before.Length == len(value) {
		return before, Unchanged, nil
	}
	h := before
	h.Consumer, h.Fingerprint, h.Length, h.Changed = consumer, fp, len(value), at
	h.Rotations++
	h.History = append(append([]Earlier{}, before.History...), Earlier{Fingerprint: before.Fingerprint, Until: at})
	return h, Rotated, l.write(path, h)
}

// Mark writes or clears a holder's retirement mark.
func (l *Ledger) Mark(as string, mark *RetiredMark) error {
	path, err := l.pathOf(as)
	if err != nil {
		return err
	}
	h, ok := l.Get(as)
	if !ok {
		return fmt.Errorf("the ledger holds nothing for %s", as)
	}
	h.Retired = mark
	return l.write(path, h)
}

// Delete forgets a holder, saying whether there was one. Only a person's `provisioner_delete` reaches it.
func (l *Ledger) Delete(as string) bool {
	path, err := l.pathOf(as)
	if err != nil {
		return false
	}
	if os.Remove(path) != nil {
		return false
	}
	_ = syncDir(l.dir)
	return true
}

// Get is one holder.
func (l *Ledger) Get(as string) (Held, bool) {
	path, err := l.pathOf(as)
	if err != nil {
		return Held{}, false
	}
	raw, err := os.ReadFile(path)
	if err != nil {
		return Held{}, false
	}
	var h Held
	if json.Unmarshal(raw, &h) != nil {
		return Held{}, false
	}
	return h, true
}

// List is every holder, by login.
func (l *Ledger) List() []Held {
	entries, err := os.ReadDir(l.dir)
	if err != nil {
		return nil
	}
	var out []Held
	for _, e := range entries {
		if strings.HasSuffix(e.Name(), ".json") {
			if h, ok := l.Get(strings.TrimSuffix(e.Name(), ".json")); ok {
				out = append(out, h)
			}
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].As < out[j].As })
	return out
}

func (l *Ledger) write(path string, h Held) error {
	raw, err := json.MarshalIndent(h, "", "  ")
	if err != nil {
		return err
	}
	return writeWhole(path, append(raw, '\n'))
}

// Contribution is one entry of the contributions file the mesh delivers to the vault.
type Contribution struct {
	From   string `json:"from,omitempty"`
	Node   string `json:"node,omitempty"`
	As     string `json:"as"`
	Secret string `json:"secret"`
}

// Contributions is what the mesh asks this vault to serve: the entries with a login and a secret file.
//
// **A file that does not say who is asked for is not "nobody".** One that is unreadable, not JSON, without a
// `given` list (missing or null), or written for another requirement than `secret` is refused, so a pass
// over it retires nobody. An empty `given` list is an answer: nobody is asked for.
func Contributions(receives string) ([]Contribution, error) {
	raw, err := os.ReadFile(receives)
	if err != nil {
		return nil, err
	}
	var doc struct {
		Requirement *string         `json:"requirement"`
		Given       json.RawMessage `json:"given"`
	}
	if err := json.Unmarshal(raw, &doc); err != nil {
		return nil, fmt.Errorf("the contributions file is not JSON: %w", err)
	}
	if doc.Requirement != nil && *doc.Requirement != "secret" {
		return nil, fmt.Errorf("the contributions file is for %q, not for secret", *doc.Requirement)
	}
	if len(doc.Given) == 0 || string(doc.Given) == "null" {
		return nil, errors.New("the contributions file has no `given` list, so it says nothing of who is asked for")
	}
	var given []Contribution
	if err := json.Unmarshal(doc.Given, &given); err != nil {
		return nil, fmt.Errorf("the contributions file's `given` is not a list of contributions: %w", err)
	}
	var out []Contribution
	for _, g := range given {
		if g.As != "" && g.Secret != "" {
			out = append(out, g)
		}
	}
	return out, nil
}

// delivered is the value the mesh delivered for c, without the newline a file may end with.
func delivered(c Contribution) (string, error) {
	raw, err := os.ReadFile(c.Secret)
	if err != nil {
		return "", fmt.Errorf("the delivered secret is not readable: %v", err)
	}
	return strings.TrimSuffix(string(raw), "\n"), nil
}

// DeliveredFingerprint is the fingerprint and length of what the mesh currently delivers for c.
func DeliveredFingerprint(c Contribution) (string, int, error) {
	v, err := delivered(c)
	if err != nil {
		return "", 0, err
	}
	return Fingerprint(v), len(v), nil
}