fix(agent): unify agent and openresty runtime user as openflare

Introduce the shared openflare service account for the agent process and
OpenResty workers, normalize data_dir ownership on startup, and ensure
managed paths are chowned with 0755/0644 during sync and apply. Docker
entrypoint fixes volume ownership before dropping privileges; local systemd
install runs the service as openflare with CAP_NET_BIND_SERVICE.

internal/apps/agent/nginx/manager.go

@@ -25,6 +25,7 @@ import (
 	"github.com/Rain-kl/Wavelet/pkg/utils"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/agent/protocol"
+	"github.com/Rain-kl/Wavelet/internal/apps/agent/runtimeuser"
 )
 
 // RuntimeConfigDirPlaceholder is substituted into generated configs at apply time.
@@ -187,6 +188,7 @@ const (
 )
 
 const safeDefaultFallbackMainConfig = `# This file is generated by OpenFlare safe default fallback.
+user ` + OpenFlareRuntimeUser + `;
 worker_processes auto;
 pid logs/nginx.pid;
 
@@ -278,64 +280,32 @@ func (m *Manager) writeTargetFiles(mainConfig string, routeConfig string, suppor
 	return m.ensureOpenRestyWorkerReadAccess()
 }
 
-// ensureOpenRestyWorkerReadAccess makes runtime config and Lua paths traversable by the
-// unprivileged OpenResty worker user (typically nobody). Volume mounts may create parent
-// directories as 0700 root-owned; MkdirAll does not fix existing modes.
+// ensureOpenRestyWorkerReadAccess assigns runtime ownership and normalized modes
+// on agent-managed paths so the agent and OpenResty workers share access.
 func (m *Manager) ensureOpenRestyWorkerReadAccess() error {
 	targets := []string{
 		m.RuntimeConfigDir,
 		m.LuaDir,
+		m.PagesDir,
 		filepath.Dir(m.MainConfigPath),
 		filepath.Dir(m.RouteConfigPath),
 	}
 	if m.AccessLogPath != "" {
 		targets = append(targets, filepath.Dir(m.AccessLogPath))
 	}
+	seen := make(map[string]struct{}, len(targets))
 	for _, target := range targets {
-		if err := ensureWorldTraversablePath(target); err != nil {
-			return err
-		}
-	}
-	if strings.TrimSpace(m.RuntimeConfigDir) == "" {
-		return nil
-	}
-	entries, err := os.ReadDir(m.RuntimeConfigDir)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil
-		}
-		return err
-	}
-	for _, entry := range entries {
-		if entry.IsDir() {
+		cleaned := filepath.Clean(strings.TrimSpace(target))
+		if cleaned == "" || cleaned == "." {
 			continue
 		}
-		path := filepath.Join(m.RuntimeConfigDir, entry.Name())
-		if chmodErr := os.Chmod(path, nginxConfigFilePerm); chmodErr != nil && !os.IsNotExist(chmodErr) {
-			return chmodErr
+		if _, ok := seen[cleaned]; ok {
+			continue
 		}
-	}
-	return nil
-}
-
-func ensureWorldTraversablePath(targetDir string) error {
-	const maxDepth = 12
-	current := filepath.Clean(strings.TrimSpace(targetDir))
-	if current == "" || current == "." {
-		return nil
-	}
-	for depth := 0; depth < maxDepth; depth++ {
-		if err := os.Chmod(current, nginxDirPerm); err != nil {
-			if os.IsNotExist(err) || os.IsPermission(err) {
-				break
-			}
-			return fmt.Errorf("chmod %s: %w", current, err)
+		seen[cleaned] = struct{}{}
+		if err := runtimeuser.EnsurePathOwnership(cleaned, nginxDirPerm, nginxConfigFilePerm); err != nil {
+			return err
 		}
-		parent := filepath.Dir(current)
-		if parent == current {
-			break
-		}
-		current = parent
 	}
 	return nil
 }

internal/apps/agent/nginx/manager_test.go

@@ -979,8 +979,8 @@ func TestEnsureWorldTraversableChainFixesRestrictedParentDirs(t *testing.T) {
 		t.Fatalf("WriteFile failed: %v", err)
 	}
 
-	if err := ensureWorldTraversablePath(runtimeDir); err != nil {
-		t.Fatalf("ensureWorldTraversablePath failed: %v", err)
+	if err := EnsureWorldTraversablePath(runtimeDir); err != nil {
+		t.Fatalf("EnsureWorldTraversablePath failed: %v", err)
 	}
 
 	info, err := os.Stat(filepath.Join(dataDir, "etc"))

internal/apps/agent/nginx/runtime_access.go

@@ -0,0 +1,31 @@
+package nginx
+
+import (
+	openrestyrender "github.com/Rain-kl/Wavelet/pkg/render/openresty"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/agent/runtimeuser"
+)
+
+// OpenFlareRuntimeUser is the shared OS account for the agent process and
+// OpenResty worker processes.
+const OpenFlareRuntimeUser = openrestyrender.OpenFlareRuntimeUser
+
+// OpenRestyWorkerUser is an alias kept for internal call sites.
+const OpenRestyWorkerUser = OpenFlareRuntimeUser
+
+// EnsureWorldTraversablePath makes targetDir and its ancestors world-traversable.
+func EnsureWorldTraversablePath(targetDir string) error {
+	return runtimeuser.EnsurePathOwnership(targetDir, nginxDirPerm, nginxConfigFilePerm)
+}
+
+// EnsureWorkerReadableTree normalizes ownership and modes under root for the
+// shared runtime user.
+func EnsureWorkerReadableTree(rootDir string) error {
+	return runtimeuser.EnsurePathOwnership(rootDir, nginxDirPerm, nginxConfigFilePerm)
+}
+
+// EnsureWorkerReadAccess makes agent-managed runtime paths accessible to the
+// shared runtime user.
+func (m *Manager) EnsureWorkerReadAccess() error {
+	return m.ensureOpenRestyWorkerReadAccess()
+}

internal/apps/agent/nginx/runtime_access_test.go

@@ -0,0 +1,75 @@
+package nginx
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestEnsureWorkerReadableTreeFixesRestrictedPagesFiles(t *testing.T) {
+	tempDir := t.TempDir()
+	pagesDir := filepath.Join(tempDir, "data", "var", "lib", "openflare", "pages")
+	releaseDir := filepath.Join(pagesDir, "deployments", "1", "releases", "abc123")
+	if err := os.MkdirAll(releaseDir, 0o700); err != nil {
+		t.Fatalf("MkdirAll failed: %v", err)
+	}
+	indexPath := filepath.Join(releaseDir, "index.html")
+	if err := os.WriteFile(indexPath, []byte("<html></html>"), 0o600); err != nil {
+		t.Fatalf("WriteFile failed: %v", err)
+	}
+
+	if err := EnsureWorldTraversablePath(pagesDir); err != nil {
+		t.Fatalf("EnsureWorldTraversablePath failed: %v", err)
+	}
+	if err := EnsureWorkerReadableTree(pagesDir); err != nil {
+		t.Fatalf("EnsureWorkerReadableTree failed: %v", err)
+	}
+
+	info, err := os.Stat(indexPath)
+	if err != nil {
+		t.Fatalf("Stat failed: %v", err)
+	}
+	if info.Mode().Perm() != nginxConfigFilePerm {
+		t.Fatalf("expected index.html mode %o, got %o", nginxConfigFilePerm, info.Mode().Perm())
+	}
+	etcInfo, err := os.Stat(filepath.Join(tempDir, "data", "var"))
+	if err != nil {
+		t.Fatalf("Stat var failed: %v", err)
+	}
+	if etcInfo.Mode().Perm()&0o005 == 0 {
+		t.Fatalf("expected var directory to be world-traversable, got %o", etcInfo.Mode().Perm())
+	}
+}
+
+func TestManagerEnsureWorkerReadAccessIncludesPagesDir(t *testing.T) {
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "data")
+	pagesRoot := filepath.Join(dataDir, "var", "lib", "openflare", "pages")
+	releaseDir := filepath.Join(pagesRoot, "deployments", "1", "releases", "abc123")
+	if err := os.MkdirAll(releaseDir, 0o700); err != nil {
+		t.Fatalf("MkdirAll failed: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(releaseDir, "index.html"), []byte("ok"), 0o600); err != nil {
+		t.Fatalf("WriteFile failed: %v", err)
+	}
+
+	manager := &Manager{PagesDir: pagesRoot}
+	if err := manager.EnsureWorkerReadAccess(); err != nil {
+		t.Fatalf("EnsureWorkerReadAccess failed: %v", err)
+	}
+
+	info, err := os.Stat(filepath.Join(tempDir, "data"))
+	if err != nil {
+		t.Fatalf("Stat data failed: %v", err)
+	}
+	if info.Mode().Perm()&0o005 == 0 {
+		t.Fatalf("expected data directory to be world-traversable, got %o", info.Mode().Perm())
+	}
+	indexInfo, err := os.Stat(filepath.Join(releaseDir, "index.html"))
+	if err != nil {
+		t.Fatalf("Stat index failed: %v", err)
+	}
+	if indexInfo.Mode().Perm() != nginxConfigFilePerm {
+		t.Fatalf("expected index.html mode %o, got %o", nginxConfigFilePerm, indexInfo.Mode().Perm())
+	}
+}