feat(web): enhance web UI with subscription management and security features

- Added new command-line flags for `--sub-only`, `--secret-path`, `--admin-token`, and `--force-local` to improve UI security and functionality.
- Implemented a random token generation for secret paths, allowing users to serve the UI under a secure prefix.
- Introduced admin authentication via a token, gating access to the UI and API.
- Updated the web server to handle requests based on the new security features, including a login mechanism.
- Enhanced documentation to reflect the new features and usage instructions.

These changes significantly improve the security and usability of the web interface, providing users with better control over access and visibility.

Author: hiddifydeveloper

cmd/main.go

@@ -3,13 +3,16 @@ package main
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/base32"
 	"encoding/json"
 	"fmt"
 	"io"
 	"io/fs"
 	"os"
 	"os/signal"
 	"path/filepath"
+	"strings"
 	"syscall"
 	"text/tabwriter"
 	"time"
@@ -19,6 +22,7 @@ import (
 	// Register core runners via side-effect imports.
 	_ "github.com/hiddify/hiddify_config_health/internal/core"
 
+	"github.com/hiddify/hiddify_config_health/internal/proxyuri"
 	"github.com/hiddify/hiddify_config_health/internal/runner"
 	"github.com/hiddify/hiddify_config_health/internal/store"
 	"github.com/hiddify/hiddify_config_health/internal/web"
@@ -382,6 +386,10 @@ func checkCmd() *cobra.Command {
 
 func serveCmd() *cobra.Command {
 	var addr string
+	var subOnly bool
+	var secretPath string
+	var adminToken string
+	var forceLocal bool
 	cmd := &cobra.Command{
 		Use:   "serve",
 		Short: "Start the web UI",
@@ -390,13 +398,30 @@ func serveCmd() *cobra.Command {
 			if db != nil {
 				defer db.Close()
 			}
+			// --secret-path: "auto" generates a random token; any other value
+			// is used literally. Empty = served at root.
+			base := strings.Trim(secretPath, "/")
+			if base == "auto" {
+				base = randToken(16)
+			}
+			if base != "" {
+				base += "/health"
+			}
+			proxyuri.ForceLocal = forceLocal
 			srv := &web.Server{
 				ExamplesDir: flagExamplesDir,
 				DB:          db,
+				SubOnly:     subOnly,
+				BasePath:    base,
+				AdminToken:  adminToken,
 			}
 			ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM)
 			defer stop()
-			fmt.Printf("Web UI: http://%s\n", addr)
+			path := "/"
+			if base != "" {
+				path = "/" + base + "/"
+			}
+			fmt.Printf("Web UI: http://%s%s\n", addr, path)
 			go func() {
 				if err := srv.ListenAndServe(addr); err != nil {
 					fmt.Fprintln(os.Stderr, "web:", err)
@@ -407,9 +432,25 @@ func serveCmd() *cobra.Command {
 		},
 	}
 	cmd.Flags().StringVar(&addr, "addr", ":8080", "listen address")
+	cmd.Flags().BoolVar(&subOnly, "sub-only", false, "subscription-only UI: hide the config/deploy mode tabs")
+	cmd.Flags().StringVar(&secretPath, "secret-path", "", "serve under a secret prefix /<path>/health/ (\"auto\" = random token)")
+	cmd.Flags().StringVar(&adminToken, "admin-token", "", "require this token (cookie login) to access the UI/API; empty = open")
+	cmd.Flags().BoolVar(&forceLocal, "force-local", false, "resolve subscription hosts to 127.0.0.1 (use behind a reverse proxy)")
 	return cmd
 }
 
+// randToken returns an uppercase alphanumeric token of n chars (base32, no
+// padding) for use as a secret URL path.
+func randToken(n int) string {
+	buf := make([]byte, n)
+	_, _ = rand.Read(buf)
+	s := base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(buf)
+	if len(s) > n {
+		s = s[:n]
+	}
+	return s
+}
+
 // --- history ---
 
 func historyCmd() *cobra.Command {

docs/web-ui.md

@@ -16,6 +16,133 @@ Flags:
 | `--addr` | `:8080` | Listen address |
 | `--examples` | `examples` | Root directory to scan for `run.json` files |
 | `--db` | `~/.hiddify-health/results.db` | SQLite history database |
+| `--sub-only` | `false` | Subscription-only UI — hide the config/deploy mode tabs |
+| `--secret-path` | `""` | Serve the whole UI under a secret prefix `/<path>/health/` (`auto` = random token) |
+| `--admin-token` | `""` | Require this token (cookie login) to access the UI/API — empty = open |
+| `--force-local` | `false` | Resolve subscription hosts to `127.0.0.1` instead of real DNS — use behind a reverse proxy |
+
+## Secret base path
+
+By default the UI is served at the root (`http://host:8090/`). To hide it
+behind an unguessable prefix, pass `--secret-path`:
+
+```bash
+# fixed secret
+./hiddify-health serve --secret-path DSJKNLIWPFKLKS
+# → http://host:8090/DSJKNLIWPFKLKS/health/
+
+# random token (printed at startup)
+./hiddify-health serve --secret-path auto
+# → http://host:8090/DDE6YYXAYMI2UMFJ/health/
+```
+
+The value is normalised to `/<path>/health/`. Behaviour:
+
+- Everything under the prefix works normally (page + `api/*` + SSE).
+- Anything **outside** the prefix returns **404** — `/`, `/api/examples`, any
+  other path. The path acts as a shared secret (obscurity gate, not auth).
+- A bare prefix without trailing slash (`/<path>/health`) `301`-redirects to
+  the trailing-slash form.
+- The page injects `<base href="/<path>/health/">`; all in-page requests are
+  relative, so they resolve under the prefix automatically.
+
+> This is obscurity, not authentication — anyone with the link has full
+> access. For real protection, also front it with a reverse proxy + auth.
+
+## Admin login (`--admin-token`)
+
+`--secret-path` alone is just obscurity — no login. To require auth on top
+of it, pass `--admin-token`:
+
+```bash
+./hiddify-health serve --secret-path auto --admin-token <strong-random-token>
+```
+
+Behaviour:
+
+- Gates the **whole** UI and API (everything under the secret prefix,
+  including `/api/sub`) behind a login cookie.
+- Unauthenticated requests are redirected to `login` (an in-prefix page);
+  `/api/*` requests get `401` instead of a redirect.
+- Login: POST the token to `login` (form field `token` or `?token=`).
+  Sets an `HttpOnly` cookie (`hch_admin`), valid 30 days.
+- Empty/unset `--admin-token` (default) = no auth, current open behaviour.
+- This panel is meant for the admin/operator to test their own configs and
+  subscription links — not for end users. Always set `--admin-token` on any
+  internet-reachable deployment.
+
+## Deploying behind a reverse proxy (TLS)
+
+Recommended production setup: run `hiddify-health serve` bound to
+`127.0.0.1`, and put a TLS-terminating reverse proxy (nginx, Caddy, etc.) in
+front of it serving `https://a.com/<secret-path>/health/`.
+
+```bash
+./hiddify-health serve --addr 127.0.0.1:8090 --secret-path auto --admin-token <token>
+```
+
+Point the reverse proxy at `127.0.0.1:8090`, terminate TLS there, and forward
+the path through unchanged.
+
+### `--force-local`
+
+When testing a subscription link that points back at your own domain (e.g.
+the panel is reachable at `https://a.com/secret_path/...` and you paste that
+same domain as the subscription URL), the panel would otherwise resolve
+`a.com` over real DNS and go back out through the public internet. Pass
+`--force-local` to make subscription fetches resolve straight to
+`127.0.0.1` (port preserved) instead:
+
+```bash
+./hiddify-health serve --addr 127.0.0.1:8090 --force-local
+```
+
+Only affects subscription URL fetches (`POST /api/sub` with `sub_url`); pasted
+proxy links (`text`) are unaffected since they're not fetched over HTTP.
+
+## Modes
+
+The page has two mutually-exclusive modes, switched by the tabs at the top of
+the sidebar:
+
+- **Configs / Deploy** — pick an example config, run it locally, or deploy the
+  server to a remote host (Global SSH). Default.
+- **Subscription / Links** — paste a subscription URL or proxy links; each
+  proxy is tested on sing-box & xray, scored, and compared to a no-proxy
+  baseline.
+
+### Subscription-only deployment
+
+To run a public, link-testing-only instance (no example/deploy UI), start with
+`--sub-only`:
+
+```bash
+./hiddify-health serve --addr :8080 --sub-only
+```
+
+The mode tabs are hidden and the page boots straight into the Subscription
+mode. (Server-side: injects `window.SUB_ONLY=true` into the page.)
+
+### URL parameters
+
+The page reads query parameters on load, so a subscription can be opened with a
+pre-filled link — e.g. `https://host/?sub=https://example.com/sub.txt`:
+
+| Param | Effect |
+|---|---|
+| `?sub=<url>` | Pre-fill the subscription URL and switch to Subscription mode |
+| `?text=<links>` | Pre-fill the proxy-links box (`,` is treated as newline) |
+| `?full=1` | Tick the full-suite checkbox |
+| `?run=1` | Auto-start the test once filled |
+| `?subonly=1` | Hide the mode tabs for this link (per-URL, no server flag) |
+
+Combine freely:
+
+```
+https://host/?sub=https://example.com/sub.txt&full=1&run=1
+```
+
+fills the URL, enables the full suite, and starts testing immediately.
 
 ## Layout
 
@@ -99,6 +226,26 @@ Returns the most recent `store.Record` for `dir`, or `null`.
 
 Returns the last 50 `store.Record` rows for `dir` (newest first).
 
+### `POST /api/sub`
+
+Tests a subscription or proxy list. Body:
+
+```json
+{ "sub_url": "https://example.com/sub.txt", "text": "vless://…\nvmess://…",
+  "full": false, "submit": false }
+```
+
+`sub_url` or `text` (one required). `full` runs the heavy check suite;
+`submit` shares anonymous, PII-stripped results to the central server and
+returns a private link. Streams SSE events:
+
+| Event | Data |
+|---|---|
+| `baseline` | No-proxy baseline metrics (JSON) |
+| `row` | One proxy×core result (JSON) as each finishes |
+| `link` | Private results URL (only when `submit:true`) |
+| `done` | Empty — stream ends |
+
 ## Concurrent runs
 
 The server blocks a second run for the same example directory while one is

internal/proxyuri/proxyuri.go

@@ -9,11 +9,18 @@ import (
 	"encoding/base64"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"strings"
 	"time"
 )
 
+// ForceLocal, when true, makes ParseSubscription resolve every subscription
+// host to 127.0.0.1 instead of its real DNS address. Set via --force-local;
+// used when the panel sits behind a reverse proxy and we want subscription
+// fetches to hit the local instance rather than the public domain.
+var ForceLocal bool
+
 // Proxy is a normalised, core-agnostic description of one proxy endpoint.
 type Proxy struct {
 	Protocol string // vless | vmess | trojan | shadowsocks | hysteria2 | tuic
@@ -111,7 +118,7 @@ func ParseSubscription(ctx context.Context, subURL string) ([]Proxy, []error) {
 		return nil, []error{err}
 	}
 	req.Header.Set("User-Agent", "hiddify-health/subscription")
-	cl := &http.Client{Timeout: 20 * time.Second}
+	cl := &http.Client{Timeout: 20 * time.Second, Transport: subscriptionTransport()}
 	resp, err := cl.Do(req)
 	if err != nil {
 		return nil, []error{fmt.Errorf("fetch subscription: %w", err)}
@@ -127,6 +134,25 @@ func ParseSubscription(ctx context.Context, subURL string) ([]Proxy, []error) {
 	return ParseList(decodeMaybeBase64(string(body)))
 }
 
+// subscriptionTransport returns an http.Transport that, when ForceLocal is
+// set, dials 127.0.0.1 for every subscription host (port preserved) instead
+// of resolving real DNS — used behind a reverse proxy so subscription
+// fetches hit the local instance rather than the public domain.
+func subscriptionTransport() http.RoundTripper {
+	if !ForceLocal {
+		return http.DefaultTransport
+	}
+	t := http.DefaultTransport.(*http.Transport).Clone()
+	t.DialContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
+		_, port, err := net.SplitHostPort(addr)
+		if err != nil {
+			return nil, err
+		}
+		return (&net.Dialer{}).DialContext(ctx, network, net.JoinHostPort("127.0.0.1", port))
+	}
+	return t
+}
+
 // decodeMaybeBase64 returns the base64-decoded text if the whole blob decodes
 // cleanly and yields proxy-looking content, else the original text.
 func decodeMaybeBase64(s string) string {

internal/web/static/index.html

@@ -147,7 +147,7 @@ <h2 id="title">Select an example</h2>
 let examplesList = [];
 
 async function loadExamples() {
-  const res = await fetch('/api/examples');
+  const res = await fetch('api/examples');
   const items = await res.json() || [];
   examplesList = items;
   // Populate the core filter dropdown (preserve current selection).
@@ -284,7 +284,7 @@ <h2 id="title">Select an example</h2>
   const deploy = document.getElementById('inp-deploy').value.trim();
   const server = document.getElementById('inp-server').value.trim();
   const gport = document.getElementById('global-port').value.trim();
-  let url = `/api/run?dir=${encodeURIComponent(selectedDir)}`;
+  let url = `api/run?dir=${encodeURIComponent(selectedDir)}`;
   if (deploy) url += `&deploy=${encodeURIComponent(deploy)}`;
   if (server) url += `&server=${encodeURIComponent(server)}`;
   if (gport) url += `&port=${encodeURIComponent(gport)}`;
@@ -383,7 +383,7 @@ <h2 id="title">Select an example</h2>
 }
 
 async function loadHistory(dir) {
-  const res = await fetch('/api/history?dir='+encodeURIComponent(dir));
+  const res = await fetch('api/history?dir='+encodeURIComponent(dir));
   const recs = await res.json() || [];
   const panel = document.getElementById('checks-list');
   // Remove existing history section before re-appending.
@@ -593,7 +593,7 @@ <h2 id="title">Select an example</h2>
 
 function runOneCollect(item) {
   return new Promise(resolve => {
-    let runURL = `/api/run?dir=${encodeURIComponent(item.dir)}`;
+    let runURL = `api/run?dir=${encodeURIComponent(item.dir)}`;
     const gd = document.getElementById('global-deploy').value.trim();
     if (gd) runURL += `&deploy=${encodeURIComponent(gd)}`;
     const gp = document.getElementById('global-port').value.trim();
@@ -708,7 +708,7 @@ <h2 id="title">Select an example</h2>
   subRows = []; subBaseline = null;
   document.getElementById('log-panel').innerHTML = '<div class="welcome">Testing… results appear when each proxy finishes.</div>';
 
-  fetch('/api/sub', {
+  fetch('api/sub', {
     method: 'POST', headers: {'Content-Type':'application/json'},
     body: JSON.stringify({sub_url: url, text: text, full: full, submit: submit})
   }).then(resp => {
@@ -735,7 +735,37 @@ <h2 id="title">Select an example</h2>
   }).catch(() => { btn.disabled=false; btn.textContent='▶ Test Proxies'; });
 };
 
-applyMode('config');
+// URL parameters + sub-only mode.
+//   ?sub=<url>      pre-fill the subscription URL (and switch to sub mode)
+//   ?text=<links>   pre-fill the proxy-links box (newline or comma separated)
+//   ?full=1         tick the full-suite box
+//   ?run=1          auto-start the test once filled
+//   ?subonly=1      hide the mode tabs entirely — subscription-only UI
+// A build-time default is exposed as window.SUB_ONLY (set by `serve --sub-only`).
+(function initFromURL() {
+  const q = new URLSearchParams(location.search);
+  const subOnly = window.SUB_ONLY || q.get('subonly') === '1' || q.get('subonly') === 'true';
+  const sub = q.get('sub');
+  const text = q.get('text');
+  const full = q.get('full') === '1' || q.get('full') === 'true';
+
+  if (subOnly) {
+    document.getElementById('mode-tabs').style.display = 'none';
+    applyMode('sub');
+  } else {
+    applyMode('config');
+  }
+
+  if (sub || text || subOnly) applyMode('sub');
+  if (sub)  document.getElementById('sub-url').value = sub;
+  if (text) document.getElementById('sub-text').value = text.replace(/,/g, '\n');
+  if (full) document.getElementById('sub-full').checked = true;
+
+  if ((sub || text) && (q.get('run') === '1' || q.get('run') === 'true')) {
+    document.getElementById('btn-test-sub').click();
+  }
+})();
+
 loadExamples();
 </script>
 </body>