@synopackageland/cli 0.3.10 → 0.4.0

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

@@ -0,0 +1,192 @@
+package helper
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"syscall"
+	"time"
+)
+
+func setParentDeath() error {
+	_, _, err := syscall.Syscall6(syscall.SYS_PRCTL, syscall.PR_SET_PDEATHSIG, uintptr(syscall.SIGKILL), 0, 0, 0, 0)
+	if err != 0 {
+		return err
+	}
+	return nil
+}
+
+type ownedLinuxChild struct {
+	process *os.Process
+	reaped  bool
+}
+
+func (c *ownedLinuxChild) exited() (bool, error) {
+	if c.reaped {
+		return true, nil
+	}
+	var status syscall.WaitStatus
+	pid, err := syscall.Wait4(c.process.Pid, &status, syscall.WNOHANG, nil)
+	if errors.Is(err, syscall.EINTR) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	} // ECHILD never permits signalling.
+	if pid == c.process.Pid {
+		c.reaped = true
+		c.process.Release()
+	}
+	return c.reaped, nil
+}
+func (c *ownedLinuxChild) signal(s syscall.Signal) error {
+	if c.reaped {
+		return errTrust
+	}
+	// This PID came from our own Start, and ONLY this event loop calls Wait4.
+	// Even if it exits here it remains an unreaped zombie, pinning its PID.
+	return syscall.Kill(c.process.Pid, s)
+}
+
+type supervisorRequest struct {
+	Process Process `json:"process"`
+	Op      string  `json:"op"`
+	Nonce   string  `json:"nonce"`
+}
+
+// The thread creating the child must remain alive: PDEATHSIG is tied to that
+// Linux thread, not merely the supervisor's thread group / Go process.
+func superviseLinux(c Client, binary string) error {
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+	r, err := readRecord(c.StateDir, 0)
+	if err != nil || !r.Enabled || r.Inventory != c.Expected {
+		return errTrust
+	}
+	identity, err := inspectSupervisor(os.Getpid(), c.Expected)
+	if err != nil {
+		return err
+	}
+	if err := writeProcess(c.RunDir, identity); err != nil {
+		return err
+	}
+	socket := filepath.Join(c.RunDir, "supervisor.sock")
+	l, err := net.ListenUnix("unix", &net.UnixAddr{Name: socket, Net: "unix"})
+	if err != nil {
+		return err
+	}
+	l.SetUnlinkOnClose(false)
+	defer l.Close()
+	if err := os.Chmod(socket, 0600); err != nil {
+		return err
+	}
+	cmd := exec.Command(binary, "serve-child")
+	cmd.Env = []string{"PATH=/usr/sbin:/usr/bin:/sbin:/bin", "SYNOPKGLAND_PARENT=" + strconv.Itoa(os.Getpid())}
+	// Go sets prctl before exec and rechecks the parent immediately afterward.
+	cmd.SysProcAttr = &syscall.SysProcAttr{Pdeathsig: syscall.SIGKILL}
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	child := &ownedLinuxChild{process: cmd.Process}
+	// No cmd.Wait goroutine: reaping and signalling are serialized below.
+	for {
+		if _, err := child.exited(); err != nil {
+			return err
+		}
+		l.SetDeadline(time.Now().Add(20 * time.Millisecond))
+		conn, err := l.AcceptUnix()
+		if err != nil {
+			if e, ok := err.(net.Error); ok && e.Timeout() {
+				continue
+			}
+			return err
+		}
+		conn.SetDeadline(time.Now().Add(3 * time.Second))
+		peer, err := peerCredentials(conn)
+		if err != nil || peer.Uid != 0 {
+			conn.Close()
+			continue
+		}
+		var req supervisorRequest
+		d := json.NewDecoder(io.LimitReader(conn, 4097))
+		d.DisallowUnknownFields()
+		if d.Decode(&req) != nil || req.Process != identity || req.Op != "stop" || len(req.Nonce) != 64 || !digestPattern.MatchString(req.Nonce) {
+			conn.Close()
+			continue
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		err = stopChild(ctx, child, time.Second)
+		cancel()
+		// Kernel process-exit fd cleanup is not ordered: close the listener
+		// before ACK, so connection EOF cannot race a still-listening socket.
+		if err == nil {
+			err = l.Close()
+		}
+		res := Response{Inventory: c.Expected, Nonce: req.Nonce, OK: err == nil}
+		if err != nil {
+			res.Error = "cleanup-required"
+		}
+		json.NewEncoder(conn).Encode(res)
+		if err == nil {
+			// Keep this connection open until OS exit. An ACK plus EOF proves both
+			// that the child was reaped and this supervisor finished cooperatively.
+			os.Exit(0)
+		}
+		conn.Close()
+	}
+}
+
+func (p LinuxProcesses) Stop(want Process) error {
+	if want.Mode != "supervised" {
+		return errTrust
+	}
+	// Loss/reboot/PID reuse is not sufficient proof of child teardown. Preserve
+	// the record for fixed admin repair; never signal this recorded PID.
+	actual, err := inspectSupervisor(want.PID, want.Inventory)
+	if err != nil || actual != want {
+		return errTrust
+	}
+	socket := filepath.Join(p.RunDir, "supervisor.sock")
+	st, err := os.Lstat(socket)
+	if err != nil {
+		return err
+	}
+	stat, ok := st.Sys().(*syscall.Stat_t)
+	if !ok || stat.Uid != 0 || st.Mode()&os.ModeSocket == 0 || st.Mode().Perm() != 0600 {
+		return errTrust
+	}
+	conn, err := net.DialTimeout("unix", socket, time.Second)
+	if err != nil {
+		return err
+	}
+	defer conn.Close()
+	peer, err := peerCredentials(conn.(*net.UnixConn))
+	if err != nil || peer.Uid != 0 || int(peer.Pid) != want.PID {
+		return errTrust
+	}
+	// Recheck after binding the connection too. A connected socket cannot be
+	// substituted by a later process that reused the path or PID.
+	actual, err = inspectSupervisor(want.PID, want.Inventory)
+	if err != nil || actual != want {
+		return errTrust
+	}
+	conn.SetDeadline(time.Now().Add(3 * time.Second))
+	var nonce [32]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return err
+	}
+	req := supervisorRequest{Process: want, Op: "stop", Nonce: hex.EncodeToString(nonce[:])}
+	if err := json.NewEncoder(conn).Encode(req); err != nil {
+		return err
+	}
+	return readSupervisorReply(conn, want.Inventory, req.Nonce)
+}

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

