magic-agent 1.0.0

package/internal/client/cors_test.go

@@ -0,0 +1,136 @@
+package client
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+/* 跨源这一层是移动端实测逼出来的：容器页面的源是 https://localhost，插件在局域网 IP，
+ * 天生跨源。没有 CORS 头时浏览器直接掐掉响应 —— 现象是 APK 装得上、闸门页打得开，
+ * 但探活永远停在「连接中…」。**curl 不主动带 Origin，所以接口级验证永远看不见这条**。
+ */
+func TestCORSForLocalOrigins(t *testing.T) {
+	svc := newTestService(t, fakeCore(t, goodContract))
+	srv := httptest.NewServer(svc.Handler())
+	defer srv.Close()
+
+	do := func(method, path, origin string, withToken bool, preflight bool) *http.Response {
+		t.Helper()
+		req, err := http.NewRequest(method, srv.URL+path, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if origin != "" {
+			req.Header.Set("Origin", origin)
+		}
+		if preflight {
+			req.Header.Set("Access-Control-Request-Method", "GET")
+			req.Header.Set("Access-Control-Request-Headers", "x-magic-token")
+		}
+		if withToken {
+			req.Header.Set("X-Magic-Token", "tok")
+		}
+		res, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return res
+	}
+
+	t.Run("预检不带令牌也必须放行（否则浏览器把真请求判死）", func(t *testing.T) {
+		res := do(http.MethodOptions, "/desk/health", "https://localhost", false, true)
+		defer res.Body.Close()
+		if res.StatusCode != http.StatusNoContent {
+			t.Fatalf("预检期望 204，得到 %d", res.StatusCode)
+		}
+		if got := res.Header.Get("Access-Control-Allow-Origin"); got != "https://localhost" {
+			t.Fatalf("期望回显 Origin，得到 %q", got)
+		}
+		if h := res.Header.Get("Access-Control-Allow-Headers"); !containsFold(h, "x-magic-token") {
+			t.Fatalf("允许头里必须有点名 X-Magic-Token，得到 %q", h)
+		}
+	})
+
+	t.Run("容器源的正常请求要带 ACAO", func(t *testing.T) {
+		res := do(http.MethodGet, "/desk/health", "https://localhost", true, false)
+		defer res.Body.Close()
+		if res.StatusCode != http.StatusOK {
+			t.Fatalf("期望 200，得到 %d", res.StatusCode)
+		}
+		if got := res.Header.Get("Access-Control-Allow-Origin"); got != "https://localhost" {
+			t.Fatalf("期望 ACAO=https://localhost，得到 %q", got)
+		}
+		if v := res.Header.Values("Vary"); !containsFold(join(v), "origin") {
+			t.Fatalf("必须 Vary: Origin，否则缓存会把一个源的响应喂给另一个源：%v", v)
+		}
+	})
+
+	t.Run("本机别的源（桌面壳的 loopback 端口）也放行", func(t *testing.T) {
+		res := do(http.MethodGet, "/desk/health", "http://127.0.0.1:5173", true, false)
+		defer res.Body.Close()
+		if got := res.Header.Get("Access-Control-Allow-Origin"); got != "http://127.0.0.1:5173" {
+			t.Fatalf("期望回显 loopback 源，得到 %q", got)
+		}
+	})
+
+	t.Run("iOS 容器的自定义 scheme 放行", func(t *testing.T) {
+		res := do(http.MethodGet, "/desk/health", "capacitor://localhost", true, false)
+		defer res.Body.Close()
+		if got := res.Header.Get("Access-Control-Allow-Origin"); got != "capacitor://localhost" {
+			t.Fatalf("期望回显 capacitor://，得到 %q", got)
+		}
+	})
+
+	t.Run("外站不给 CORS 头（后面是执行面，不能给任意网页开门）", func(t *testing.T) {
+		res := do(http.MethodGet, "/desk/health", "https://evil.example", true, false)
+		defer res.Body.Close()
+		if got := res.Header.Get("Access-Control-Allow-Origin"); got != "" {
+			t.Fatalf("外站不该拿到 ACAO，得到 %q", got)
+		}
+		// 令牌仍然是唯一门锁：没令牌时即便源合法也是 401
+		res2 := do(http.MethodGet, "/desk/health", "https://localhost", false, false)
+		defer res2.Body.Close()
+		if res2.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("没令牌期望 401，得到 %d", res2.StatusCode)
+		}
+	})
+}
+
+func containsFold(s, sub string) bool {
+	return len(s) >= len(sub) && (indexFold(s, sub) >= 0)
+}
+
+func indexFold(s, sub string) int {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		match := true
+		for j := 0; j < len(sub); j++ {
+			a, b := s[i+j], sub[j]
+			if 'A' <= a && a <= 'Z' {
+				a += 'a' - 'A'
+			}
+			if 'A' <= b && b <= 'Z' {
+				b += 'a' - 'A'
+			}
+			if a != b {
+				match = false
+				break
+			}
+		}
+		if match {
+			return i
+		}
+	}
+	return -1
+}
+
+func join(v []string) string {
+	out := ""
+	for i, s := range v {
+		if i > 0 {
+			out += ","
+		}
+		out += s
+	}
+	return out
+}

