@synopackageland/cli 0.3.10 → 0.4.1

package/templates/native-go/backend/internal/helper/status.go

@@ -0,0 +1,334 @@
+// Package helper implements the opt-in per-package lifecycle contract. It has
+// no file/grant/job API: all unimplemented operations fail closed.
+package helper
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"io/fs"
+	"net"
+	"os"
+	"path/filepath"
+	"regexp"
+	"syscall"
+	"time"
+)
+
+type Inventory struct {
+	Package        string `json:"package"`
+	Version        string `json:"version"`
+	Protocol       int    `json:"protocol"`
+	PayloadDigest  string `json:"payloadDigest"`
+	RegistryDigest string `json:"registryDigest"`
+	DataAccess     string `json:"dataAccess,omitempty"`
+}
+
+var digestPattern = regexp.MustCompile(`^[a-f0-9]{64}$`)
+var packagePattern = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9]{1,63}$`)
+var versionPattern = regexp.MustCompile(`^\d+(\.\d+){0,3}-\d{4}$`)
+
+func (i Inventory) Valid() bool {
+	mode := i.DataAccess == "" || i.Protocol == DataProtocol && (i.DataAccess == "unavailable" || i.DataAccess == "relaxed")
+	return mode && packagePattern.MatchString(i.Package) && versionPattern.MatchString(i.Version) && (i.Protocol == 1 || i.Protocol == DataProtocol) && digestPattern.MatchString(i.PayloadDigest) && digestPattern.MatchString(i.RegistryDigest)
+}
+
+type Record struct {
+	Schema    int        `json:"schema,omitempty"`
+	Lifecycle *Lifecycle `json:"lifecycle,omitempty"`
+	Inventory Inventory  `json:"inventory"`
+	Enabled   bool       `json:"enabled"`
+	Residual  bool       `json:"residual,omitempty"`
+}
+type Request struct {
+	Inventory Inventory `json:"inventory"`
+	Op        string    `json:"op"`
+	Nonce     string    `json:"nonce"`
+}
+type Response struct {
+	Inventory Inventory `json:"inventory"`
+	Nonce     string    `json:"nonce"`
+	OK        bool      `json:"ok"`
+	Error     string    `json:"error,omitempty"`
+}
+
+func Respond(i Inventory, disabled bool, req Request) Response {
+	r := Response{Inventory: i, Nonce: req.Nonce}
+	switch {
+	case disabled:
+		r.Error = "disabled"
+	case !i.Valid() || req.Inventory != i:
+		r.Error = "incompatible"
+	case req.Op != "health":
+		r.Error = "unsupported"
+	default:
+		r.OK = true
+	}
+	return r
+}
+
+// State is safe to expose to any authenticated DSM user. Paths, PIDs, worker
+// internals, scheduler definitions and raw errors never enter this envelope.
+type State struct {
+	State          string `json:"state"`
+	Reason         string `json:"reason"`
+	PackageRunning string `json:"packageRunning"`
+	Scheduler      string `json:"scheduler"`
+	Cleanup        string `json:"cleanup,omitempty"`
+}
+
+type Client struct {
+	Expected         Inventory
+	StateDir, RunDir string
+	// Production uses UID 0 and RootPeer. Tests inject only local fixture identity.
+	Owner uint32
+	Peer  func(*net.UnixConn) error
+}
+
+func NewClient(i Inventory) Client {
+	return Client{Expected: i, StateDir: "/var/lib/synopkgland-" + i.Package, RunDir: "/run/synopkgland-helper-" + i.Package, Peer: RootPeer}
+}
+
+// LocalClient is a nonprivileged diagnostic entry point for package hooks.
+// Hashing the local executable establishes only the expected build inventory;
+// readiness still requires the protected record and root socket handshake.
+func LocalClient(i Inventory) (Client, error) {
+	exe, err := os.Executable()
+	if err != nil {
+		return Client{}, err
+	}
+	f, err := os.Open(exe)
+	if err != nil {
+		return Client{}, err
+	}
+	defer f.Close()
+	h := sha256.New()
+	if _, err := io.Copy(h, io.LimitReader(f, (64<<20)+1)); err != nil {
+		return Client{}, err
+	}
+	i.PayloadDigest = hex.EncodeToString(h.Sum(nil))
+	if !i.Valid() {
+		return Client{}, errTrust
+	}
+	return NewClient(i), nil
+}
+
+func (c Client) CheckStopped(ctx context.Context) error {
+	s := c.Status(ctx)
+	if s.Cleanup != "" || (s.State != "not-enabled" && s.State != "stopped" && s.State != "needs-approval") {
+		return errors.New("approved helper teardown required")
+	}
+	for _, file := range []string{"process.json", "helper.sock", "supervisor.sock"} {
+		if _, err := os.Lstat(filepath.Join(c.RunDir, file)); !errors.Is(err, fs.ErrNotExist) {
+			return errors.New("helper residue; approved teardown required")
+		}
+	}
+	return nil
+}
+
+var errTrust = errors.New("untrusted helper state")
+
+func protected(path string, owner uint32, directory bool) error {
+	st, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	s, ok := st.Sys().(*syscall.Stat_t)
+	if !ok || s.Uid != owner || st.Mode().Perm()&0022 != 0 || (directory && !st.IsDir()) || (!directory && !st.Mode().IsRegular()) {
+		return errTrust
+	}
+	return nil
+}
+
+func readRecord(dir string, owner uint32) (Record, error) {
+	var r Record
+	if err := protected(dir, owner, true); err != nil {
+		return r, err
+	}
+	f, err := os.OpenFile(filepath.Join(dir, "approval.json"), os.O_RDONLY|syscall.O_NOFOLLOW, 0)
+	if err != nil {
+		return r, err
+	}
+	defer f.Close()
+	st, err := f.Stat()
+	if err != nil {
+		return r, err
+	}
+	s, ok := st.Sys().(*syscall.Stat_t)
+	if !ok || s.Uid != owner || st.Mode().Perm()&0022 != 0 || !st.Mode().IsRegular() || st.Size() > 4096 {
+		return r, errTrust
+	}
+	d := json.NewDecoder(io.LimitReader(f, 4097))
+	d.DisallowUnknownFields()
+	var decoded struct {
+		Schema    int        `json:"schema,omitempty"`
+		Lifecycle *Lifecycle `json:"lifecycle,omitempty"`
+		Inventory Inventory  `json:"inventory"`
+		Enabled   *bool      `json:"enabled"`
+		Residual  bool       `json:"residual,omitempty"`
+	}
+	if d.Decode(&decoded) != nil || d.Decode(new(any)) != io.EOF || !decoded.Inventory.Valid() || decoded.Enabled == nil || !decoded.Lifecycle.valid() || (decoded.Schema != 0 && decoded.Schema != 2) {
+		return r, errTrust
+	}
+	r = Record{Schema: decoded.Schema, Inventory: decoded.Inventory, Enabled: *decoded.Enabled, Residual: decoded.Residual, Lifecycle: decoded.Lifecycle}
+	return r, nil
+}
+
+func (c Client) Status(ctx context.Context) State {
+	result := func(state, reason string) State {
+		return State{State: state, Reason: reason, PackageRunning: "unknown", Scheduler: "not-probed"}
+	}
+	if c.Expected.Package == "" {
+		return result("not-enabled", "not-requested")
+	}
+	if !c.Expected.Valid() {
+		return result("incompatible", "invalid-inventory")
+	}
+	r, err := readRecord(c.StateDir, c.Owner)
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return result("incompatible", "untrusted-approval")
+	}
+	if err == nil && !r.Enabled {
+		s := result("not-enabled", "disabled")
+		if r.Residual {
+			s.Cleanup = "required"
+		}
+		return s
+	}
+	if err == nil && r.Inventory != c.Expected {
+		return result("incompatible", "inventory-mismatch")
+	}
+	if err == nil && r.Residual {
+		s := result("failed", "incomplete-transition")
+		s.Cleanup = "required"
+		return s
+	}
+	if err == nil && r.Lifecycle != nil && r.Lifecycle.Phase != "running" {
+		if e := protected(c.RunDir, c.Owner, true); e != nil && !errors.Is(e, fs.ErrNotExist) {
+			return result("incompatible", "untrusted-runtime")
+		}
+		if r.Lifecycle.Completion != "" {
+			path := filepath.Join(c.StateDir, "completion-"+r.Lifecycle.Epoch+".json")
+			st, e := os.Lstat(path)
+			ok := e == nil && st.Mode().IsRegular() && st.Mode().Perm() == 0600
+			if ok {
+				s, valid := st.Sys().(*syscall.Stat_t)
+				ok = valid && s.Uid == c.Owner
+			}
+			if ok && uint32(os.Geteuid()) == c.Owner {
+				_, e = completionRecord(c, r)
+				ok = e == nil
+			}
+			if !ok {
+				s := result("failed", "invalid-completion")
+				s.Cleanup = "required"
+				return s
+			}
+		}
+
+		if !runtimeAbsent(c) {
+			s := result("failed", "incomplete-transition")
+			s.Cleanup = "required"
+			return s
+		}
+		return result("stopped", "admin-recover-required")
+	}
+	// Conflict has precedence over missing approval. Even an unapproved leftover
+	// socket is probed before claiming that authorization alone can fix it.
+	if e := protected(c.RunDir, c.Owner, true); e != nil && !errors.Is(e, fs.ErrNotExist) {
+		return result("incompatible", "untrusted-runtime")
+	}
+	socket := filepath.Join(c.RunDir, "helper.sock")
+	st, e := os.Lstat(socket)
+	if e == nil {
+		s, ok := st.Sys().(*syscall.Stat_t)
+		if !ok || s.Uid != c.Owner || st.Mode()&os.ModeSocket == 0 || st.Mode().Perm()&0002 != 0 {
+			return result("incompatible", "untrusted-socket")
+		}
+		state, reason := c.probe(ctx, socket)
+		if state != "ready" {
+			s := result(state, reason)
+			if state == "pending" {
+				if err == nil && r.Lifecycle != nil && r.Lifecycle.Phase == "running" {
+					s.PackageRunning = "running"
+					return s
+				}
+				s.State, s.Reason = "failed", "health-refused"
+			}
+			if r.Lifecycle != nil {
+				if _, err := readProcess(c.RunDir, c.Owner); err == nil {
+					s.State = "failed"
+					s.Cleanup = "required"
+				}
+			}
+			if reason == "lifecycle-fenced" {
+				s.Cleanup = "required"
+			}
+			return s
+		}
+	} else if !errors.Is(e, fs.ErrNotExist) {
+		return result("failed", "runtime-unreadable")
+	}
+	if err != nil {
+		return result("needs-approval", "approval-missing")
+	}
+	if e != nil {
+		return result("stopped", "runtime-missing")
+	}
+	s := result("ready", "live-handshake")
+	if r.Lifecycle != nil {
+		s.PackageRunning = "running"
+	}
+	return s
+}
+
+func (c Client) probe(ctx context.Context, socket string) (string, string) {
+	deadline := time.Now().Add(time.Second)
+	if d, ok := ctx.Deadline(); ok && d.Before(deadline) {
+		deadline = d
+	}
+	dialer := net.Dialer{Deadline: deadline}
+	conn, err := dialer.DialContext(ctx, "unix", socket)
+	if err != nil {
+		if errors.Is(err, syscall.ECONNREFUSED) || errors.Is(err, fs.ErrNotExist) {
+			return "stopped", "runtime-not-listening"
+		}
+		return "failed", "probe-failed"
+	}
+	defer conn.Close()
+	if c.Peer == nil || c.Peer(conn.(*net.UnixConn)) != nil {
+		return "incompatible", "untrusted-peer"
+	}
+	conn.SetDeadline(deadline)
+	var nonce [32]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return "failed", "probe-failed"
+	}
+	req := Request{c.Expected, "health", hex.EncodeToString(nonce[:])}
+	if json.NewEncoder(conn).Encode(req) != nil {
+		return "failed", "probe-failed"
+	}
+	var res Response
+	d := json.NewDecoder(io.LimitReader(conn, 4097))
+	d.DisallowUnknownFields()
+	if d.Decode(&res) != nil {
+		return "failed", "invalid-handshake"
+	}
+	if res.Nonce != req.Nonce || res.Inventory != c.Expected || res.Error == "incompatible" {
+		return "incompatible", "handshake-mismatch"
+	}
+	if !res.OK && res.Error == "reload-revalidating" {
+		return "pending", "reload-revalidating"
+	}
+	if !res.OK && res.Error == "fenced" {
+		return "failed", "lifecycle-fenced"
+	}
+	if !res.OK || res.Error != "" {
+		return "failed", "health-refused"
+	}
+	return "ready", "live-handshake"
+}

package/templates/native-go/backend/internal/helper/status_test.go

@@ -0,0 +1,288 @@
+package helper
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func fixture(t *testing.T) Client {
+	t.Helper()
+	i := Inventory{Package: "Fixture", Version: "1.0.0-0001", Protocol: 1, PayloadDigest: strings.Repeat("a", 64), RegistryDigest: strings.Repeat("b", 64)}
+	run, err := os.MkdirTemp("/tmp", "m1a-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.RemoveAll(run) })
+	return Client{Expected: i, StateDir: t.TempDir(), RunDir: run, Owner: uint32(os.Getuid()), Peer: func(*net.UnixConn) error { return nil }}
+}
+
+func record(t *testing.T, c Client, r Record) {
+	t.Helper()
+	b, _ := json.Marshal(r)
+	if err := os.WriteFile(filepath.Join(c.StateDir, "approval.json"), b, 0644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func live(t *testing.T, c Client, i Inventory, reply func(Request) Response) {
+	t.Helper()
+	l, err := net.ListenUnix("unix", &net.UnixAddr{Name: filepath.Join(c.RunDir, "helper.sock"), Net: "unix"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { l.Close() })
+	go func() {
+		for {
+			conn, err := l.AcceptUnix()
+			if err != nil {
+				return
+			}
+			go func() {
+				defer conn.Close()
+				var req Request
+				if json.NewDecoder(conn).Decode(&req) != nil {
+					return
+				}
+				r := Respond(i, false, req)
+				if reply != nil {
+					r = reply(req)
+				}
+				json.NewEncoder(conn).Encode(r)
+			}()
+		}
+	}()
+}
+
+func TestSixStatesAndPriority(t *testing.T) {
+	c := fixture(t)
+	check := func(want string) {
+		t.Helper()
+		s := c.Status(context.Background())
+		if s.State != want {
+			t.Fatalf("want %s, got %+v", want, s)
+		}
+	}
+	c.Expected = Inventory{}
+	check("not-enabled")
+	c.Expected = fixture(t).Expected
+	check("needs-approval")
+	record(t, c, Record{Inventory: c.Expected, Enabled: true})
+	check("stopped")
+	live(t, c, c.Expected, nil)
+	check("ready")
+	old := c.Expected
+	old.Protocol++
+	record(t, c, Record{Inventory: old, Enabled: true})
+	check("incompatible")
+	record(t, c, Record{Inventory: old, Enabled: false})
+	check("not-enabled")
+}
+
+func TestLiveProbeCannotBeReplacedByApprovalOrHistoricalOutput(t *testing.T) {
+	c := fixture(t)
+	record(t, c, Record{Inventory: c.Expected, Enabled: true})
+	if err := os.WriteFile(filepath.Join(c.RunDir, "helper.sock"), []byte("ready"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if got := c.Status(context.Background()).State; got != "incompatible" {
+		t.Fatal(got)
+	}
+}
+
+func TestHandshakeFailuresAreRedacted(t *testing.T) {
+	for _, kind := range []string{"nonce", "protocol", "payload", "worker", "version", "peer"} {
+		t.Run(kind, func(t *testing.T) {
+			c := fixture(t)
+			record(t, c, Record{Inventory: c.Expected, Enabled: true})
+			live(t, c, c.Expected, func(req Request) Response {
+				r := Respond(c.Expected, false, req)
+				switch kind {
+				case "nonce":
+					r.Nonce = "replay"
+				case "protocol":
+					r.Inventory.Protocol++
+				case "payload":
+					r.Inventory.PayloadDigest = "foreign"
+				case "worker":
+					r.Inventory.RegistryDigest = "foreign"
+				case "version":
+					r.Inventory.Version = "old"
+				}
+				return r
+			})
+			if kind == "peer" {
+				c.Peer = func(*net.UnixConn) error { return os.ErrPermission }
+			}
+			s := c.Status(context.Background())
+			if s.State != "incompatible" {
+				t.Fatalf("%+v", s)
+			}
+			b, _ := json.Marshal(s)
+			if strings.Contains(string(b), c.StateDir) || strings.Contains(string(b), "foreign") {
+				t.Fatal(string(b))
+			}
+		})
+	}
+	c := fixture(t)
+	record(t, c, Record{Inventory: c.Expected, Enabled: true})
+	live(t, c, c.Expected, func(req Request) Response { return Response{Inventory: c.Expected, Nonce: req.Nonce, Error: "failed"} })
+	if c.Status(context.Background()).State != "failed" {
+		t.Fatal("health failure must be failed")
+	}
+}
+
+func TestUntrustedPersistentStateFailsClosed(t *testing.T) {
+	for _, kind := range []string{"writable", "symlink", "malformed"} {
+		t.Run(kind, func(t *testing.T) {
+			c := fixture(t)
+			record(t, c, Record{Inventory: c.Expected, Enabled: true})
+			p := filepath.Join(c.StateDir, "approval.json")
+			switch kind {
+			case "writable":
+				os.Chmod(p, 0666)
+			case "symlink":
+				os.Rename(p, p+".real")
+				os.Symlink(p+".real", p)
+			case "malformed":
+				os.WriteFile(p, []byte(`{"enabled":false}`), 0644)
+			}
+			if c.Status(context.Background()).State != "incompatible" {
+				t.Fatal("untrusted state accepted")
+			}
+		})
+	}
+}
+
+func TestOldHelperRejectsNewInventoryAndAllUnimplementedWork(t *testing.T) {
+	i := fixture(t).Expected
+	for _, field := range []string{"protocol", "payload", "workers", "version", "package"} {
+		new := i
+		switch field {
+		case "protocol":
+			new.Protocol++
+		case "payload":
+			new.PayloadDigest = strings.Repeat("c", 64)
+		case "workers":
+			new.RegistryDigest = strings.Repeat("c", 64)
+		case "version":
+			new.Version = "2.0.0-0001"
+		case "package":
+			new.Package = "Other"
+		}
+		r := Respond(i, false, Request{Inventory: new, Op: "work", Nonce: "test"})
+		if r.Error != "incompatible" || r.OK {
+			t.Fatalf("%s: %+v", field, r)
+		}
+	}
+	if r := Respond(i, true, Request{Inventory: i, Op: "health"}); r.OK || r.Error != "disabled" {
+		t.Fatal(r)
+	}
+	if r := Respond(i, false, Request{Inventory: i, Op: "work"}); r.OK || r.Error != "unsupported" {
+		t.Fatal(r)
+	}
+}
+
+func TestMissingEnableFieldIsNotARevocationRecord(t *testing.T) {
+	c := fixture(t)
+	b, _ := json.Marshal(map[string]any{"inventory": c.Expected})
+	os.WriteFile(filepath.Join(c.StateDir, "approval.json"), b, 0644)
+	if c.Status(context.Background()).State != "incompatible" {
+		t.Fatal("incomplete approval treated as trusted disable")
+	}
+}
+
+func TestProcessRecordIsNotReadableByOrdinaryOSUsers(t *testing.T) {
+	c, _ := controlFixture(t)
+	s, err := os.Stat(filepath.Join(c.RunDir, "process.json"))
+	if err != nil || s.Mode().Perm() != 0600 {
+		t.Fatalf("process record permissions: %v %v", s, err)
+	}
+}
+
+func TestS8InventoryHealthRejectsUnknownProtocol(t *testing.T) {
+	c := fixture(t)
+	for _, protocol := range []int{1, 2} {
+		i := c.Expected
+		i.Protocol = protocol
+		if !i.Valid() || !Respond(i, false, Request{Inventory: i, Op: "health", Nonce: strings.Repeat("c", 64)}).OK {
+			t.Fatal("supported protocol", protocol)
+		}
+	}
+	for _, protocol := range []int{0, 3, 99} {
+		i := c.Expected
+		i.Protocol = protocol
+		res := Respond(i, false, Request{Inventory: i, Op: "health", Nonce: strings.Repeat("c", 64)})
+		if i.Valid() || res.OK || res.Error != "incompatible" {
+			t.Fatal("unknown protocol accepted", protocol, res)
+		}
+	}
+}
+
+func TestPendingHealthRequiresTrustedRunningApproval(t *testing.T) {
+	for _, kind := range []string{"running", "missing", "legacy", "disabled", "residual", "fenced", "nonce", "inventory", "contradictory"} {
+		t.Run(kind, func(t *testing.T) {
+			c := fixture(t)
+			r := Record{Inventory: c.Expected, Enabled: true, Lifecycle: testLifecycle("running")}
+			switch kind {
+			case "legacy":
+				r.Lifecycle = nil
+			case "disabled":
+				r.Enabled = false
+			case "residual":
+				r.Residual = true
+			case "fenced":
+				r.Lifecycle.Phase = "fenced"
+			}
+			if kind != "missing" {
+				record(t, c, r)
+			}
+			live(t, c, c.Expected, func(req Request) Response {
+				res := Response{Inventory: c.Expected, Nonce: req.Nonce, Error: "reload-revalidating"}
+				switch kind {
+				case "nonce":
+					res.Nonce = "replay"
+				case "inventory":
+					res.Inventory.Protocol++
+				case "contradictory":
+					res.OK = true
+				}
+				return res
+			})
+			got := c.Status(context.Background())
+			if kind == "running" {
+				if got.State != "pending" || got.Reason != "reload-revalidating" || got.Cleanup != "" || got.PackageRunning != "running" {
+					t.Fatalf("%+v", got)
+				}
+				if c.CheckStopped(context.Background()) == nil {
+					t.Fatal("pending accepted as stopped")
+				}
+			} else if got.State == "pending" || got.State == "ready" {
+				t.Fatalf("untrusted pending: %+v", got)
+			}
+		})
+	}
+}
+
+func TestS1RInventoryModeIsProtocolTwoOnly(t *testing.T) {
+	i := Inventory{Package: "Fixture", Version: "1.0.0-0001", Protocol: 2, PayloadDigest: strings.Repeat("a", 64), RegistryDigest: strings.Repeat("b", 64)}
+	for _, mode := range []string{"", "unavailable", "relaxed"} {
+		i.DataAccess = mode
+		if !i.Valid() {
+			t.Fatal("known mode refused", mode)
+		}
+	}
+	i.DataAccess = "active"
+	if i.Valid() {
+		t.Fatal("unknown mode accepted")
+	}
+	i.DataAccess = "relaxed"
+	i.Protocol = 1
+	if i.Valid() {
+		t.Fatal("protocol 1 accepted relaxed")
+	}
+}