@@ -0,0 +1,302 @@
+package helper
+
+import (
+	"context"
+	"errors"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// This opt-in fixture uses a root-only, disposable Linux VM and an independently
+// cross-compiled cmd/helper. Never creates accounts or accesses a NAS.
+func linuxFixture(t *testing.T) LinuxProcesses {
+	t.Helper()
+	source := os.Getenv("M1C_HELPER_FIXTURE")
+	if source == "" {
+		t.Skip("requires disposable Linux root VM and M1C_HELPER_FIXTURE")
+	}
+	if os.Geteuid() != 0 {
+		t.Fatal("VM fixture requires root")
+	}
+	digest, err := executableDigest(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	i := Inventory{Package: "root", Version: "1.0.0-0001", Protocol: 1, PayloadDigest: digest, RegistryDigest: strings.Repeat("b", 64)}
+	c := NewClient(i)
+	for _, dir := range []string{c.StateDir, c.RunDir} {
+		if err := os.Mkdir(dir, 0700); err != nil {
+			t.Fatal(err)
+		}
+		t.Cleanup(func() { os.RemoveAll(dir) })
+	}
+	exe := filepath.Join(c.StateDir, "payload-"+digest)
+	b, err := os.ReadFile(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(exe, b, 0700); err != nil {
+		t.Fatal(err)
+	}
+	return LinuxProcesses{Client: c, Binary: exe}
+}
+func startVMHelper(t *testing.T, p LinuxProcesses) Process {
+	t.Helper()
+	ctl := Controller{Client: p.Client, Processes: p}
+	if err := ctl.Control(context.Background(), "enable"); err != nil {
+		t.Fatal(err)
+	}
+	record, err := readProcess(p.RunDir, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { ctl.Control(context.Background(), "disable") })
+	return record
+}
+func supervisedPID(t *testing.T, pid int) int {
+	t.Helper()
+	paths, _ := filepath.Glob("/proc/" + strconv.Itoa(pid) + "/task/*/children")
+	for _, path := range paths {
+		b, _ := os.ReadFile(path)
+		for _, s := range strings.Fields(string(b)) {
+			child, _ := strconv.Atoi(s)
+			if child > 1 {
+				return child
+			}
+		}
+	}
+	t.Fatal("supervisor has no child")
+	return 0
+}
+
+// Observation only: an absent process or zombie has exited. No signal is sent
+// to this PID, including if it has been reused. These fixtures run in a fresh VM.
+func waitPIDExit(t *testing.T, pid int) {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	if waitHealthy(ctx, func(context.Context) bool {
+		b, err := os.ReadFile("/proc/" + strconv.Itoa(pid) + "/stat")
+		if os.IsNotExist(err) {
+			return true
+		}
+		end := strings.LastIndex(string(b), ") ")
+		return err == nil && end >= 0 && strings.HasPrefix(string(b)[end+2:], "Z ")
+	}) != nil {
+		t.Fatal("owned process survived")
+	}
+}
+func TestLinuxActivationAlwaysUsesSupervisorAndNormalStop(t *testing.T) {
+	p := linuxFixture(t)
+	for n := 0; n < 20; n++ {
+		t.Run("cycle-"+strconv.Itoa(n), func(t *testing.T) {
+			proc := startVMHelper(t, p)
+			if proc.Mode != "supervised" {
+				t.Fatalf("activation did not select supervisor: %+v", proc)
+			}
+			child := supervisedPID(t, proc.PID)
+			if p.Status(context.Background()).State != "ready" {
+				t.Fatal("missing live handshake")
+			}
+			if err := (Controller{Client: p.Client, Processes: p}).Control(context.Background(), "disable"); err != nil {
+				t.Fatal(err)
+			}
+			waitPIDExit(t, child)
+			if err := p.CheckStopped(context.Background()); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+}
+
+func TestLinuxHelperSelfExitIsReapedWithoutSignallingReusedPID(t *testing.T) {
+	p := linuxFixture(t)
+	proc := startVMHelper(t, p)
+	if proc.Mode != "supervised" {
+		t.Fatal("not supervised")
+	}
+	child := supervisedPID(t, proc.PID)
+	// The VM-only helper fixture exits itself when this root-owned marker exists.
+	if err := os.WriteFile(filepath.Join(p.RunDir, "fixture-exit"), nil, 0600); err != nil {
+		t.Fatal(err)
+	}
+	waitPIDExit(t, child)
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if waitHealthy(ctx, func(context.Context) bool {
+		_, err := os.Stat("/proc/" + strconv.Itoa(child))
+		return os.IsNotExist(err)
+	}) != nil {
+		t.Fatal("supervisor did not reap")
+	}
+	if err := p.Stop(proc); err != nil {
+		t.Fatal(err)
+	}
+}
+func TestLinuxSupervisorDeathKillsHelperAndPreservesFailedCleanup(t *testing.T) {
+	p := linuxFixture(t)
+	record(t, p.Client, Record{Inventory: p.Expected, Enabled: true})
+	// Keep the supervisor as our own unreaped child; only its parent signals it.
+	cmd := exec.Command(p.Binary, "supervise")
+	if err := cmd.Start(); err != nil {
+		t.Fatal(err)
+	}
+	owned := &ownedLinuxChild{process: cmd.Process}
+	t.Cleanup(func() { stopChild(context.Background(), owned, time.Millisecond) })
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	err := waitHealthy(ctx, func(ctx context.Context) bool { return p.Status(ctx).State == "ready" })
+	cancel()
+	if err != nil {
+		t.Fatal(err)
+	}
+	proc, err := readProcess(p.RunDir, 0)
+	if err != nil || proc.Mode != "supervised" || proc.PID != cmd.Process.Pid {
+		t.Fatalf("%+v %v", proc, err)
+	}
+	child := supervisedPID(t, proc.PID)
+	if err := owned.signal(syscall.SIGKILL); err != nil {
+		t.Fatal(err)
+	}
+	waitPIDExit(t, child)
+	waitPIDExit(t, proc.PID)
+	ctl := Controller{Client: p.Client, Processes: p}
+	if ctl.Control(context.Background(), "teardown") == nil {
+		t.Fatal("lost supervisor falsely cleaned")
+	}
+	s := p.Status(context.Background())
+	if s.State != "failed" || s.Cleanup != "required" {
+		t.Fatal(s)
+	}
+	if ctl.Control(context.Background(), "disable") == nil {
+		t.Fatal("lost supervisor falsely disabled cleanly")
+	}
+	r, err := readRecord(p.StateDir, 0)
+	if err != nil || r.Enabled || !r.Residual {
+		t.Fatalf("%+v %v", r, err)
+	}
+	if _, err := os.Stat(filepath.Join(p.RunDir, "process.json")); err != nil {
+		t.Fatal("failure evidence removed")
+	}
+}
+func TestLinuxUnsupervisedRecordAndDirectServeRefuse(t *testing.T) {
+	p := linuxFixture(t)
+	proc := startVMHelper(t, p)
+	for _, mode := range []string{"", "unknown"} {
+		foreign := proc
+		foreign.Mode = mode
+		if p.Stop(foreign) == nil {
+			t.Fatal("unsupervised record accepted")
+		}
+	}
+	// Remove stopped sockets before testing the retired action, so a bind
+	// conflict cannot masquerade as refusal of unsupervised startup.
+	if err := (Controller{Client: p.Client, Processes: p}).Control(context.Background(), "teardown"); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, p.Binary, "serve")
+	if cmd.Run() == nil || ctx.Err() != nil {
+		t.Fatal("direct unsupervised serve accepted")
+	}
+	if _, err := os.Stat(filepath.Join(p.RunDir, "helper.sock")); !os.IsNotExist(err) {
+		t.Fatal("direct serve opened socket")
+	}
+}
+
+func TestLinuxOwnedChildSelfExitAndECHILDRefusal(t *testing.T) {
+	for _, externallyReaped := range []bool{false, true} {
+		cmd := exec.Command("/bin/sh", "-c", "exit 0")
+		if err := cmd.Start(); err != nil {
+			t.Fatal(err)
+		}
+		child := &ownedLinuxChild{process: cmd.Process}
+		if externallyReaped {
+			if err := cmd.Wait(); err != nil {
+				t.Fatal(err)
+			}
+			if err := stopChild(context.Background(), child, time.Millisecond); !errors.Is(err, syscall.ECHILD) {
+				t.Fatal("ECHILD did not refuse", err)
+			}
+		} else {
+			ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+			err := waitHealthy(ctx, func(context.Context) bool { done, err := child.exited(); return done && err == nil })
+			cancel()
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := stopChild(context.Background(), child, time.Millisecond); err != nil {
+				t.Fatal(err)
+			}
+			if child.signal(syscall.SIGTERM) == nil {
+				t.Fatal("reaped PID signalled")
+			}
+		}
+	}
+}
+func TestLinuxSupervisorIdentityConflictsAndSocketSubstitutionRefuse(t *testing.T) {
+	p := linuxFixture(t)
+	proc := startVMHelper(t, p)
+	for _, field := range []string{"boot", "start", "inode", "digest", "mode"} {
+		foreign := proc
+		switch field {
+		case "boot":
+			foreign.Boot = "reboot"
+		case "start":
+			foreign.Start = "reuse"
+		case "inode":
+			foreign.Inode++
+		case "digest":
+			foreign.Inventory.PayloadDigest = strings.Repeat("c", 64)
+		case "mode":
+			foreign.Mode = "unknown"
+		}
+		if p.Stop(foreign) == nil {
+			t.Fatal("foreign supervisor accepted", field)
+		}
+	}
+	socket := filepath.Join(p.RunDir, "supervisor.sock")
+	old := socket + ".owned"
+	if err := os.Rename(socket, old); err != nil {
+		t.Fatal(err)
+	}
+	fake, err := net.ListenUnix("unix", &net.UnixAddr{Name: socket, Net: "unix"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chmod(socket, 0600); err != nil {
+		t.Fatal(err)
+	}
+	if p.Stop(proc) == nil {
+		t.Fatal("other root PID substituted supervisor")
+	}
+	fake.Close()
+	if err := os.Rename(old, socket); err != nil {
+		t.Fatal(err)
+	}
+	if p.Status(context.Background()).State != "ready" {
+		t.Fatal("refusal stopped real helper")
+	}
+	if err := p.Stop(proc); err != nil {
+		t.Fatal(err)
+	}
+}
+func TestLinuxReparentedChildRefusesBeforeSocket(t *testing.T) {
+	p := linuxFixture(t)
+	record(t, p.Client, Record{Inventory: p.Expected, Enabled: true})
+	cmd := exec.Command(p.Binary, "serve-child")
+	cmd.Env = []string{"PATH=/usr/sbin:/usr/bin:/sbin:/bin", "SYNOPKGLAND_PARENT=1"}
+	if cmd.Run() == nil {
+		t.Fatal("already reparented child served")
+	}
+	if _, err := os.Stat(filepath.Join(p.RunDir, "helper.sock")); !os.IsNotExist(err) {
+		t.Fatal("unsafe child opened socket")
+	}
+}

package/templates/native-go/dsm-package.yaml

@@ -0,0 +1,58 @@
+# Standalone native DSM package: an unsigned SPK that runs as its own package
+# `synopkgland build-spk` reads this file.
+schema: 1
+
+# INFO.package: letters and digits, starting with a letter. It also names the
+# DSM app (SYNO.SDS.<package>) and the CGI URL /webman/3rdparty/<package>/.
+package: __PACKAGE__
+version: 0.1.0
+# Increase for every SPK you hand out with the same version (INFO 0.1.0-0001).
+build: 1
+displayname: __DISPLAY_NAME__
+description: A native DSM package with a Go backend and a DSM window UI.
+maintainer: Your Name
+os_min_ver: "7.2-64570"
+
+# One SPK per architecture. Supported: x86_64, aarch64.
+arches: [x86_64, aarch64]
+
+backend:
+  # Build the Go module in ./backend (package ./cmd/app) as the CGI.
+  go:
+    dir: backend
+    main: ./cmd/app
+  # Or ship a CGI executable you already have (remove `go:` above). Each file
+  # must be a static Linux ELF for its arch; it then owns authentication itself.
+  # binary:
+  #   x86_64: prebuilt/api-x86_64
+  #   aarch64: prebuilt/api-aarch64
+
+ui:
+  # Static files served at /webman/3rdparty/<package>/app/. app.js and app.css
+  # are required; anything else (images, chunks) is copied as is.
+  dir: ui
+
+# UI languages: i18n/messages/<locale>.json for en, zh-TW, zh-CN, ja, ko, de,
+# fr, es and it (DSM's other languages fall back to English). build-spk checks
+# that every language has the en.json keys and placeholders, and that the keys
+# listed in the glossary use Synology's own DSM wording.
+i18n:
+  messages: i18n/messages
+  glossary: i18n/glossary.json
+  # Package Center text per language (INFO displayname_<lang>/description_<lang>).
+  # English comes from displayname/description above.
+  info:
+    zh-TW: { description: 以 Go 後端與 DSM 視窗介面打造的原生 DSM 套件。 }
+    zh-CN: { description: 以 Go 后端与 DSM 窗口界面构建的原生 DSM 套件。 }
+    ja: { description: Go バックエンドと DSM ウィンドウ UI を備えたネイティブ DSM パッケージ。 }
+    ko: { description: Go 백엔드와 DSM 창 UI를 갖춘 네이티브 DSM 패키지. }
+    de: { description: Ein natives DSM-Paket mit Go-Backend und DSM-Fenster-Oberfläche. }
+    fr: { description: Un paquet DSM natif avec un backend Go et une interface en fenêtre DSM. }
+    es: { description: Un paquete nativo de DSM con backend en Go e interfaz en ventana de DSM. }
+    it: { description: Un pacchetto DSM nativo con backend Go e interfaccia in una finestra DSM. }
+
+# none: everything runs as the package account.
+# root: also fixed root operations, one root/<name>.sh each, that run only
+#       after a DSM administrator approves them in the package window.
+#       See README.md "Root access" before using it.
+privilege: __PRIVILEGE__

package/templates/native-go/gitignore

@@ -0,0 +1 @@
+dist/