v0.106.0: offsite provisioning SLICE 2 — controller apply-bridge

On startup reconcile the hub-served offsite: descriptor into a key-only offbox
target. internal/offsiteapply.Bridge: verify-pin box host key vs host_fingerprint
(NO blind TOFU) → consume the one-time password (single-use, never logged) →
sshpass ssh-copy-id -s -f install + verify → configure offbox → EscrowState=pending
(fork-4 via Manager.ApplyOffsiteTarget) → persist a descriptor-hash marker LAST.
Idempotent + fail-safe. Seams faked in tests; both red-proofs run+reverted.
Dockerfile + sshpass. NOT yet live-applied (supervised end-to-end next runbook).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
This commit is contained in:
2026-07-09 19:14:14 +02:00
parent fa9362f36f
commit aa61fb3411
10 changed files with 686 additions and 61 deletions
@@ -0,0 +1,155 @@
// Package offsiteapply is the controller-side apply-bridge (SLICE 2): it turns the hub-served offsite
// descriptor + the one-time password into a working key-only offbox target. On config apply it consumes the
// one-time password, VERIFIES the box host key against the hub-captured fingerprint (no blind TOFU), pins it,
// installs the controller's own key, and configures the offbox target → EscrowState="pending" (the fork-4
// enable path). Idempotent (a descriptor hash marker prevents re-consuming a spent password) and fail-safe
// (any step fails → nothing persisted, retried next cycle; never a half-configured offbox).
package offsiteapply
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
"log"
"os"
"path/filepath"
"gitea.dooplex.hu/admin/felhom-controller/internal/config"
)
// The apply-bridge seams (tests inject fakes — no live SSH / hub calls in unit tests).
type (
// PasswordConsumer fetches the one-time transient password from the hub (single-use).
PasswordConsumer interface {
Consume(ctx context.Context) (string, error)
}
// HostKeyScanner returns the box's host-key fingerprint (SHA256:…) + the known_hosts line to pin.
HostKeyScanner interface {
Scan(ctx context.Context, host string, port int) (fingerprint, knownHostsLine string, err error)
}
// KeyGenerator produces a fresh keypair: the private key (PEM) and the authorized_keys pub line.
KeyGenerator interface {
Generate() (privPEM, pubAuthorized string, err error)
}
// KeyInstaller installs the pub line on the box using the one-time password, then verifies passwordless
// key auth with the private key. Fails if the install or the verify fails.
KeyInstaller interface {
Install(ctx context.Context, host, user string, port int, password, privPEM, pubAuthorized string) error
}
// OffboxEnabler configures the offbox target (key + known_hosts + target) and goes EscrowState="pending"
// (the fork-4 enable path).
OffboxEnabler interface {
ConfigureOffbox(ctx context.Context, host, user string, port int, repoPath, privPEM, knownHosts string) error
}
)
// Bridge reconciles the offsite descriptor into a configured offbox target.
type Bridge struct {
Cfg *config.Config
Consumer PasswordConsumer
Scanner HostKeyScanner
KeyGen KeyGenerator
Installer KeyInstaller
Enabler OffboxEnabler
MarkerPath string // where the applied-descriptor-hash is persisted (e.g. <dataDir>/offbox/applied_marker)
Logger *log.Logger
}
func (b *Bridge) logf(f string, a ...any) {
if b.Logger != nil {
b.Logger.Printf(f, a...)
}
}
// descriptorHash is the applied-marker key: a hash of the identity-bearing descriptor fields. A change
// (re-provision → new host/user/fingerprint) yields a new hash → the bridge re-applies (new password).
func descriptorHash(o config.OffsiteConfig) string {
s := fmt.Sprintf("%s|%s|%s|%d|%s|%s", o.Type, o.Host, o.User, o.Port, o.RepoPath, o.HostFingerprint)
sum := sha256.Sum256([]byte(s))
return hex.EncodeToString(sum[:])
}
func (b *Bridge) readMarker() string {
data, err := os.ReadFile(b.MarkerPath)
if err != nil {
return ""
}
return string(data)
}
func (b *Bridge) writeMarker(h string) error {
if err := os.MkdirAll(filepath.Dir(b.MarkerPath), 0o700); err != nil {
return err
}
tmp := b.MarkerPath + ".tmp"
if err := os.WriteFile(tmp, []byte(h), 0o600); err != nil {
return err
}
return os.Rename(tmp, b.MarkerPath)
}
// Reconcile applies the offsite descriptor. Safe to call repeatedly (idempotent) and on any error leaves
// nothing half-configured (fail-safe). Returns an error for logging; callers run it async and retry.
func (b *Bridge) Reconcile(ctx context.Context) error {
o := b.Cfg.Offsite
if !o.Enabled {
return nil // disabled → the fork-4 gate blocks runs; nothing to apply
}
port := o.Port
if port == 0 {
port = 23
}
h := descriptorHash(o)
if b.readMarker() == h {
return nil // already applied for this descriptor (idempotent) — do NOT re-consume a spent password
}
if o.HostFingerprint == "" {
return fmt.Errorf("offsite-apply: descriptor has no host_fingerprint — refusing (no blind TOFU)")
}
if o.Host == "" || o.User == "" || o.RepoPath == "" {
return fmt.Errorf("offsite-apply: descriptor missing host/user/repo_path")
}
// 1) Scan + VERIFY the host key BEFORE consuming the password (don't waste it on a mismatch).
scannedFP, knownHostsLine, err := b.Scanner.Scan(ctx, o.Host, port)
if err != nil {
return fmt.Errorf("offsite-apply: host-key scan: %w", err)
}
if scannedFP != o.HostFingerprint {
return fmt.Errorf("offsite-apply: host-key MISMATCH for %s (got %s, want %s) — refusing to pin/install (possible MITM)", o.Host, scannedFP, o.HostFingerprint)
}
// 2) Generate the controller keypair.
privPEM, pubAuthorized, err := b.KeyGen.Generate()
if err != nil {
return fmt.Errorf("offsite-apply: keygen: %w", err)
}
// 3) Consume the one-time password (single-use). After this the password is SPENT.
password, err := b.Consumer.Consume(ctx)
if err != nil {
return fmt.Errorf("offsite-apply: consume one-time password: %w", err)
}
// 4) Install the pubkey using the password (proven ssh-copy-id -s -f), verify key auth.
if err := b.Installer.Install(ctx, o.Host, o.User, port, password, privPEM, pubAuthorized); err != nil {
// The password is now SPENT but install failed — a loud, distinct signal: the operator must reset
// the box password on the hub and let the bridge retry. Do NOT mark applied.
b.logf("[ERROR] [offsite-apply] key install FAILED after consuming the one-time password for %s@%s — the password is spent; reset it on the hub to retry: %v", o.User, o.Host, err)
return fmt.Errorf("offsite-apply: install key (password spent — needs hub reset): %w", err)
}
// 5) Configure the offbox target + go EscrowState="pending" (fork-4 enable path).
if err := b.Enabler.ConfigureOffbox(ctx, o.Host, o.User, port, o.RepoPath, privPEM, knownHostsLine); err != nil {
return fmt.Errorf("offsite-apply: configure offbox: %w", err)
}
// 6) Persist the marker LAST — only a fully-applied descriptor is recorded (fail-safe).
if err := b.writeMarker(h); err != nil {
b.logf("[WARN] [offsite-apply] applied offsite for %s but failed to persist the marker (will re-apply next cycle — the password is spent, needs reset): %v", o.Host, err)
return err
}
b.logf("[INFO] [offsite-apply] offsite configured for %s@%s:%s (pending key escrow)", o.User, o.Host, o.RepoPath)
return nil
}
@@ -0,0 +1,188 @@
package offsiteapply
import (
"bytes"
"context"
"errors"
"log"
"os"
"path/filepath"
"strings"
"testing"
"gitea.dooplex.hu/admin/felhom-controller/internal/config"
)
// --- fakes ---
type fakeConsumer struct {
pw string
err error
calls int
panics bool
}
func (f *fakeConsumer) Consume(_ context.Context) (string, error) {
if f.panics {
panic("consume must NOT be called (idempotent no-op)")
}
f.calls++
return f.pw, f.err
}
type fakeScanner struct {
fp, line string
err error
}
func (f *fakeScanner) Scan(_ context.Context, _ string, _ int) (string, string, error) {
return f.fp, f.line, f.err
}
type fakeKeyGen struct{ priv, pub string }
func (f *fakeKeyGen) Generate() (string, string, error) { return f.priv, f.pub, nil }
type fakeInstaller struct {
err error
calls int
gotPub string
gotPriv string
gotPw string
}
func (f *fakeInstaller) Install(_ context.Context, _, _ string, _ int, password, privPEM, pub string) error {
f.calls++
f.gotPub, f.gotPriv, f.gotPw = pub, privPEM, password
return f.err
}
type fakeEnabler struct {
err error
calls int
gotHost string
gotKnownHost string
gotPriv string
}
func (f *fakeEnabler) ConfigureOffbox(_ context.Context, host, _ string, _ int, _, privPEM, knownHosts string) error {
f.calls++
f.gotHost, f.gotKnownHost, f.gotPriv = host, knownHosts, privPEM
return f.err
}
func newBridge(t *testing.T, o config.OffsiteConfig) (*Bridge, *fakeConsumer, *fakeInstaller, *fakeEnabler, *bytes.Buffer) {
t.Helper()
cfg := &config.Config{}
cfg.Offsite = o
cons := &fakeConsumer{pw: "the-transient-pw"}
inst := &fakeInstaller{}
en := &fakeEnabler{}
var logbuf bytes.Buffer
b := &Bridge{
Cfg: cfg,
Consumer: cons,
Scanner: &fakeScanner{fp: "SHA256:goodfp", line: "[h]:23 ssh-ed25519 AAAAKEY"},
KeyGen: &fakeKeyGen{priv: "PRIVPEM", pub: "ssh-ed25519 AAAAPUB felhom"},
Installer: inst,
Enabler: en,
MarkerPath: filepath.Join(t.TempDir(), "offbox", "applied_marker"),
Logger: log.New(&logbuf, "", 0),
}
return b, cons, inst, en, &logbuf
}
func goodOffsite() config.OffsiteConfig {
return config.OffsiteConfig{Enabled: true, Type: "shared", Host: "h", User: "u", Port: 23, RepoPath: "/home/felhom-repo", HostFingerprint: "SHA256:goodfp"}
}
// Scenario A — full apply: consume → verify-pin → install → configure offbox → marker persisted; pw not logged.
func TestBridge_AppliesEndToEnd(t *testing.T) {
b, cons, inst, en, logbuf := newBridge(t, goodOffsite())
if err := b.Reconcile(context.Background()); err != nil {
t.Fatalf("reconcile: %v", err)
}
if cons.calls != 1 {
t.Fatalf("consume calls = %d, want 1", cons.calls)
}
if inst.calls != 1 || inst.gotPw != "the-transient-pw" || inst.gotPub == "" {
t.Fatalf("installer not called with pw+pub: %+v", inst)
}
if en.calls != 1 || en.gotHost != "h" || en.gotKnownHost != "[h]:23 ssh-ed25519 AAAAKEY" || en.gotPriv != "PRIVPEM" {
t.Fatalf("enabler not called with the pinned known_hosts + key: %+v", en)
}
if b.readMarker() != descriptorHash(b.Cfg.Offsite) {
t.Fatal("marker not persisted after a successful apply")
}
if strings.Contains(logbuf.String(), "the-transient-pw") {
t.Fatal("the one-time password LEAKED into a log line")
}
}
// Scenario B — host-key mismatch → refuse: no consume, no install, no configure, no marker.
func TestBridge_HostKeyMismatchRefuses(t *testing.T) {
b, cons, inst, en, _ := newBridge(t, goodOffsite())
b.Scanner = &fakeScanner{fp: "SHA256:ATTACKER", line: "[h]:23 ssh-ed25519 EVIL"}
err := b.Reconcile(context.Background())
if err == nil || !strings.Contains(err.Error(), "MISMATCH") {
t.Fatalf("mismatch must refuse, got %v", err)
}
if cons.calls != 0 || inst.calls != 0 || en.calls != 0 {
t.Fatalf("nothing may proceed on a host-key mismatch: cons=%d inst=%d en=%d", cons.calls, inst.calls, en.calls)
}
if b.readMarker() != "" {
t.Fatal("no marker may be written on a mismatch")
}
}
// Scenario C — idempotent: marker already matches → no-op, consume is NOT called.
func TestBridge_IdempotentNoReconsume(t *testing.T) {
b, cons, inst, en, _ := newBridge(t, goodOffsite())
cons.panics = true // Consume must not be called
// pre-seed the marker with the current descriptor hash
_ = os.MkdirAll(filepath.Dir(b.MarkerPath), 0o700)
if err := os.WriteFile(b.MarkerPath, []byte(descriptorHash(b.Cfg.Offsite)), 0o600); err != nil {
t.Fatal(err)
}
if err := b.Reconcile(context.Background()); err != nil {
t.Fatalf("idempotent reconcile must be a clean no-op, got %v", err)
}
if cons.calls != 0 || inst.calls != 0 || en.calls != 0 {
t.Fatal("an already-applied descriptor must be a full no-op")
}
}
// Scenario D — install fails → fail-safe: marker NOT persisted, offbox NOT configured, loud log.
func TestBridge_InstallFailIsFailSafe(t *testing.T) {
b, cons, inst, en, logbuf := newBridge(t, goodOffsite())
inst.err = errors.New("ssh-copy-id refused")
err := b.Reconcile(context.Background())
if err == nil {
t.Fatal("install failure must error")
}
if en.calls != 0 {
t.Fatal("offbox must NOT be configured when install fails")
}
if b.readMarker() != "" {
t.Fatal("marker must NOT be persisted on a failed apply (fail-safe)")
}
if cons.calls != 1 {
t.Fatal("the password was consumed (spent) before install")
}
if !strings.Contains(logbuf.String(), "password is spent") {
t.Fatal("a consumed-but-failed install must log the loud 'password is spent' signal")
}
}
// Disabled → no-op (no consume/install/configure).
func TestBridge_DisabledNoOp(t *testing.T) {
o := goodOffsite()
o.Enabled = false
b, cons, inst, en, _ := newBridge(t, o)
if err := b.Reconcile(context.Background()); err != nil {
t.Fatal(err)
}
if cons.calls+inst.calls+en.calls != 0 {
t.Fatal("disabled offsite must be a no-op")
}
}
+182
View File
@@ -0,0 +1,182 @@
package offsiteapply
import (
"context"
"crypto/ed25519"
"encoding/json"
"encoding/pem"
"errors"
"fmt"
"io"
"net"
"net/http"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"time"
"golang.org/x/crypto/ssh"
"golang.org/x/crypto/ssh/knownhosts"
)
// --- func adapters (convenient wiring in main.go) ---
type ConsumerFunc func(ctx context.Context) (string, error)
func (f ConsumerFunc) Consume(ctx context.Context) (string, error) { return f(ctx) }
type EnablerFunc func(ctx context.Context, host, user string, port int, repoPath, privPEM, knownHosts string) error
func (f EnablerFunc) ConfigureOffbox(ctx context.Context, host, user string, port int, repoPath, privPEM, knownHosts string) error {
return f(ctx, host, user, port, repoPath, privPEM, knownHosts)
}
// --- HTTPConsumer: POST the hub consume-password endpoint with the per-customer API key ---
type HTTPConsumer struct {
HubURL string
CustomerID string
APIKey string
HC *http.Client
}
func (c HTTPConsumer) Consume(ctx context.Context) (string, error) {
if c.HubURL == "" || c.CustomerID == "" || c.APIKey == "" {
return "", fmt.Errorf("offsite-apply: consume: hub url/customer/apikey not configured")
}
hc := c.HC
if hc == nil {
hc = &http.Client{Timeout: 20 * time.Second}
}
url := strings.TrimRight(c.HubURL, "/") + "/api/v1/offsite/consume-password/" + c.CustomerID
req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, nil)
if err != nil {
return "", err
}
req.Header.Set("Authorization", "Bearer "+c.APIKey)
resp, err := hc.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
if resp.StatusCode == http.StatusNotFound {
return "", fmt.Errorf("no unconsumed offsite password (already consumed or none provisioned)")
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return "", fmt.Errorf("consume: HTTP %d", resp.StatusCode)
}
var body struct {
Password string `json:"password"`
}
if err := json.Unmarshal(raw, &body); err != nil || body.Password == "" {
return "", fmt.Errorf("consume: malformed response")
}
return body.Password, nil // NEVER logged
}
// --- KeyscanScanner: capture the box host key (x/crypto/ssh, no binary) → fingerprint + known_hosts line ---
type KeyscanScanner struct {
Timeout time.Duration
}
var errScanCaptured = errors.New("host key captured")
func (s KeyscanScanner) Scan(ctx context.Context, host string, port int) (string, string, error) {
timeout := s.Timeout
if timeout == 0 {
timeout = 10 * time.Second
}
var fp, line string
cfg := &ssh.ClientConfig{
User: "felhom-keyscan",
Timeout: timeout,
HostKeyCallback: func(_ string, _ net.Addr, key ssh.PublicKey) error {
fp = ssh.FingerprintSHA256(key)
line = knownhosts.Line([]string{knownhosts.Normalize(net.JoinHostPort(host, strconv.Itoa(port)))}, key)
return errScanCaptured
},
}
d := net.Dialer{Timeout: timeout}
conn, err := d.DialContext(ctx, "tcp", net.JoinHostPort(host, strconv.Itoa(port)))
if err != nil {
return "", "", fmt.Errorf("dial: %w", err)
}
defer conn.Close()
c, _, _, herr := ssh.NewClientConn(conn, host, cfg)
if c != nil {
c.Close()
}
if fp != "" && line != "" {
return fp, line, nil
}
return "", "", fmt.Errorf("host-key handshake: %w", herr)
}
// --- ED25519KeyGen: a fresh keypair (OpenSSH private PEM + authorized_keys pub line) ---
type ED25519KeyGen struct{}
func (ED25519KeyGen) Generate() (string, string, error) {
pub, priv, err := ed25519.GenerateKey(nil)
if err != nil {
return "", "", err
}
block, err := ssh.MarshalPrivateKey(priv, "felhom-offbox")
if err != nil {
return "", "", err
}
sshPub, err := ssh.NewPublicKey(pub)
if err != nil {
return "", "", err
}
privPEM := string(pem.EncodeToMemory(block))
pubLine := string(ssh.MarshalAuthorizedKey(sshPub)) // includes trailing newline
return privPEM, pubLine, nil
}
// --- SSHCopyIDInstaller: install the pubkey via the proven `sshpass -e ssh-copy-id -p N -s -f`, verify ---
type SSHCopyIDInstaller struct{}
func (SSHCopyIDInstaller) Install(ctx context.Context, host, user string, port int, password, privPEM, pubAuthorized string) error {
work, err := os.MkdirTemp("", "felhom-keyinstall-")
if err != nil {
return err
}
defer os.RemoveAll(work)
pubPath := filepath.Join(work, "id.pub")
privPath := filepath.Join(work, "id")
if err := os.WriteFile(pubPath, []byte(pubAuthorized), 0o600); err != nil {
return err
}
if err := os.WriteFile(privPath, []byte(privPEM), 0o600); err != nil {
return err
}
// Install (SSHPASS env is read by `sshpass -e`; the password never appears on argv).
install := exec.CommandContext(ctx, "sshpass", "-e", "ssh-copy-id", "-p", strconv.Itoa(port), "-s", "-f",
"-i", pubPath, "-o", "StrictHostKeyChecking=accept-new", user+"@"+host)
install.Env = append(os.Environ(), "SSHPASS="+password)
if out, err := install.CombinedOutput(); err != nil {
return fmt.Errorf("ssh-copy-id: %w: %s", err, truncate(out))
}
// Verify passwordless key auth (an SFTP no-op; the box's restricted shell only offers SFTP).
verify := exec.CommandContext(ctx, "sftp", "-b", "-", "-P", strconv.Itoa(port),
"-i", privPath, "-oBatchMode=yes", "-oStrictHostKeyChecking=accept-new", user+"@"+host)
verify.Stdin = strings.NewReader("pwd\n")
if out, err := verify.CombinedOutput(); err != nil {
return fmt.Errorf("key-auth verify failed after install: %w: %s", err, truncate(out))
}
return nil
}
func truncate(b []byte) string {
s := strings.TrimSpace(string(b))
if len(s) > 300 {
return s[:300] + "…"
}
return s
}