From 8d6e7c0098eec10209f76b8ba34632b99ec76032 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 24 Aug 2026 16:12:38 +0800
Subject: [PATCH 1/4] HH-620: expose SSClash Web UI on port 9091

Co-authored-by: multica-agent <github@multica.ai>
---
 .env.example             |  2 ++
 Dockerfile               |  4 ++--
 README.md                |  8 ++++----
 compose.yaml             |  1 +
 tests/container-smoke.sh | 13 +++++++++----
 5 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/.env.example b/.env.example
index 5223a04..5864a2a 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,7 @@
 IMAGE_NAME=mohomo-docker:local
 CONTAINER_NAME=mohomo-docker
 SUBSCRIPTION_URL=https://subscription.example.invalid/mihomo
+WEB_BIND=0.0.0.0
+WEB_PORT=9091
 PROXY_BIND=0.0.0.0
 PROXY_PORT=7890
diff --git a/Dockerfile b/Dockerfile
index e1999ba..daa8e5d 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -77,12 +77,12 @@ COPY config/config.yaml /usr/local/share/ssclash/config.yaml
 ENV SSCLASH_ROOT=/opt/clash \
     SSCLASH_TMP=/tmp/ssclash \
     SSCLASH_PLATFORM=linux \
-    SSCLASH_ADDR=127.0.0.1:9091 \
+    SSCLASH_ADDR=0.0.0.0:9091 \
     SAFE_PATHS=/usr/local/share/ssclash
 
 USER ssclash
 VOLUME ["/opt/clash"]
-EXPOSE 7890/tcp 7890/udp
+EXPOSE 9091/tcp 7890/tcp 7890/udp
 HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=4 \
     CMD curl --fail --silent --show-error http://127.0.0.1:9090/version >/dev/null
 ENTRYPOINT ["/usr/local/bin/bootstrap"]
diff --git a/README.md b/README.md
index af6c30b..bb86bd3 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # mohomo-docker
 
-Minimal Mihomo service with the ACL4SSR `Online Full MultiMode` routing model. The host exposes only mixed proxy port `7890`; SSClash and Mihomo's controller remain loopback-only inside the container.
+Minimal Mihomo service with the ACL4SSR `Online Full MultiMode` routing model. The host exposes the SSClash Web UI on port `9091` and the mixed proxy on port `7890`; Mihomo's controller remains private to the container.
 
 ## Quick start
 
@@ -11,14 +11,14 @@ docker compose up -d --build
 docker compose logs -f ssclash
 ```
 
-The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. Clients connect to either endpoint:
+The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. Open `http://<server>:9091` to manage SSClash. Proxy clients connect to either endpoint:
 
 ```text
 HTTP proxy:   http://<server>:7890
 SOCKS5 proxy: socks5://<server>:7890
 ```
 
-`PROXY_BIND` and `PROXY_PORT` are optional deployment overrides. Configure Mihomo proxy authentication before publishing port `7890` outside a trusted network.
+`WEB_BIND`, `WEB_PORT`, `PROXY_BIND`, and `PROXY_PORT` are optional deployment overrides; both services bind all host interfaces by default. Set the SSClash administrator password and place the Web UI behind HTTPS and additional access control before exposing it to the Internet. Configure Mihomo proxy authentication before publishing port `7890` outside a trusted network.
 
 ## Update and secret handling
 
@@ -55,7 +55,7 @@ The GitHub Actions workflow builds `linux/amd64`, runs tests first, publishes on
 ./tests/container-smoke.sh
 ```
 
-The unit suite checks atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test builds the image, validates the generated configuration, checks that only port `7890` is published, and verifies that the subscription credential is neither persisted nor logged.
+The unit suite checks atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test builds the image, validates the generated configuration, reaches the Web UI through its published port, checks that only ports `7890` and `9091` are published, and verifies that the subscription credential is neither persisted nor logged.
 
 ## License boundary
 
diff --git a/compose.yaml b/compose.yaml
index 78c8631..b6b80e5 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -9,6 +9,7 @@ services:
     environment:
       SUBSCRIPTION_URL: ${SUBSCRIPTION_URL:?set SUBSCRIPTION_URL in .env}
     ports:
+      - "${WEB_BIND:-0.0.0.0}:${WEB_PORT:-9091}:9091/tcp"
       - "${PROXY_BIND:-0.0.0.0}:${PROXY_PORT:-7890}:7890/tcp"
       - "${PROXY_BIND:-0.0.0.0}:${PROXY_PORT:-7890}:7890/udp"
     volumes:
diff --git a/tests/container-smoke.sh b/tests/container-smoke.sh
index 64fbee0..5f3cd6e 100755
--- a/tests/container-smoke.sh
+++ b/tests/container-smoke.sh
@@ -67,6 +67,7 @@ docker run --detach \
 	--volume "$volume:/opt/clash" \
 	--publish 127.0.0.1::7890/tcp \
 	--publish 127.0.0.1::7890/udp \
+	--publish 127.0.0.1::9091/tcp \
 	"$image" >/dev/null
 
 attempt=0
@@ -81,11 +82,15 @@ until [ "$(docker inspect --format '{{.State.Health.Status}}' "$container")" = h
 done
 
 published=$(docker port "$container")
-printf '%s\n' "$published" | grep -E '^7890/(tcp|udp)' >/dev/null
-if printf '%s\n' "$published" | grep -vE '^7890/(tcp|udp)' >/dev/null; then
-	echo "container published a port other than 7890" >&2
+for port in 7890/tcp 7890/udp 9091/tcp; do
+	printf '%s\n' "$published" | grep -F "$port ->" >/dev/null
+done
+if printf '%s\n' "$published" | grep -vE '^(7890/(tcp|udp)|9091/tcp)' >/dev/null; then
+	echo "container published a port other than 7890 or 9091" >&2
 	exit 1
 fi
+web_port=$(docker port "$container" 9091/tcp | awk -F: 'NR == 1 { print $NF }')
+curl --fail --silent --show-error "http://127.0.0.1:${web_port}/" >/dev/null
 
 docker exec "$container" grep -Fx 'OPERATING_MODE=server' /opt/clash/.ssclash/settings >/dev/null
 docker exec "$container" grep -Fx 'PROXY_MODE=none' /opt/clash/.ssclash/settings >/dev/null
@@ -104,4 +109,4 @@ if docker logs "$container" 2>&1 | grep -F "$secret" >/dev/null; then
 	exit 1
 fi
 
-echo "container smoke test passed: only port 7890 published; subscription credential not persisted or logged"
+echo "container smoke test passed: only ports 7890 and 9091 published; subscription credential not persisted or logged"
-- 
2.54.0


From ab0f9d3eec5ffee3cd06f3d3ba2b6a2db2316827 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 24 Aug 2026 16:44:55 +0800
Subject: [PATCH 2/4] HH-620: require authentication before exposing setup

Co-authored-by: multica-agent <github@multica.ai>
---
 .env.example                         |  1 +
 README.md                            | 13 ++---
 cmd/bootstrap/main.go                |  7 ++-
 compose.yaml                         |  1 +
 internal/bootstrap/bootstrap.go      | 67 +++++++++++++++++++++--
 internal/bootstrap/bootstrap_test.go | 62 ++++++++++++++++++++++
 tests/container-smoke.sh             | 79 ++++++++++++++++++++++++++--
 7 files changed, 215 insertions(+), 15 deletions(-)

diff --git a/.env.example b/.env.example
index 5864a2a..1607977 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,7 @@
 IMAGE_NAME=mohomo-docker:local
 CONTAINER_NAME=mohomo-docker
 SUBSCRIPTION_URL=https://subscription.example.invalid/mihomo
+SSCLASH_PASSWORD=
 WEB_BIND=0.0.0.0
 WEB_PORT=9091
 PROXY_BIND=0.0.0.0
diff --git a/README.md b/README.md
index bb86bd3..c6e3623 100644
--- a/README.md
+++ b/README.md
@@ -6,27 +6,28 @@ Minimal Mihomo service with the ACL4SSR `Online Full MultiMode` routing model. T
 
 ```sh
 cp .env.example .env
