@x47base/pocketbase-addon 0.1.0 → 0.2.0

package/hosting/blueprint.go

@@ -0,0 +1,242 @@
+package hosting
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+type Domain struct {
+	Host  string `json:"host"`
+	Store string `json:"store"`
+}
+type Blueprint struct {
+	Name            string   `json:"name"`
+	PocketBaseImage string   `json:"pocketbaseImage"`
+	VendureImage    string   `json:"vendureImage"`
+	GatewayImage    string   `json:"gatewayImage"`
+	PostgresImage   string   `json:"postgresImage"`
+	TLSImage        string   `json:"tlsImage"`
+	Email           string   `json:"email"`
+	Domains         []Domain `json:"domains"`
+	StorageClass    string   `json:"storageClass"`
+	IngressClass    string   `json:"ingressClass"`
+	Issuer          string   `json:"issuer"`
+	EgressCIDRs     []string `json:"egressCIDRs"`
+}
+
+func (b Blueprint) Validate() error {
+	if !dnsLabel(b.Name) {
+		return errors.New("DNS-label deployment name required")
+	}
+	for _, image := range []string{b.PocketBaseImage, b.VendureImage, b.GatewayImage, b.PostgresImage, b.TLSImage} {
+		if strings.ContainsAny(image, " \r\n\t\"'$") || !strings.Contains(image, ":") || strings.HasSuffix(image, ":latest") {
+			return errors.New("provide explicit versioned container images")
+		}
+	}
+	if b.Email == "" || strings.ContainsAny(b.Email, " \r\n{}") || len(b.Domains) < 1 || len(b.Domains) > 10000 {
+		return errors.New("email and verified domains required")
+	}
+	if !dnsHost(b.StorageClass) || !dnsHost(b.IngressClass) || !dnsHost(b.Issuer) {
+		return errors.New("storageClass, ingressClass and issuer names required")
+	}
+	seen := map[string]bool{}
+	for _, d := range b.Domains {
+		if !dnsHost(d.Host) || !strings.Contains(d.Host, ".") || net.ParseIP(d.Host) != nil || seen[d.Host] || !regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`).MatchString(d.Store) {
+			return errors.New("invalid domain/store route")
+		}
+		seen[d.Host] = true
+	}
+	for _, cidr := range b.EgressCIDRs {
+		if _, _, err := net.ParseCIDR(cidr); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+func (b Blueprint) Render(dir string) error {
+	if err := b.Validate(); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return err
+	}
+	write := func(name string, value any) error {
+		raw, err := json.MarshalIndent(value, "", "  ")
+		if err != nil {
+			return err
+		}
+		return os.WriteFile(filepath.Join(dir, name), append(raw, '\n'), 0600)
+	}
+	routes := []map[string]any{}
+	for _, d := range b.Domains {
+		routes = append(routes, map[string]any{"host": d.Host, "store": d.Store, "origin": "http://pocketbase:8090", "publicPaths": []string{"/api/commerce/stores/" + d.Store, "/api/commerce/stores/" + d.Store + "/offers"}})
+	}
+	if err := write("gateway.json", map[string]any{"tenants": routes, "allowHTTP": true, "cacheSeconds": 2, "maxConcurrent": 128, "maxBodyBytes": 2097152}); err != nil {
+		return err
+	}
+	if err := write("compose.json", b.compose()); err != nil {
+		return err
+	}
+	if err := write("kubernetes.json", map[string]any{"apiVersion": "v1", "kind": "List", "items": b.kubernetes()}); err != nil {
+		return err
+	}
+	caddy := "{\n email " + b.Email + "\n}\n"
+	for _, d := range b.Domains {
+		caddy += d.Host + " {\n reverse_proxy gateway:8095\n}\n"
+	}
+	if err := os.WriteFile(filepath.Join(dir, "Caddyfile"), []byte(caddy), 0600); err != nil {
+		return err
+	}
+	return write("dns-plan.json", map[string]any{"domains": b.Domains, "instructions": "Only export verified PocketBase domain records. Configure TXT ownership proof and A/AAAA/CNAME to your ingress. TLS is provisioned by Caddy (Docker) or cert-manager (Kubernetes). Cloudflare/Route53 changes must use the actual zone and target supplied by your operator."})
+}
+func (b Blueprint) compose() map[string]any {
+	hard := func(image string, networks []string) map[string]any {
+		return map[string]any{"image": image, "restart": "unless-stopped", "read_only": true, "cap_drop": []string{"ALL"}, "security_opt": []string{"no-new-privileges:true"}, "networks": networks, "tmpfs": []string{"/tmp:rw,noexec,nosuid,size=256m"}, "mem_limit": "1g", "cpus": 2}
+	}
+	gw := hard(b.GatewayImage, []string{"edge", "application"})
+	gw["volumes"] = []string{"./gateway.json:/config/gateway.json:ro"}
+	gw["user"] = "65532:65532"
+	pb := hard(b.PocketBaseImage, []string{"application", "backup_egress"})
+	pb["command"] = []string{"serve", "--http=0.0.0.0:8090", "--dir=/data"}
+	pb["volumes"] = []string{"pocketbase_data:/data", "./commerce.json:/config/commerce.json:ro", "./hosting.json:/config/hosting.json:ro", "./pb_migrations:/app/pb_migrations:ro"}
+	pb["env_file"] = []string{"./owner.env"}
+	pb["environment"] = map[string]string{"VENDURE_ADDON_CONFIG": "/config/commerce.json", "HOSTING_ADDON_CONFIG": "/config/hosting.json"}
+	pb["ports"] = []string{"127.0.0.1:8090:8090"}
+	pb["stop_grace_period"] = "60s"
+	vendure := hard(b.VendureImage, []string{"application", "data", "service_egress"})
+	vendure["env_file"] = []string{"./vendure.env"}
+	vendure["depends_on"] = map[string]any{"postgres": map[string]string{"condition": "service_healthy"}}
+	postgres := map[string]any{"image": b.PostgresImage, "restart": "unless-stopped", "env_file": []string{"./postgres.env"}, "volumes": []string{"postgres_data:/var/lib/postgresql"}, "networks": []string{"data"}, "healthcheck": map[string]any{"test": []string{"CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"}, "interval": "10s", "timeout": "5s", "retries": 10}, "mem_limit": "2g", "cpus": 2}
+	tls := map[string]any{"image": b.TLSImage, "restart": "unless-stopped", "ports": []string{"80:80", "443:443", "443:443/udp"}, "volumes": []string{"./Caddyfile:/etc/caddy/Caddyfile:ro", "tls_data:/data", "tls_config:/config"}, "networks": []string{"edge"}, "security_opt": []string{"no-new-privileges:true"}, "mem_limit": "512m", "cpus": 1}
+	return map[string]any{"name": b.Name, "services": map[string]any{"tls": tls, "gateway": gw, "pocketbase": pb, "vendure": vendure, "postgres": postgres}, "networks": map[string]any{"edge": map[string]any{}, "application": map[string]bool{"internal": true}, "data": map[string]bool{"internal": true}, "backup_egress": map[string]any{}, "service_egress": map[string]any{}}, "volumes": map[string]any{"pocketbase_data": map[string]any{}, "postgres_data": map[string]any{}, "tls_data": map[string]any{}, "tls_config": map[string]any{}}}
+}
+func (b Blueprint) kubernetes() []any {
+	namespace := map[string]any{"apiVersion": "v1", "kind": "Namespace", "metadata": map[string]any{"name": b.Name, "labels": map[string]string{"pod-security.kubernetes.io/enforce": "restricted"}}}
+	resource := func(kind, name string, spec any) map[string]any {
+		return map[string]any{"apiVersion": "v1", "kind": kind, "metadata": map[string]any{"name": name, "namespace": b.Name}, "spec": spec}
+	}
+	items := []any{namespace}
+	for _, name := range []string{"pocketbase", "postgres"} {
+		pvc := resource("PersistentVolumeClaim", name+"-data", map[string]any{"accessModes": []string{"ReadWriteOncePod"}, "storageClassName": b.StorageClass, "resources": map[string]any{"requests": map[string]string{"storage": "20Gi"}}})
+		items = append(items, pvc)
+	}
+	ports := map[string]int{"gateway": 8095, "pocketbase": 8090, "vendure": 3000, "postgres": 5432}
+	images := map[string]string{"gateway": b.GatewayImage, "pocketbase": b.PocketBaseImage, "vendure": b.VendureImage, "postgres": b.PostgresImage}
+	for _, name := range []string{"gateway", "pocketbase", "vendure", "postgres"} {
+		replicas := 1
+		if name == "gateway" {
+			replicas = 2
+		}
+		container := map[string]any{"name": name, "image": images[name], "ports": []any{map[string]any{"containerPort": ports[name]}}, "resources": map[string]any{"requests": map[string]string{"cpu": "100m", "memory": "256Mi"}, "limits": map[string]string{"cpu": "2", "memory": "2Gi"}}, "securityContext": map[string]any{"allowPrivilegeEscalation": false, "readOnlyRootFilesystem": true, "capabilities": map[string]any{"drop": []string{"ALL"}}}, "readinessProbe": map[string]any{"tcpSocket": map[string]int{"port": ports[name]}, "initialDelaySeconds": 10, "periodSeconds": 10}, "livenessProbe": map[string]any{"tcpSocket": map[string]int{"port": ports[name]}, "initialDelaySeconds": 60, "periodSeconds": 20}, "volumeMounts": []any{map[string]string{"name": "tmp", "mountPath": "/tmp"}}}
+		volumes := []any{map[string]any{"name": "tmp", "emptyDir": map[string]string{"sizeLimit": "256Mi"}}}
+		mounts := container["volumeMounts"].([]any)
+		if name == "pocketbase" || name == "postgres" {
+			mount := "/data"
+			if name == "postgres" {
+				mount = "/var/lib/postgresql"
+			}
+			mounts = append(mounts, map[string]string{"name": "data", "mountPath": mount})
+			volumes = append(volumes, map[string]any{"name": "data", "persistentVolumeClaim": map[string]string{"claimName": name + "-data"}})
+		}
+		if name == "gateway" || name == "pocketbase" {
+			mounts = append(mounts, map[string]any{"name": "config", "mountPath": "/config", "readOnly": true})
+			volumes = append(volumes, map[string]any{"name": "config", "configMap": map[string]string{"name": "commerce-config"}})
+		}
+		if name != "gateway" {
+			container["envFrom"] = []any{map[string]any{"secretRef": map[string]string{"name": name + "-env"}}}
+		}
+		if name == "pocketbase" {
+			container["args"] = []string{"serve", "--http=0.0.0.0:8090", "--dir=/data"}
+			container["env"] = []any{map[string]string{"name": "VENDURE_ADDON_CONFIG", "value": "/config/commerce.json"}, map[string]string{"name": "HOSTING_ADDON_CONFIG", "value": "/config/hosting.json"}}
+		}
+		if name == "postgres" {
+			mounts = append(mounts, map[string]string{"name": "postgres-run", "mountPath": "/var/run/postgresql"})
+			volumes = append(volumes, map[string]any{"name": "postgres-run", "emptyDir": map[string]string{"sizeLimit": "16Mi"}})
+		}
+		container["volumeMounts"] = mounts
+		pod := map[string]any{"automountServiceAccountToken": false, "securityContext": map[string]any{"runAsNonRoot": true, "runAsUser": 65532, "runAsGroup": 65532, "fsGroup": 65532, "seccompProfile": map[string]string{"type": "RuntimeDefault"}}, "containers": []any{container}, "volumes": volumes, "terminationGracePeriodSeconds": 60}
+		if name == "postgres" {
+			pod["securityContext"].(map[string]any)["runAsUser"] = 70
+			pod["securityContext"].(map[string]any)["runAsGroup"] = 70
+			pod["securityContext"].(map[string]any)["fsGroup"] = 70
+		}
+		d := resource("Deployment", name, map[string]any{"replicas": replicas, "strategy": map[string]string{"type": "Recreate"}, "selector": map[string]any{"matchLabels": map[string]string{"app": name}}, "template": map[string]any{"metadata": map[string]any{"labels": map[string]string{"app": name}}, "spec": pod}})
+		if name == "gateway" {
+			d["spec"].(map[string]any)["strategy"] = map[string]any{"type": "RollingUpdate", "rollingUpdate": map[string]int{"maxUnavailable": 1, "maxSurge": 1}}
+		}
+		if name == "gateway" || name == "pocketbase" {
+			path := "/healthz"
+			if name == "pocketbase" {
+				path = "/api/health"
+			}
+			container["readinessProbe"] = map[string]any{"httpGet": map[string]any{"path": path, "port": ports[name]}, "initialDelaySeconds": 5, "periodSeconds": 10}
+		}
+		d["apiVersion"] = "apps/v1"
+		items = append(items, d, resource("Service", name, map[string]any{"selector": map[string]string{"app": name}, "ports": []any{map[string]int{"port": ports[name], "targetPort": ports[name]}}}))
+	}
+	policy := func(name string, spec any) {
+		v := resource("NetworkPolicy", name, spec)
+		v["apiVersion"] = "networking.k8s.io/v1"
+		items = append(items, v)
+	}
+	policy("default-deny", map[string]any{"podSelector": map[string]any{}, "policyTypes": []string{"Ingress", "Egress"}})
+	// Both ends of each application connection are explicitly allowed.
+	for _, edge := range []struct {
+		from, to string
+		port     int
+	}{{"gateway", "pocketbase", 8090}, {"pocketbase", "vendure", 3000}, {"vendure", "postgres", 5432}} {
+		for _, direction := range []string{"ingress", "egress"} {
+			name, peer := edge.to, edge.from
+			selector := "from"
+			if direction == "egress" {
+				name, peer = edge.from, edge.to
+				selector = "to"
+			}
+			policy(name+"-"+direction+"-"+peer, map[string]any{"podSelector": map[string]any{"matchLabels": map[string]string{"app": name}}, direction: []any{map[string]any{selector: []any{map[string]any{"podSelector": map[string]any{"matchLabels": map[string]string{"app": peer}}}}, "ports": []any{map[string]any{"protocol": "TCP", "port": edge.port}}}}})
+		}
+	}
+	policy("cluster-dns", map[string]any{"podSelector": map[string]any{}, "egress": []any{map[string]any{"to": []any{map[string]any{"namespaceSelector": map[string]any{"matchLabels": map[string]string{"kubernetes.io/metadata.name": "kube-system"}}}}, "ports": []any{map[string]any{"protocol": "UDP", "port": 53}, map[string]any{"protocol": "TCP", "port": 53}}}}})
+	policy("ingress-to-gateway", map[string]any{"podSelector": map[string]any{"matchLabels": map[string]string{"app": "gateway"}}, "ingress": []any{map[string]any{"from": []any{map[string]any{"namespaceSelector": map[string]any{"matchLabels": map[string]string{"x47-ingress": "true"}}}}, "ports": []any{map[string]any{"protocol": "TCP", "port": 8095}}}}})
+	if len(b.EgressCIDRs) > 0 {
+		destinations := []any{}
+		for _, cidr := range b.EgressCIDRs {
+			destinations = append(destinations, map[string]any{"ipBlock": map[string]string{"cidr": cidr}})
+		}
+		policy("configured-https-egress", map[string]any{"podSelector": map[string]any{"matchExpressions": []any{map[string]any{"key": "app", "operator": "In", "values": []string{"pocketbase", "vendure"}}}}, "egress": []any{map[string]any{"to": destinations, "ports": []any{map[string]any{"protocol": "TCP", "port": 443}}}}})
+	}
+	pdb := resource("PodDisruptionBudget", "gateway", map[string]any{"minAvailable": 1, "selector": map[string]any{"matchLabels": map[string]string{"app": "gateway"}}})
+	pdb["apiVersion"] = "policy/v1"
+	items = append(items, pdb)
+	rules := []any{}
+	tls := []any{}
+	for i, d := range b.Domains {
+		rules = append(rules, map[string]any{"host": d.Host, "http": map[string]any{"paths": []any{map[string]any{"path": "/", "pathType": "Prefix", "backend": map[string]any{"service": map[string]any{"name": "gateway", "port": map[string]int{"number": 8095}}}}}}})
+		tls = append(tls, map[string]any{"hosts": []string{d.Host}, "secretName": fmt.Sprintf("store-tls-%d", i)})
+	}
+	ingress := resource("Ingress", "stores", map[string]any{"ingressClassName": b.IngressClass, "rules": rules, "tls": tls})
+	ingress["apiVersion"] = "networking.k8s.io/v1"
+	ingress["metadata"].(map[string]any)["annotations"] = map[string]string{"cert-manager.io/cluster-issuer": b.Issuer}
+	items = append(items, ingress)
+	return items
+}
+
+func dnsLabel(s string) bool {
+	return len(s) <= 63 && regexp.MustCompile(`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`).MatchString(s)
+}
+func dnsHost(s string) bool {
+	if s == "" || len(s) > 253 {
+		return false
+	}
+	for _, part := range strings.Split(s, ".") {
+		if !dnsLabel(part) {
+			return false
+		}
+	}
+	return true
+}

package/hosting/blueprint_test.go

@@ -0,0 +1,98 @@
+package hosting
+
+import (
+	"encoding/json"
+	"github.com/spink-dev/pocketbase-extension/multinode"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func testBlueprint() Blueprint {
+	return Blueprint{Name: "commerce", PocketBaseImage: "example/pocketbase:1.0.0", VendureImage: "example/vendure:1.0.0", GatewayImage: "example/gateway:1.0.0", PostgresImage: "postgres:18.6-alpine", TLSImage: "caddy:2.10.2-alpine", Email: "admin@example.com", Domains: []Domain{{Host: "team.example.com", Store: "team"}}, StorageClass: "standard", IngressClass: "nginx", Issuer: "letsencrypt", EgressCIDRs: []string{"203.0.113.0/24"}}
+}
+func TestRenderPrivateOriginsAndSingleWriter(t *testing.T) {
+	b := testBlueprint()
+	dir := t.TempDir()
+	if err := b.Render(dir); err != nil {
+		t.Fatal(err)
+	}
+	var compose map[string]any
+	raw, _ := os.ReadFile(filepath.Join(dir, "compose.json"))
+	json.Unmarshal(raw, &compose)
+	services := compose["services"].(map[string]any)
+	if _, ok := services["postgres"].(map[string]any)["ports"]; ok {
+		t.Fatal("public database")
+	}
+	if _, ok := services["vendure"].(map[string]any)["ports"]; ok {
+		t.Fatal("public Vendure origin")
+	}
+	pb := services["pocketbase"].(map[string]any)
+	if pb["ports"].([]any)[0] != "127.0.0.1:8090:8090" {
+		t.Fatal("public management")
+	}
+	var kube struct{ Items []map[string]any }
+	raw, _ = os.ReadFile(filepath.Join(dir, "kubernetes.json"))
+	json.Unmarshal(raw, &kube)
+	deny, pdb := false, false
+	for _, v := range kube.Items {
+		meta := v["metadata"].(map[string]any)
+		if v["kind"] == "NetworkPolicy" && meta["name"] == "default-deny" {
+			deny = true
+		}
+		if v["kind"] == "PodDisruptionBudget" {
+			pdb = true
+		}
+		if v["kind"] == "Deployment" && meta["name"] == "pocketbase" {
+			spec := v["spec"].(map[string]any)
+			if spec["replicas"] != float64(1) || spec["strategy"].(map[string]any)["type"] != "Recreate" {
+				t.Fatal("unsafe SQLite deployment")
+			}
+		}
+	}
+	if !deny || !pdb {
+		t.Fatal("missing networking or disruption protection")
+	}
+}
+func TestBlueprintRejectsConfigInjection(t *testing.T) {
+	for _, host := range []string{"*.example.com", "example.com\n}", "example.com/path", "user@example.com"} {
+		b := testBlueprint()
+		b.Domains[0].Host = host
+		if b.Validate() == nil {
+			t.Fatal(host)
+		}
+	}
+	b := testBlueprint()
+	b.PocketBaseImage = "example:latest"
+	if b.Validate() == nil {
+		t.Fatal("mutable image accepted")
+	}
+}
+
+func TestRenderedRoutesMatchGatewayContract(t *testing.T) {
+	b := testBlueprint()
+	b.Domains[0].Store = strings.Repeat("a", 64)
+	dir := t.TempDir()
+	if err := b.Render(dir); err != nil {
+		t.Fatal(err)
+	}
+	f, err := os.Open(filepath.Join(dir, "gateway.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	c, err := multinode.Load(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g, err := multinode.New(c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer g.CloseIdleConnections()
+	b.Domains[0].Store += "a"
+	if b.Validate() == nil {
+		t.Fatal("renderer accepted store rejected by gateway")
+	}
+}

package/hosting/config.go

@@ -0,0 +1,126 @@
+package hosting
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"github.com/pocketbase/pocketbase/core"
+	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+type Target struct {
+	Key          string `json:"key"`
+	Kind         string `json:"kind"`
+	Path         string `json:"path,omitempty"`
+	Bucket       string `json:"bucket,omitempty"`
+	Region       string `json:"region,omitempty"`
+	Endpoint     string `json:"endpoint,omitempty"`
+	AccessKeyEnv string `json:"accessKeyEnv,omitempty"`
+	SecretEnv    string `json:"secretEnv,omitempty"`
+	PathStyle    bool   `json:"pathStyle,omitempty"`
+}
+type Config struct {
+	Targets []Target `json:"targets"`
+}
+
+var keyPattern = regexp.MustCompile(`^[a-z][a-z0-9_-]{0,63}$`)
+var envPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]{0,127}$`)
+
+func (c Config) Validate() error {
+	seen := map[string]bool{}
+	if len(c.Targets) < 1 || len(c.Targets) > 32 {
+		return errors.New("configure 1-32 backup targets")
+	}
+	for _, t := range c.Targets {
+		if !keyPattern.MatchString(t.Key) || seen[t.Key] {
+			return errors.New("invalid or duplicate target key")
+		}
+		seen[t.Key] = true
+		switch t.Kind {
+		case "native":
+		case "local":
+			if !filepath.IsAbs(t.Path) {
+				return errors.New("local backup target must be absolute")
+			}
+		case "s3":
+			u, err := url.Parse(t.Endpoint)
+			if err != nil || u.Scheme != "https" || u.Hostname() == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" || t.Bucket == "" || t.Region == "" || !envPattern.MatchString(t.AccessKeyEnv) || !envPattern.MatchString(t.SecretEnv) {
+				return errors.New("S3 requires fixed HTTPS endpoint, bucket and credential environment references")
+			}
+		default:
+			return errors.New("unknown backup target kind")
+		}
+	}
+	return nil
+}
+func Load(path string) (Config, error) {
+	var c Config
+	f, err := os.Open(path)
+	if err != nil {
+		return c, err
+	}
+	defer f.Close()
+	raw, err := io.ReadAll(io.LimitReader(f, 65537))
+	if err != nil || len(raw) > 65536 {
+		return c, errors.New("invalid hosting configuration")
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	if err = decoder.Decode(&c); err != nil {
+		return c, err
+	}
+	if decoder.Decode(new(any)) != io.EOF {
+		return c, errors.New("unexpected trailing configuration")
+	}
+	return c, c.Validate()
+}
+
+// Resolve existing parents too, so a not-yet-created directory cannot hide a symlink.
+func resolvedPath(path string) (string, error) {
+	path, err := filepath.Abs(path)
+	if err != nil {
+		return "", err
+	}
+	resolved, err := filepath.EvalSymlinks(path)
+	if err == nil {
+		return resolved, nil
+	}
+	if !os.IsNotExist(err) {
+		return "", err
+	}
+	parent := filepath.Dir(path)
+	if parent == path {
+		return "", err
+	}
+	resolved, err = resolvedPath(parent)
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(resolved, filepath.Base(path)), nil
+}
+func validateLocalTarget(dataDir, target string) error {
+	data, err := resolvedPath(dataDir)
+	if err != nil {
+		return err
+	}
+	dest, err := resolvedPath(target)
+	if err != nil {
+		return err
+	}
+	rel, err := filepath.Rel(data, dest)
+	if err != nil {
+		return err
+	}
+	if rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
+		return nil
+	}
+	if rel == core.LocalBackupsDirName || strings.HasPrefix(rel, core.LocalBackupsDirName+string(os.PathSeparator)) {
+		return nil
+	}
+	return errors.New("local backup target must be outside pb_data or inside its excluded backups directory")
+}

