@opensoha/contracts 0.1.27 → 0.2.0

package/proxypolicy/narrow_test.go

@@ -0,0 +1,138 @@
+package proxypolicy
+
+import (
+	"encoding/json"
+	"reflect"
+	"testing"
+
+	api "github.com/opensoha/soha/contracts/gen/go/sohaapi"
+)
+
+func narrowFixture() ([]api.NetworkProxyGroup, []api.NetworkProxyRule) {
+	groups := []api.NetworkProxyGroup{{GroupID: "choice", Label: "Choice", Type: "select", NodeIDs: []string{"a", "b"}, SelectedNodeID: "a"}, {GroupID: "only-a", Label: "A", Type: "select", NodeIDs: []string{"a"}, SelectedNodeID: "a"}}
+	rules := []api.NetworkProxyRule{rule("mandatory", "organization_required", "domain", "example.invalid", "node"), rule("personal", "personal", "all", "", "group"), rule("empty-group", "organization_default", "all", "", "group"), rule("protected", "protection", "cidr", "10.0.0.0/8", "reject")}
+	rules[0].Action.TargetID = "a"
+	rules[0].Order = 9
+	rules[1].Action.TargetID = "choice"
+	rules[2].Action.TargetID = "only-a"
+	rules[2].Enabled = false
+	return groups, rules
+}
+func TestNarrowTargetsPreservesPolicyAndInput(t *testing.T) {
+	groups, rules := narrowFixture()
+	before, _ := json.Marshal([]any{groups, rules})
+	got, err := NarrowTargets(groups, rules, []string{"b"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Groups) != 1 || !reflect.DeepEqual(got.Groups[0].NodeIDs, []string{"b"}) || got.Groups[0].SelectedNodeID != "" {
+		t.Fatalf("selection was replaced or group retained: %+v", got.Groups)
+	}
+	if got.Rules[0].Action.Type != "reject" || got.Rules[0].Action.TargetID != "" || got.Rules[0].Source != rules[0].Source || got.Rules[0].Matcher != rules[0].Matcher || got.Rules[0].Order != 9 || !got.Rules[0].Enabled {
+		t.Fatalf("mandatory weakened: %+v", got.Rules[0])
+	}
+	if got.Rules[1].Action != rules[1].Action || got.Rules[2].Action.Type != "reject" || got.Rules[2].Enabled || len(got.Conflicts) != 2 {
+		t.Fatalf("rules/conflicts: %+v", got)
+	}
+	for _, c := range got.Conflicts {
+		if c.ReasonCode != "invalid_target" || c.BlockingRuleID != c.RuleID {
+			t.Fatalf("invalid conflict: %+v", c)
+		}
+	}
+	after, _ := json.Marshal([]any{groups, rules})
+	if string(before) != string(after) {
+		t.Fatal("mutated input")
+	}
+	got.Groups[0].NodeIDs[0] = "changed"
+	got.Rules[0].Matcher.Value = "changed"
+	after, _ = json.Marshal([]any{groups, rules})
+	if string(before) != string(after) {
+		t.Fatal("output aliases input")
+	}
+}
+func TestNarrowTargetsComposesEffectivePolicy(t *testing.T) {
+	groups, rules := narrowFixture()
+	for _, s1 := range [][]string{{"a", "b"}, {"a"}, {"b"}, {}} {
+		for _, s2 := range [][]string{{"a", "b"}, {"a"}, {"b"}, {}} {
+			subset := true
+			for _, id := range s2 {
+				found := false
+				for _, old := range s1 {
+					found = found || id == old
+				}
+				subset = subset && found
+			}
+			if !subset {
+				continue
+			}
+			first, err := NarrowTargets(groups, rules, s1)
+			if err != nil {
+				t.Fatal(err)
+			}
+			twice, err := NarrowTargets(first.Groups, first.Rules, s2)
+			if err != nil {
+				t.Fatal(err)
+			}
+			direct, err := NarrowTargets(groups, rules, s2)
+			if err != nil {
+				t.Fatal(err)
+			}
+			// Diagnostics are per invocation; original references are deliberately lost
+			// after reject. Only effective Groups/Rules obey the composition identity.
+			if !reflect.DeepEqual(twice.Groups, direct.Groups) || !reflect.DeepEqual(twice.Rules, direct.Rules) {
+				t.Fatalf("nonmonotonic %v -> %v", s1, s2)
+			}
+		}
+	}
+	empty, err := NarrowTargets(groups, rules, nil)
+	if err != nil || len(empty.Groups) != 0 {
+		t.Fatalf("empty scope: %+v %v", empty, err)
+	}
+	for _, r := range empty.Rules {
+		if r.Action.Type != "reject" {
+			t.Fatalf("empty scope widened: %+v", r)
+		}
+	}
+}
+func TestNarrowTargetsRejectsInvalidFields(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		mutate func(*[]api.NetworkProxyGroup, *[]api.NetworkProxyRule, *[]string)
+	}{
+		{"empty allowed ID", func(_ *[]api.NetworkProxyGroup, _ *[]api.NetworkProxyRule, a *[]string) { *a = []string{""} }},
+		{"duplicate allowed ID", func(_ *[]api.NetworkProxyGroup, _ *[]api.NetworkProxyRule, a *[]string) { *a = []string{"a", "a"} }},
+		{"unknown group type", func(g *[]api.NetworkProxyGroup, _ *[]api.NetworkProxyRule, _ *[]string) { (*g)[0].Type = "unknown" }},
+		{"invalid group selection", func(g *[]api.NetworkProxyGroup, _ *[]api.NetworkProxyRule, _ *[]string) {
+			(*g)[0].SelectedNodeID = "missing"
+		}},
+		{"unknown matcher", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) {
+			(*r)[0].Matcher.Type = "regex"
+		}},
+		{"unknown source", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) { (*r)[0].Source = "unknown" }},
+		{"unknown action", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) {
+			(*r)[0].Action.Type = "unknown"
+		}},
+		{"invalid target syntax", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) {
+			(*r)[0].Action.TargetID = "bad/id"
+		}},
+		{"extra reject target", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) {
+			(*r)[3].Action.TargetID = "a"
+		}},
+		{"extra all matcher value", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) {
+			(*r)[1].Matcher.Value = "unexpected"
+		}},
+		{"mandatory process", func(_ *[]api.NetworkProxyGroup, r *[]api.NetworkProxyRule, _ *[]string) {
+			(*r)[0].Matcher.Type = "process_name"
+			(*r)[0].Matcher.Value = "browser"
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			g, r := narrowFixture()
+			a := []string{"b"}
+			tc.mutate(&g, &r, &a)
+			if _, err := NarrowTargets(g, r, a); err == nil {
+				t.Fatal("invalid policy silently narrowed")
+			}
+		})
+	}
+}