package/internal/client/lan.go

@@ -0,0 +1,68 @@
+package client
+
+import (
+	"fmt"
+	"net"
+	"strings"
+)
+
+/* 局域网接入（P4 的第一级：让手机能连上）。
+ *
+ * 默认只绑 127.0.0.1 是刻意的：本地端口对同机所有进程可见，开了鉴权才敢往外露。
+ * 手机要连就得绑到局域网，而这一开，**令牌就成了唯一的门锁** —— 所以这里的两条
+ * 守卫是配套的：`--lan` 必须给足强度的令牌，短令牌直接拒绝启动。
+ *
+ * 三级接入里这一级是 L1（局域网）；L2 的跨网中继需要服务端，不在本文件范围。
+ */
+
+// MinLanTokenLen 绑到局域网时令牌的最小长度（字符）。
+// 为什么是 24：局域网内能被扫到，短令牌（哪怕 6 位）在本地网络里是可以暴力猜的。
+// 生成的默认令牌是 16 字节 = 32 个十六进制字符，远超这条线。
+const MinLanTokenLen = 24
+
+// ValidateLanToken 检查绑到局域网时的令牌强度。
+func ValidateLanToken(token string) error {
+	tok := strings.TrimSpace(token)
+	if tok == "" {
+		return fmt.Errorf("绑到局域网不允许空令牌：空令牌会让鉴权整体失效（等于没有门锁）")
+	}
+	if len(tok) < MinLanTokenLen {
+		return fmt.Errorf("绑到局域网的令牌至少要 %d 个字符（当前 %d 个）：局域网内能被扫到，短令牌不安全",
+			MinLanTokenLen, len(tok))
+	}
+	return nil
+}
+
+// LanAddresses 列出本机可用于局域网访问的 IPv4 地址（形如 `192.168.1.5:50022`）。
+//
+// 过滤掉回环、链路本地（169.254.x）与非 IPv4：这三类给手机都没用。
+// 一台机器可能有多个（有线 + 无线 + 虚拟网卡），所以返回切片让调用方全都打印出来 ——
+// 猜错网卡比多打两行地址麻烦得多。
+func LanAddresses(port int) []string {
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		return nil
+	}
+	var out []string
+	for _, ifc := range ifaces {
+		if ifc.Flags&net.FlagUp == 0 || ifc.Flags&net.FlagLoopback != 0 {
+			continue
+		}
+		addrs, err := ifc.Addrs()
+		if err != nil {
+			continue
+		}
+		for _, a := range addrs {
+			ipnet, ok := a.(*net.IPNet)
+			if !ok {
+				continue
+			}
+			ip4 := ipnet.IP.To4()
+			if ip4 == nil || ip4.IsLoopback() || ip4.IsLinkLocalUnicast() {
+				continue
+			}
+			out = append(out, fmt.Sprintf("%s:%d", ip4.String(), port))
+		}
+	}
+	return out
+}

