mesh-host/internal/link/handover.go

package link

import (
	"crypto/ed25519"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"strings"
	"sync"
	"time"
)

// A hand-over asked over the bus (novox/hq issue 356, issue 339).
//
// A directory used as found is handed to the mesh by its operator, at the controller's terminal:
// `nox node hand-over <node> <path>` on the control-node (novox/hq ADR 0272). The controller asks this
// node's engine on AskHandOverSubject, a request on core NATS, and the engine answers once, on the reply
// the request carried.
//
// **The subject proves nothing; the signature does** (review of issue 356). Only the controller is granted
// a publish on the subject, but the bus lets any principal allowed to answer reply to a message it received,
// on whatever reply subject that message named — a tool server asked on its own subject with this reply
// would deliver a body of its choosing here. So the controller signs the ask with the mesh's key, over
// HandOverContext and the ask's bytes, and the engine verifies it with the key it verifies declarations with
// before it reads anything out of it; then it holds the ask to this node, to its expiry, and to a nonce it
// takes once. Then it judges every value and records the hand-over, or refuses and records nothing; the next
// apply gives the directory its declared owner and mode. The controller holds the same shapes in its own link
// code, with a test on each side holding the field names.

// AskHandOverSubject is where the controller asks this node's engine to take a directory used as found as
// the mesh's.
func AskHandOverSubject(node string) string { return "mesh.node." + node + ".ask.hand-over" }

// HandOverAsk is one hand-over asked: the node it is for, the directory's absolute path as the engine states
// it, who asked in the controller's words, when it stops being good, and a nonce taken once.
type HandOverAsk struct {
	Node    string    `json:"node"`
	Path    string    `json:"path"`
	By      string    `json:"by"`
	Expires time.Time `json:"expires"`
	Nonce   string    `json:"nonce"`
}

// SignedHandOver is the ask as it travels: its bytes exactly as signed, and the mesh's signature.
type SignedHandOver struct {
	Ask       []byte `json:"ask"`
	Signature []byte `json:"signature"`
}

// HandOverContext is prefixed to an ask's bytes before signing: a hand-over's signature is never a
// declaration's, which the same key makes over a declaration's bytes alone.
const HandOverContext = "novox-mesh hand-over v1\n"

// HandOverGood is how long the controller makes an ask good for; HandOverSkew is how far the machines' clocks
// may differ. An ask whose expiry is further ahead than both together is refused: it would be good too long.
const (
	HandOverGood = time.Minute
	HandOverSkew = time.Minute
)

// HandOverAnswer is the engine's answer: what it recorded, or why it refused — never both, never neither.
type HandOverAnswer struct {
	Said    string `json:"said,omitempty"`
	Refused string `json:"refused,omitempty"`
}

// HandOverFunc judges and records one hand-over: the words to answer with, or the refusal.
type HandOverFunc func(path, by string) (string, error)

// MaxHandOverAsk bounds a request: a path, a name, a time, a nonce and a signature are hundreds of bytes.
const MaxHandOverAsk = 8 << 10

// MaxHandOverBy bounds who asked.
const MaxHandOverBy = 200

// HandOverCheck is what an ask is held to: the mesh's key, this node's name, the clock, and the nonces taken.
type HandOverCheck struct {
	Signer ed25519.PublicKey
	Node   string
	Now    func() time.Time
	Nonces *Nonces
}

// Nonces are the nonces of asks taken, each kept until its ask expires: an ask is taken once. Kept in memory —
// an ask outlives no restart by more than its minute, and taking one again records the same hand-over again.
type Nonces struct {
	mu   sync.Mutex
	seen map[string]time.Time
}

// take records a nonce until its expiry, and says false when it was already taken.
func (n *Nonces) take(nonce string, expires, now time.Time) bool {
	n.mu.Lock()
	defer n.mu.Unlock()
	if n.seen == nil {
		n.seen = map[string]time.Time{}
	}
	for k, until := range n.seen {
		if now.After(until) {
			delete(n.seen, k)
		}
	}
	if _, taken := n.seen[nonce]; taken {
		return false
	}
	n.seen[nonce] = expires
	return true
}

// HandOverNonces are this process's: every link it opens takes from the same set, so a reconnect is no replay.
var HandOverNonces = &Nonces{}

func refusedAsk(why string) HandOverAnswer {
	return HandOverAnswer{Refused: why + "; nothing was handed over"}
}

// AnswerHandOver is the engine's judgement of one ask's bytes: the signature first, then this node, the expiry
// and the nonce, then every value — and only then the handler, given only what passed. A refusal records nothing.
func AnswerHandOver(check HandOverCheck, handle HandOverFunc, body []byte) HandOverAnswer {
	if handle == nil {
		return refusedAsk("this engine takes no hand-over")
	}
	if len(body) > MaxHandOverAsk {
		return refusedAsk(fmt.Sprintf("the ask is %d bytes, more than a hand-over", len(body)))
	}
	var signed SignedHandOver
	if err := json.Unmarshal(body, &signed); err != nil {
		return refusedAsk("the ask is not a signed hand-over: " + err.Error())
	}
	if len(check.Signer) != ed25519.PublicKeySize ||
		!ed25519.Verify(check.Signer, append([]byte(HandOverContext), signed.Ask...), signed.Signature) {
		return refusedAsk("the ask is not signed by the mesh")
	}
	var ask HandOverAsk
	if err := json.Unmarshal(signed.Ask, &ask); err != nil {
		return refusedAsk("the signed ask is not a hand-over: " + err.Error())
	}
	now := time.Now()
	if check.Now != nil {
		now = check.Now()
	}
	nonces := check.Nonces
	if nonces == nil {
		nonces = HandOverNonces
	}
	by := strings.TrimSpace(ask.By)
	nonce, nonceErr := hex.DecodeString(ask.Nonce)
	switch {
	case check.Node == "" || ask.Node != check.Node:
		return refusedAsk(fmt.Sprintf("the ask is for %q, and this is %q", ask.Node, check.Node))
	case ask.Expires.IsZero() || !now.Before(ask.Expires):
		return refusedAsk("the ask has expired")
	case ask.Expires.After(now.Add(HandOverGood + HandOverSkew)):
		return refusedAsk("the ask is good for longer than an ask may be")
	case nonceErr != nil || len(nonce) < 16:
		return refusedAsk("the ask carries no nonce of its own")
	case by == "":
		return refusedAsk("the ask names nobody as asking")
	case len(by) > MaxHandOverBy || strings.ContainsAny(by, "\r\n\x00"):
		return refusedAsk("who asked is not one short line")
	case ask.Path == "":
		return refusedAsk("the ask names no directory")
	case !nonces.take(ask.Nonce, ask.Expires, now):
		return refusedAsk("the ask was taken already")
	}
	said, err := handle(ask.Path, by)
	if err != nil {
		return HandOverAnswer{Refused: err.Error()}
	}
	return HandOverAnswer{Said: said}
}

// HandOverReply is what a hand-over request is answered with, and whether to answer: a request with no reply
// subject is nobody's question, so nothing is judged, recorded or said.
func HandOverReply(check HandOverCheck, handle HandOverFunc, reply string, body []byte) ([]byte, bool) {
	if reply == "" {
		return nil, false
	}
	answer, err := json.Marshal(AnswerHandOver(check, handle, body))
	if err != nil {
		return nil, false
	}
	return answer, true
}

// HandOvers is a link that hears the controller asking this node to hand a directory over. Optional, as
// Asked is.
type HandOvers interface {
	HearHandOvers(HandOverFunc)
}