package/proxypolicy/policy.go

@@ -0,0 +1,329 @@
+// Package proxypolicy owns deterministic managed/personal proxy rule composition.
+// It is shared by server and endpoint consumers and has no runtime dependencies.
+package proxypolicy
+
+import (
+	"errors"
+	"fmt"
+	"net/netip"
+	"sort"
+	"strings"
+
+	api "github.com/opensoha/soha/contracts/gen/go/sohaapi"
+)
+
+type Rule = api.NetworkProxyRule
+type Matcher = api.NetworkProxyRuleMatcher
+type Action = api.NetworkProxyRuleAction
+type Conflict = api.NetworkProxyRuleConflict
+type Composition struct {
+	OrgRevision      int64      `json:"orgRevision"`
+	PersonalRevision int64      `json:"personalRevision"`
+	EffectiveRules   []Rule     `json:"effectiveRules"`
+	Conflicts        []Conflict `json:"conflicts"`
+}
+type Target struct {
+	ID   string
+	Kind string
+}
+
+var ErrRevisionConflict = errors.New("proxy rule revision conflict")
+
+func CheckRevision(expectedOrg, expectedPersonal, actualOrg, actualPersonal int64) error {
+	if expectedOrg != actualOrg || expectedPersonal != actualPersonal {
+		return ErrRevisionConflict
+	}
+	return nil
+}
+func layer(s string) int {
+	switch s {
+	case "protection":
+		return 0
+	case "organization_required":
+		return 1
+	case "personal":
+		return 2
+	case "organization_default":
+		return 3
+	case "fallback":
+		return 4
+	}
+	return -1
+}
+func value(m Matcher) string {
+	return m.Value
+}
+
+// IsMandatory identifies only the two trusted mandatory layers.
+func IsMandatory(r Rule) bool {
+	return string(r.Source) == "protection" || string(r.Source) == "organization_required"
+}
+func mandatory(r Rule) bool { return IsMandatory(r) }
+func ValidateRule(r Rule, targets []Target, server bool) error {
+	if r.RuleID == "" || len(r.RuleID) > 128 || r.Order < 0 || layer(string(r.Source)) < 0 {
+		return errors.New("invalid rule identity/source/order")
+	}
+	if err := validateMatcher(r.Matcher, server && mandatory(r)); err != nil {
+		return err
+	}
+
+	switch string(r.Action.Type) {
+	case "reject", "direct":
+		if r.Action.TargetID != "" {
+			return errors.New("unexpected target")
+		}
+	case "node", "group":
+		if r.Action.TargetID == "" {
+			return errors.New("missing logical target")
+		}
+		found := false
+		for _, t := range targets {
+			if t.ID == r.Action.TargetID && t.Kind == string(r.Action.Type) {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return errors.New("invalid_target")
+		}
+	default:
+		return errors.New("unsupported action")
+	}
+	if string(r.Source) == "protection" && string(r.Action.Type) != "reject" {
+		return errors.New("protection must reject")
+	}
+	return nil
+}
+func sameAction(a, b Action) bool {
+	return a.Type == b.Type && a.TargetID == b.TargetID
+}
+
+// overlap is deliberately conservative for cross-family matchers: a process and
+// destination matcher can match the same flow. Unprovable mandatory conflicts fail.
+func overlap(a, b Matcher) bool {
+	at, bt := string(a.Type), string(b.Type)
+	av, bv := strings.ToLower(value(a)), strings.ToLower(value(b))
+	if at == "all" || bt == "all" {
+		return true
+	}
+	if at == "cidr" && bt == "cidr" {
+		ap, _ := netip.ParsePrefix(av)
+		bp, _ := netip.ParsePrefix(bv)
+		return ap.Overlaps(bp)
+	}
+	if (at == "domain" || at == "domain_suffix") && (bt == "domain" || bt == "domain_suffix") {
+		if at == "domain" && bt == "domain" {
+			return av == bv
+		}
+		return av == bv || (at == "domain_suffix" && strings.HasSuffix(bv, "."+av)) || (bt == "domain_suffix" && strings.HasSuffix(av, "."+bv))
+	}
+	if at == bt && (at == "process_name" || at == "process_path") {
+		return value(a) == value(b)
+	}
+	return true
+}
+func covers(a, b Matcher) bool {
+	if string(a.Type) == "all" {
+		return true
+	}
+	if a.Type == b.Type && value(a) == value(b) {
+		return true
+	}
+	if string(a.Type) == "domain_suffix" && (string(b.Type) == "domain" || string(b.Type) == "domain_suffix") {
+		av, bv := strings.ToLower(value(a)), strings.ToLower(value(b))
+		return av == bv || strings.HasSuffix(bv, "."+av)
+	}
+	if string(a.Type) == "cidr" && string(b.Type) == "cidr" {
+		ap, _ := netip.ParsePrefix(value(a))
+		bp, _ := netip.ParsePrefix(value(b))
+		return ap.Bits() <= bp.Bits() && ap.Contains(bp.Addr())
+	}
+	return false
+}
+
+// Compose never mutates the input/draft. ProtectedSet deny precedes all rules;
+// required organization, personal, organization defaults and fallback follow.
+// Mandatory contradictions reject the publication. Partial masks remain ordered
+// and explained; a wholly masked personal rule is retained only in its draft.
+func Compose(orgRevision, personalRevision int64, rules []Rule, targets []Target, server bool) (Composition, error) {
+	out := Composition{OrgRevision: orgRevision, PersonalRevision: personalRevision, EffectiveRules: []Rule{}, Conflicts: []Conflict{}}
+	if orgRevision < 0 || personalRevision < 0 {
+		return out, errors.New("negative revision")
+	}
+	ordered := append([]Rule(nil), rules...)
+	seen := map[string]bool{}
+	counts := map[string]int{}
+	for _, r := range ordered {
+		counts[string(r.Source)]++
+		if counts[string(r.Source)] > 2048 {
+			return out, errors.New("rule layer quota exceeded")
+		}
+		if seen[r.RuleID] {
+			return out, errors.New("duplicate ruleId")
+		}
+		seen[r.RuleID] = true
+		if err := ValidateRule(r, targets, server); err != nil {
+			return out, fmt.Errorf("rule %s: %w", r.RuleID, err)
+		}
+	}
+	sort.SliceStable(ordered, func(i, j int) bool {
+		a, b := ordered[i], ordered[j]
+		if layer(string(a.Source)) != layer(string(b.Source)) {
+			return layer(string(a.Source)) < layer(string(b.Source))
+		}
+		if a.Order != b.Order {
+			return a.Order < b.Order
+		}
+		return a.RuleID < b.RuleID
+	})
+	for i, r := range ordered {
+		if !r.Enabled {
+			continue
+		}
+		masked := false
+		for _, higher := range ordered[:i] {
+			if !higher.Enabled || !overlap(higher.Matcher, r.Matcher) || sameAction(higher.Action, r.Action) {
+				continue
+			}
+			if mandatory(higher) && mandatory(r) && string(higher.Source) != "protection" {
+				return out, fmt.Errorf("mandatory_conflict: %s and %s", higher.RuleID, r.RuleID)
+			}
+			if mandatory(higher) && string(r.Source) == "personal" {
+				out.Conflicts = append(out.Conflicts, Conflict{RuleID: r.RuleID, BlockingRuleID: higher.RuleID, ReasonCode: api.NetworkProxyRuleConflictReasonCode("masked_by_required")})
+				if covers(higher.Matcher, r.Matcher) {
+					masked = true
+				}
+			}
+		}
+		if !masked {
+			out.EffectiveRules = append(out.EffectiveRules, r)
+		}
+	}
+	return out, nil
+}
+
+func validateMatcher(m Matcher, serverMandatory bool) error {
+	v := value(m)
+	switch string(m.Type) {
+	case "domain", "domain_suffix":
+		if v == "" || len(v) > 253 || strings.ContainsAny(v, " /:@*\\\t\r\n") || strings.HasPrefix(v, ".") || strings.HasSuffix(v, ".") {
+			return errors.New("invalid domain matcher")
+		}
+	case "cidr":
+		p, e := netip.ParsePrefix(v)
+		if e != nil || p.Masked().String() != v {
+			return errors.New("noncanonical CIDR")
+		}
+	case "process_name", "process_path":
+		if v == "" || len(v) > 1024 {
+			return errors.New("invalid process matcher")
+		}
+		if serverMandatory {
+			return errors.New("unsupported_matcher: mandatory process identity is not trusted at server")
+		}
+	case "all":
+		if m.Value != "" {
+			return errors.New("all matcher forbids value")
+		}
+	default:
+		return errors.New("unsupported_matcher")
+	}
+	return nil
+}
+
+// MatchesDestination evaluates only destination-visible matchers. The supplied
+// addresses must be the complete resolved, pinned destination set. A CIDR match
+// against any address is a match; a missing address set cannot bypass CIDR rules.
+// Process conditions cannot be established by a remote proxy and return an error.
+func MatchesDestination(m Matcher, host string, addresses []netip.Addr) (bool, error) {
+	if err := validateMatcher(m, true); err != nil {
+		return false, err
+	}
+	if strings.TrimSpace(host) != host || host == "" || strings.ContainsAny(host, "/@?#\\\t\r\n%") {
+		return false, errors.New("invalid destination host")
+	}
+	host = strings.TrimSuffix(strings.ToLower(host), ".")
+	switch string(m.Type) {
+	case "all":
+		return true, nil
+	case "domain":
+		return strings.EqualFold(host, m.Value), nil
+	case "domain_suffix":
+		suffix := strings.ToLower(m.Value)
+		return host == suffix || strings.HasSuffix(host, "."+suffix), nil
+	case "cidr":
+		prefix, _ := netip.ParsePrefix(m.Value)
+		candidates := append([]netip.Addr(nil), addresses...)
+		if literal, err := netip.ParseAddr(host); err == nil {
+			candidates = append(candidates, literal)
+		}
+		if len(candidates) == 0 {
+			return false, errors.New("resolved destination addresses required for CIDR matcher")
+		}
+		matched := false
+		for _, addr := range candidates {
+			if !addr.IsValid() {
+				return false, errors.New("invalid resolved destination address")
+			}
+			if prefix.Contains(addr.Unmap()) {
+				matched = true
+			}
+		}
+		return matched, nil
+	}
+	return false, errors.New("unsupported destination matcher")
+}
+
+// EvaluateMandatory shares destination enforcement between Core and App.
+// Rules must come from the authenticated policy and their logical targets must
+// already be checked against the current inventory/scope. This function checks
+// rule shape and matching; it never grants access to an unverified target.
+// A matching reject wins over every matching route action. Contradictory route
+// actions or unsupported mandatory process conditions fail closed. matched=false
+// is not an authorization grant and must not be interpreted as automatic DIRECT.
+func EvaluateMandatory(rules []Rule, host string, addresses []netip.Addr) (action Action, matched bool, err error) {
+	reject := false
+	conflict := false
+	for _, r := range rules {
+		if !r.Enabled {
+			continue
+		}
+		if layer(string(r.Source)) < 0 {
+			return Action{}, false, errors.New("invalid rule source")
+		}
+		if !IsMandatory(r) {
+			continue
+		}
+		// Validate structural action shape without claiming inventory authorization.
+		targets := []Target(nil)
+		if r.Action.TargetID != "" {
+			targets = append(targets, Target{ID: r.Action.TargetID, Kind: string(r.Action.Type)})
+		}
+		if err := ValidateRule(r, targets, true); err != nil {
+			return Action{}, false, err
+		}
+		matches, e := MatchesDestination(r.Matcher, host, addresses)
+		if e != nil {
+			return Action{}, false, e
+		}
+		if !matches {
+			continue
+		}
+		if string(r.Action.Type) == "reject" {
+			reject = true
+			continue
+		}
+		if matched && !sameAction(action, r.Action) {
+			conflict = true
+		}
+		action = r.Action
+		matched = true
+	}
+	if reject {
+		return Action{Type: api.NetworkProxyRuleActionType("reject")}, true, nil
+	}
+	if conflict {
+		return Action{}, false, errors.New("mandatory_conflict")
+	}
+	return action, matched, nil
+}

package/proxypolicy/policy_test.go

@@ -0,0 +1,36 @@
+package proxypolicy
+
+import (
+	api "github.com/opensoha/soha/contracts/gen/go/sohaapi"
+	"testing"
+)
+
+func rule(id, source, matcher, v, action string) Rule {
+	r := Rule{RuleID: id, Source: api.NetworkProxyRuleSource(source), Enabled: true, Matcher: Matcher{Type: api.NetworkProxyRuleMatcherType(matcher)}, Action: Action{Type: api.NetworkProxyRuleActionType(action)}}
+	if v != "" {
+		r.Matcher.Value = v
+	}
+	return r
+}
+func TestComposePriorityAndDraft(t *testing.T) {
+	rules := []Rule{rule("mine", "personal", "domain", "x.example.invalid", "direct"), rule("guard", "protection", "domain_suffix", "example.invalid", "reject"), rule("default", "organization_default", "all", "", "direct")}
+	got, err := Compose(2, 3, rules, nil, false)
+	if err != nil || len(got.EffectiveRules) != 2 || len(got.Conflicts) != 1 || got.EffectiveRules[0].RuleID != "guard" || rules[0].RuleID != "mine" {
+		t.Fatalf("%+v %v", got, err)
+	}
+	if CheckRevision(2, 2, 2, 3) == nil {
+		t.Fatal("stale CAS accepted")
+	}
+}
+func TestMandatoryAndUnknownReject(t *testing.T) {
+	for _, rules := range [][]Rule{{rule("a", "organization_required", "all", "", "reject"), rule("b", "organization_required", "all", "", "direct")}, {rule("a", "organization_required", "process_name", "app", "reject")}, {rule("a", "personal", "regex", ".*", "direct")}} {
+		if _, err := Compose(0, 0, rules, nil, true); err == nil {
+			t.Fatalf("accepted %+v", rules)
+		}
+	}
+}
+func TestDomainBoundary(t *testing.T) {
+	if overlap(rule("a", "personal", "domain_suffix", "example.invalid", "reject").Matcher, rule("b", "personal", "domain", "notexample.invalid", "direct").Matcher) {
+		t.Fatal("suffix crossed label boundary")
+	}
+}

package/proxytransport/README.md

@@ -0,0 +1,141 @@
+# Guarded proxy transports
+
+TCP keeps the existing `New` / `Handler` behavior. UDP is opt-in plumbing; it
+is not proof of Mihomo/upstream/platform UDP compatibility. Advertise
+`guarded_udp_v1` only after installing and verifying the real guarded chain.
+`ErrPacketUnsupported` from a verified dial callback maps to a static HTTP 501
+with the UDP transport header. The client recognizes it only after verified TLS
+and exact protocol-header checks, without reading/echoing the response body.
+Other unsafe protocol responses are not converted into unsupported.
+TCP-only upstreams must produce that static unsupported result, never a direct OS
+UDP fallback or a downloaded replacement transport.
+
+## Frozen UDP v1
+
+The approved internal HTTPS endpoint accepts HTTP/1 CONNECT `host:port` with
+exactly one `Soha-Transport: udp/1` and the existing HTTP Basic mapped username
+(`EncodeMappedUsername`) and credential secret. The 200 response must echo
+exactly one identical transport header. Missing/unknown/duplicate transport
+values fail the UDP handshake. Header-free requests continue to the existing
+TCP Handler. This private protocol is **not** RFC 9298 CONNECT-UDP.
+
+After the headers, each datagram is a two-byte unsigned big-endian payload length
+followed by exactly that many bytes. Zero is a valid empty datagram, not EOF.
+The payload maximum is 65507 bytes. Oversize/truncated frames and insufficient
+Read buffers close the association; data is never truncated. Each remote
+association has one immutable destination; frames contain no alternative target,
+credential or upstream/source metadata. TLS stream transport can cause head of
+line blocking; this does not claim native UDP timing, QUIC performance or loss
+semantics.
+
+A SOCKS UDP datagram must additionally fit its **whole header plus payload**
+within 65507 bytes. Header space is charged per address type; oversized replies
+are rejected, not fragmented/truncated. RSV is zero and FRAG must be zero;
+SOCKS fragmentation is unsupported. This rule does not promise that the OS or
+an upstream network never performs IP fragmentation.
+
+## Shared APIs
+
+```go
+type DialPacket func(context.Context, string /* user */, string /* target */) (net.Conn, error)
+type PacketAuthorize func(context.Context, string /* user */, string /* target */) error
+
+NewPacketConn(net.Conn, time.Time) (*PacketConn, error)
+NewPacketHandler(map[string]string, DialPacket, PacketAuthorize, time.Time) (*PacketHandler, error)
+DialPacketTunnel(context.Context, net.Conn /* verified *tls.Conn */, string /* target */, string /* user */, string /* secret */, time.Time) (*PacketConn, error)
+NewSOCKS5Gate(map[string]string, Dial, DialPacket, PacketAuthorize, time.Time) (*SOCKS5Gate, error)
+DialSOCKS5UDP(context.Context, string /* owned loopback backend */, string /* user */, string /* secret */, string /* pinned literal IP:port */, time.Time) (net.Conn, error)
+```
+
+`Read` / `Write` on packet connections each represent one datagram, including
+empty datagrams. Never use `io.Copy` to bridge a packet connection.
+`PacketConn.Refresh`, `PacketHandler.Refresh` and `SOCKS5Gate.Refresh` require
+that the previous lease is still alive. The next expiry must be in the future
+and at most five minutes from now. There is no arbitrary five-minute lifetime
+limit on a continuously authorized flow. Callers cap renewal by the current
+configuration/certificate/credential limits and cannot renew old authorization
+past an in-flight check's expiry. Expired, closed or idle packet connections
+cannot be revived; a new association needs fresh authorization.
+
+`PacketAuthorize` is required before forwarding **each datagram in both
+directions**. Callers recheck current node/credential/epoch/scope, ProtectedSet,
+mandatory rules, approved destination resolution and their hard expiry. A
+bounded current grant/cache may be used only until its expiry; online grants
+must expire within five seconds. The package does not grant access based on
+capabilities or a successful earlier handshake. Dial callbacks resolve, validate
+all DNS answers and pin one authorized IP. Packet callbacks and dials have
+bounded contexts; callers must honor cancellation.
+
+Packet connections have a 30-second activity idle window. Renewals do not reset
+activity. Per-packet operations are serialized per direction, with no unbounded
+queue or multiplexing buffer. Each gate permits at most 4096 controls and at
+most 4096 destination-specific UDP associations; each local SOCKS control has
+at most 128 inner destinations. These are upper bounds, not capacity claims.
+`ActiveCount` counts admitted **UDP destination associations**, not TCP controls,
+and is not an overall TCP+UDP service count. Callers combine it with TCP counts
+for drain/stop proof, or track the returned connections themselves.
+
+## Local SOCKS boundary and backend
+
+`SOCKS5Gate.Serve` accepts only a loopback listener and loopback clients. It
+supports RFC 1929 password authentication, TCP CONNECT via the supplied existing
+`Dial`, and UDP ASSOCIATE through `DialPacket`. Local usernames/passwords have a
+255-byte RFC limit: use short random/node-local names, not the potentially
+354-byte mapped HTTP username. Keep local credentials private.
+
+Each TCP UDP control owns a dedicated loopback UDP socket. The source IP must
+match the TCP peer. A requested nonzero port must match exactly; port zero pins
+the first valid datagram's source port. A malicious local process capable of
+racing/spoofing that source remains inside the local-host trust boundary; this
+is not process identity isolation. The control's close/expiry closes its socket
+and children. Multiple destinations on one SOCKS control get independent
+single-destination inner associations; there is no remote wildcard association.
+
+`DialSOCKS5UDP` connects only to an installer-owned **literal loopback** TCP
+backend, performs password authentication and UDP ASSOCIATE, and requires a
+literal loopback relay reply. It connects an OS UDP socket only to that relay;
+the owned engine routes to the target. Replies must carry the pinned target,
+RSV=0 and FRAG=0. Closing it closes both relay UDP and control TCP. The caller
+verifies backend process/port ownership and UDP support for the selected node;
+loopback address validation alone is not ownership proof.
+
+## Lifecycle and integration
+
+Use an explicit HTTP dispatcher: requests with `Soha-Transport` go to
+`PacketHandler`; absent header goes to the legacy TCP handler. No existing TCP
+code or authentication behavior is changed by installing these new types.
+
+`NoNew` denies new associations and new local SOCKS destinations, retaining
+already admitted destinations for bounded drain. `Close` terminates the gate
+and all owned associations/controls. It cannot be reversed with Refresh.
+Callers retain per-user/node connection registries and close only revoked node
+connections immediately; the next per-packet check independently rejects stale
+scope. Do not implement node revocation by closing a shared gate for unrelated B.
+
+Secrets, payloads, original source URLs and upstream parameters must never be
+logged or exported. Shared code emits static errors only. Real validation still
+requires the pinned Mihomo native SOCKS UDP backend, distinct A/B upstreams,
+ProtectedSet/rule refusal, revoked A with surviving B, grant expiry/late renewal,
+and drain/stop confirmation; package socket tests are not that acceptance.
+
+## Original SOCKS5 upstream relay boundary
+
+`UpstreamConnect func(context.Context) (net.Conn, error)` is supplied by the
+caller. Both `DialSOCKS5UpstreamTCP` and `DialSOCKS5UpstreamUDP` take
+`(ctx, connect, approvedUpstreamIP netip.Addr, user, secret, pinnedTarget, deadline)`.
+The caller owns source Scope resolution/pinning, verified TLS/SNI when required,
+source credentials/authentication choice and original-node compatibility. The
+factory returns the connected TCP/TLS stream before SOCKS negotiation. The helpers
+first check that the connected TCP/TLS `RemoteAddr` equals the explicit approved
+source IP, then perform SOCKS authentication and request negotiation. Empty user plus empty secret selects NoAuth;
+otherwise upstream RFC 1929 credentials are bounded to 255 bytes each.
+
+The UDP helper accepts only a literal same-IP BND relay; unspecified IPv4/IPv6
+BND addresses become the approved IP. Other IPs, hostnames and invalid ports are
+rejected before creating the UDP socket. The OS socket connects only to the
+approved proxy IP and validated relay port, never directly to `pinnedTarget`.
+Replies must retain the literal pinned target, FRAG=0 and the total datagram
+budget. This helper supplements caller authorization/protection/lease checks;
+it neither grants source/target access nor proves an upstream server's UDP
+support. Only the original SOCKS5 node needs this controlled second loopback
+bridge; it is not a general-purpose network sandbox.

package/proxytransport/handler.go

@@ -35,7 +35,7 @@ func New(credentials map[string]string, dial Dial, deadline time.Time) (*Handler
 	}
 	h := &Handler{credentials: map[string][32]byte{}, dial: dial, deadline: deadline.UTC(), connections: map[net.Conn]struct{}{}}
 	for user, password := range credentials {
-		if user == "" || len(user) > 128 || len(password) < 32 {
+		if user == "" || len(user) > MaxUsernameBytes || len(password) < 32 {
 			return nil, errors.New("invalid proxy transport credential")
 		}
 		h.credentials[user] = sha256.Sum256([]byte(password))
@@ -53,6 +53,10 @@ func (h *Handler) Refresh(deadline time.Time) error {
 	h.deadline = deadline
 	for conn := range h.connections {
 		if err := conn.SetDeadline(deadline); err != nil {
+			if errors.Is(err, net.ErrClosed) {
+				delete(h.connections, conn)
+				continue
+			}
 			return err
 		}
 	}