package/internal/client/lan_test.go

@@ -0,0 +1,53 @@
+package client
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestValidateLanToken 绑到局域网时令牌就是唯一门锁，短的一律拒绝。
+func TestValidateLanToken(t *testing.T) {
+	cases := []struct {
+		name  string
+		token string
+		want  bool // true = 通过
+	}{
+		{"空令牌", "", false},
+		{"纯空格", "    ", false},
+		{"短令牌", "abc123", false},
+		{"差一字符", strings.Repeat("a", MinLanTokenLen-1), false},
+		{"刚够", strings.Repeat("a", MinLanTokenLen), true},
+		{"生成的 32 位十六进制", "0123456789abcdef0123456789abcdef", true},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			err := ValidateLanToken(c.token)
+			if c.want && err != nil {
+				t.Errorf("应通过，却报错：%v", err)
+			}
+			if !c.want && err == nil {
+				t.Error("应拒绝，却通过了")
+			}
+		})
+	}
+}
+
+// TestLanAddresses 返回的地址里不能有回环或链路本地 —— 那两类给手机都没用。
+func TestLanAddresses(t *testing.T) {
+	got := LanAddresses(50022)
+	for _, a := range got {
+		if strings.HasPrefix(a, "127.") || strings.HasPrefix(a, "169.254.") {
+			t.Errorf("不该出现回环/链路本地地址：%s", a)
+		}
+		if !strings.HasSuffix(a, ":50022") {
+			t.Errorf("应带上端口：%s", a)
+		}
+		if i := strings.Index(a, ":"); i > 0 {
+			if strings.Contains(a[:i], ":") {
+				t.Errorf("IPv6 不该出现在这个列表里：%s", a)
+			}
+		}
+	}
+	// 本机可能只连着回环（离线环境），所以不要求非空，只在有结果时做上面的形状断言。
+	t.Logf("局域网地址：%v", got)
+}

package/internal/client/pair.go

