feat: backend core - auth, user, role, permission, device, webhook, monitoring, cache, repository, service, middleware, API handlers

2026-04-02 11:19:50 +08:00
parent e59a77bc49
commit dcc1f186f8
298 changed files with 62603 additions and 0 deletions
--- a/internal/util/urlvalidator/validator.go
+++ b/internal/util/urlvalidator/validator.go
@@ -0,0 +1,175 @@
+package urlvalidator
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type ValidationOptions struct {
+	AllowedHosts     []string
+	RequireAllowlist bool
+	AllowPrivate     bool
+}
+
+// ValidateHTTPURL validates an outbound HTTP/HTTPS URL.
+//
+// It provides a single validation entry point that supports:
+// - scheme 校验（https 或可选允许 http）
+// - 可选 allowlist（支持 *.example.com 通配）
+// - allow_private_hosts 策略（阻断 localhost/私网字面量 IP）
+//
+// 注意：DNS Rebinding 防护（解析后 IP 校验）应在实际发起请求时执行，避免 TOCTOU。
+func ValidateHTTPURL(raw string, allowInsecureHTTP bool, opts ValidationOptions) (string, error) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return "", errors.New("url is required")
+	}
+
+	parsed, err := url.Parse(trimmed)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return "", fmt.Errorf("invalid url: %s", trimmed)
+	}
+
+	scheme := strings.ToLower(parsed.Scheme)
+	if scheme != "https" && (!allowInsecureHTTP || scheme != "http") {
+		return "", fmt.Errorf("invalid url scheme: %s", parsed.Scheme)
+	}
+
+	host := strings.ToLower(strings.TrimSpace(parsed.Hostname()))
+	if host == "" {
+		return "", errors.New("invalid host")
+	}
+	if !opts.AllowPrivate && isBlockedHost(host) {
+		return "", fmt.Errorf("host is not allowed: %s", host)
+	}
+
+	if port := parsed.Port(); port != "" {
+		num, err := strconv.Atoi(port)
+		if err != nil || num <= 0 || num > 65535 {
+			return "", fmt.Errorf("invalid port: %s", port)
+		}
+	}
+
+	allowlist := normalizeAllowlist(opts.AllowedHosts)
+	if opts.RequireAllowlist && len(allowlist) == 0 {
+		return "", errors.New("allowlist is not configured")
+	}
+	if len(allowlist) > 0 && !isAllowedHost(host, allowlist) {
+		return "", fmt.Errorf("host is not allowed: %s", host)
+	}
+
+	parsed.Path = strings.TrimRight(parsed.Path, "/")
+	parsed.RawPath = ""
+	return strings.TrimRight(parsed.String(), "/"), nil
+}
+
+func ValidateURLFormat(raw string, allowInsecureHTTP bool) (string, error) {
+	// 最小格式校验：仅保证 URL 可解析且 scheme 合规，不做白名单/私网/SSRF 校验
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return "", errors.New("url is required")
+	}
+
+	parsed, err := url.Parse(trimmed)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return "", fmt.Errorf("invalid url: %s", trimmed)
+	}
+
+	scheme := strings.ToLower(parsed.Scheme)
+	if scheme != "https" && (!allowInsecureHTTP || scheme != "http") {
+		return "", fmt.Errorf("invalid url scheme: %s", parsed.Scheme)
+	}
+
+	host := strings.TrimSpace(parsed.Hostname())
+	if host == "" {
+		return "", errors.New("invalid host")
+	}
+
+	if port := parsed.Port(); port != "" {
+		num, err := strconv.Atoi(port)
+		if err != nil || num <= 0 || num > 65535 {
+			return "", fmt.Errorf("invalid port: %s", port)
+		}
+	}
+
+	return strings.TrimRight(trimmed, "/"), nil
+}
+
+func ValidateHTTPSURL(raw string, opts ValidationOptions) (string, error) {
+	return ValidateHTTPURL(raw, false, opts)
+}
+
+// ValidateResolvedIP 验证 DNS 解析后的 IP 地址是否安全
+// 用于防止 DNS Rebinding 攻击：在实际 HTTP 请求时调用此函数验证解析后的 IP
+func ValidateResolvedIP(host string) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	ips, err := net.DefaultResolver.LookupIP(ctx, "ip", host)
+	if err != nil {
+		return fmt.Errorf("dns resolution failed: %w", err)
+	}
+
+	for _, ip := range ips {
+		if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() ||
+			ip.IsLinkLocalMulticast() || ip.IsUnspecified() {
+			return fmt.Errorf("resolved ip %s is not allowed", ip.String())
+		}
+	}
+	return nil
+}
+
+func normalizeAllowlist(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	normalized := make([]string, 0, len(values))
+	for _, v := range values {
+		entry := strings.ToLower(strings.TrimSpace(v))
+		if entry == "" {
+			continue
+		}
+		if host, _, err := net.SplitHostPort(entry); err == nil {
+			entry = host
+		}
+		normalized = append(normalized, entry)
+	}
+	return normalized
+}
+
+func isAllowedHost(host string, allowlist []string) bool {
+	for _, entry := range allowlist {
+		if entry == "" {
+			continue
+		}
+		if strings.HasPrefix(entry, "*.") {
+			suffix := strings.TrimPrefix(entry, "*.")
+			if host == suffix || strings.HasSuffix(host, "."+suffix) {
+				return true
+			}
+			continue
+		}
+		if host == entry {
+			return true
+		}
+	}
+	return false
+}
+
+func isBlockedHost(host string) bool {
+	if host == "localhost" || strings.HasSuffix(host, ".localhost") {
+		return true
+	}
+	if ip := net.ParseIP(host); ip != nil {
+		if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || ip.IsUnspecified() {
+			return true
+		}
+	}
+	return false
+}
--- a/internal/util/urlvalidator/validator_test.go
+++ b/internal/util/urlvalidator/validator_test.go
@@ -0,0 +1,75 @@
+package urlvalidator
+
+import "testing"
+
+func TestValidateURLFormat(t *testing.T) {
+	if _, err := ValidateURLFormat("", false); err == nil {
+		t.Fatalf("expected empty url to fail")
+	}
+	if _, err := ValidateURLFormat("://bad", false); err == nil {
+		t.Fatalf("expected invalid url to fail")
+	}
+	if _, err := ValidateURLFormat("http://example.com", false); err == nil {
+		t.Fatalf("expected http to fail when allow_insecure_http is false")
+	}
+	if _, err := ValidateURLFormat("https://example.com", false); err != nil {
+		t.Fatalf("expected https to pass, got %v", err)
+	}
+	if _, err := ValidateURLFormat("http://example.com", true); err != nil {
+		t.Fatalf("expected http to pass when allow_insecure_http is true, got %v", err)
+	}
+	if _, err := ValidateURLFormat("https://example.com:bad", true); err == nil {
+		t.Fatalf("expected invalid port to fail")
+	}
+
+	// 验证末尾斜杠被移除
+	normalized, err := ValidateURLFormat("https://example.com/", false)
+	if err != nil {
+		t.Fatalf("expected trailing slash url to pass, got %v", err)
+	}
+	if normalized != "https://example.com" {
+		t.Fatalf("expected trailing slash to be removed, got %s", normalized)
+	}
+
+	// 验证多个末尾斜杠被移除
+	normalized, err = ValidateURLFormat("https://example.com///", false)
+	if err != nil {
+		t.Fatalf("expected multiple trailing slashes to pass, got %v", err)
+	}
+	if normalized != "https://example.com" {
+		t.Fatalf("expected all trailing slashes to be removed, got %s", normalized)
+	}
+
+	// 验证带路径的 URL 末尾斜杠被移除
+	normalized, err = ValidateURLFormat("https://example.com/api/v1/", false)
+	if err != nil {
+		t.Fatalf("expected trailing slash url with path to pass, got %v", err)
+	}
+	if normalized != "https://example.com/api/v1" {
+		t.Fatalf("expected trailing slash to be removed from path, got %s", normalized)
+	}
+}
+
+func TestValidateHTTPURL(t *testing.T) {
+	if _, err := ValidateHTTPURL("http://example.com", false, ValidationOptions{}); err == nil {
+		t.Fatalf("expected http to fail when allow_insecure_http is false")
+	}
+	if _, err := ValidateHTTPURL("http://example.com", true, ValidationOptions{}); err != nil {
+		t.Fatalf("expected http to pass when allow_insecure_http is true, got %v", err)
+	}
+	if _, err := ValidateHTTPURL("https://example.com", false, ValidationOptions{RequireAllowlist: true}); err == nil {
+		t.Fatalf("expected require allowlist to fail when empty")
+	}
+	if _, err := ValidateHTTPURL("https://example.com", false, ValidationOptions{AllowedHosts: []string{"api.example.com"}}); err == nil {
+		t.Fatalf("expected host not in allowlist to fail")
+	}
+	if _, err := ValidateHTTPURL("https://api.example.com", false, ValidationOptions{AllowedHosts: []string{"api.example.com"}}); err != nil {
+		t.Fatalf("expected allowlisted host to pass, got %v", err)
+	}
+	if _, err := ValidateHTTPURL("https://sub.api.example.com", false, ValidationOptions{AllowedHosts: []string{"*.example.com"}}); err != nil {
+		t.Fatalf("expected wildcard allowlist to pass, got %v", err)
+	}
+	if _, err := ValidateHTTPURL("https://localhost", false, ValidationOptions{AllowPrivate: false}); err == nil {
+		t.Fatalf("expected localhost to be blocked when allow_private_hosts is false")
+	}
+}