-# Replace only SUBSCRIPTION_URL in .env.
+# Generate a password, then set SUBSCRIPTION_URL and SSCLASH_PASSWORD in .env.
+openssl rand -base64 24
 docker compose up -d --build
 docker compose logs -f ssclash
 ```
 
-The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. Open `http://<server>:9091` to manage SSClash. Proxy clients connect to either endpoint:
+The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. A fresh volume refuses to start without an `SSCLASH_PASSWORD` of at least 12 characters; bootstrap uses SSClash's own `setpass` command before the Web listener starts. Open `http://<server>:9091` and log in with that password. Existing authentication files are preserved, so later starts do not require or replace the password. Proxy clients connect to either endpoint:
 
 ```text
 HTTP proxy:   http://<server>:7890
 SOCKS5 proxy: socks5://<server>:7890
 ```
 
-`WEB_BIND`, `WEB_PORT`, `PROXY_BIND`, and `PROXY_PORT` are optional deployment overrides; both services bind all host interfaces by default. Set the SSClash administrator password and place the Web UI behind HTTPS and additional access control before exposing it to the Internet. Configure Mihomo proxy authentication before publishing port `7890` outside a trusted network.
+`WEB_BIND`, `WEB_PORT`, `PROXY_BIND`, and `PROXY_PORT` are optional deployment overrides; both services bind all host interfaces by default. Authentication prevents anonymous first-run setup, but the Web UI still serves plain HTTP: place it behind HTTPS and additional access control before exposing it to the Internet. Configure Mihomo proxy authentication before publishing port `7890` outside a trusted network.
 
 ## Update and secret handling
 
 The bootstrap fetches the subscription once before startup and every hour thereafter. Each candidate is limited to 16 MiB and validated with the packaged Mihomo binary before an atomic replacement and hot reload. A failed reload restores and reloads the previous provider; if that recovery cannot be confirmed, both services stop instead of running with uncertain state.
 
-The subscription URL is read from `SUBSCRIPTION_URL`, removed from child-process environments, and never printed. The generated configuration contains only a local provider path. Subscription data lives under `/dev/shm/mohomo`, so neither the image nor the `/opt/clash` volume stores its URL, response, or node credentials. Container restarts intentionally fetch a fresh subscription instead of persisting credentials.
+The subscription URL and bootstrap administrator password are removed from child-process environments and never printed. The password is persisted only as SSClash's PBKDF2 authentication file. The generated configuration contains only a local provider path. Subscription data lives under `/dev/shm/mohomo`, so neither the image nor the `/opt/clash` volume stores its URL, response, or node credentials. Container restarts intentionally fetch a fresh subscription instead of persisting credentials.
 
-Do not commit `.env`; it is ignored by Git. Docker still exposes container environment variables to principals allowed to inspect the container, so restrict Docker daemon access.
+Do not commit `.env`; it is ignored by Git. Docker still exposes bootstrap environment variables to principals allowed to inspect the container, so restrict Docker daemon access.
 
 ## ACL4SSR rules
 