@@ -0,0 +1,163 @@
+package client
+
+import (
+	"fmt"
+	"net/http"
+	neturl "net/url"
+	"strings"
+
+	qrcode "github.com/skip2/go-qrcode"
+)
+
+/* 二维码配对：把「桌面地址 + 令牌」变成手机能扫的一串东西。
+ *
+ * ── 为什么由插件出这张码 ──
+ * 插件是**唯一**知道真实监听地址与端口的地方（端口从 0 起、由系统分配，profile 里没有）。
+ * 手机端只负责「扫到什么就连什么」，不承担任何拼装责任 —— 拼装一旦分散到两端，
+ * 就会出现「地址看着对、其实少一段路径」这类最难查的问题。
+ *
+ * ── 地址从哪来：请求本身 ──
+ * 配对地址用 `r.Host` 拼（即「你是怎么打开这个页面的」），端口自然就对。
+ * 所以启动时会把 `/pair` 页面**按每个网卡地址各打印一条链接**：在桌面上点局域网那条，
+ * 码里就是局域网地址；点回环那条，码里就是回环地址。不需要再往 Options 里塞端口。
+ *
+ * ── 安全口径：用令牌本身把门 ──
+ * 这张码的内容就是令牌，所以 `/pair*` 走**普通鉴权**（要带 token）。
+ * 拿到令牌的人本来就拥有令牌，看这个页面没有任何提权 —— 而没令牌的人看到的只是 401。
+ *
+ * ⚠️ 我最初写的是「只允许 remote addr 是回环」，那是错的：桌面浏览器点局域网链接打开
+ * `/pair` 时，源地址就是本机的局域网 IP（macOS 连自己也是走网卡地址），会被判 403，
+ * 而那条链接正是我打印给用户点的。**守卫拦住的必须是攻击者，不能是正确用法**。
+ */
+
+// pairURL 拼出配对地址：**外部入口**优先，退回请求自身的 host（含端口），带上令牌。
+//
+// ⚠️ 为什么要认 X-Forwarded-*：隧道 / nginx 这类入口要在这里终止 TLS，源侧收到的是明文
+// HTTP —— 请求本身看不出「外面其实是 https」。第一版写死 `http://` + `r.Host`，隧道下
+// 生成的二维码就编成了 `http://<公网域名>/?token=…`：手机扫出来的一瞬间，令牌跟着一条
+// 明文请求先发到边缘节点。能不能靠 301 跳回 https 是另一回事，**不该拿跳转当密钥的兜底**。
+// （这条是隧道实测暴露的，不是推演出来的。）
+//
+// 信任边界：这两个头能被本机进程伪造。但 /pair* 本来就走令牌鉴权，能伪造的人已经持有令牌，
+// 它能改变的只是「二维码写给谁看」；真正要挡的没令牌的人连这个页面都拿不到。
+func (s *Service) pairURL(r *http.Request) string {
+	scheme, host := pairTarget(r)
+	u := scheme + "://" + host + "/"
+	if s.opts.Token != "" {
+		u += "?token=" + s.opts.Token
+	}
+	return u
+}
+
+// pairTarget 求出「手机该连哪儿」：外部入口给的 scheme+host，没有就退回请求自身的。
+//
+// 单独抽出来是因为 /desk/pair 也要报同一个 host —— 两处各拼一次就会漂移，
+// 而这类漂移的表现是「壳里显示的地址是对的、二维码扫出来是错的」，最难查。
+func pairTarget(r *http.Request) (scheme, host string) {
+	scheme = "http"
+	if p := firstForwarded(r.Header.Get("X-Forwarded-Proto")); p != "" {
+		scheme = p
+	}
+	host = firstForwarded(r.Header.Get("X-Forwarded-Host"))
+	if host == "" {
+		host = r.Host
+	}
+	if host == "" {
+		host = "127.0.0.1"
+	}
+	return scheme, host
+}
+
+// firstForwarded 取逗号分隔转发头的第一段（`a, b` → `a`）并去掉空白：
+// 代理链会把多跳叠成一串，最左边那个才代表最初的客户端。
+func firstForwarded(v string) string {
+	if i := strings.Index(v, ","); i >= 0 {
+		v = v[:i]
+	}
+	return strings.TrimSpace(v)
+}
+
+// handlePairInfo 机器读：给壳 / 自动化用。
+//
+// host 给的是**外部**主机（与 url / 二维码一致）；requestHost 另给一份原始值做排障 ——
+// 隧道下这两个不一样（原始值是 127.0.0.1:端口），而壳真正要用的是前者。
+func (s *Service) handlePairInfo(w http.ResponseWriter, r *http.Request) {
+	_, host := pairTarget(r)
+	writeJSON(w, http.StatusOK, map[string]any{
+		"url":         s.pairURL(r),
+		"host":        host,
+		"requestHost": r.Host,
+		"hint":        "手机端扫 /pair 页面上的二维码；地址与令牌都在这个 url 里。",
+	})
+}
+
+// handlePairQR 二维码 PNG。
+func (s *Service) handlePairQR(w http.ResponseWriter, r *http.Request) {
+	png, err := qrcode.Encode(s.pairURL(r), qrcode.Medium, 512)
+	if err != nil {
+		writeErr(w, http.StatusInternalServerError, "生成二维码失败: "+err.Error())
+		return
+	}
+	w.Header().Set("Content-Type", "image/png")
+	w.Header().Set("Cache-Control", "no-store") // 令牌可能在变，别缓存
+	_, _ = w.Write(png)
+}
+
+// handlePairPage 人看的页面：桌面浏览器打开，手机扫屏幕。
+func (s *Service) handlePairPage(w http.ResponseWriter, r *http.Request) {
+	url := s.pairURL(r)
+
+	/* 只显示「地址」和「令牌」两段，方便手抄兜底；整条 url 也一并给出便于复制。
+	   页面本身不含任何脚本 —— 它就一张图加几行字，没有可被注入的面。 */
+	addr, token := url, ""
+	if i := strings.Index(url, "?token="); i >= 0 {
+		addr, token = url[:i], url[i+len("?token="):]
+	}
+
+	page := `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>掌天瓶 · 配对</title>
+<style>
+ body{margin:0;background:#0A0A0B;color:#FAFAFA;padding:30px 24px 44px;
+      font:15px/1.65 -apple-system,BlinkMacSystemFont,"PingFang SC","Noto Sans CJK SC",sans-serif}
+ h1{font-size:20px;margin:0 0 6px} .sub{color:#8A8A8F;font-size:13px;margin:0 0 24px}
+ .qr{background:#fff;padding:14px;border-radius:18px;width:max-content;margin:0 auto 22px}
+ .qr img{display:block;width:272px;height:272px;image-rendering:pixelated}
+ .row{background:#141416;border:1px solid #232327;border-radius:14px;padding:14px 16px;margin-bottom:10px}
+ .k{color:#8A8A8F;font-size:12px;margin-bottom:4px}
+ .v{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:14px;word-break:break-all}
+ ol{color:#8A8A8F;font-size:13px;padding-left:20px;margin:22px 0 0}
+ li{margin:5px 0}
+</style></head><body>
+ <h1>掌天瓶 · 配对</h1>
+ <p class="sub">用手机上的掌天瓶 App 扫下面这张码。手机要和这台电脑在同一个网络里。</p>
+ <div class="qr"><img src="/pair/qr.png?token=__TOKENRAW__" alt="配对二维码"></div>
+ <div class="row"><div class="k">桌面地址</div><div class="v">__ADDR__</div></div>
+ <div class="row"><div class="k">令牌</div><div class="v">__TOKEN__</div></div>
+ <ol>
+  <li><b>推荐</b>：把上面「桌面地址」那一整行复制到手机（微信、隔空投送都行），
+      在 App 的配对页粘进地址栏 —— 它会自动拆出令牌，不用手抄。</li>
+  <li>或者用手机<b>系统相机</b>扫上面这张码：会在浏览器里打开同一套界面（走网页版，不是 App）。</li>
+  <li>App 内的相机扫码还没做。连不上时先确认桌面是以局域网方式起的，且两边在同一个 Wi-Fi。</li>
+ </ol>
+</body></html>`
+
+	page = strings.ReplaceAll(page, "__ADDR__", htmlEscape(addr))
+	page = strings.ReplaceAll(page, "__TOKEN__", htmlEscape(token))
+	/* ⚠️ 二维码图必须**自带令牌**：`<img>` 是浏览器自己发起的子资源请求，带不上
+	   `X-Magic-Token` 头，而 /pair/qr.png 走的是普通鉴权 —— 第一版我写成 src="/pair/qr.png"，
+	   结果页面上永远只有一张 401 的碎图，也就是「没看到二维码」。
+	   同一类坑在模块那边也踩过（产物缩略图），凡是子资源都要把令牌放进 URL。 */
+	page = strings.ReplaceAll(page, "__TOKENRAW__", neturl.QueryEscape(token))
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = fmt.Fprint(w, page)
+}
+
+// htmlEscape 最小转义：这个页面里只插两段我们自己生成的值，但仍然不信任地转义 ——
+// 一旦哪天有人把 Host 头指过来，未转义就是一个反射点。
+func htmlEscape(s string) string {
+	r := strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&#39;")
+	return r.Replace(s)
+}

