feat(plugins): 给 Lua 插件加受限出站 HTTP（__llmsproxy_http）

billing 插件从不主动出站——它报告的一切都随网关转发请求时的 hook payload 一起到达。额度插件是第一个必须自己发请求的东西：套餐余量不主动问就拿不到。问题在于这恰好是插件模型最锋利的边。插件是 WebUI 文本框里装进来的单个 .lua 文件，跑在网关进程里：给它一个通用 HTTP 客户端，等于让每次安装都成为一件常备的 SSFP 工具，还顺带打开了读环境变量拿凭据的第二扇门。所以这个桥刻意做窄： - 目标必须命中某个「已配置源」已经在通信的主机。那些是运维声明过的，不是插件声明的——插件无法靠编一个 URL 扩大自己的触及面，而源的主机正是本部署已经愿意交付 API key 的那批上游。 - 非 loopback 主机上拒绝明文 http。凭据只该走 HTTPS。 - loopback 免登记：它出不了本机，而 billing 规则页读网关自己的 API 正是这么做的。 - 每请求都有超时、响应体有 4MiB 上限，插件无法占死 worker 或吃光内存。 - 绝不从环境变量读凭据。需要 key 的插件必须被显式给（state 或调用方配置），这样授权对运维可见，而不是环境里默默存在的东西。 - 不跟随重定向：白名单是逐跳检查的，跟随就等于绕过它，3xx 原样返回。能力只装在插件运行时（bootPluginState），不装进 setupGlobals——后者被 adapter 池共用，adapter 是运维的配置而非安装的代码。判据 8 条钉的是拒绝路径而非快乐路径：未登记主机（含 169.254.169.254、后缀欺骗 api.example.com.evil.test）、明文 http、空名单必须全拒、不得跟随重定向、超时与响应体被钳制、超大响应宁可报错也不截断（截断会解析成损坏 JSON，插件会报解析错而不是真因）。测试当场抓到一个真 bug：loopback 被白名单一起拦了，与代码注释里「loopback 免登记」自相矛盾。变异（把主机检查换成 if false）被 3 条判据抓住。 Co-Authored-By: ModelRouter <noreply@modelrouter.dev> (cherry picked from commit 0fbb8e5e88) (cherry picked from commit e76e1623e4)
2026-11-07 09:47:23 +00:00 · 2026-10-04 07:43:56 +08:00
parent 0bf0653d00
commit a2bb6de9fb
5 changed files with 579 additions and 2 deletions
--- a/internal/lua/plugin_http.go
+++ b/internal/lua/plugin_http.go
@ -0,0 +1,248 @@
+package lua
+
+// Outbound HTTP for plugins.
+//
+// The billing plugin never needed this: everything it reports arrives on a hook
+// payload that the gateway produced while forwarding a request. A quota plugin
+// is the first thing that must REACH OUT on its own — Command Code exposes
+// /alpha/billing/credits and friends, and there is no way to learn a plan's
+// remaining balance without asking.
+//
+// That capability is also the sharpest edge in the plugin model. A plugin is a
+// single .lua file the WebUI installs from a textarea: untrusted, browser-facing
+// code that runs in the gateway process. Handing it a general-purpose HTTP
+// client would make every install a standing SSRF primitive against whatever
+// the gateway can reach — the cloud metadata endpoint, the cluster control
+// plane, whatever else sits on 127.0.0.1 in this deployment. Reading the
+// environment for credentials is a second door out.
+//
+// So the bridge is deliberately narrow:
+//
+//   - Destination must match a host that a CONFIGURED SOURCE already talks to.
+//     Those are operator-declared, not plugin-declared: a plugin cannot widen
+//     its own reach by inventing a URL, and an existing source's host is
+//     exactly the set of upstreams this deployment already trusts with API keys.
+//   - http:// on a non-loopback host is refused. Credentials belong in HTTPS.
+//   - Loopback needs no explicit opt-in: it is the only way a plugin can read
+//     the gateway's own API (the billing rules UI does exactly that), and it
+//     cannot leave the machine.
+//   - Every request is bounded by a timeout and the response is size-capped, so
+//     a plugin cannot wedge a worker goroutine or exhaust memory.
+//   - Credentials are NEVER read from the environment here. A plugin that needs
+//     a key must be given it (state, or the caller's own config), which keeps
+//     the grant visible to the operator instead of silently ambient.
+//
+// Redirects are NOT followed: the allowlist is checked per hop, and a redirect
+// to an unlisted host would otherwise walk straight past it. A 3xx is returned
+// as-is so the plugin can see it.
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	golua "github.com/aarzilli/golua/lua"
+)
+
+// httpDefaultTimeout bounds a whole request; httpMaxResponseBytes caps the body
+// a plugin can pull into the gateway's heap.
+const (
+	httpDefaultTimeout = 15 * time.Second
+	httpMaxTimeout     = 60 * time.Second
+	httpMaxResponse    = 4 << 20 // 4 MiB
+)
+
+// httpClient is shared by every plugin request. It deliberately has no
+// ProxyFromEnvironment: an operator who proxies upstreams configures the proxy
+// per source, and a plugin request should not silently inherit one.
+var httpClient = &http.Client{
+	Timeout: httpDefaultTimeout,
+	Transport: &http.Transport{
+		Proxy:                 nil,
+		DialContext:           (&net.Dialer{Timeout: 10 * time.Second, KeepAlive: 30 * time.Second}).DialContext,
+		ForceAttemptHTTP2:     true,
+		MaxIdleConns:          16,
+		IdleConnTimeout:       60 * time.Second,
+		TLSHandshakeTimeout:   10 * time.Second,
+		ExpectContinueTimeout: time.Second,
+	},
+	// See above: a redirect is a hop the allowlist has not seen.
+	CheckRedirect: func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse
+	},
+}
+
+// httpGlobal is the Lua name of the outbound bridge.
+const httpGlobal = "__llmsproxy_http"
+
+// httpAllowlist is the set of hosts plugins may contact: the host of every
+// configured source's base_url.
+type httpAllowlist struct {
+	hosts map[string]bool
+}
+
+func newHTTPAllowlist(hosts []string) *httpAllowlist {
+	m := make(map[string]bool, len(hosts))
+	for _, h := range hosts {
+		if h != "" {
+			m[strings.ToLower(h)] = true
+		}
+	}
+	return &httpAllowlist{hosts: m}
+}
+
+// allows reports whether host:port may be contacted. Ports 80/443 are implied
+// by the bare host so a source configured as https://api.example.com/v1 does not
+// have to spell the port.
+func (a *httpAllowlist) allows(host string, port string) bool {
+	host = strings.ToLower(host)
+	if host == "" {
+		return false
+	}
+	if a.hosts[host] {
+		return true
+	}
+	switch port {
+	case "", "80", "443":
+		return a.hosts[host]
+	}
+	return a.hosts[net.JoinHostPort(host, port)]
+}
+
+// checkURL validates a plugin-supplied URL against the allowlist. It returns
+// the parsed URL plus a reason when it is refused.
+func (a *httpAllowlist) checkURL(raw string) (*url.URL, error) {
+	u, err := url.Parse(strings.TrimSpace(raw))
+	if err != nil {
+		return nil, fmt.Errorf("bad url: %v", err)
+	}
+	switch strings.ToLower(u.Scheme) {
+	case "https":
+	case "http":
+		// Plain HTTP is only tolerated on loopback, where it stays on this
+		// machine and is how the gateway's own plain-HTTP dev port is reached.
+		if !isLoopbackHost(u.Hostname()) {
+			return nil, fmt.Errorf("refusing plain http to non-loopback host %q: use https", u.Hostname())
+		}
+	default:
+		return nil, fmt.Errorf("unsupported scheme %q", u.Scheme)
+	}
+	if !a.allows(u.Hostname(), u.Port()) && !isLoopbackHost(u.Hostname()) {
+		// Loopback needs no entry: it cannot leave the machine, and the billing
+		// rules UI reads the gateway's own API over plain HTTP in dev setups.
+		return nil, fmt.Errorf("host %q is not an allowed outbound destination "+
+			"(allowed: the hosts of configured sources, plus loopback)", u.Hostname())
+	}
+	return u, nil
+}
+
+func isLoopbackHost(h string) bool {
+	if h == "localhost" {
+		return true
+	}
+	ip := net.ParseIP(strings.Trim(h, "[]"))
+	return ip != nil && ip.IsLoopback()
+}
+
+// httpRequestSpec is the decoded argument table Lua passes to __llmsproxy_http.
+type httpRequestSpec struct {
+	URL     string
+	Method  string
+	Headers map[string]string
+	Body    string
+	Timeout time.Duration
+}
+
+// luaHTTPFn builds the golua closure. It takes one Lua table argument and
+// returns (responseTable, nil) or (nil, errorMessage) — never raises, so a
+// plugin mistake cannot take the gateway with it.
+func luaHTTPFn(L *golua.State, allow *httpAllowlist) golua.LuaGoFunction {
+	return func(L *golua.State) int {
+		spec, err := readHTTPRequestSpec(L)
+		if err != nil {
+			L.PushNil()
+			L.PushString(err.Error())
+			return 2
+		}
+		u, err := allow.checkURL(spec.URL)
+		if err != nil {
+			L.PushNil()
+			L.PushString(err.Error())
+			return 2
+		}
+		resp, err := performHTTP(u, spec)
+		if err != nil {
+			L.PushNil()
+			L.PushString(err.Error())
+			return 2
+		}
+		pushHTTPResponse(L, resp)
+		L.PushNil()
+		return 2
+	}
+}
+
+func performHTTP(u *url.URL, spec httpRequestSpec) (*httpResult, error) {
+	method := strings.ToUpper(spec.Method)
+	if method == "" {
+		method = http.MethodGet
+	}
+	timeout := spec.Timeout
+	if timeout <= 0 || timeout > httpMaxTimeout {
+		timeout = httpDefaultTimeout
+	}
+
+	var body io.Reader
+	if spec.Body != "" {
+		body = strings.NewReader(spec.Body)
+	}
+	req, err := http.NewRequest(method, u.String(), body)
+	if err != nil {
+		return nil, fmt.Errorf("build request: %v", err)
+	}
+	for k, v := range spec.Headers {
+		req.Header.Set(k, v)
+	}
+	if req.Header.Get("User-Agent") == "" {
+		req.Header.Set("User-Agent", "ModelRouter-plugin")
+	}
+
+	client := *httpClient
+	client.Timeout = timeout
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, httpMaxResponse+1))
+	if err != nil {
+		return nil, fmt.Errorf("read body: %v", err)
+	}
+	if len(data) > httpMaxResponse {
+		return nil, fmt.Errorf("response exceeds %d byte cap", httpMaxResponse)
+	}
+	return &httpResult{
+		Status:  resp.StatusCode,
+		Headers: flattenHeaders(resp.Header),
+		Body:    string(data),
+	}, nil
+}
+
+type httpResult struct {
+	Status  int
+	Headers map[string]string
+	Body    string
+}
+
+func flattenHeaders(h http.Header) map[string]string {
+	out := make(map[string]string, len(h))
+	for k := range h {
+		out[strings.ToLower(k)] = h.Get(k)
+	}
+	return out
+}