@@ -55,7 +56,7 @@ The GitHub Actions workflow builds `linux/amd64`, runs tests first, publishes on
 ./tests/container-smoke.sh
 ```
 
-The unit suite checks atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test builds the image, validates the generated configuration, reaches the Web UI through its published port, checks that only ports `7890` and `9091` are published, and verifies that the subscription credential is neither persisted nor logged.
+The unit suite checks fail-closed authentication initialization, atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test verifies that a fresh volume without an administrator password never starts the Web UI, then logs in through published port `9091`, checks the exact `7890`/`9091` port set, and confirms that plaintext credentials are neither persisted nor logged.
 
 ## License boundary
 
diff --git a/cmd/bootstrap/main.go b/cmd/bootstrap/main.go
index ee63424..9a2eb88 100644
--- a/cmd/bootstrap/main.go
+++ b/cmd/bootstrap/main.go
@@ -33,12 +33,17 @@ func main() {
 	if err != nil {
 		log.Fatalf("bootstrap: runtime preparation failed: %v", err)
 	}
+	adminPasswordInitialized, err := bootstrap.EnsureAdminPassword(root, ssclashBinary, os.Getenv("SSCLASH_PASSWORD"))
+	if err != nil {
+		log.Fatalf("bootstrap: admin authentication setup failed: %v", err)
+	}
 	log.Printf(
-		"bootstrap: ready root=%s core_initialized=%t config_initialized=%t server_settings_changed=%t",
+		"bootstrap: ready root=%s core_initialized=%t config_initialized=%t server_settings_changed=%t admin_password_initialized=%t",
 		root,
 		result.CoreInitialized,
 		result.ConfigInitialized,
 		result.ServerSettingsChanged,
+		adminPasswordInitialized,
 	)
 
 	subscriptionURL := os.Getenv("SUBSCRIPTION_URL")
diff --git a/compose.yaml b/compose.yaml
index b6b80e5..ca4f3e2 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -8,6 +8,7 @@ services:
     init: true
     environment:
       SUBSCRIPTION_URL: ${SUBSCRIPTION_URL:?set SUBSCRIPTION_URL in .env}
+      SSCLASH_PASSWORD: ${SSCLASH_PASSWORD:-}
     ports:
       - "${WEB_BIND:-0.0.0.0}:${WEB_PORT:-9091}:9091/tcp"
       - "${PROXY_BIND:-0.0.0.0}:${PROXY_PORT:-7890}:7890/tcp"
diff --git a/internal/bootstrap/bootstrap.go b/internal/bootstrap/bootstrap.go
index f6fdac3..80b0fbc 100644
--- a/internal/bootstrap/bootstrap.go
+++ b/internal/bootstrap/bootstrap.go
@@ -16,7 +16,10 @@ import (
 	"time"
 )
 
-const maxSubscriptionSize = 16 << 20
+const (
+	maxSubscriptionSize    = 16 << 20
+	minAdminPasswordLength = 12
+)
 
 var errMihomoStateUncertain = errors.New("Mihomo subscription state could not be restored")
 
@@ -101,6 +104,63 @@ func Prepare(config Config) (Result, error) {
 	return result, nil
 }
 
+func EnsureAdminPassword(root, binary, password string) (bool, error) {
+	root = filepath.Clean(root)
+	if root == "." || root == string(filepath.Separator) || !filepath.IsAbs(root) {
+		return false, fmt.Errorf("unsafe root %q", root)
+	}
+	passwordPath := filepath.Join(root, ".ssclash", "password")
+	configured, err := adminPasswordConfigured(passwordPath)
+	if err != nil {
+		return false, err
+	}
+	if configured {
+		return false, nil
+	}
+	if password == "" {
+		return false, errors.New("SSCLASH_PASSWORD is required to initialize a fresh volume")
+	}
+	if len(password) < minAdminPasswordLength {
+		return false, fmt.Errorf("SSCLASH_PASSWORD must be at least %d characters", minAdminPasswordLength)
+	}
+	if err := validateSource(binary, "SSClash binary"); err != nil {
+		return false, err
+	}
+
+	command := exec.Command(binary, "setpass", password)
+	command.Env = childEnvironment()
+	command.Stdout = io.Discard
+	command.Stderr = io.Discard
+	if err := command.Run(); err != nil {
+		return false, errors.New("SSClash password initialization failed")
+	}
+	configured, err = adminPasswordConfigured(passwordPath)
+	if err != nil {
+		return false, err
+	}
+	if !configured {
+		return false, errors.New("SSClash password initialization did not create an authentication file")
+	}
+	return true, nil
+}
+
+func adminPasswordConfigured(path string) (bool, error) {
+	info, err := os.Lstat(path)
+	if errors.Is(err, os.ErrNotExist) {
+		return false, nil
+	}
+	if err != nil {
+		return false, fmt.Errorf("inspect SSClash authentication file: %w", err)
+	}
+	if !info.Mode().IsRegular() || info.Size() == 0 {
+		return false, errors.New("SSClash authentication file must be a non-empty regular file")
+	}
+	if info.Mode().Perm()&0o077 != 0 {
+		return false, fmt.Errorf("SSClash authentication file permissions are %o; want 600", info.Mode().Perm())
+	}
+	return true, nil
+}
+
 func Run(ctx context.Context, config RuntimeConfig) error {
 	if err := validateSubscriptionURL(config.SubscriptionURL); err != nil {
 		return err
@@ -336,9 +396,10 @@ func childEnvironment() []string {
 	environment := os.Environ()
 	result := environment[:0]
 	for _, entry := range environment {
-		if !strings.HasPrefix(entry, "SUBSCRIPTION_URL=") {
-			result = append(result, entry)
+		if strings.HasPrefix(entry, "SUBSCRIPTION_URL=") || strings.HasPrefix(entry, "SSCLASH_PASSWORD=") {
+			continue
 		}
+		result = append(result, entry)
 	}
 	return result
 }
diff --git a/internal/bootstrap/bootstrap_test.go b/internal/bootstrap/bootstrap_test.go
index e5aab69..ab5b30e 100644
--- a/internal/bootstrap/bootstrap_test.go
+++ b/internal/bootstrap/bootstrap_test.go
@@ -90,6 +90,68 @@ func TestPreparePreservesUserDataAndForcesServerMode(t *testing.T) {
 	assertFileContent(t, filepath.Join(root, ".ssclash", "settings"), "LOG_LEVEL=debug\nOPERATING_MODE=server\nPROXY_MODE=none\n")
 }
 
+func TestEnsureAdminPasswordFailsClosedOnFreshVolume(t *testing.T) {
+	t.Parallel()
+
+	_, err := EnsureAdminPassword(t.TempDir(), "unused", "")
+	if err == nil || !strings.Contains(err.Error(), "SSCLASH_PASSWORD") {
+		t.Fatalf("EnsureAdminPassword() error = %v, want missing password error", err)
+	}
+}
+
+func TestEnsureAdminPasswordInitializesOnlyWhenMissing(t *testing.T) {
+	t.Parallel()
+
+	root := filepath.Join(t.TempDir(), "data")
+	if err := os.MkdirAll(filepath.Join(root, ".ssclash"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	binary := writeFixture(t, filepath.Join(root, "bin"), "ssclash", `#!/bin/sh
+set -eu
+[ "$1" = setpass ]
+[ "$2" = fresh-volume-password ]
+password="$(dirname "$0")/../.ssclash/password"
+printf 'pbkdf2$test\n' > "$password"
+chmod 0600 "$password"
+`)
+	if err := os.Chmod(binary, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	initialized, err := EnsureAdminPassword(root, binary, "fresh-volume-password")
+	if err != nil {
+		t.Fatalf("EnsureAdminPassword() error = %v", err)
+	}
+	if !initialized {
+		t.Fatal("EnsureAdminPassword() initialized = false, want true")
+	}
+	assertFileContent(t, filepath.Join(root, ".ssclash", "password"), "pbkdf2$test\n")
+
+	if err := os.Remove(binary); err != nil {
+		t.Fatal(err)
+	}
+	initialized, err = EnsureAdminPassword(root, binary, "replacement-password")
+	if err != nil {
+		t.Fatalf("EnsureAdminPassword() existing password error = %v", err)
+	}
+	if initialized {
+		t.Fatal("EnsureAdminPassword() replaced existing password")
+	}
+	assertFileContent(t, filepath.Join(root, ".ssclash", "password"), "pbkdf2$test\n")
+}
+
+func TestChildEnvironmentRemovesCredentials(t *testing.T) {
+	t.Setenv("SUBSCRIPTION_URL", "https://subscription.example.invalid/?token=secret")
+	t.Setenv("SSCLASH_PASSWORD", "secret-password")
+
+	environment := strings.Join(childEnvironment(), "\n")
+	for _, key := range []string{"SUBSCRIPTION_URL=", "SSCLASH_PASSWORD="} {
+		if strings.Contains(environment, key) {
+			t.Errorf("childEnvironment() retained %s", key)
+		}
+	}
+}
+
 func TestPrepareRejectsUnsafeOrAmbiguousState(t *testing.T) {
 	t.Parallel()
 
diff --git a/tests/container-smoke.sh b/tests/container-smoke.sh
index 5f3cd6e..e686d4a 100755
--- a/tests/container-smoke.sh
+++ b/tests/container-smoke.sh
@@ -4,22 +4,26 @@ set -eu
 image=${1:-mohomo-docker:smoke}
 suffix="$$"
 container="mohomo-docker-smoke-${suffix}"
+unconfigured="mohomo-docker-unconfigured-${suffix}"
 provider="mohomo-provider-smoke-${suffix}"
 network="mohomo-network-smoke-${suffix}"
 volume="mohomo-volume-smoke-${suffix}"
 provider_dir=""
+cookie=""
 secret="container-smoke-secret"
+admin_password="container-smoke-admin-password"
 
-case "$container:$provider:$network:$volume" in
-mohomo-docker-smoke-*':mohomo-provider-smoke-'*':mohomo-network-smoke-'*':mohomo-volume-smoke-'*) ;;
+case "$container:$unconfigured:$provider:$network:$volume" in
+mohomo-docker-smoke-*':mohomo-docker-unconfigured-'*':mohomo-provider-smoke-'*':mohomo-network-smoke-'*':mohomo-volume-smoke-'*) ;;
 *) echo "refusing unsafe cleanup targets" >&2; exit 1 ;;
 esac
 
 cleanup() {
-	docker container rm --force "$container" "$provider" >/dev/null 2>&1 || true
+	docker container rm --force "$container" "$unconfigured" "$provider" >/dev/null 2>&1 || true
 	docker volume rm "$volume" >/dev/null 2>&1 || true
 	docker network rm "$network" >/dev/null 2>&1 || true
 	[ -z "$provider_dir" ] || rm -rf "$provider_dir"
+	[ -z "$cookie" ] || rm -f "$cookie"
 }
 trap cleanup EXIT INT TERM
 
@@ -58,12 +62,49 @@ until docker exec "$provider" wget -qO- http://127.0.0.1:8080/provider.yaml >/de
 	fi
 	sleep 1
 done
+
+docker run --detach \
+	--name "$unconfigured" \
+	--network "$network" \
+	--cap-drop ALL \
+	--security-opt no-new-privileges:true \
+	--env "SUBSCRIPTION_URL=http://${provider}:8080/provider.yaml" \
+	--volume "$volume:/opt/clash" \
+	--publish 127.0.0.1::9091/tcp \
+	"$image" >/dev/null
+unconfigured_port=$(docker port "$unconfigured" 9091/tcp | awk -F: 'NR == 1 { print $NF }')
+attempt=0
+while [ "$(docker inspect --format '{{.State.Running}}' "$unconfigured")" = true ]; do
+	if curl --fail --silent --show-error --max-time 1 \
+		"http://127.0.0.1:${unconfigured_port}/setup" >/dev/null 2>&1; then
+		echo "fresh volume exposed anonymous setup" >&2
+		exit 1
+	fi
+	attempt=$((attempt + 1))
+	if [ "$attempt" -ge 10 ]; then
+		echo "fresh volume did not fail closed without SSCLASH_PASSWORD" >&2
+		exit 1
+	fi
+	sleep 1
+done
+if [ "$(docker inspect --format '{{.State.ExitCode}}' "$unconfigured")" -eq 0 ]; then
+	echo "fresh volume exited successfully without SSCLASH_PASSWORD" >&2
+	exit 1
+fi
+docker logs "$unconfigured" 2>&1 | grep -F 'SSCLASH_PASSWORD is required' >/dev/null
+if docker logs "$unconfigured" 2>&1 | grep -F 'web UI listening' >/dev/null; then
+	echo "fresh volume started the Web UI before authentication was configured" >&2
+	exit 1
+fi
+docker container rm "$unconfigured" >/dev/null
+
 docker run --detach \
 	--name "$container" \
 	--network "$network" \
 	--cap-drop ALL \
 	--security-opt no-new-privileges:true \
 	--env "SUBSCRIPTION_URL=http://${provider}:8080/provider.yaml?token=${secret}" \
+	--env "SSCLASH_PASSWORD=${admin_password}" \
 	--volume "$volume:/opt/clash" \
 	--publish 127.0.0.1::7890/tcp \
 	--publish 127.0.0.1::7890/udp \
@@ -90,7 +131,27 @@ if printf '%s\n' "$published" | grep -vE '^(7890/(tcp|udp)|9091/tcp)' >/dev/null
 	exit 1
 fi
 web_port=$(docker port "$container" 9091/tcp | awk -F: 'NR == 1 { print $NF }')
-curl --fail --silent --show-error "http://127.0.0.1:${web_port}/" >/dev/null
+setup_redirect=$(curl --silent --show-error --output /dev/null \
+	--write-out '%{http_code} %{redirect_url}' \
+	"http://127.0.0.1:${web_port}/setup")
+if [ "$setup_redirect" != "303 http://127.0.0.1:${web_port}/login" ]; then
+	echo "configured Web UI exposed setup: ${setup_redirect}" >&2
+	exit 1
+fi
+cookie=$(mktemp)
+login_html=$(curl --fail --silent --show-error --cookie-jar "$cookie" \
+	"http://127.0.0.1:${web_port}/login")
+login_csrf=$(printf '%s' "$login_html" | sed -n 's/.*name="csrf" value="\([^"]*\)".*/\1/p' | head -1)
+test -n "$login_csrf"
+curl --fail --silent --show-error \
+	--cookie "$cookie" \
+	--cookie-jar "$cookie" \
+	--request POST \
+	--data-urlencode "csrf=${login_csrf}" \
+	--data-urlencode "password=${admin_password}" \
+	"http://127.0.0.1:${web_port}/login" >/dev/null
+curl --fail --silent --show-error --cookie "$cookie" \
+	"http://127.0.0.1:${web_port}/config" | grep -F 'csrf-token' >/dev/null
 
 docker exec "$container" grep -Fx 'OPERATING_MODE=server' /opt/clash/.ssclash/settings >/dev/null
 docker exec "$container" grep -Fx 'PROXY_MODE=none' /opt/clash/.ssclash/settings >/dev/null
@@ -108,5 +169,13 @@ if docker logs "$container" 2>&1 | grep -F "$secret" >/dev/null; then
 	echo "subscription URL credential was written to logs" >&2
 	exit 1
 fi
+if docker exec "$container" grep -R -F "$admin_password" /opt/clash /dev/shm/mohomo >/dev/null 2>&1; then
+	echo "administrator password was written to runtime files" >&2
+	exit 1
+fi
+if docker logs "$container" 2>&1 | grep -F "$admin_password" >/dev/null; then
+	echo "administrator password was written to logs" >&2
+	exit 1
+fi
 
-echo "container smoke test passed: only ports 7890 and 9091 published; subscription credential not persisted or logged"
+echo "container smoke test passed: fresh volume fails closed; authenticated 9091 and proxy credentials are protected"
-- 
2.54.0


From 6a349f62c866dc9dd118b53ed3b819ccb5e936e2 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 24 Aug 2026 17:18:29 +0800
Subject: [PATCH 3/4] HH-620: harden authentication and volume rebuild

Co-authored-by: multica-agent <github@multica.ai>
---
 README.md                            |   8 +-
 cmd/bootstrap/main.go                |   2 +
 internal/bootstrap/bootstrap.go      | 108 ++++++++++++++++-
 internal/bootstrap/bootstrap_test.go | 172 ++++++++++++++++++++++++++-
 tests/container-smoke.sh             | 118 +++++++++++-------
 5 files changed, 355 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index c6e3623..d60627c 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ docker compose up -d --build
 docker compose logs -f ssclash
 ```
 