package/hosting/deploy/dns.example.json

@@ -0,0 +1 @@
+{"provider":"cloudflare","zoneID":"00000000000000000000000000000000","tokenEnv":"CLOUDFLARE_DNS_TOKEN","records":[{"name":"_x47-store.team.example.com","type":"TXT","content":"x47=REPLACE_WITH_POCKETBASE_CHALLENGE","ttl":300},{"name":"team.example.com","type":"CNAME","content":"ingress.example.com","ttl":300}]}

package/hosting/docs/DEPLOYMENT.md

@@ -0,0 +1,98 @@
+# Docker and Kubernetes deployment
+
+## Application image contract
+
+Build versioned images before rendering. Use the standard PocketBase Go host plus the base, commerce and hosting registrations; include your own storefront endpoints, assets, business hooks and schema migrations. Do not deploy the local SQL.js/dummy-payment commerce fixture as a production Vendure image.
+
+| Image | Required behavior |
+|---|---|
+| PocketBase owner | Entrypoint is the Go binary; accepts `serve --http=0.0.0.0:8090 --dir=/data`. Register all three add-ons. Read `VENDURE_ADDON_CONFIG` and `HOSTING_ADDON_CONFIG`. Bind the custom-domain guard, keep management on the private origin, ship the application's storefront assets. Run as non-root with writable `/data` and `/tmp`. |
+| Vendure | Production Vendure server on port 3000, `shop-api` and `admin-api`; PostgreSQL configuration from environment. Register the commerce campaign and store-scope plugins, use the same store signing secret as the owner. Ship the dashboard and assets, run migrations deliberately before release. Run workers/queues for production jobs according to your Vendure application. |
+| Gateway | Combined package Dockerfile built with `--target gateway`; listens on 8095, reads `/config/gateway.json`, runs as UID 65532. |
+| PostgreSQL | Example targets the official PostgreSQL 18 Alpine layout, UID/GID 70 for Kubernetes, data below `/var/lib/postgresql`. Adapt security context and paths if replacing it with another image. |
+
+Use the base add-on's Go/JavaScript migration integration in your owner. Docker mounts `./pb_migrations` at `/app/pb_migrations`; the owner must explicitly register that directory. For Kubernetes, bake immutable migrations into the versioned image and configure their path there. Schema generation/synchronization is not automatically enabled. Back up before schema changes; do not auto-retry failed payment/order mutations.
+
+## Docker
+
+In `generated/`, provide:
+
+- `commerce.json`: real fixed Vendure Admin API URL `http://vendure:3000/admin-api`, configured channel aliases and credential environment references. Explicitly allow private HTTP inside this deployment. Set `domainTarget` to your ingress hostname. Never accept upstream URLs from the browser.
+- `hosting.json`: named backup targets, typically local `/data/backups/archives` plus encrypted S3.
+- `owner.env`: configured Vendure Admin credentials, store signing key and base backup encryption key. Do not place secrets directly in the blueprint.
+- `vendure.env`: database connection to `postgres:5432`, matching store secret and production application settings.
+- `postgres.env`: `POSTGRES_DB`, `POSTGRES_USER`, strong `POSTGRES_PASSWORD`; values must match Vendure's database configuration.
+- `pb_migrations/`: your versioned migrations.
+
+Environment key names other than the two add-on config paths and official PostgreSQL keys are your image's contract. Configure the same Vendure store-scope secret in both services. Register backup encryption through the base add-on's settings rather than merely setting a key and assuming encryption is enabled.
+
+Rendered files are private by default. Non-root containers need read permission on bind-mounted **nonsecret** gateway/commerce/hosting config files and Caddyfile. Set ownership for the container user or use `chmod 644 gateway.json commerce.json hosting.json Caddyfile` when they contain only public configuration/environment references. Keep `*.env` at mode 600. Ensure your image initializes named volume ownership for its runtime user; never make the database publicly writable.
+
+```sh
+cd generated
+docker compose -f compose.json config --quiet
+docker compose -f compose.json up -d
+```
+
+Only Caddy exposes public 80/443; management binds `127.0.0.1:8090`. PostgreSQL and Vendure publish no host ports. Use SSH tunneling for remote PocketBase management. For temporary Vendure dashboard access, run an explicitly loopback-bound service override or a private authenticated administration ingress; never put the generic Admin API behind a public shop hostname.
+
+Docker networks separate ingress, application, data, backup egress and Vendure service egress. Internal networks have no direct external routing. The two egress networks allow outbound access; they are **not destination allowlists**. Use host firewall rules or an egress proxy for destination restrictions. TLS termination and gateway body/concurrency limits reduce origin work but do not eliminate volumetric attacks against the network uplink.
+
+On route changes, bind-mounted files require care: atomic host file replacement may leave a running container on the old bind-mount inode. Recreate the gateway service after replacing `gateway.json`, or mount the config directory and send SIGHUP after validation. Native SIGHUP reload keeps the prior configuration if the replacement is invalid. Recreate/reload Caddy after changing its hostname list.
+
+## Kubernetes
+
+Use an existing cluster with an enforcing CNI, CSI storage supporting `ReadWriteOncePod`, an ingress controller and a configured cert-manager **DNS-01 ClusterIssuer**. The default-deny policy does not permit arbitrary HTTP-01 solver pods. The storage class and controller names in the blueprint must exist. Namespace labels alone do not install those components.
+
+Separate namespaces/projects should use separate rendered blueprints and secrets. Apply to a test namespace first. These example commands change cluster resources; run them only against the intended context:
+
+```sh
+kubectl config current-context
+kubectl apply --dry-run=client --validate=strict -f generated/kubernetes.json
+kubectl create namespace commerce --dry-run=client -o yaml | kubectl apply -f -
+kubectl -n commerce create secret generic pocketbase-env --from-env-file=generated/owner.env
+kubectl -n commerce create secret generic vendure-env --from-env-file=generated/vendure.env
+kubectl -n commerce create secret generic postgres-env --from-env-file=generated/postgres.env
+kubectl -n commerce create configmap commerce-config \
+  --from-file=generated/gateway.json --from-file=generated/commerce.json --from-file=generated/hosting.json
+# Label your actual ingress controller namespace, after reviewing its isolation.
+kubectl label namespace YOUR_INGRESS_NAMESPACE x47-ingress=true
+kubectl apply -f generated/kubernetes.json
+kubectl -n commerce rollout status deployment/gateway
+kubectl -n commerce rollout status deployment/pocketbase
+kubectl -n commerce port-forward service/pocketbase 8090:8090
+# In another terminal, for private Vendure administration:
+kubectl -n commerce port-forward service/vendure 19400:3000
+```
+
+Replace `commerce` with the blueprint's namespace. Update existing secrets/configmaps through your secret management/GitOps process, without committing secret values. Mounted configmap updates do not reload a running gateway by themselves: after the new mounted content is visible, roll out the gateway. Roll out the owner for changes to its static channel/target configuration. Never roll out more than one owner writer.
+
+The gateway uses two replicas and a disruption budget. PocketBase and PostgreSQL use one replica with Recreate and single-pod persistent access. This prevents intentionally scheduled concurrent writers, not arbitrary storage corruption or all split-brain scenarios. Planned owner/PostgreSQL restarts interrupt their availability. Add partitioning or separately designed database failover when required; do not simply increase replicas.
+
+```mermaid
+flowchart LR
+  clients[Shop clients] --> ingress[TLS ingress]
+  ingress --> gateway[Store-bound gateways]
+  gateway --> owner[One PocketBase writer per partition]
+  owner --> vendure[Vendure commerce service]
+  vendure --> postgres[PostgreSQL]
+  owner --> backups[Configured backup target]
+  operators[Private administration] --> owner
+  operators --> vendure
+```
+
+NetworkPolicy permits gateway→owner:8090, owner→Vendure:3000 and Vendure→PostgreSQL:5432, plus cluster DNS. Public ingress is permitted only from namespaces labeled `x47-ingress=true` to gateway:8095. Egress CIDRs allow owner/Vendure HTTPS to configured remote storage/payment services. An empty CIDR list disables that external HTTPS access. CIDRs do not follow changing DNS answers: maintain provider ranges or use an egress gateway/CNI FQDN policy. Node-local DNS and controller-specific health checks may require cluster-specific policies. There is no automatically public Vendure webhook endpoint; add a narrowly scoped, authenticated/verified application route for your payment provider.
+
+## Backup and restore operations
+
+1. In native PocketBase **Hosting**, create a paused policy and run a snapshot. Check its completed record and destination object. Enable the schedule only after verifying a recovery copy.
+2. Keep encryption keys separately from snapshots. A key on the same failed owner is not a recovery plan.
+3. Restore a copy in a disposable owner using the matching application/migrations. For alternate targets, securely retrieve the snapshot and upload/import it through the base add-on's supported backup recovery flow; the native PocketBase backup browser lists only its configured default target.
+4. Verify records, file attachments, store memberships, policies and authentication after restoration. Review restored schedules before reconnecting remote destinations to avoid unexpected retention deletions. Rotate copied credentials in a recovery environment.
+5. Back up PostgreSQL independently with your chosen PostgreSQL backup/WAL tooling and test its recovery. A PocketBase snapshot is not a cross-database atomic commerce snapshot. Reconcile application state across recovery points.
+
+## Provider interfaces and verification boundary
+
+DNS plans support explicit Cloudflare API creation and Route 53 `CREATE` batches. Cloudflare requires zone-scoped DNS Read/Edit; AWS should limit `route53:ChangeResourceRecordSets` to the intended hosted zone/record names. Provider apply was not exercised against a real account in this implementation. S3 plaintext rejection, local snapshot retention, application authorization, browser flows and generated manifest validation were exercised; actual S3 delivery, public ACME, cluster admission/scheduling and restore drills still require deployment-specific verification.
+
+Primary references: [Kubernetes network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/), [single-pod volume access](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-access-mode-readwriteoncepod/), [official PostgreSQL image](https://hub.docker.com/_/postgres), [Cloudflare DNS create](https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/create/), [AWS Route 53 CLI](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html), [Vercel Go request handlers](https://vercel.com/docs/functions/runtimes/go).

package/hosting/hosting.example.json

@@ -0,0 +1 @@
+{"targets":[{"key":"owner-default","kind":"native"},{"key":"local-archive","kind":"local","path":"/data/backups/archives"},{"key":"remote-s3","kind":"s3","bucket":"replace-me","region":"auto","endpoint":"https://account-id.r2.cloudflarestorage.com","accessKeyEnv":"BACKUP_ACCESS_KEY","secretEnv":"BACKUP_SECRET_KEY","pathStyle":false}]}

package/hosting/local_target_test.go

@@ -0,0 +1,29 @@
+package hosting
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLocalTargetCannotIncludeBackupsInNextSnapshot(t *testing.T) {
+	root := t.TempDir()
+	data := filepath.Join(root, "pb_data")
+	if err := os.MkdirAll(filepath.Join(data, "backups"), 0700); err != nil {
+		t.Fatal(err)
+	}
+	alias := filepath.Join(root, "alias")
+	if err := os.Symlink(data, alias); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range []string{data, filepath.Join(data, "archives"), filepath.Join(alias, "archives", "new")} {
+		if err := validateLocalTarget(data, path); err == nil {
+			t.Errorf("accepted recursive target %s", path)
+		}
+	}
+	for _, path := range []string{filepath.Join(root, "outside"), filepath.Join(data, "backups", "archives")} {
+		if err := validateLocalTarget(data, path); err != nil {
+			t.Fatal(err)
+		}
+	}
+}