feat: publish Tend v0.2 preview source

Publish the reviewed allowlisted snapshot whose exact binary completed maintenance deployment, rollback, and reactivation exercises for Gamertan and Sandwich Hime.

Private-Source-Commit: 4d7094c8b7c61991bfb67b11fc1558724c874eb2

Private-Source-Tree: 54a2f74804f7acddf3755d7d4da5b97f5fc28381

AI-Assistance: OpenAI Codex assisted implementation, testing, security review, and release verification.
Signed-off-by: Cole Speelman <crspeelman@gmail.com>

internal/config/config.go

@@ -9,13 +9,17 @@ import (
 	"fmt"
 	"io"
 	"net/netip"
+	"net/url"
 	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
 )
 
-const SchemaVersion = 1
+const (
+	SchemaVersion  = 2
+	SharedLockFile = "/run/lock/tend-deploy.lock"
+)
 
 var (
 	namePattern    = regexp.MustCompile(`^[a-z][a-z0-9-]{1,62}$`)
@@ -33,8 +37,9 @@ type Config struct {
 }
 
 type Service struct {
-	Name        string `json:"name"`
-	AllowedHost string `json:"allowed_host"`
+	Name            string `json:"name"`
+	AllowedHost     string `json:"allowed_host"`
+	EnvironmentFile string `json:"environment_file"`
 }
 
 type Build struct {
@@ -47,16 +52,17 @@ type Build struct {
 }
 
 type Deployment struct {
-	Strategy             string     `json:"strategy"`
-	Root                 string     `json:"root"`
-	LockFile             string     `json:"lock_file"`
-	StateFile            string     `json:"state_file"`
-	HealthPath           string     `json:"health_path"`
-	ReadinessPath        string     `json:"readiness_path"`
-	CandidateTimeoutSecs int        `json:"candidate_timeout_seconds"`
-	Smoke                []Smoke    `json:"smoke"`
-	BlueGreen            *BlueGreen `json:"blue_green,omitempty"`
-	Singleton            *Singleton `json:"singleton,omitempty"`
+	Strategy             string        `json:"strategy"`
+	Root                 string        `json:"root"`
+	LockFile             string        `json:"lock_file"`
+	StateFile            string        `json:"state_file"`
+	HealthPath           string        `json:"health_path"`
+	ReadinessPath        string        `json:"readiness_path"`
+	CandidateTimeoutSecs int           `json:"candidate_timeout_seconds"`
+	Smoke                []Smoke       `json:"smoke"`
+	PublicSmoke          []PublicSmoke `json:"public_smoke"`
+	BlueGreen            *BlueGreen    `json:"blue_green,omitempty"`
+	Singleton            *Singleton    `json:"singleton,omitempty"`
 }
 
 type Smoke struct {
@@ -64,6 +70,11 @@ type Smoke struct {
 	Contains string `json:"contains"`
 }
 
+type PublicSmoke struct {
+	URL      string `json:"url"`
+	Contains string `json:"contains"`
+}
+
 type BlueGreen struct {
 	CaddyConfig          string `json:"caddy_config"`
 	CaddyHandler         string `json:"caddy_handler"`
@@ -80,13 +91,12 @@ type Slot struct {
 }
 
 type Singleton struct {
-	Unit             string            `json:"unit"`
-	Address          string            `json:"address"`
-	CandidateAddress string            `json:"candidate_address"`
-	ListenEnv        string            `json:"listen_env"`
-	Environment      map[string]string `json:"environment,omitempty"`
-	CurrentLink      string            `json:"current_link"`
-	PreviousLink     string            `json:"previous_link"`
+	Unit             string `json:"unit"`
+	Address          string `json:"address"`
+	CandidateAddress string `json:"candidate_address"`
+	ListenEnv        string `json:"listen_env"`
+	CurrentLink      string `json:"current_link"`
+	PreviousLink     string `json:"previous_link"`
 }
 
 func Load(path string) (Config, error) {
@@ -140,6 +150,12 @@ func (c Config) Validate() error {
 	if c.Service.AllowedHost == "" || strings.ContainsAny(c.Service.AllowedHost, "/\\\x00\r\n\t ") {
 		return errors.New("service.allowed_host is invalid")
 	}
+	if err := safeAbsolute("service.environment_file", c.Service.EnvironmentFile); err != nil {
+		return err
+	}
+	if !within("/etc/tend/environment", c.Service.EnvironmentFile) {
+		return errors.New("service.environment_file must be below /etc/tend/environment")
+	}
 	if !packagePattern.MatchString(c.Build.Package) || strings.Contains(c.Build.Package, "..") {
 		return errors.New("build.package must be a local package without traversal")
 	}
@@ -185,6 +201,15 @@ func (c Config) Validate() error {
 			return fmt.Errorf("deployment.smoke[%d] is invalid", i)
 		}
 	}
+	if len(d.PublicSmoke) == 0 || len(d.PublicSmoke) > 16 {
+		return errors.New("deployment.public_smoke must contain 1 to 16 checks")
+	}
+	for i, smoke := range d.PublicSmoke {
+		parsed, err := url.Parse(smoke.URL)
+		if err != nil || parsed.Scheme != "https" || parsed.Host == "" || parsed.User != nil || parsed.Fragment != "" || parsed.RawQuery != "" || parsed.Opaque != "" || smoke.Contains == "" || len(smoke.Contains) > 4096 || strings.ContainsRune(smoke.Contains, '\x00') {
+			return fmt.Errorf("deployment.public_smoke[%d] is invalid", i)
+		}
+	}
 	switch d.Strategy {
 	case "blue_green":
 		if d.BlueGreen == nil || d.Singleton != nil {
@@ -273,11 +298,6 @@ func validateSingleton(root string, s Singleton) error {
 	if s.CurrentLink == s.PreviousLink {
 		return errors.New("current and previous links must differ")
 	}
-	for key, value := range s.Environment {
-		if !regexp.MustCompile(`^[A-Z][A-Z0-9_]{0,63}$`).MatchString(key) || strings.ContainsAny(value, "\x00\r\n") {
-			return fmt.Errorf("singleton environment entry %q is invalid", key)
-		}
-	}
 	return nil
 }
 

internal/config/config_test.go

@@ -9,13 +9,14 @@ import (
 
 func validConfig() Config {
 	return Config{
-		SchemaVersion: 1,
-		Service:       Service{Name: "example-site", AllowedHost: "example.test"},
+		SchemaVersion: 2,
+		Service:       Service{Name: "example-site", AllowedHost: "example.test", EnvironmentFile: "/etc/tend/environment/example-site.env"},
 		Build:         Build{Package: "./cmd/site", Binary: "example-site", Branch: "main"},
 		Deployment: Deployment{
-			Strategy: "blue_green", Root: "/opt/example-site", LockFile: "/run/lock/example-site.lock",
+			Strategy: "blue_green", Root: "/opt/example-site", LockFile: SharedLockFile,
 			StateFile: "/opt/example-site/state.json", HealthPath: "/healthz", ReadinessPath: "/readyz",
 			CandidateTimeoutSecs: 30, Smoke: []Smoke{{Path: "/", Contains: "Example"}},
+			PublicSmoke: []PublicSmoke{{URL: "https://example.test/", Contains: "Example"}},
 			BlueGreen: &BlueGreen{
 				CaddyConfig: "/etc/caddy/Caddyfile", CaddyHandler: "/etc/caddy/example.caddy",
 				CaddyHandlerTemplate: "/etc/example/caddy.template",
@@ -35,12 +36,15 @@ func TestValidateAcceptsBlueGreen(t *testing.T) {
 
 func TestValidateRejectsHostileValues(t *testing.T) {
 	tests := map[string]func(*Config){
-		"unknown strategy": func(c *Config) { c.Deployment.Strategy = "shell" },
-		"nonloopback":      func(c *Config) { c.Deployment.BlueGreen.Blue.Address = "203.0.113.7:80" },
-		"root path":        func(c *Config) { c.Deployment.Root = "/" },
-		"traversal":        func(c *Config) { c.Build.Package = "./cmd/../secret" },
-		"shared slot":      func(c *Config) { c.Deployment.BlueGreen.Green.Link = c.Deployment.BlueGreen.Blue.Link },
-		"bad smoke":        func(c *Config) { c.Deployment.Smoke[0].Path = "https://attacker.test/" },
+		"unknown strategy":    func(c *Config) { c.Deployment.Strategy = "shell" },
+		"nonloopback":         func(c *Config) { c.Deployment.BlueGreen.Blue.Address = "203.0.113.7:80" },
+		"root path":           func(c *Config) { c.Deployment.Root = "/" },
+		"traversal":           func(c *Config) { c.Build.Package = "./cmd/../secret" },
+		"shared slot":         func(c *Config) { c.Deployment.BlueGreen.Green.Link = c.Deployment.BlueGreen.Blue.Link },
+		"bad smoke":           func(c *Config) { c.Deployment.Smoke[0].Path = "https://attacker.test/" },
+		"bad public smoke":    func(c *Config) { c.Deployment.PublicSmoke[0].URL = "http://example.test/" },
+		"public secret query": func(c *Config) { c.Deployment.PublicSmoke[0].URL = "https://example.test/?token=secret" },
+		"environment sibling": func(c *Config) { c.Service.EnvironmentFile = "/etc/tend/environment-old/example.env" },
 	}
 	for name, mutate := range tests {
 		t.Run(name, func(t *testing.T) {

internal/deploy/deploy.go

@@ -177,6 +177,9 @@ func (m Manager) deployBlueGreen(ctx context.Context, cfg config.Config, record
 	if err = m.probeAll(ctx, cfg, slot.Address); err != nil {
 		return fmt.Errorf("post-activation smoke failed: %w", err)
 	}
+	if err = m.probePublic(ctx, cfg, true); err != nil {
+		return fmt.Errorf("public-origin smoke failed: %w", err)
+	}
 	next := state.Record{SchemaVersion: 1, Strategy: cfg.Deployment.Strategy, ActiveSlot: inactive, ActiveRelease: release, PreviousSlot: record.ActiveSlot, PreviousRelease: record.ActiveRelease, UpdatedAt: m.Now().UTC().Format(time.RFC3339)}
 	if err = state.Store(cfg.Deployment.StateFile, cfg.Deployment.Root, next); err != nil {
 		return err
@@ -187,10 +190,9 @@ func (m Manager) deployBlueGreen(ctx context.Context, cfg config.Config, record
 func (m Manager) deploySingleton(ctx context.Context, cfg config.Config, record state.Record, release string) (err error) {
 	single := *cfg.Deployment.Singleton
 	candidateUnit := cfg.Service.Name + "-tend-candidate.service"
-	env := copyMap(single.Environment)
-	env[single.ListenEnv] = single.CandidateAddress
+	env := map[string]string{single.ListenEnv: single.CandidateAddress}
 	binary := filepath.Join(release, cfg.Build.Binary)
-	if err = m.Operator.StartCandidate(ctx, candidateUnit, binary, env); err != nil {
+	if err = m.Operator.StartCandidate(ctx, candidateUnit, binary, cfg.Service.EnvironmentFile, env); err != nil {
 		return err
 	}
 	defer func() {
@@ -238,6 +240,9 @@ func (m Manager) deploySingleton(ctx context.Context, cfg config.Config, record
 	if err = m.probeAll(ctx, cfg, single.Address); err != nil {
 		return fmt.Errorf("post-activation smoke failed: %w", err)
 	}
+	if err = m.probePublic(ctx, cfg, true); err != nil {
+		return fmt.Errorf("public-origin smoke failed: %w", err)
+	}
 	next := state.Record{SchemaVersion: 1, Strategy: cfg.Deployment.Strategy, ActiveSlot: "singleton", ActiveRelease: release, PreviousSlot: "singleton", PreviousRelease: record.ActiveRelease, UpdatedAt: m.Now().UTC().Format(time.RFC3339)}
 	if err = state.Store(cfg.Deployment.StateFile, cfg.Deployment.Root, next); err != nil {
 		return err
@@ -313,6 +318,9 @@ func (m Manager) rollbackBlueGreen(ctx context.Context, cfg config.Config, recor
 	if err = m.probeHealthReadiness(ctx, cfg, slot.Address); err != nil {
 		return err
 	}
+	if err = m.probePublic(ctx, cfg, false); err != nil {
+		return err
+	}
 	next := state.Record{SchemaVersion: 1, Strategy: record.Strategy, ActiveSlot: record.PreviousSlot, ActiveRelease: record.PreviousRelease, PreviousSlot: record.ActiveSlot, PreviousRelease: record.ActiveRelease, UpdatedAt: m.Now().UTC().Format(time.RFC3339)}
 	return state.Store(cfg.Deployment.StateFile, cfg.Deployment.Root, next)
 }
@@ -337,6 +345,9 @@ func (m Manager) rollbackSingleton(ctx context.Context, cfg config.Config, recor
 	if err = m.probeHealthReadiness(ctx, cfg, single.Address); err != nil {
 		return err
 	}
+	if err = m.probePublic(ctx, cfg, false); err != nil {
+		return err
+	}
 	_ = replaceSymlink(single.PreviousLink, record.ActiveRelease)
 	next := state.Record{SchemaVersion: 1, Strategy: record.Strategy, ActiveSlot: "singleton", ActiveRelease: record.PreviousRelease, PreviousSlot: "singleton", PreviousRelease: record.ActiveRelease, UpdatedAt: m.Now().UTC().Format(time.RFC3339)}
 	return state.Store(cfg.Deployment.StateFile, cfg.Deployment.Root, next)
@@ -435,6 +446,23 @@ func (m Manager) probeHealthReadiness(ctx context.Context, cfg config.Config, ad
 	return m.probe(ctx, cfg, address, checks)
 }
 
+func (m Manager) probePublic(ctx context.Context, cfg config.Config, checkMarkers bool) error {
+	timeout := time.Duration(cfg.Deployment.CandidateTimeoutSecs) * time.Second
+	for _, check := range cfg.Deployment.PublicSmoke {
+		attempt, cancel := context.WithTimeout(ctx, timeout)
+		contains := check.Contains
+		if !checkMarkers {
+			contains = ""
+		}
+		err := m.Operator.ProbeURL(attempt, check.URL, contains)
+		cancel()
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func (m Manager) probe(ctx context.Context, cfg config.Config, address string, checks []config.Smoke) error {
 	timeout := time.Duration(cfg.Deployment.CandidateTimeoutSecs) * time.Second
 	for _, check := range checks {
@@ -465,13 +493,6 @@ func slotConfig(bg config.BlueGreen, name string) config.Slot {
 	}
 	return bg.Green
 }
-func copyMap(source map[string]string) map[string]string {
-	target := make(map[string]string, len(source)+1)
-	for k, v := range source {
-		target[k] = v
-	}
-	return target
-}
 func resolveReleaseLink(root, link string) (string, error) {
 	info, err := os.Lstat(link)
 	if err != nil {

internal/deploy/deploy_test.go

@@ -22,6 +22,10 @@ type fakeOperator struct {
 	active                  map[string]bool
 	starts, stops, restarts []string
 	probes                  []string
+	publicProbes            []string
+	failPublic              bool
+	candidateEnvironment    map[string]string
+	candidateFile           string
 }
 
 func (f *fakeOperator) Restart(_ context.Context, unit string) error {
@@ -40,14 +44,58 @@ func (f *fakeOperator) Stop(_ context.Context, unit string) error {
 func (f *fakeOperator) IsActive(_ context.Context, unit string) (bool, error) {
 	return f.active[unit], nil
 }
-func (f *fakeOperator) StartCandidate(_ context.Context, unit, binary string, env map[string]string) error {
-	if !filepath.IsAbs(binary) || len(env) == 0 {
+func (f *fakeOperator) StartCandidate(_ context.Context, unit, binary, environmentFile string, env map[string]string) error {
+	if !filepath.IsAbs(binary) || !filepath.IsAbs(environmentFile) || len(env) == 0 {
 		return errors.New("bad candidate")
 	}
 	f.starts = append(f.starts, unit)
+	f.candidateFile = environmentFile
+	f.candidateEnvironment = make(map[string]string, len(env))
+	for key, value := range env {
+		f.candidateEnvironment[key] = value
+	}
 	f.active[unit] = true
 	return nil
 }
+func (f *fakeOperator) ProbeURL(_ context.Context, value, contains string) error {
+	f.publicProbes = append(f.publicProbes, value)
+	if f.failPublic {
+		return errors.New("injected public smoke failure")
+	}
+	if f.rejectMarkers && contains != "" {
+		return errors.New("unexpected future-release smoke marker")
+	}
+	return nil
+}
+
+func TestPublicSmokeFailureRestoresBlueGreenHandlerAndSlot(t *testing.T) {
+	cfg, old, fresh := baseConfig(t, "blue_green")
+	handler := filepath.Join(cfg.Deployment.Root, "handler.caddy")
+	template := filepath.Join(cfg.Deployment.Root, "handler.template")
+	original := []byte("reverse_proxy 127.0.0.1:8090\n")
+	_ = os.WriteFile(handler, original, 0o644)
+	_ = os.WriteFile(template, []byte("reverse_proxy {{UPSTREAM}}\n"), 0o644)
+	blue := filepath.Join(cfg.Deployment.Root, "slots", "blue")
+	green := filepath.Join(cfg.Deployment.Root, "slots", "green")
+	_ = replaceSymlink(blue, old)
+	_ = replaceSymlink(green, old)
+	cfg.Deployment.BlueGreen = &config.BlueGreen{CaddyConfig: filepath.Join(cfg.Deployment.Root, "Caddyfile"), CaddyHandler: handler, CaddyHandlerTemplate: template, BootstrapActive: "blue", Blue: config.Slot{Unit: "example-blue.service", Address: "127.0.0.1:8090", Link: blue}, Green: config.Slot{Unit: "example-green.service", Address: "127.0.0.1:8091", Link: green}}
+	operator := &fakeOperator{active: map[string]bool{}, failPublic: true}
+	if _, err := manager(operator, fresh).Deploy(context.Background(), cfg, Request{Activate: true}); err == nil {
+		t.Fatal("expected public smoke failure")
+	}
+	body, _ := os.ReadFile(handler)
+	if string(body) != string(original) {
+		t.Fatalf("handler not restored: %q", body)
+	}
+	target, err := resolveReleaseLink(cfg.Deployment.Root, green)
+	if err != nil || target != old {
+		t.Fatalf("green=%q err=%v", target, err)
+	}
+	if _, err = os.Stat(cfg.Deployment.StateFile); !os.IsNotExist(err) {
+		t.Fatal("failed public smoke wrote state")
+	}
+}
 func (f *fakeOperator) ValidateCaddy(context.Context, string) error { return nil }
 func (f *fakeOperator) ReloadCaddy(context.Context) error {
 	if f.failReload {
@@ -79,7 +127,7 @@ func baseConfig(t *testing.T, strategy string) (config.Config, string, string) {
 			t.Fatal(err)
 		}
 	}
-	cfg := config.Config{SchemaVersion: 1, Service: config.Service{Name: "example-site", AllowedHost: "example.test"}, Build: config.Build{Package: "./cmd/site", Binary: "app", Branch: "main"}, Deployment: config.Deployment{Strategy: strategy, Root: root, LockFile: filepath.Join(root, "deploy.lock"), StateFile: filepath.Join(root, "state.json"), HealthPath: "/healthz", ReadinessPath: "/readyz", CandidateTimeoutSecs: 2, Smoke: []config.Smoke{{Path: "/", Contains: "Example"}}}}
+	cfg := config.Config{SchemaVersion: 2, Service: config.Service{Name: "example-site", AllowedHost: "example.test", EnvironmentFile: "/etc/tend/environment/example-site.env"}, Build: config.Build{Package: "./cmd/site", Binary: "app", Branch: "main"}, Deployment: config.Deployment{Strategy: strategy, Root: root, LockFile: filepath.Join(root, "deploy.lock"), StateFile: filepath.Join(root, "state.json"), HealthPath: "/healthz", ReadinessPath: "/readyz", CandidateTimeoutSecs: 2, Smoke: []config.Smoke{{Path: "/", Contains: "Example"}}, PublicSmoke: []config.PublicSmoke{{URL: "https://example.test/", Contains: "Example"}}}}
 	return cfg, old, fresh
 }
 func manager(operator Operator, fresh string) Manager {
@@ -210,4 +258,7 @@ func TestStatePersistsOnlyAfterSuccessfulActivation(t *testing.T) {
 	if record.ActiveRelease != fresh || record.PreviousRelease != old {
 		t.Fatalf("state=%+v", record)
 	}
+	if operator.candidateFile != cfg.Service.EnvironmentFile || len(operator.candidateEnvironment) != 1 || operator.candidateEnvironment["EXAMPLE_LISTEN"] != "127.0.0.1:18092" {
+		t.Fatalf("candidate file=%q environment=%#v", operator.candidateFile, operator.candidateEnvironment)
+	}
 }

internal/deploy/lock_linux_test.go

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+//go:build linux
+
+package deploy
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestHostWideLockSerializesIndependentServices(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "tend-deploy.lock")
+	first, err := acquireLock(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer first.Close()
+	if second, err := acquireLock(path); err == nil {
+		_ = second.Close()
+		t.Fatal("second service acquired the shared activation lock")
+	}
+	if err = first.Close(); err != nil {
+		t.Fatal(err)
+	}
+	third, err := acquireLock(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = third.Close()
+}

internal/deploy/operator.go

@@ -20,10 +20,11 @@ type Operator interface {
 	Restart(context.Context, string) error
 	Stop(context.Context, string) error
 	IsActive(context.Context, string) (bool, error)
-	StartCandidate(context.Context, string, string, map[string]string) error
+	StartCandidate(context.Context, string, string, string, map[string]string) error
 	ValidateCaddy(context.Context, string) error
 	ReloadCaddy(context.Context) error
 	Probe(context.Context, string, string, string, string) error
+	ProbeURL(context.Context, string, string) error
 }
 
 type SystemOperator struct {
@@ -49,7 +50,7 @@ func (o SystemOperator) IsActive(ctx context.Context, unit string) (bool, error)
 	}
 	return strings.TrimSpace(string(out)) == "active", nil
 }
-func (o SystemOperator) StartCandidate(ctx context.Context, unit, binary string, env map[string]string) error {
+func (o SystemOperator) StartCandidate(ctx context.Context, unit, binary, environmentFile string, env map[string]string) error {
 	args := []string{
 		"--unit", unit, "--collect",
 		"--property=DynamicUser=yes", "--property=NoNewPrivileges=yes",
@@ -63,6 +64,7 @@ func (o SystemOperator) StartCandidate(ctx context.Context, unit, binary string,
 		"--property=RestrictSUIDSGID=yes", "--property=LockPersonality=yes",
 		"--property=MemoryDenyWriteExecute=yes", "--property=CapabilityBoundingSet=",
 		"--property=AmbientCapabilities=",
+		"--property=EnvironmentFile=" + environmentFile,
 	}
 	keys := make([]string, 0, len(env))
 	for key := range env {
@@ -86,11 +88,23 @@ func (o SystemOperator) ReloadCaddy(ctx context.Context) error {
 }
 func (o SystemOperator) Probe(ctx context.Context, address, host, path, contains string) error {
 	u := url.URL{Scheme: "http", Host: address, Path: path}
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
+	return o.probeRequest(ctx, u.String(), host, contains)
+}
+func (o SystemOperator) ProbeURL(ctx context.Context, value, contains string) error {
+	u, err := url.Parse(value)
+	if err != nil || u.Scheme != "https" || u.Host == "" || u.User != nil || u.Fragment != "" {
+		return errors.New("public probe URL is invalid")
+	}
+	return o.probeRequest(ctx, u.String(), "", contains)
+}
+func (o SystemOperator) probeRequest(ctx context.Context, value, host, contains string) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, value, nil)
 	if err != nil {
 		return err
 	}
-	req.Host = host
+	if host != "" {
+		req.Host = host
+	}
 	client := &http.Client{Timeout: o.Timeout, CheckRedirect: func(*http.Request, []*http.Request) error { return errors.New("redirect refused") }}
 	response, err := client.Do(req)
 	if err != nil {

internal/deploy/operator_test.go

@@ -5,6 +5,7 @@ package deploy
 import (
 	"context"
 	"reflect"
+	"strings"
 	"testing"
 )
 
@@ -23,13 +24,13 @@ func TestStartCandidateUsesArgumentVectorAndHardenedUnit(t *testing.T) {
 	runner := &recordingRunner{}
 	operator := SystemOperator{Runner: runner}
 	env := map[string]string{"Z_ENV": "safe value", "A_ENV": "first"}
-	if err := operator.StartCandidate(context.Background(), "example-tend-candidate.service", "/opt/example/releases/sha256-a/app", env); err != nil {
+	if err := operator.StartCandidate(context.Background(), "example-tend-candidate.service", "/opt/example/releases/sha256-a/app", "/etc/tend/environment/example.env", env); err != nil {
 		t.Fatal(err)
 	}
 	if runner.name != "systemd-run" {
 		t.Fatalf("command=%q", runner.name)
 	}
-	required := []string{"--property=DynamicUser=yes", "--property=NoNewPrivileges=yes", "--property=ProtectSystem=strict", "--property=MemoryDenyWriteExecute=yes", "--property=CapabilityBoundingSet=", "--setenv", "A_ENV=first", "--setenv", "Z_ENV=safe value", "--", "/opt/example/releases/sha256-a/app"}
+	required := []string{"--property=DynamicUser=yes", "--property=NoNewPrivileges=yes", "--property=ProtectSystem=strict", "--property=MemoryDenyWriteExecute=yes", "--property=CapabilityBoundingSet=", "--property=EnvironmentFile=/etc/tend/environment/example.env", "--setenv", "A_ENV=first", "--setenv", "Z_ENV=safe value", "--", "/opt/example/releases/sha256-a/app"}
 	cursor := 0
 	for _, arg := range runner.args {
 		if cursor < len(required) && arg == required[cursor] {
@@ -42,4 +43,7 @@ func TestStartCandidateUsesArgumentVectorAndHardenedUnit(t *testing.T) {
 	if reflect.DeepEqual(runner.args, []string{"sh", "-c"}) {
 		t.Fatal("candidate command used a shell")
 	}
+	if strings.Contains(strings.Join(runner.args, "\n"), "SUPER_SECRET") {
+		t.Fatal("candidate arguments exposed a secret value")
+	}
 }

internal/serverpolicy/ownership_linux.go

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+//go:build linux
+
+package serverpolicy
+
+import (
+	"os"
+	"syscall"
+)
+
+func rootOwned(info os.FileInfo) bool {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	return ok && stat.Uid == 0
+}

internal/serverpolicy/ownership_other.go

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+//go:build !linux
+
+package serverpolicy
+
+import "os"
+
+func rootOwned(os.FileInfo) bool { return false }

internal/serverpolicy/policy.go

@@ -0,0 +1,300 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Package serverpolicy validates the root-owned allowlist used by Tend's
+// restricted SSH receiver. It contains service names and paths, never secrets.
+package serverpolicy
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"gamertan.com/tend/internal/config"
+)
+
+const SchemaVersion = 1
+
+var servicePattern = regexp.MustCompile(`^[a-z][a-z0-9-]{1,62}$`)
+
+type Policy struct {
+	SchemaVersion  int                      `json:"schema_version"`
+	ConfigRoot     string                   `json:"config_root"`
+	IncomingRoot   string                   `json:"incoming_root"`
+	SharedLockFile string                   `json:"shared_lock_file"`
+	Services       map[string]ServicePolicy `json:"services"`
+}
+
+type ServicePolicy struct {
+	Config           string `json:"config"`
+	MaxArtifactBytes int64  `json:"max_artifact_bytes"`
+}
+
+type CheckedService struct {
+	Name   string
+	Config config.Config
+	Policy ServicePolicy
+}
+
+func Parse(reader io.Reader) (Policy, error) {
+	limited := io.LimitReader(reader, 1<<20+1)
+	body, err := io.ReadAll(limited)
+	if err != nil {
+		return Policy{}, err
+	}
+	if len(body) > 1<<20 {
+		return Policy{}, errors.New("server policy exceeds 1 MiB")
+	}
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.DisallowUnknownFields()
+	var policy Policy
+	if err = decoder.Decode(&policy); err != nil {
+		return Policy{}, fmt.Errorf("decode server policy: %w", err)
+	}
+	var trailing any
+	if err = decoder.Decode(&trailing); !errors.Is(err, io.EOF) {
+		return Policy{}, errors.New("server policy contains trailing data")
+	}
+	if err = policy.Validate(); err != nil {
+		return Policy{}, err
+	}
+	return policy, nil
+}
+
+func Load(path string) (Policy, error) {
+	if err := secureDirectory(filepath.Dir(path), 0); err != nil {
+		return Policy{}, fmt.Errorf("server policy directory: %w", err)
+	}
+	if err := secureFile(path, 0o600); err != nil {
+		return Policy{}, fmt.Errorf("server policy: %w", err)
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return Policy{}, err
+	}
+	defer file.Close()
+	return Parse(file)
+}
+
+func (policy Policy) Validate() error {
+	if policy.SchemaVersion != SchemaVersion {
+		return fmt.Errorf("server policy schema_version must be %d", SchemaVersion)
+	}
+	if policy.ConfigRoot != "/etc/tend/services" {
+		return errors.New("server policy config_root must be /etc/tend/services")
+	}
+	if policy.IncomingRoot != "/var/lib/tend/incoming" {
+		return errors.New("server policy incoming_root must be /var/lib/tend/incoming")
+	}
+	if policy.SharedLockFile != config.SharedLockFile {
+		return fmt.Errorf("server policy shared_lock_file must be %s", config.SharedLockFile)
+	}
+	if len(policy.Services) == 0 || len(policy.Services) > 128 {
+		return errors.New("server policy must allow 1 to 128 services")
+	}
+	for name, service := range policy.Services {
+		if !servicePattern.MatchString(name) {
+			return fmt.Errorf("invalid service name %q", name)
+		}
+		expected := filepath.Join(policy.ConfigRoot, name+".json")
+		if service.Config != expected {
+			return fmt.Errorf("service %s config must be %s", name, expected)
+		}
+		if service.MaxArtifactBytes < 1<<20 || service.MaxArtifactBytes > 512<<20 {
+			return fmt.Errorf("service %s artifact limit is invalid", name)
+		}
+	}
+	return nil
+}
+
+func (policy Policy) CheckFiles() ([]CheckedService, error) {
+	if err := policy.CheckDirectories(); err != nil {
+		return nil, err
+	}
+	names := make([]string, 0, len(policy.Services))
+	for name := range policy.Services {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	checked := make([]CheckedService, 0, len(names))
+	for _, name := range names {
+		service, err := policy.CheckService(name)
+		if err != nil {
+			return nil, err
+		}
+		checked = append(checked, service)
+	}
+	return checked, nil
+}
+
+func (policy Policy) CheckDirectories() error {
+	if err := secureDirectory(policy.ConfigRoot, 0); err != nil {
+		return fmt.Errorf("config root: %w", err)
+	}
+	if err := secureDirectory(policy.IncomingRoot, 0o700); err != nil {
+		return fmt.Errorf("incoming root: %w", err)
+	}
+	if err := secureDirectory("/etc/tend/environment", 0o700); err != nil {
+		return fmt.Errorf("environment root: %w", err)
+	}
+	return nil
+}
+
+func (policy Policy) CheckService(name string) (CheckedService, error) {
+	entry, ok := policy.Services[name]
+	if !ok {
+		return CheckedService{}, errors.New("service is not allowed by server policy")
+	}
+	if err := secureFile(entry.Config, 0); err != nil {
+		return CheckedService{}, fmt.Errorf("service %s config: %w", name, err)
+	}
+	cfg, err := config.Load(entry.Config)
+	if err != nil {
+		return CheckedService{}, fmt.Errorf("service %s config: %w", name, err)
+	}
+	if cfg.Service.Name != name {
+		return CheckedService{}, fmt.Errorf("service %s config identity does not match", name)
+	}
+	if cfg.Deployment.LockFile != policy.SharedLockFile {
+		return CheckedService{}, fmt.Errorf("service %s does not use the host-wide lock", name)
+	}
+	if err = secureFile(cfg.Service.EnvironmentFile, 0o600); err != nil {
+		return CheckedService{}, fmt.Errorf("service %s environment file: %w", name, err)
+	}
+	if cfg.Deployment.Singleton != nil {
+		if err = rejectEnvironmentKey(cfg.Service.EnvironmentFile, cfg.Deployment.Singleton.ListenEnv); err != nil {
+			return CheckedService{}, fmt.Errorf("service %s environment file: %w", name, err)
+		}
+	}
+	return CheckedService{Name: name, Config: cfg, Policy: entry}, nil
+}
+
+func CheckConfig(path string, cfg config.Config) error {
+	expected := filepath.Join("/etc/tend/services", cfg.Service.Name+".json")
+	if path != expected {
+		return fmt.Errorf("production config must be %s", expected)
+	}
+	if err := secureDirectory("/etc/tend/services", 0); err != nil {
+		return fmt.Errorf("config root: %w", err)
+	}
+	if err := secureDirectory("/etc/tend/environment", 0o700); err != nil {
+		return fmt.Errorf("environment root: %w", err)
+	}
+	if err := secureFile(path, 0); err != nil {
+		return fmt.Errorf("production config: %w", err)
+	}
+	if cfg.Deployment.LockFile != config.SharedLockFile {
+		return fmt.Errorf("deployment lock must be %s", config.SharedLockFile)
+	}
+	if err := secureFile(cfg.Service.EnvironmentFile, 0o600); err != nil {
+		return fmt.Errorf("environment file: %w", err)
+	}
+	if cfg.Deployment.Singleton != nil {
+		if err := rejectEnvironmentKey(cfg.Service.EnvironmentFile, cfg.Deployment.Singleton.ListenEnv); err != nil {
+			return fmt.Errorf("environment file: %w", err)
+		}
+	}
+	return nil
+}
+
+func rejectEnvironmentKey(path, key string) error {
+	file, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+	body, err := io.ReadAll(io.LimitReader(file, 1<<20+1))
+	if err != nil {
+		return err
+	}
+	if len(body) > 1<<20 {
+		return errors.New("environment file exceeds 1 MiB")
+	}
+	for _, raw := range bytes.Split(body, []byte{'\n'}) {
+		line := strings.TrimSpace(string(raw))
+		if !strings.HasPrefix(line, key) {
+			continue
+		}
+		remainder := strings.TrimSpace(strings.TrimPrefix(line, key))
+		if strings.HasPrefix(remainder, "=") {
+			return errors.New("singleton candidate listen key must not be set in the shared environment file")
+		}
+	}
+	return nil
+}
+
+func secureFile(path string, exactMode os.FileMode) error {
+	if !filepath.IsAbs(path) || filepath.Clean(path) != path || strings.ContainsRune(path, '\x00') {
+		return errors.New("path must be clean and absolute")
+	}
+	if err := rejectSymlinkAncestors(filepath.Dir(path)); err != nil {
+		return err
+	}
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+		return errors.New("must be a regular non-symlink file")
+	}
+	if !rootOwned(info) {
+		return errors.New("must be owned by root")
+	}
+	if exactMode != 0 && info.Mode().Perm() != exactMode {
+		return fmt.Errorf("mode must be %04o", exactMode)
+	}
+	if exactMode == 0 && info.Mode().Perm()&0o022 != 0 {
+		return errors.New("must not be group- or world-writable")
+	}
+	return nil
+}
+
+func secureDirectory(path string, exactMode os.FileMode) error {
+	if !filepath.IsAbs(path) || filepath.Clean(path) != path || strings.ContainsRune(path, '\x00') {
+		return errors.New("path must be clean and absolute")
+	}
+	if err := rejectSymlinkAncestors(filepath.Dir(path)); err != nil {
+		return err
+	}
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		return errors.New("must be a real directory")
+	}
+	if !rootOwned(info) {
+		return errors.New("must be owned by root")
+	}
+	if exactMode != 0 && info.Mode().Perm() != exactMode {
+		return fmt.Errorf("mode must be %04o", exactMode)
+	}
+	if exactMode == 0 && info.Mode().Perm()&0o022 != 0 {
+		return errors.New("must not be group- or world-writable")
+	}
+	return nil
+}
+
+func rejectSymlinkAncestors(path string) error {
+	current := string(filepath.Separator)
+	for _, part := range strings.Split(strings.TrimPrefix(filepath.Clean(path), string(filepath.Separator)), string(filepath.Separator)) {
+		if part == "" {
+			continue
+		}
+		current = filepath.Join(current, part)
+		info, err := os.Lstat(current)
+		if err != nil {
+			return err
+		}
+		if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("symlink or non-directory ancestor refused: %s", current)
+		}
+	}
+	return nil
+}

internal/serverpolicy/policy_test.go

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+package serverpolicy
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParseAcceptsStrictServiceMap(t *testing.T) {
+	body := `{"schema_version":1,"config_root":"/etc/tend/services","incoming_root":"/var/lib/tend/incoming","shared_lock_file":"/run/lock/tend-deploy.lock","services":{"example-site":{"config":"/etc/tend/services/example-site.json","max_artifact_bytes":1048576}}}`
+	policy, err := Parse(strings.NewReader(body))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if policy.Services["example-site"].MaxArtifactBytes != 1<<20 {
+		t.Fatalf("policy=%+v", policy)
+	}
+}
+
+func TestRejectEnvironmentKeyProtectsSingletonCandidateOverride(t *testing.T) {
+	directory := t.TempDir()
+	path := filepath.Join(directory, "service.env")
+	for _, test := range []struct {
+		name    string
+		body    string
+		wantErr bool
+	}{
+		{name: "shared values only", body: "APP_SECRET=private\n"},
+		{name: "exact listen key", body: "EXAMPLE_LISTEN=127.0.0.1:8092\n", wantErr: true},
+		{name: "spaced listen key", body: "  EXAMPLE_LISTEN = 127.0.0.1:8092\n", wantErr: true},
+		{name: "commented listen key", body: "# EXAMPLE_LISTEN=127.0.0.1:8092\n"},
+		{name: "longer key", body: "EXAMPLE_LISTENER=safe\n"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			if err := os.WriteFile(path, []byte(test.body), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			err := rejectEnvironmentKey(path, "EXAMPLE_LISTEN")
+			if (err != nil) != test.wantErr {
+				t.Fatalf("error=%v wantErr=%v", err, test.wantErr)
+			}
+		})
+	}
+}
+
+func TestParseRejectsUnknownAndForgedPaths(t *testing.T) {
+	tests := []string{
+		`{"schema_version":1,"config_root":"/etc/tend/services","incoming_root":"/var/lib/tend/incoming","shared_lock_file":"/run/lock/tend-deploy.lock","services":{"example-site":{"config":"/tmp/example.json","max_artifact_bytes":1048576}}}`,
+		`{"schema_version":1,"config_root":"/etc/tend/services","incoming_root":"/var/lib/tend/incoming","shared_lock_file":"/run/lock/tend-deploy.lock","services":{},"surprise":true}`,
+	}
+	for _, body := range tests {
+		if _, err := Parse(strings.NewReader(body)); err == nil {
+			t.Fatalf("accepted %s", body)
+		}
+	}
+}

internal/transport/protocol.go

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Package transport implements Tend's bounded, versioned deployment stream.
+package transport
+
+import (
+	"bufio"
+	"bytes"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+)
+
+const (
+	Protocol         = "tend-receive-v1"
+	MaxArtifactBytes = 512 << 20
+	maxHeaderBytes   = 64 << 10
+	maxArtifactName  = 128
+)
+
+var (
+	servicePattern  = regexp.MustCompile(`^[a-z][a-z0-9-]{1,62}$`)
+	artifactPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`)
+)
+
+type Header struct {
+	Protocol       string `json:"protocol"`
+	Service        string `json:"service"`
+	ArtifactName   string `json:"artifact_name"`
+	Size           int64  `json:"size"`
+	SHA256         string `json:"sha256"`
+	ApprovedSHA256 string `json:"approved_sha256"`
+	Activate       bool   `json:"activate"`
+}
+
+func (h Header) Validate(maxBytes int64) error {
+	if h.Protocol != Protocol {
+		return errors.New("unsupported receive protocol")
+	}
+	if !servicePattern.MatchString(h.Service) {
+		return errors.New("invalid service name")
+	}
+	if len(h.ArtifactName) > maxArtifactName || !artifactPattern.MatchString(h.ArtifactName) {
+		return errors.New("invalid artifact name")
+	}
+	if h.Size <= 0 || h.Size > maxBytes {
+		return errors.New("artifact size exceeds policy")
+	}
+	if h.SHA256 != h.ApprovedSHA256 || len(h.SHA256) != 64 || strings.ToLower(h.SHA256) != h.SHA256 {
+		return errors.New("artifact digest was not explicitly approved")
+	}
+	if _, err := hex.DecodeString(h.SHA256); err != nil {
+		return errors.New("artifact digest is not hexadecimal")
+	}
+	return nil
+}
+
+func Prefix(header Header) ([]byte, error) {
+	if err := header.Validate(MaxArtifactBytes); err != nil {
+		return nil, err
+	}
+	body, err := json.Marshal(header)
+	if err != nil {
+		return nil, err
+	}
+	if len(body) > maxHeaderBytes {
+		return nil, errors.New("receive header exceeds limit")
+	}
+	prefix := make([]byte, 4+len(body))
+	binary.BigEndian.PutUint32(prefix[:4], uint32(len(body)))
+	copy(prefix[4:], body)
+	return prefix, nil
+}
+
+func ReadHeader(reader *bufio.Reader) (Header, error) {
+	var size [4]byte
+	if _, err := io.ReadFull(reader, size[:]); err != nil {
+		return Header{}, fmt.Errorf("read receive header length: %w", err)
+	}
+	length := binary.BigEndian.Uint32(size[:])
+	if length == 0 || length > maxHeaderBytes {
+		return Header{}, errors.New("receive header length is invalid")
+	}
+	body := make([]byte, length)
+	if _, err := io.ReadFull(reader, body); err != nil {
+		return Header{}, fmt.Errorf("read receive header: %w", err)
+	}
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.DisallowUnknownFields()
+	var header Header
+	if err := decoder.Decode(&header); err != nil {
+		return Header{}, fmt.Errorf("decode receive header: %w", err)
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) {
+		return Header{}, errors.New("receive header contains trailing data")
+	}
+	return header, nil
+}
+
+func CopyArtifact(destination io.Writer, reader *bufio.Reader, header Header, maxBytes int64) error {
+	if err := header.Validate(maxBytes); err != nil {
+		return err
+	}
+	hash := sha256.New()
+	written, err := io.CopyN(io.MultiWriter(destination, hash), reader, header.Size)
+	if err != nil || written != header.Size {
+		return errors.New("artifact stream ended before declared size")
+	}
+	if _, err = reader.ReadByte(); !errors.Is(err, io.EOF) {
+		return errors.New("artifact stream contains trailing bytes")
+	}
+	if hex.EncodeToString(hash.Sum(nil)) != header.SHA256 {
+		return errors.New("artifact stream digest does not match")
+	}
+	return nil
+}

internal/transport/protocol_test.go

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+package transport
+
+import (
+	"bufio"
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"strings"
+	"testing"
+)
+
+func validFrame(t *testing.T, artifact string) ([]byte, Header) {
+	t.Helper()
+	hash := sha256.Sum256([]byte(artifact))
+	digest := hex.EncodeToString(hash[:])
+	header := Header{Protocol: Protocol, Service: "example-site", ArtifactName: "example.tar.gz", Size: int64(len(artifact)), SHA256: digest, ApprovedSHA256: digest, Activate: true}
+	prefix, err := Prefix(header)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return append(prefix, artifact...), header
+}
+
+func TestProtocolRoundTrip(t *testing.T) {
+	frame, expected := validFrame(t, "artifact")
+	reader := bufio.NewReader(bytes.NewReader(frame))
+	header, err := ReadHeader(reader)
+	if err != nil || header != expected {
+		t.Fatalf("header=%+v err=%v", header, err)
+	}
+	var artifact bytes.Buffer
+	if err = CopyArtifact(&artifact, reader, header, 1<<20); err != nil {
+		t.Fatal(err)
+	}
+	if artifact.String() != "artifact" {
+		t.Fatalf("artifact=%q", artifact.String())
+	}
+}
+
+func TestProtocolRejectsTrailingAndForgedInputs(t *testing.T) {
+	frame, header := validFrame(t, "artifact")
+	reader := bufio.NewReader(bytes.NewReader(append(frame, 'x')))
+	read, _ := ReadHeader(reader)
+	if err := CopyArtifact(&bytes.Buffer{}, reader, read, 1<<20); err == nil {
+		t.Fatal("accepted trailing bytes")
+	}
+	header.Service = "../../root"
+	if _, err := Prefix(header); err == nil {
+		t.Fatal("accepted forged service")
+	}
+	header.Service = "example-site"
+	header.ApprovedSHA256 = strings.Repeat("0", 64)
+	if _, err := Prefix(header); err == nil {
+		t.Fatal("accepted unapproved digest")
+	}
+}
+
+func FuzzProtocolFraming(f *testing.F) {
+	hash := sha256.Sum256([]byte("artifact"))
+	digest := hex.EncodeToString(hash[:])
+	prefix, err := Prefix(Header{Protocol: Protocol, Service: "example-site", ArtifactName: "example.tar.gz", Size: 8, SHA256: digest, ApprovedSHA256: digest})
+	if err != nil {
+		f.Fatal(err)
+	}
+	frame := append(prefix, []byte("artifact")...)
+	f.Add(frame)
+	f.Add([]byte{0, 0, 0, 0})
+	f.Fuzz(func(t *testing.T, input []byte) {
+		if len(input) > 2<<20 {
+			t.Skip()
+		}
+		reader := bufio.NewReader(bytes.NewReader(input))
+		header, err := ReadHeader(reader)
+		if err != nil {
+			return
+		}
+		_ = CopyArtifact(&bytes.Buffer{}, reader, header, 1<<20)
+	})
+}

internal/transport/push.go

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+package transport
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+var targetPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]*@[A-Za-z0-9][A-Za-z0-9.-]*$`)
+
+type PushOptions struct {
+	Target         string
+	Port           int
+	KnownHosts     string
+	Identity       string
+	Service        string
+	Artifact       string
+	SHA256         string
+	ApprovedSHA256 string
+	Activate       bool
+}
+
+type SSHRunner interface {
+	Run(context.Context, string, []string, io.Reader) ([]byte, error)
+}
+
+type ExecSSHRunner struct{}
+
+func (ExecSSHRunner) Run(ctx context.Context, name string, args []string, stdin io.Reader) ([]byte, error) {
+	command := exec.CommandContext(ctx, name, args...)
+	command.Stdin = stdin
+	var output, diagnostic boundedBuffer
+	command.Stdout = &output
+	command.Stderr = &diagnostic
+	err := command.Run()
+	if err != nil {
+		return output.Bytes(), fmt.Errorf("ssh failed: %w: %s", err, strings.TrimSpace(diagnostic.String()))
+	}
+	return output.Bytes(), nil
+}
+
+type boundedBuffer struct{ bytes.Buffer }
+
+func (b *boundedBuffer) Write(value []byte) (int, error) {
+	written := len(value)
+	remaining := (1 << 20) - b.Len()
+	if remaining > 0 {
+		if len(value) > remaining {
+			value = value[:remaining]
+		}
+		_, _ = b.Buffer.Write(value)
+	}
+	return written, nil
+}
+
+func Push(ctx context.Context, runner SSHRunner, options PushOptions) (json.RawMessage, error) {
+	if !targetPattern.MatchString(options.Target) || strings.HasPrefix(options.Target, "-") {
+		return nil, errors.New("target must be user@host without shell syntax")
+	}
+	if options.Port < 1 || options.Port > 65535 {
+		return nil, errors.New("SSH port is invalid")
+	}
+	if err := safeClientFile(options.KnownHosts, false); err != nil {
+		return nil, fmt.Errorf("known-hosts file: %w", err)
+	}
+	if options.Identity != "" {
+		if err := safeClientFile(options.Identity, true); err != nil {
+			return nil, fmt.Errorf("identity file: %w", err)
+		}
+	}
+	if !filepath.IsAbs(options.Artifact) || filepath.Clean(options.Artifact) != options.Artifact || strings.ContainsAny(options.Artifact, "\x00\r\n\t") {
+		return nil, errors.New("artifact path must be clean and absolute")
+	}
+	artifactInfo, err := os.Lstat(options.Artifact)
+	if err != nil || !artifactInfo.Mode().IsRegular() || artifactInfo.Mode()&os.ModeSymlink != 0 || artifactInfo.Size() <= 0 || artifactInfo.Size() > MaxArtifactBytes {
+		return nil, errors.New("artifact must be a bounded regular non-symlink file")
+	}
+	artifact, err := os.Open(options.Artifact)
+	if err != nil {
+		return nil, err
+	}
+	defer artifact.Close()
+	info, err := artifact.Stat()
+	if err != nil || !info.Mode().IsRegular() || !os.SameFile(artifactInfo, info) {
+		return nil, errors.New("artifact must be a bounded regular file")
+	}
+	hash := sha256.New()
+	if _, err = io.Copy(hash, artifact); err != nil {
+		return nil, err
+	}
+	actual := hex.EncodeToString(hash.Sum(nil))
+	if actual != options.SHA256 || options.SHA256 != options.ApprovedSHA256 {
+		return nil, errors.New("artifact digest was not explicitly approved")
+	}
+	if _, err = artifact.Seek(0, io.SeekStart); err != nil {
+		return nil, err
+	}
+	header := Header{Protocol: Protocol, Service: options.Service, ArtifactName: filepath.Base(options.Artifact), Size: info.Size(), SHA256: options.SHA256, ApprovedSHA256: options.ApprovedSHA256, Activate: options.Activate}
+	prefix, err := Prefix(header)
+	if err != nil {
+		return nil, err
+	}
+	args := []string{"-F", os.DevNull, "-T", "-p", strconv.Itoa(options.Port), "-o", "BatchMode=yes", "-o", "ClearAllForwardings=yes", "-o", "ExitOnForwardFailure=yes", "-o", "ForwardAgent=no", "-o", "IdentitiesOnly=yes", "-o", "LogLevel=ERROR", "-o", "PermitLocalCommand=no", "-o", "ProxyCommand=none", "-o", "RequestTTY=no", "-o", "StrictHostKeyChecking=yes", "-o", "UserKnownHostsFile=" + options.KnownHosts}
+	if options.Identity != "" {
+		args = append(args, "-i", options.Identity)
+	}
+	args = append(args, options.Target, Protocol)
+	output, err := runner.Run(ctx, "ssh", args, io.MultiReader(bytes.NewReader(prefix), artifact))
+	if err != nil {
+		return nil, err
+	}
+	if !json.Valid(output) {
+		return nil, errors.New("receiver returned invalid JSON")
+	}
+	return json.RawMessage(output), nil
+}
+
+func safeClientFile(path string, private bool) error {
+	if !filepath.IsAbs(path) || filepath.Clean(path) != path || strings.ContainsAny(path, "\x00\r\n\t") {
+		return errors.New("path must be clean and absolute")
+	}
+	parent, err := os.Lstat(filepath.Dir(path))
+	if err != nil || !parent.IsDir() || parent.Mode()&os.ModeSymlink != 0 || parent.Mode().Perm()&0o022 != 0 {
+		return errors.New("parent must be a real directory not writable by group or others")
+	}
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+		return errors.New("must be a regular non-symlink file")
+	}
+	if info.Mode().Perm()&0o022 != 0 {
+		return errors.New("must not be group- or world-writable")
+	}
+	if private && info.Mode().Perm()&0o077 != 0 {
+		return errors.New("must not be accessible by group or others")
+	}
+	return nil
+}

internal/transport/push_test.go

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+package transport
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"os"
+	"path/filepath"
+	"slices"
+	"testing"
+)
+
+type captureRunner struct {
+	name  string
+	args  []string
+	input []byte
+	calls int
+}
+
+func (runner *captureRunner) Run(_ context.Context, name string, args []string, input io.Reader) ([]byte, error) {
+	runner.calls++
+	runner.name = name
+	runner.args = append([]string(nil), args...)
+	runner.input, _ = io.ReadAll(input)
+	return []byte(`{"validated":true,"mutation":"activated"}`), nil
+}
+
+func TestPushUsesPinnedSSHAndExactFrame(t *testing.T) {
+	dir := t.TempDir()
+	knownHosts := filepath.Join(dir, "known_hosts")
+	identity := filepath.Join(dir, "identity")
+	artifact := filepath.Join(dir, "release.tar.gz")
+	if err := os.WriteFile(knownHosts, []byte("host key\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(identity, []byte("private\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	content := []byte("artifact")
+	if err := os.WriteFile(artifact, content, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	hash := sha256.Sum256(content)
+	digest := hex.EncodeToString(hash[:])
+	runner := &captureRunner{}
+	result, err := Push(context.Background(), runner, PushOptions{Target: "tend-deploy@example.test", Port: 2222, KnownHosts: knownHosts, Identity: identity, Service: "example-site", Artifact: artifact, SHA256: digest, ApprovedSHA256: digest, Activate: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Contains(result, []byte(`"activated"`)) || runner.calls != 1 || runner.name != "ssh" {
+		t.Fatalf("result=%s calls=%d name=%q", result, runner.calls, runner.name)
+	}
+	if !slices.Contains(runner.args, "ProxyCommand=none") || !slices.Contains(runner.args, "StrictHostKeyChecking=yes") || runner.args[len(runner.args)-1] != Protocol {
+		t.Fatalf("args=%#v", runner.args)
+	}
+	reader := bufio.NewReader(bytes.NewReader(runner.input))
+	header, err := ReadHeader(reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var copied bytes.Buffer
+	if err = CopyArtifact(&copied, reader, header, 1<<20); err != nil {
+		t.Fatal(err)
+	}
+	if copied.String() != string(content) || header.Service != "example-site" || !header.Activate {
+		t.Fatalf("header=%+v body=%q", header, copied.String())
+	}
+}
+
+func TestPushRejectsShellTargetBeforeExecution(t *testing.T) {
+	runner := &captureRunner{}
+	_, err := Push(context.Background(), runner, PushOptions{Target: "root@example.test;touch", Port: 22})
+	if err == nil || runner.calls != 0 {
+		t.Fatalf("err=%v calls=%d", err, runner.calls)
+	}
+}

internal/transport/receive.go

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+package transport
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"os"
+
+	"gamertan.com/tend/internal/deploy"
+	"gamertan.com/tend/internal/serverpolicy"
+)
+
+func Receive(ctx context.Context, input io.Reader, policy serverpolicy.Policy, manager deploy.Manager) (deploy.Report, error) {
+	if err := policy.CheckDirectories(); err != nil {
+		return deploy.Report{}, err
+	}
+	reader := bufio.NewReaderSize(input, maxHeaderBytes+4)
+	header, err := ReadHeader(reader)
+	if err != nil {
+		return deploy.Report{}, err
+	}
+	service, err := policy.CheckService(header.Service)
+	if err != nil {
+		return deploy.Report{}, err
+	}
+	if err = header.Validate(service.Policy.MaxArtifactBytes); err != nil {
+		return deploy.Report{}, err
+	}
+	file, err := os.CreateTemp(policy.IncomingRoot, ".tend-receive-"+header.Service+"-")
+	if err != nil {
+		return deploy.Report{}, err
+	}
+	path := file.Name()
+	defer os.Remove(path)
+	if err = file.Chmod(0o600); err == nil {
+		err = CopyArtifact(file, reader, header, service.Policy.MaxArtifactBytes)
+	}
+	if closeErr := file.Close(); err == nil {
+		err = closeErr
+	}
+	if err != nil {
+		return deploy.Report{}, fmt.Errorf("receive artifact: %w", err)
+	}
+	return manager.Deploy(ctx, service.Config, deploy.Request{Artifact: path, SHA256: header.SHA256, ApprovedSHA256: header.ApprovedSHA256, Activate: header.Activate})
+}