package/internal/client/pair_test.go

@@ -0,0 +1,109 @@
+package client
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+/* 配对地址是「手机该连哪儿」的唯一来源，所以它必须跟着**用户实际打开的那个入口**走。
+ *
+ * 这条测试是隧道实测逼出来的：源侧收到的是明文 HTTP（TLS 在边缘终止），
+ * 只认 r.Host + 写死 http:// 时，隧道下生成的二维码编成了
+ * `http://<公网域名>/?token=…` —— 手机一扫，令牌先跟着一条明文请求出门。
+ */
+func TestPairURLFollowsForwardedHeaders(t *testing.T) {
+	svc := newTestService(t, fakeCore(t, goodContract))
+	srv := httptest.NewServer(svc.Handler())
+	defer srv.Close()
+
+	pairInfo := func(hdrs map[string]string) (url, host string) {
+		t.Helper()
+		req, err := http.NewRequest(http.MethodGet, srv.URL+"/desk/pair?token=tok", nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for k, v := range hdrs {
+			req.Header.Set(k, v)
+		}
+		res, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+		var out struct {
+			URL  string `json:"url"`
+			Host string `json:"host"`
+		}
+		if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+			t.Fatal(err)
+		}
+		return out.URL, out.Host
+	}
+
+	t.Run("没有转发头：退回请求自身的 host", func(t *testing.T) {
+		url, host := pairInfo(nil)
+		if !strings.HasPrefix(url, "http://127.0.0.1:") {
+			t.Fatalf("期望回环地址，得到 %q", url)
+		}
+		if !strings.HasSuffix(url, "/?token=tok") {
+			t.Fatalf("令牌没带上：%q", url)
+		}
+		if !strings.HasPrefix(host, "127.0.0.1:") {
+			t.Fatalf("host 期望是回环，得到 %q", host)
+		}
+	})
+
+	t.Run("隧道/nginx：跟随 X-Forwarded-Proto 与 Host", func(t *testing.T) {
+		url, host := pairInfo(map[string]string{
+			"X-Forwarded-Proto": "https",
+			"X-Forwarded-Host":  "pub.example.com",
+		})
+		// 这一条就是实测里失败的那一条：https 入口不能生成 http:// 的二维码。
+		if url != "https://pub.example.com/?token=tok" {
+			t.Fatalf("期望 https://pub.example.com/?token=tok，得到 %q", url)
+		}
+		if host != "pub.example.com" {
+			t.Fatalf("host 期望 pub.example.com，得到 %q", host)
+		}
+	})
+
+	t.Run("代理链叠成一串时只取第一段", func(t *testing.T) {
+		url, _ := pairInfo(map[string]string{
+			"X-Forwarded-Proto": "https, http",
+			"X-Forwarded-Host":  "pub.example.com, inner.local:8080",
+		})
+		if url != "https://pub.example.com/?token=tok" {
+			t.Fatalf("期望取第一段，得到 %q", url)
+		}
+	})
+
+	t.Run("二维码内容与 /desk/pair 一致", func(t *testing.T) {
+		req, err := http.NewRequest(http.MethodGet, srv.URL+"/pair/qr.png?token=tok", nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		req.Header.Set("X-Forwarded-Proto", "https")
+		req.Header.Set("X-Forwarded-Host", "pub.example.com")
+		res, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+		/* 这里不断言图片像素（那是解码器的活，已经在真机上验过），只钉住
+		   「同一份请求头，两条路径不会给出两个不同地址」这个前提 ——
+		   它们共用一个 pairURL，一旦有人把其中一条改成各自拼，这条就会红。 */
+		if ct := res.Header.Get("Content-Type"); ct != "image/png" {
+			t.Fatalf("期望 image/png，得到 %q", ct)
+		}
+		url, _ := pairInfo(map[string]string{
+			"X-Forwarded-Proto": "https",
+			"X-Forwarded-Host":  "pub.example.com",
+		})
+		if svc.opts.Token != "tok" || !strings.Contains(url, "token=tok") {
+			t.Fatalf("配对信息里没有令牌：%q", url)
+		}
+	})
+}