-The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. A fresh volume refuses to start without an `SSCLASH_PASSWORD` of at least 12 characters; bootstrap uses SSClash's own `setpass` command before the Web listener starts. Open `http://<server>:9091` and log in with that password. Existing authentication files are preserved, so later starts do not require or replace the password. Proxy clients connect to either endpoint:
+The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. A fresh volume refuses to start without an `SSCLASH_PASSWORD` of at least 12 characters; bootstrap uses SSClash's own `setpass` command before the Web listener starts. Open `http://<server>:9091` and log in with that password. A valid existing authentication file is preserved, so later starts do not require or replace the password. Proxy clients connect to either endpoint:
 
 ```text
 HTTP proxy:   http://<server>:7890
@@ -25,7 +25,7 @@ SOCKS5 proxy: socks5://<server>:7890
 
 The bootstrap fetches the subscription once before startup and every hour thereafter. Each candidate is limited to 16 MiB and validated with the packaged Mihomo binary before an atomic replacement and hot reload. A failed reload restores and reloads the previous provider; if that recovery cannot be confirmed, both services stop instead of running with uncertain state.
 
-The subscription URL and bootstrap administrator password are removed from child-process environments and never printed. The password is persisted only as SSClash's PBKDF2 authentication file. The generated configuration contains only a local provider path. Subscription data lives under `/dev/shm/mohomo`, so neither the image nor the `/opt/clash` volume stores its URL, response, or node credentials. Container restarts intentionally fetch a fresh subscription instead of persisting credentials.
+The subscription URL and bootstrap administrator password are removed from child-process environments and never printed. The password is persisted only as SSClash's PBKDF2 authentication file. Before opening the Web listener, bootstrap requires that file to be a readable, process-owned regular file with exact mode `0600` and SSClash v6.1.0's expected PBKDF2 format; a missing or abnormal file fails closed. The generated configuration contains only a local provider path. Subscription data lives under `/dev/shm/mohomo`, so neither the image nor the `/opt/clash` volume stores its URL, response, or node credentials. Container restarts intentionally fetch a fresh subscription instead of persisting credentials.
 
 Do not commit `.env`; it is ignored by Git. Docker still exposes bootstrap environment variables to principals allowed to inspect the container, so restrict Docker daemon access.
 
@@ -37,7 +37,7 @@ The generated groups and rule order mirror `ACL4SSR_Online_Full_MultiMode.ini`:
 
 ## Persistent data
 
-`/opt/clash` stores only SSClash settings, the packaged Mihomo core, and the non-secret generated configuration. Bootstrap creates missing files, preserves existing regular non-empty files, enforces `OPERATING_MODE=server` and `PROXY_MODE=none`, and rejects corrupt or ambiguous persistent state.
+`/opt/clash` stores only SSClash settings, the packaged Mihomo core, and the non-secret generated configuration. Bootstrap creates missing files, preserves existing regular non-empty files, enforces `OPERATING_MODE=server` and `PROXY_MODE=none`, and rejects corrupt or ambiguous persistent state. On container replacement it repairs only SSClash's exact `rule-providers` and `proxy-providers` links into `SSCLASH_TMP`; unexpected links are rejected without deleting their targets.
 
 ## Reproducible inputs
 
@@ -56,7 +56,7 @@ The GitHub Actions workflow builds `linux/amd64`, runs tests first, publishes on
 ./tests/container-smoke.sh
 ```
 
-The unit suite checks fail-closed authentication initialization, atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test verifies that a fresh volume without an administrator password never starts the Web UI, then logs in through published port `9091`, checks the exact `7890`/`9091` port set, and confirms that plaintext credentials are neither persisted nor logged.
+The unit suite checks strict fail-closed authentication-file validation, provider-link recovery, atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test verifies that a fresh volume without an administrator password never starts the Web UI, logs in through published port `9091`, checks the exact `7890`/`9091` port set, confirms that plaintext credentials are neither persisted nor logged, and repeats health and login checks after recreating the container with the same volume.
 
 ## License boundary
 
diff --git a/cmd/bootstrap/main.go b/cmd/bootstrap/main.go
index 9a2eb88..fceff85 100644
--- a/cmd/bootstrap/main.go
+++ b/cmd/bootstrap/main.go
@@ -14,6 +14,7 @@ import (
 
 const (
 	defaultRoot         = "/opt/clash"
+	defaultSSClashTemp  = "/tmp/ssclash"
 	defaultCoreSource   = "/usr/local/lib/ssclash/clash"
 	defaultConfigSource = "/usr/local/share/ssclash/config.yaml"
 	ssclashBinary       = "/usr/local/bin/ssclash"
@@ -27,6 +28,7 @@ func main() {
 
 	result, err := bootstrap.Prepare(bootstrap.Config{
 		Root:         root,
+		SSClashTemp:  envOrDefault("SSCLASH_TMP", defaultSSClashTemp),
 		CoreSource:   defaultCoreSource,
 		ConfigSource: defaultConfigSource,
 	})
diff --git a/internal/bootstrap/bootstrap.go b/internal/bootstrap/bootstrap.go
index 80b0fbc..7de6441 100644
--- a/internal/bootstrap/bootstrap.go
+++ b/internal/bootstrap/bootstrap.go
@@ -2,6 +2,7 @@ package bootstrap
 
 import (
 	"context"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"io"
@@ -38,14 +39,15 @@ var runtimeDirectories = []string{
 	".ssclash",
 	"configs",
 	"local-rules",
-	"rule-providers",
-	"proxy-providers",
 	"subscriptions",
 	"ui",
 }
 
+var managedProviderDirectories = []string{"rule-providers", "proxy-providers"}
+
 type Config struct {
 	Root         string
+	SSClashTemp  string
 	CoreSource   string
 	ConfigSource string
 }
@@ -74,6 +76,10 @@ func Prepare(config Config) (Result, error) {
 	if !filepath.IsAbs(root) {
 		return result, fmt.Errorf("root must be absolute: %q", config.Root)
 	}
+	ssclashTemp := filepath.Clean(config.SSClashTemp)
+	if !filepath.IsAbs(ssclashTemp) || ssclashTemp == string(filepath.Separator) {
+		return result, fmt.Errorf("unsafe SSClash temporary directory %q", config.SSClashTemp)
+	}
 	if err := validateSource(config.CoreSource, "core source"); err != nil {
 		return result, err
 	}
@@ -86,6 +92,11 @@ func Prepare(config Config) (Result, error) {
 			return result, fmt.Errorf("create runtime directory %s: %w", directory, err)
 		}
 	}
+	for _, directory := range managedProviderDirectories {
+		if err := reconcileManagedProviderDirectory(root, ssclashTemp, directory); err != nil {
+			return result, err
+		}
+	}
 
 	var err error
 	result.CoreInitialized, err = copyIfAbsent(config.CoreSource, filepath.Join(root, "bin", "clash"), 0o755)
@@ -145,6 +156,10 @@ func EnsureAdminPassword(root, binary, password string) (bool, error) {
 }
 
 func adminPasswordConfigured(path string) (bool, error) {
+	return adminPasswordConfiguredFor(path, uint32(os.Geteuid()), uint32(os.Getegid()))
+}
+
+func adminPasswordConfiguredFor(path string, expectedUID, expectedGID uint32) (bool, error) {
 	info, err := os.Lstat(path)
 	if errors.Is(err, os.ErrNotExist) {
 		return false, nil
@@ -152,15 +167,98 @@ func adminPasswordConfigured(path string) (bool, error) {
 	if err != nil {
 		return false, fmt.Errorf("inspect SSClash authentication file: %w", err)
 	}
-	if !info.Mode().IsRegular() || info.Size() == 0 {
-		return false, errors.New("SSClash authentication file must be a non-empty regular file")
+	if !info.Mode().IsRegular() {
+		return false, errors.New("SSClash authentication file must be a regular file")
 	}
-	if info.Mode().Perm()&0o077 != 0 {
+	if info.Mode().Perm() != 0o600 {
 		return false, fmt.Errorf("SSClash authentication file permissions are %o; want 600", info.Mode().Perm())
 	}
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return false, errors.New("SSClash authentication file ownership could not be verified")
+	}
+	if stat.Uid != expectedUID || stat.Gid != expectedGID {
+		return false, fmt.Errorf("SSClash authentication file owner is %d:%d; want %d:%d", stat.Uid, stat.Gid, expectedUID, expectedGID)
+	}
+
+	file, err := os.Open(path)
+	if err != nil {
+		return false, fmt.Errorf("read SSClash authentication file: %w", err)
+	}
+	defer file.Close()
+	openedInfo, err := file.Stat()
+	if err != nil {
+		return false, fmt.Errorf("inspect opened SSClash authentication file: %w", err)
+	}
+	if !os.SameFile(info, openedInfo) {
+		return false, errors.New("SSClash authentication file changed while being verified")
+	}
+	content, err := io.ReadAll(io.LimitReader(file, 257))
+	if err != nil {
+		return false, fmt.Errorf("read SSClash authentication file: %w", err)
+	}
+	if len(content) > 256 {
+		return false, errors.New("SSClash authentication file is too large")
+	}
+	if err := validateAdminPasswordHash(content); err != nil {
+		return false, err
+	}
 	return true, nil
 }
 
+func validateAdminPasswordHash(content []byte) error {
+	text := string(content)
+	if !strings.HasSuffix(text, "\n") {
+		return errors.New("SSClash authentication file has an invalid password hash")
+	}
+	parts := strings.Split(strings.TrimSuffix(text, "\n"), "$")
+	if len(parts) != 4 || parts[0] != "pbkdf2" || parts[1] != "120000" || len(parts[2]) != 32 || len(parts[3]) != 64 {
+		return errors.New("SSClash authentication file has an invalid password hash")
+	}
+	if _, err := hex.DecodeString(parts[2]); err != nil {
+		return errors.New("SSClash authentication file has an invalid password hash")
+	}
+	if _, err := hex.DecodeString(parts[3]); err != nil {
+		return errors.New("SSClash authentication file has an invalid password hash")
+	}
+	return nil
+}
+
+func reconcileManagedProviderDirectory(root, ssclashTemp, directory string) error {
+	path := filepath.Join(root, directory)
+	expectedTarget := filepath.Join(ssclashTemp, directory)
+	info, err := os.Lstat(path)
+	if errors.Is(err, os.ErrNotExist) {
+		if err := os.MkdirAll(path, 0o755); err != nil {
+			return fmt.Errorf("create runtime directory %s: %w", directory, err)
+		}
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("inspect runtime directory %s: %w", directory, err)
+	}
+	if info.IsDir() {
+		return nil
+	}
+	if info.Mode()&os.ModeSymlink == 0 {
+		return fmt.Errorf("runtime path %s is not a directory", directory)
+	}
+	target, err := os.Readlink(path)
+	if err != nil {
+		return fmt.Errorf("read runtime symlink %s: %w", directory, err)
+	}
+	if target != expectedTarget {
+		return fmt.Errorf("runtime path %s has unexpected symlink target %q", directory, target)
+	}
+	if err := os.Remove(path); err != nil {
+		return fmt.Errorf("remove managed runtime symlink %s: %w", directory, err)
+	}
+	if err := os.MkdirAll(path, 0o755); err != nil {
+		return fmt.Errorf("recreate runtime directory %s: %w", directory, err)
+	}
+	return nil
+}
+
 func Run(ctx context.Context, config RuntimeConfig) error {
 	if err := validateSubscriptionURL(config.SubscriptionURL); err != nil {
 		return err
diff --git a/internal/bootstrap/bootstrap_test.go b/internal/bootstrap/bootstrap_test.go
index ab5b30e..0a1dcb8 100644
--- a/internal/bootstrap/bootstrap_test.go
+++ b/internal/bootstrap/bootstrap_test.go
@@ -24,6 +24,7 @@ func TestPrepareInitializesServerRuntime(t *testing.T) {
 
 	result, err := Prepare(Config{
 		Root:         root,
+		SSClashTemp:  filepath.Join(tempDir, "tmp"),
 		CoreSource:   coreSource,
 		ConfigSource: configSource,
 	})
@@ -75,6 +76,7 @@ func TestPreparePreservesUserDataAndForcesServerMode(t *testing.T) {
 
 	result, err := Prepare(Config{
 		Root:         root,
+		SSClashTemp:  filepath.Join(tempDir, "tmp"),
 		CoreSource:   writeFixture(t, tempDir, "mihomo", "image-core"),
 		ConfigSource: writeFixture(t, tempDir, "default.yaml", "image: config\n"),
 	})
@@ -111,7 +113,7 @@ set -eu
 [ "$1" = setpass ]
 [ "$2" = fresh-volume-password ]
 password="$(dirname "$0")/../.ssclash/password"
-printf 'pbkdf2$test\n' > "$password"
+printf 'pbkdf2$120000$0123456789abcdef0123456789abcdef$0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n' > "$password"
 chmod 0600 "$password"
 `)
 	if err := os.Chmod(binary, 0o755); err != nil {
@@ -125,7 +127,7 @@ chmod 0600 "$password"
 	if !initialized {
 		t.Fatal("EnsureAdminPassword() initialized = false, want true")
 	}
-	assertFileContent(t, filepath.Join(root, ".ssclash", "password"), "pbkdf2$test\n")
+	assertFileContent(t, filepath.Join(root, ".ssclash", "password"), validAdminPasswordHash)
 
 	if err := os.Remove(binary); err != nil {
 		t.Fatal(err)
@@ -137,7 +139,153 @@ chmod 0600 "$password"
 	if initialized {
 		t.Fatal("EnsureAdminPassword() replaced existing password")
 	}
-	assertFileContent(t, filepath.Join(root, ".ssclash", "password"), "pbkdf2$test\n")
+	assertFileContent(t, filepath.Join(root, ".ssclash", "password"), validAdminPasswordHash)
+}
+
+func TestAdminPasswordConfiguredRejectsUnsafeFiles(t *testing.T) {
+	t.Parallel()
+
+	for _, testCase := range []struct {
+		name  string
+		setup func(t *testing.T, path string)
+	}{
+		{name: "mode 000", setup: passwordFileSetup(validAdminPasswordHash, 0o000)},
+		{name: "mode 0200", setup: passwordFileSetup(validAdminPasswordHash, 0o200)},
+		{name: "mode 0400", setup: passwordFileSetup(validAdminPasswordHash, 0o400)},
+		{name: "mode 0644", setup: passwordFileSetup(validAdminPasswordHash, 0o644)},
+		{name: "empty", setup: passwordFileSetup("", 0o600)},
+		{name: "invalid hash", setup: passwordFileSetup("pbkdf2$test\n", 0o600)},
+		{name: "non-hex hash", setup: passwordFileSetup("pbkdf2$120000$zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz$0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n", 0o600)},
+		{name: "directory", setup: func(t *testing.T, path string) {
+			t.Helper()
+			if err := os.Mkdir(path, 0o700); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "symlink", setup: func(t *testing.T, path string) {
+			t.Helper()
+			target := path + ".target"
+			passwordFileSetup(validAdminPasswordHash, 0o600)(t, target)
+			if err := os.Symlink(target, path); err != nil {
+				t.Fatal(err)
+			}
+		}},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "password")
+			testCase.setup(t, path)
+			if configured, err := adminPasswordConfigured(path); err == nil || configured {
+				t.Fatalf("adminPasswordConfigured() = %t, %v; want false, error", configured, err)
+			}
+		})
+	}
+}
+
+func TestAdminPasswordConfiguredRequiresOwner(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "password")
+	passwordFileSetup(validAdminPasswordHash, 0o600)(t, path)
+	for _, owner := range []struct {
+		name string
+		uid  uint32
+		gid  uint32
+	}{
+		{name: "UID", uid: uint32(os.Geteuid() + 1), gid: uint32(os.Getegid())},
+		{name: "GID", uid: uint32(os.Geteuid()), gid: uint32(os.Getegid() + 1)},
+	} {
+		t.Run(owner.name, func(t *testing.T) {
+			configured, err := adminPasswordConfiguredFor(path, owner.uid, owner.gid)
+			if err == nil || configured {
+				t.Fatalf("adminPasswordConfiguredFor() = %t, %v; want false, owner error", configured, err)
+			}
+		})
+	}
+}
+
+func TestAdminPasswordConfiguredAcceptsSecureFile(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "password")
+	passwordFileSetup(validAdminPasswordHash, 0o600)(t, path)
+	configured, err := adminPasswordConfigured(path)
+	if err != nil || !configured {
+		t.Fatalf("adminPasswordConfigured() = %t, %v; want true, nil", configured, err)
+	}
+}
+
+func TestPrepareRepairsManagedProviderSymlinks(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	root := filepath.Join(tempDir, "data")
+	ssclashTemp := filepath.Join(tempDir, "tmp")
+	config := Config{
+		Root:         root,
+		SSClashTemp:  ssclashTemp,
+		CoreSource:   writeFixture(t, tempDir, "mihomo", "core"),
+		ConfigSource: writeFixture(t, tempDir, "config.yaml", "config"),
+	}
+	if _, err := Prepare(config); err != nil {
+		t.Fatalf("first Prepare() error = %v", err)
+	}
+	for _, directory := range []string{"rule-providers", "proxy-providers"} {
+		path := filepath.Join(root, directory)
+		if err := os.Remove(path); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Symlink(filepath.Join(ssclashTemp, directory), path); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	if _, err := Prepare(config); err != nil {
+		t.Fatalf("second Prepare() error = %v", err)
+	}
+	for _, directory := range []string{"rule-providers", "proxy-providers"} {
+		info, err := os.Lstat(filepath.Join(root, directory))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !info.IsDir() {
+			t.Errorf("%s mode = %s, want directory", directory, info.Mode())
+		}
+	}
+}
+
+func TestPrepareRejectsUnexpectedProviderSymlink(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+	root := filepath.Join(tempDir, "data")
+	ssclashTemp := filepath.Join(tempDir, "tmp")
+	config := Config{
+		Root:         root,
+		SSClashTemp:  ssclashTemp,
+		CoreSource:   writeFixture(t, tempDir, "mihomo", "core"),
+		ConfigSource: writeFixture(t, tempDir, "config.yaml", "config"),
+	}
+	if _, err := Prepare(config); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(root, "rule-providers")
+	if err := os.Remove(path); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(filepath.Join(tempDir, "unexpected"), path); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := Prepare(config); err == nil || !strings.Contains(err.Error(), "unexpected symlink") {
+		t.Fatalf("Prepare() error = %v, want unexpected symlink error", err)
+	}
+	target, err := os.Readlink(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if target != filepath.Join(tempDir, "unexpected") {
+		t.Fatalf("unexpected symlink target = %q", target)
+	}
 }
 
 func TestChildEnvironmentRemovesCredentials(t *testing.T) {
@@ -169,6 +317,7 @@ func TestPrepareRejectsUnsafeOrAmbiguousState(t *testing.T) {
 			name: "filesystem root",
 			config: Config{
 				Root:         "/",
+				SSClashTemp:  filepath.Join(tempDir, "tmp"),
 				CoreSource:   coreSource,
 				ConfigSource: configSource,
 			},
@@ -178,6 +327,7 @@ func TestPrepareRejectsUnsafeOrAmbiguousState(t *testing.T) {
 			name: "missing core source",
 			config: Config{
 				Root:         filepath.Join(tempDir, "missing-core"),
+				SSClashTemp:  filepath.Join(tempDir, "tmp"),
 				CoreSource:   filepath.Join(tempDir, "does-not-exist"),
 				ConfigSource: configSource,
 			},
@@ -187,6 +337,7 @@ func TestPrepareRejectsUnsafeOrAmbiguousState(t *testing.T) {
 			name: "duplicate operating mode",
 			config: Config{
 				Root:         filepath.Join(tempDir, "duplicate-mode"),
+				SSClashTemp:  filepath.Join(tempDir, "tmp"),
 				CoreSource:   coreSource,
 				ConfigSource: configSource,
 			},
@@ -203,6 +354,7 @@ func TestPrepareRejectsUnsafeOrAmbiguousState(t *testing.T) {
 			name: "duplicate proxy mode",
 			config: Config{
 				Root:         filepath.Join(tempDir, "duplicate-proxy-mode"),
+				SSClashTemp:  filepath.Join(tempDir, "tmp"),
 				CoreSource:   coreSource,
 				ConfigSource: configSource,
 			},
@@ -403,6 +555,20 @@ func writeFixture(t *testing.T, directory, name, content string) string {
 	return path
 }
 
+const validAdminPasswordHash = "pbkdf2$120000$0123456789abcdef0123456789abcdef$0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n"
+
+func passwordFileSetup(content string, mode os.FileMode) func(t *testing.T, path string) {
+	return func(t *testing.T, path string) {
+		t.Helper()
+		if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Chmod(path, mode); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
 func assertFileContent(t *testing.T, path, want string) {
 	t.Helper()
 	content, err := os.ReadFile(path)
diff --git a/tests/container-smoke.sh b/tests/container-smoke.sh
index e686d4a..bf4cbd9 100755
--- a/tests/container-smoke.sh
+++ b/tests/container-smoke.sh
@@ -27,6 +27,55 @@ cleanup() {
 }
 trap cleanup EXIT INT TERM
 
+wait_for_health() {
+	attempt=0
+	until [ "$(docker inspect --format '{{.State.Health.Status}}' "$container")" = healthy ]; do
+		attempt=$((attempt + 1))
+		if [ "$attempt" -ge 30 ]; then
+			docker logs "$container" >&2
+			echo "container did not become healthy" >&2
+			exit 1
+		fi
+		sleep 1
+	done
+}
+
+assert_published_ports() {
+	published=$(docker port "$container")
+	for port in 7890/tcp 7890/udp 9091/tcp; do
+		printf '%s\n' "$published" | grep -F "$port ->" >/dev/null
+	done
+	if printf '%s\n' "$published" | grep -vE '^(7890/(tcp|udp)|9091/tcp)' >/dev/null; then
+		echo "container published a port other than 7890 or 9091" >&2
+		exit 1
+	fi
+}
+
+assert_web_login() {
+	web_port=$1
+	: > "$cookie"
+	setup_redirect=$(curl --silent --show-error --output /dev/null \
+		--write-out '%{http_code} %{redirect_url}' \
+		"http://127.0.0.1:${web_port}/setup")
+	if [ "$setup_redirect" != "303 http://127.0.0.1:${web_port}/login" ]; then
+		echo "configured Web UI exposed setup: ${setup_redirect}" >&2
+		exit 1
+	fi
+	login_html=$(curl --fail --silent --show-error --cookie-jar "$cookie" \
+		"http://127.0.0.1:${web_port}/login")
+	login_csrf=$(printf '%s' "$login_html" | sed -n 's/.*name="csrf" value="\([^"]*\)".*/\1/p' | head -1)
+	test -n "$login_csrf"
+	curl --fail --silent --show-error \
+		--cookie "$cookie" \
+		--cookie-jar "$cookie" \
+		--request POST \
+		--data-urlencode "csrf=${login_csrf}" \
+		--data-urlencode "password=${admin_password}" \
+		"http://127.0.0.1:${web_port}/login" >/dev/null
+	curl --fail --silent --show-error --cookie "$cookie" \
+		"http://127.0.0.1:${web_port}/config" | grep -F 'csrf-token' >/dev/null
+}
+
 docker build --tag "$image" .
 docker run --rm --entrypoint /usr/local/lib/ssclash/clash "$image" \
 	-t -d /usr/local/share/ssclash -f /usr/local/share/ssclash/config.yaml >/dev/null 2>&1 && {
@@ -97,6 +146,7 @@ if docker logs "$unconfigured" 2>&1 | grep -F 'web UI listening' >/dev/null; the
 	exit 1
 fi
 docker container rm "$unconfigured" >/dev/null
+cookie=$(mktemp)
 
 docker run --detach \
 	--name "$container" \
@@ -111,47 +161,10 @@ docker run --detach \
 	--publish 127.0.0.1::9091/tcp \
 	"$image" >/dev/null
 
-attempt=0
-until [ "$(docker inspect --format '{{.State.Health.Status}}' "$container")" = healthy ]; do
-	attempt=$((attempt + 1))
-	if [ "$attempt" -ge 30 ]; then
-		docker logs "$container" >&2
-		echo "container did not become healthy" >&2
-		exit 1
-	fi
-	sleep 1
-done
-
-published=$(docker port "$container")
-for port in 7890/tcp 7890/udp 9091/tcp; do
-	printf '%s\n' "$published" | grep -F "$port ->" >/dev/null
-done
-if printf '%s\n' "$published" | grep -vE '^(7890/(tcp|udp)|9091/tcp)' >/dev/null; then
-	echo "container published a port other than 7890 or 9091" >&2
-	exit 1
-fi
+wait_for_health
+assert_published_ports
 web_port=$(docker port "$container" 9091/tcp | awk -F: 'NR == 1 { print $NF }')
-setup_redirect=$(curl --silent --show-error --output /dev/null \
-	--write-out '%{http_code} %{redirect_url}' \
-	"http://127.0.0.1:${web_port}/setup")
-if [ "$setup_redirect" != "303 http://127.0.0.1:${web_port}/login" ]; then
-	echo "configured Web UI exposed setup: ${setup_redirect}" >&2
-	exit 1
-fi
-cookie=$(mktemp)
-login_html=$(curl --fail --silent --show-error --cookie-jar "$cookie" \
-	"http://127.0.0.1:${web_port}/login")
-login_csrf=$(printf '%s' "$login_html" | sed -n 's/.*name="csrf" value="\([^"]*\)".*/\1/p' | head -1)
-test -n "$login_csrf"
-curl --fail --silent --show-error \
-	--cookie "$cookie" \
-	--cookie-jar "$cookie" \
-	--request POST \
-	--data-urlencode "csrf=${login_csrf}" \
-	--data-urlencode "password=${admin_password}" \
-	"http://127.0.0.1:${web_port}/login" >/dev/null
-curl --fail --silent --show-error --cookie "$cookie" \
-	"http://127.0.0.1:${web_port}/config" | grep -F 'csrf-token' >/dev/null
+assert_web_login "$web_port"
 
 docker exec "$container" grep -Fx 'OPERATING_MODE=server' /opt/clash/.ssclash/settings >/dev/null
 docker exec "$container" grep -Fx 'PROXY_MODE=none' /opt/clash/.ssclash/settings >/dev/null
@@ -178,4 +191,27 @@ if docker logs "$container" 2>&1 | grep -F "$admin_password" >/dev/null; then
 	exit 1
 fi
 
-echo "container smoke test passed: fresh volume fails closed; authenticated 9091 and proxy credentials are protected"
+docker container rm --force "$container" >/dev/null
+docker run --rm \
+	--volume "$volume:/opt/clash" \
+	--entrypoint /bin/sh \
+	"$image" -c 'test -L /opt/clash/rule-providers && test ! -e /opt/clash/rule-providers && test "$(readlink /opt/clash/rule-providers)" = /tmp/ssclash/rule-providers'
+
+docker run --detach \
+	--name "$container" \
+	--network "$network" \
+	--cap-drop ALL \
+	--security-opt no-new-privileges:true \
+	--env "SUBSCRIPTION_URL=http://${provider}:8080/provider.yaml?token=${secret}" \
+	--volume "$volume:/opt/clash" \
+	--publish 127.0.0.1::7890/tcp \
+	--publish 127.0.0.1::7890/udp \
+	--publish 127.0.0.1::9091/tcp \
+	"$image" >/dev/null
+
+wait_for_health
+assert_published_ports
+web_port=$(docker port "$container" 9091/tcp | awk -F: 'NR == 1 { print $NF }')
+assert_web_login "$web_port"
+
+echo "container smoke test passed: fresh volume fails closed; authenticated 9091 survives same-volume rebuild; only 7890/9091 are published"
-- 
2.54.0


From 925ce8433969dc0eaf991f06e82e21196024b7ed Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 24 Aug 2026 17:44:55 +0800
Subject: [PATCH 4/4] HH-620: secure default host bindings

Co-authored-by: multica-agent <github@multica.ai>
---
 .env.example             |  5 +++--
 README.md                | 22 ++++++++++++++++------
 compose.yaml             |  7 ++++---
 tests/container-smoke.sh | 31 +++++++++++++++++++++++++++++++
 4 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/.env.example b/.env.example
index 1607977..c83b589 100644
--- a/.env.example
+++ b/.env.example
@@ -2,7 +2,8 @@ IMAGE_NAME=mohomo-docker:local
 CONTAINER_NAME=mohomo-docker
 SUBSCRIPTION_URL=https://subscription.example.invalid/mihomo
 SSCLASH_PASSWORD=
-WEB_BIND=0.0.0.0
+# 9091 is always host-loopback; expose it through a host HTTPS reverse proxy.
 WEB_PORT=9091
-PROXY_BIND=0.0.0.0
+# Public opt-in: use 0.0.0.0 only behind a trusted-network firewall/ACL.
+PROXY_BIND=127.0.0.1
 PROXY_PORT=7890
diff --git a/README.md b/README.md
index d60627c..3fb78e8 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # mohomo-docker
 
-Minimal Mihomo service with the ACL4SSR `Online Full MultiMode` routing model. The host exposes the SSClash Web UI on port `9091` and the mixed proxy on port `7890`; Mihomo's controller remains private to the container.
+Minimal Mihomo service with the ACL4SSR `Online Full MultiMode` routing model. The host publishes the SSClash Web UI on loopback port `9091` and the mixed proxy on loopback port `7890` by default; Mihomo's controller remains private to the container.
 
 ## Quick start
 
@@ -12,14 +12,24 @@ docker compose up -d --build
 docker compose logs -f ssclash
 ```
 
-The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. A fresh volume refuses to start without an `SSCLASH_PASSWORD` of at least 12 characters; bootstrap uses SSClash's own `setpass` command before the Web listener starts. Open `http://<server>:9091` and log in with that password. A valid existing authentication file is preserved, so later starts do not require or replace the password. Proxy clients connect to either endpoint:
+The subscription endpoint must return a Clash/Mihomo proxy-provider YAML document (`proxies:`). Use an HTTPS endpoint when its URL contains a credential. A fresh volume refuses to start without an `SSCLASH_PASSWORD` of at least 12 characters; bootstrap uses SSClash's own `setpass` command before the Web listener starts. On the Docker host, open `http://127.0.0.1:9091` and log in with that password. A valid existing authentication file is preserved, so later starts do not require or replace the password. Local proxy clients connect to either endpoint:
 
 ```text
-HTTP proxy:   http://<server>:7890
-SOCKS5 proxy: socks5://<server>:7890
+HTTP proxy:   http://127.0.0.1:7890
+SOCKS5 proxy: socks5://127.0.0.1:7890
 ```
 
-`WEB_BIND`, `WEB_PORT`, `PROXY_BIND`, and `PROXY_PORT` are optional deployment overrides; both services bind all host interfaces by default. Authentication prevents anonymous first-run setup, but the Web UI still serves plain HTTP: place it behind HTTPS and additional access control before exposing it to the Internet. Configure Mihomo proxy authentication before publishing port `7890` outside a trusted network.
+The Compose boundary fixes plaintext `9091` to host loopback. To provide the required external Web access, configure a host HTTPS reverse proxy to `127.0.0.1:${WEB_PORT:-9091}`; for example, a host-native Caddy configuration is:
+
+```caddyfile
+ssclash.example.com {
+    reverse_proxy 127.0.0.1:9091
+}
+```
+
+Replace the domain and ensure its DNS reaches the host; Caddy then obtains and serves the TLS certificate. Do not publish 9091 directly as public HTTP.
+
+`WEB_PORT`, `PROXY_BIND`, and `PROXY_PORT` are optional deployment overrides. Port 7890 also defaults to `127.0.0.1`; setting `PROXY_BIND=0.0.0.0` is the explicit public opt-in. The packaged Mihomo proxy has no client authentication, so use that opt-in only when a host firewall or network ACL restricts clients to a trusted range. Prefer binding `PROXY_BIND` to a specific trusted host address.
 
 ## Update and secret handling
 
@@ -56,7 +66,7 @@ The GitHub Actions workflow builds `linux/amd64`, runs tests first, publishes on
 ./tests/container-smoke.sh
 ```
 
-The unit suite checks strict fail-closed authentication-file validation, provider-link recovery, atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test verifies that a fresh volume without an administrator password never starts the Web UI, logs in through published port `9091`, checks the exact `7890`/`9091` port set, confirms that plaintext credentials are neither persisted nor logged, and repeats health and login checks after recreating the container with the same volume.
+The unit suite checks strict fail-closed authentication-file validation, provider-link recovery, atomic rollback, URL redaction, server-only listeners, local ACL4SSR providers, and at least 65% bootstrap coverage. The container smoke test verifies loopback-only Compose defaults and proxy-only public opt-in, proves 7890/9091 are unreachable through a non-loopback host address, checks fresh-volume authentication and credential isolation, and repeats health and login checks after recreating the container with the same volume.
 
 ## License boundary
 
diff --git a/compose.yaml b/compose.yaml
index ca4f3e2..7b72864 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -10,9 +10,10 @@ services:
       SUBSCRIPTION_URL: ${SUBSCRIPTION_URL:?set SUBSCRIPTION_URL in .env}
       SSCLASH_PASSWORD: ${SSCLASH_PASSWORD:-}
     ports:
-      - "${WEB_BIND:-0.0.0.0}:${WEB_PORT:-9091}:9091/tcp"
-      - "${PROXY_BIND:-0.0.0.0}:${PROXY_PORT:-7890}:7890/tcp"
-      - "${PROXY_BIND:-0.0.0.0}:${PROXY_PORT:-7890}:7890/udp"
+      # Keep the plaintext Web UI behind a host-local HTTPS reverse proxy.
+      - "127.0.0.1:${WEB_PORT:-9091}:9091/tcp"
+      - "${PROXY_BIND:-127.0.0.1}:${PROXY_PORT:-7890}:7890/tcp"
+      - "${PROXY_BIND:-127.0.0.1}:${PROXY_PORT:-7890}:7890/udp"
     volumes:
       - ssclash-data:/opt/clash
     cap_drop:
diff --git a/tests/container-smoke.sh b/tests/container-smoke.sh
index bf4cbd9..4629333 100755
--- a/tests/container-smoke.sh
+++ b/tests/container-smoke.sh
@@ -76,6 +76,22 @@ assert_web_login() {
 		"http://127.0.0.1:${web_port}/config" | grep -F 'csrf-token' >/dev/null
 }
 
+default_compose=$(SUBSCRIPTION_URL=https://subscription.example.invalid/mihomo docker compose config)
+loopback_bindings=$(printf '%s\n' "$default_compose" | awk '$1 == "host_ip:" && $2 == "127.0.0.1" { count++ } END { print count + 0 }')
+if [ "$loopback_bindings" -ne 3 ]; then
+	echo "Compose must bind 7890/tcp, 7890/udp, and 9091/tcp to host loopback by default" >&2
+	exit 1
+fi
+
+public_proxy_compose=$(SUBSCRIPTION_URL=https://subscription.example.invalid/mihomo \
+	PROXY_BIND=0.0.0.0 WEB_BIND=0.0.0.0 docker compose config)
+public_bindings=$(printf '%s\n' "$public_proxy_compose" | awk '$1 == "host_ip:" && $2 == "0.0.0.0" { count++ } END { print count + 0 }')
+loopback_bindings=$(printf '%s\n' "$public_proxy_compose" | awk '$1 == "host_ip:" && $2 == "127.0.0.1" { count++ } END { print count + 0 }')
+if [ "$public_bindings" -ne 2 ] || [ "$loopback_bindings" -ne 1 ]; then
+	echo "public opt-in must affect only 7890; 9091 must remain on host loopback" >&2
+	exit 1
+fi
+
 docker build --tag "$image" .
 docker run --rm --entrypoint /usr/local/lib/ssclash/clash "$image" \
 	-t -d /usr/local/share/ssclash -f /usr/local/share/ssclash/config.yaml >/dev/null 2>&1 && {
@@ -166,6 +182,21 @@ assert_published_ports
 web_port=$(docker port "$container" 9091/tcp | awk -F: 'NR == 1 { print $NF }')
 assert_web_login "$web_port"
 
+host_gateway=$(docker network inspect "$network" --format '{{(index .IPAM.Config 0).Gateway}}')
+container_ip=$(docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$container")
+proxy_port=$(docker port "$container" 7890/tcp | awk -F: 'NR == 1 { print $NF }')
+if curl --fail --silent --show-error --max-time 2 --noproxy "" \
+	--proxy "http://${host_gateway}:${proxy_port}" \
+	"http://${container_ip}:9090/version" >/dev/null 2>&1; then
+	echo "default 7890 publish was reachable through a non-loopback host address" >&2
+	exit 1
+fi
+if curl --fail --silent --show-error --max-time 2 \
+	"http://${host_gateway}:${web_port}/login" >/dev/null 2>&1; then
+	echo "default 9091 publish was reachable through a non-loopback host address" >&2
+	exit 1
+fi
+
 docker exec "$container" grep -Fx 'OPERATING_MODE=server' /opt/clash/.ssclash/settings >/dev/null
 docker exec "$container" grep -Fx 'PROXY_MODE=none' /opt/clash/.ssclash/settings >/dev/null
 docker exec "$container" test -s /dev/shm/mohomo/subscription.yaml
-- 
2.54.0