@opensoha/contracts 0.1.27 → 0.2.0

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.27"
-	YAMLSHA256 = "7ec8930963123f5b79dff6dfaddf7200dd0fce51ada6212d47f415d4e7539727"
-	JSONSHA256 = "6c1d5c0d4871c5ff6ea82241a02ff8ee4147792c6026a474a9d10a3ef3ca051b"
+	Version    = "0.2.0"
+	YAMLSHA256 = "53142496b7e62b324e4be4cf9c8b6836be3cdc540566e40aa37a5599f8f23832"
+	JSONSHA256 = "e48e5093cc70ecaff089068975dbf54683cbcbbee95024937f9596e9424cfc99"
 )
 
 //go:embed soha-api.yaml

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.27",
+  "version": "0.2.0",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/opensoha/soha-contracts"
+    "url": "https://github.com/opensoha/soha",
+    "directory": "contracts"
   },
   "type": "module",
   "scripts": {
@@ -19,13 +20,14 @@
     "validate": "node --test scripts/validate-fixtures.checks.mjs && node scripts/validate.mjs",
     "lint:openapi": "node scripts/lint-openapi.mjs",
     "check:openapi-breaking": "node scripts/check-openapi-breaking.mjs",
-    "check:openapi-loose-boundaries": "node scripts/check-openapi-loose-boundaries.mjs",
+    "check:openapi-loose-boundaries": "node --test scripts/check-baseline-versions.checks.mjs && node scripts/check-openapi-loose-boundaries.mjs",
     "check:json-schema-compat": "node scripts/check-json-schema-compat.mjs",
     "check:openapi-breaking:update": "node scripts/check-openapi-breaking.mjs --update-baseline",
     "release:artifacts": "node scripts/prepare-release-artifacts.mjs",
     "release:verify": "node scripts/prepare-release-artifacts.mjs --verify",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "npm run check:version-sync && npm run check:generated && npm run validate && npm run lint:openapi && npm run check:openapi-breaking && npm run check:openapi-loose-boundaries && npm run check:json-schema-compat && npm run typecheck && go test ./..."
+    "test": "node --test scripts/check-consumer-dependency-mode.checks.mjs && npm run check:version-sync && npm run check:generated && npm run validate && npm run lint:openapi && npm run check:openapi-breaking && npm run check:openapi-loose-boundaries && npm run check:json-schema-compat && npm run typecheck && go test ./...",
+    "validate:dsh-runtime": "node scripts/validate-dsh-runtime.mjs"
   },
   "exports": {
     "./delivery/document.schema.json": "./delivery/document.schema.json",
@@ -106,7 +108,15 @@
     "./agent/personal-guest-tools.schema.json": "./agent/personal-guest-tools.schema.json",
     "./agent/personal-browser-network-request.schema.json": "./agent/personal-browser-network-request.schema.json",
     "./agent/personal-browser-network-response.schema.json": "./agent/personal-browser-network-response.schema.json",
-    "./endpointcontrol/protocol.schema.json": "./endpointcontrol/protocol.schema.json"
+    "./runner/docker-project-identity.schema.json": "./runner/docker-project-identity.schema.json",
+    "./runner/docker-container-identity.schema.json": "./runner/docker-container-identity.schema.json",
+    "./runner/docker-runtime-read.schema.json": "./runner/docker-runtime-read.schema.json",
+    "./runner/docker-runtime-read-result.schema.json": "./runner/docker-runtime-read-result.schema.json",
+    "./endpointcontrol/protocol.schema.json": "./endpointcontrol/protocol.schema.json",
+    "./network/proxy-adapter.schema.json": "./network/proxy-adapter.schema.json",
+    "./network/radius-password-verifier.schema.json": "./network/radius-password-verifier.schema.json",
+    "./network/radius-runtime.schema.json": "./network/radius-runtime.schema.json",
+    "./agent/dsh-runtime.schema.json": "./agent/dsh-runtime.schema.json"
   },
   "files": [
     "delivery",
@@ -138,8 +148,11 @@
     "network",
     "knowledge",
     "memory",
+    "docker",
     "proxytransport",
-    "endpointcontrol"
+    "endpointcontrol",
+    "proxyadapter",
+    "proxypolicy"
   ],
   "devDependencies": {
     "ajv": "^8.20.0",

package/proxyadapter/mihomo_udp.go

@@ -0,0 +1,15 @@
+package proxyadapter
+
+// SupportsMihomoUDP reports eligibility in the controlled native Mihomo protocol
+// set. Input must already be normalized by the source converter: aliases,
+// whitespace and case variants are rejected. An explicit udp:false remains false
+// at the caller. Eligibility does not prove an upstream server supports UDP and
+// never bypasses authorization, destination protection, rules or lease checks.
+func SupportsMihomoUDP(protocol string) bool {
+	switch protocol {
+	case "socks5", "ss", "trojan", "vmess", "vless":
+		return true
+	default:
+		return false
+	}
+}

package/proxyadapter/mihomo_udp_test.go

@@ -0,0 +1,21 @@
+package proxyadapter
+
+import "testing"
+
+func TestSupportsMihomoUDP(t *testing.T) {
+	for _, tc := range []struct {
+		protocol string
+		want     bool
+	}{
+		{"socks5", true}, {"ss", true}, {"trojan", true}, {"vmess", true}, {"vless", true},
+		{"http", false}, {"https", false}, {"ssr", false}, {"snell", false}, {"unknown", false}, {"", false},
+		{"SOCKS5", false}, {"SS", false}, {"Trojan", false}, {"socks", false}, {"shadowsocks", false},
+		{" socks5", false}, {"socks5 ", false}, {"socks5\n", false}, {"ss\x00", false},
+	} {
+		t.Run(tc.protocol, func(t *testing.T) {
+			if got := SupportsMihomoUDP(tc.protocol); got != tc.want {
+				t.Fatalf("SupportsMihomoUDP(%q)=%v, want %v", tc.protocol, got, tc.want)
+			}
+		})
+	}
+}

package/proxyadapter/protocol.go

@@ -0,0 +1,286 @@
+// Package proxyadapter defines the bounded local host/adapter PX-v1 protocol.
+// The host retains mTLS, lease/floor, authorization and the egress gate.
+package proxyadapter
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"regexp"
+	"time"
+
+	api "github.com/opensoha/soha/contracts/gen/go/sohaapi"
+)
+
+const Major = 1
+const Minor = 0
+const MaxFrameBytes = 1 << 20
+const MaxStderrBytes = 64 << 10
+const MaxCommandLifetime = 30 * time.Second
+
+// BinaryApproval is installer configuration, not caller-controlled input.
+// Hosts must verify an absolute regular binary path, ownership and digest before spawn.
+type BinaryApproval struct {
+	AdapterID string `json:"adapterId"`
+	Binary    string `json:"binary"`
+	SHA256    string `json:"sha256"`
+	Version   string `json:"version"`
+}
+
+type Method string
+
+const (
+	Handshake   Method = "handshake"
+	Prepare     Method = "prepare"
+	Apply       Method = "apply"
+	Observe     Method = "observe"
+	Close       Method = "close"
+	Select      Method = "select"
+	Probe       Method = "probe"
+	Refresh     Method = "refresh"
+	Logs        Method = "logs"
+	Diagnostics Method = "diagnostics"
+	Stop        Method = "stop"
+)
+
+type Payload struct {
+	Challenge    string                               `json:"challenge,omitempty"`
+	Descriptor   *api.NetworkProxyEngineDescriptor    `json:"descriptor,omitempty"`
+	Revision     *int64                               `json:"revision,omitempty"`
+	ContentHash  string                               `json:"contentHash,omitempty"`
+	Content      string                               `json:"content,omitempty"`
+	ValidUntil   *time.Time                           `json:"validUntil,omitempty"`
+	Command      *api.NetworkProxyRuntimeCommandInput `json:"command,omitempty"`
+	ConnectionID string                               `json:"connectionId,omitempty"`
+	IssuedAt     *time.Time                           `json:"issuedAt,omitempty"`
+	ExpiresAt    *time.Time                           `json:"expiresAt,omitempty"`
+}
+type Observation struct {
+	SampleSequence int64                        `json:"sampleSequence"`
+	UploadTotal    int64                        `json:"uploadTotal"`
+	DownloadTotal  int64                        `json:"downloadTotal"`
+	TotalActive    int64                        `json:"totalActive"`
+	ReturnedCount  int64                        `json:"returnedCount"`
+	Truncated      bool                         `json:"truncated"`
+	Freshness      string                       `json:"freshness"`
+	Connections    []api.NetworkProxyConnection `json:"connections"`
+}
+type Result struct {
+	CloseStatus  string                                `json:"closeStatus,omitempty"`
+	Challenge    string                                `json:"challenge,omitempty"`
+	Descriptor   *api.NetworkProxyEngineDescriptor     `json:"descriptor,omitempty"`
+	ReadbackHash string                                `json:"readbackHash,omitempty"`
+	Revision     *int64                                `json:"revision,omitempty"`
+	Observation  *Observation                          `json:"observation,omitempty"`
+	Command      *api.NetworkProxyRuntimeCommandResult `json:"command,omitempty"`
+}
+type ProtocolError struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+type Frame struct {
+	Major        int            `json:"major"`
+	Minor        int            `json:"minor"`
+	RequestID    string         `json:"requestId"`
+	Deadline     time.Time      `json:"deadline"`
+	ProcessEpoch string         `json:"processEpoch"`
+	Method       Method         `json:"method"`
+	Payload      *Payload       `json:"payload,omitempty"`
+	Result       *Result        `json:"result,omitempty"`
+	Error        *ProtocolError `json:"error,omitempty"`
+}
+
+var identifier = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`)
+var digest = regexp.MustCompile(`^sha256:[a-f0-9]{64}$`)
+
+// DecodeFrame accepts exactly one newline-delimited frame, including its newline
+// in the limit. stdout must contain only these frames; logs use bounded stderr.
+func DecodeFrame(line []byte, now time.Time) (Frame, error) {
+	var f Frame
+	if len(line) > MaxFrameBytes || len(line) == 0 || line[len(line)-1] != '\n' || bytes.Contains(line[:len(line)-1], []byte{'\n'}) {
+		return f, errors.New("invalid frame boundary or size")
+	}
+	d := json.NewDecoder(bytes.NewReader(line))
+	d.DisallowUnknownFields()
+	if err := d.Decode(&f); err != nil {
+		return f, err
+	}
+	if err := d.Decode(new(any)); err != io.EOF {
+		return f, errors.New("trailing frame data")
+	}
+	return f, f.Validate(now)
+}
+func (f Frame) Validate(now time.Time) error {
+	if f.Major != Major || f.Minor != Minor {
+		return errors.New("incompatible_version")
+	}
+	if !identifier.MatchString(f.RequestID) || !identifier.MatchString(f.ProcessEpoch) {
+		return errors.New("invalid correlation identity")
+	}
+	if !f.Deadline.After(now) || f.Deadline.After(now.Add(MaxCommandLifetime)) {
+		return errors.New("expired or excessive deadline")
+	}
+	switch f.Method {
+	case Handshake, Prepare, Apply, Observe, Close, Select, Probe, Refresh, Logs, Diagnostics, Stop:
+	default:
+		return errors.New("unsupported method")
+	}
+	count := 0
+	for _, v := range []bool{f.Payload != nil, f.Result != nil, f.Error != nil} {
+		if v {
+			count++
+		}
+	}
+	if count != 1 {
+		return errors.New("exactly one payload, result or error required")
+	}
+	if f.Error != nil {
+		switch f.Error.Code {
+		case "unsupported", "unavailable", "invalid_request", "expired", "epoch_mismatch", "incompatible_version", "failed":
+		default:
+			return errors.New("invalid error code")
+		}
+		if len(f.Error.Message) > 512 {
+			return errors.New("error too long")
+		}
+	}
+	if p := f.Payload; p != nil {
+		switch f.Method {
+		case Handshake:
+			if len(p.Challenge) < 32 || len(p.Challenge) > 128 {
+				return errors.New("random challenge required")
+			}
+		case Prepare, Apply:
+			if p.Revision == nil || *p.Revision < 1 || !digest.MatchString(p.ContentHash) || p.Content == "" || len(p.Content) > MaxFrameBytes || p.ValidUntil == nil || !p.ValidUntil.After(now) {
+				return errors.New("configuration identity and valid lease required")
+			}
+		case Close:
+			if !identifier.MatchString(p.ConnectionID) || p.IssuedAt == nil || p.ExpiresAt == nil {
+				return errors.New("close identity and times required")
+			}
+			if err := ValidateWindow(*p.IssuedAt, *p.ExpiresAt, now); err != nil {
+				return err
+			}
+		case Select, Probe, Refresh, Logs, Diagnostics:
+			if p.Command == nil {
+				return errors.New("typed command required")
+			}
+			if err := ValidateCommand(*p.Command, f.ProcessEpoch, now); err != nil {
+				return err
+			}
+			if string(p.Command.Kind) != string(f.Method) {
+				return errors.New("command method mismatch")
+			}
+		}
+	}
+	if r := f.Result; r != nil {
+		if r.Descriptor != nil {
+			if err := ValidateDescriptor(*r.Descriptor); err != nil {
+				return err
+			}
+		}
+		switch f.Method {
+		case Handshake:
+			if len(r.Challenge) < 32 || r.Descriptor == nil {
+				return errors.New("handshake challenge/descriptor required")
+			}
+		case Apply:
+			if r.Revision == nil || *r.Revision < 1 || !digest.MatchString(r.ReadbackHash) {
+				return errors.New("apply readback required")
+			}
+		case Close:
+			if r.CloseStatus != "closed" && r.CloseStatus != "not-found" && r.CloseStatus != "failed" {
+				return errors.New("close status required")
+			}
+		case Observe:
+			if r.Observation == nil {
+				return errors.New("observation required")
+			}
+			o := r.Observation
+			if o.SampleSequence < 0 || o.UploadTotal < 0 || o.DownloadTotal < 0 || o.TotalActive < 0 || o.ReturnedCount != int64(len(o.Connections)) || o.TotalActive < o.ReturnedCount || o.Truncated != (o.TotalActive > o.ReturnedCount) || len(o.Connections) > 200 {
+				return errors.New("invalid counts")
+			}
+			switch o.Freshness {
+			case "fresh", "stale", "unavailable":
+			default:
+				return errors.New("invalid freshness")
+			}
+		}
+	}
+	return nil
+}
+func ValidateWindow(issuedAt, expiresAt, now time.Time) error {
+	if issuedAt.After(now) || !expiresAt.After(now) || !expiresAt.After(issuedAt) || expiresAt.Sub(issuedAt) > MaxCommandLifetime {
+		return errors.New("expired or excessive command lifetime")
+	}
+	return nil
+}
+func ValidateCommand(c api.NetworkProxyRuntimeCommandInput, epoch string, now time.Time) error {
+	if !identifier.MatchString(c.RequestID) || c.ProcessEpoch != epoch || !identifier.MatchString(epoch) {
+		return errors.New("epoch or request identity mismatch")
+	}
+	if err := ValidateWindow(c.IssuedAt, c.ExpiresAt, now); err != nil {
+		return err
+	}
+	switch string(c.Kind) {
+	case "groups", "rules", "dns", "refresh", "logs", "diagnostics":
+	case "select":
+		if c.GroupID == "" || c.NodeID == "" {
+			return errors.New("selection refs required")
+		}
+	case "probe":
+		if c.ProbeProfileID == "" {
+			return errors.New("approved probe profile required")
+		}
+	default:
+		return fmt.Errorf("unsupported command %q", c.Kind)
+	}
+	return nil
+}
+
+// MatchResponse prevents late or cross-process replies from satisfying a request.
+func MatchResponse(request, response Frame, challenge string, now time.Time) error {
+	if err := response.Validate(now); err != nil {
+		return err
+	}
+	if response.Payload != nil || response.RequestID != request.RequestID || response.ProcessEpoch != request.ProcessEpoch || response.Method != request.Method || !response.Deadline.Equal(request.Deadline) {
+		return errors.New("response correlation mismatch")
+	}
+	if request.Method == Handshake && response.Error == nil && (response.Result == nil || response.Result.Challenge != challenge) {
+		return errors.New("challenge mismatch")
+	}
+	return nil
+}
+
+// EncodeFrame includes the delimiter in the maximum frame size.
+func EncodeFrame(f Frame, now time.Time) ([]byte, error) {
+	if err := f.Validate(now); err != nil {
+		return nil, err
+	}
+	b, err := json.Marshal(f)
+	if err != nil {
+		return nil, err
+	}
+	if len(b)+1 > MaxFrameBytes {
+		return nil, errors.New("frame too large")
+	}
+	return append(b, '\n'), nil
+}
+
+// ValidateDescriptor checks identity/protocol only. Host security capabilities
+// are installer verified and cannot be granted by an adapter declaration.
+func ValidateDescriptor(d api.NetworkProxyEngineDescriptor) error {
+	if !regexp.MustCompile(`^[a-z][a-z0-9.-]{0,63}$`).MatchString(d.EngineID) || !regexp.MustCompile(`^[a-z][a-z0-9.-]{0,63}$`).MatchString(d.AdapterID) || d.Version == "" || len(d.Version) > 64 || int(d.ProtocolMajor) != Major || int(d.ProtocolMinor) != Minor || len(d.Capabilities) > 64 {
+		return errors.New("invalid descriptor")
+	}
+	seen := map[string]bool{}
+	for _, c := range d.Capabilities {
+		if c == "" || len(c) > 64 || seen[c] {
+			return errors.New("invalid capabilities")
+		}
+		seen[c] = true
+	}
+	return nil
+}

package/proxyadapter/protocol_test.go

@@ -0,0 +1,76 @@
+package proxyadapter
+
+import (
+	"bytes"
+	"encoding/json"
+	"io/fs"
+	"os"
+	"path"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestAdapterResultFixtures(t *testing.T) {
+	now := time.Date(2026, 11, 8, 1, 0, 0, 0, time.UTC)
+	for _, method := range []Method{Handshake, Apply, Observe, Close} {
+		for _, valid := range []bool{true, false} {
+			dir, name := "valid", string(method)+"-result.json"
+			if !valid {
+				dir, name = "invalid", string(method)+"-incomplete-result.json"
+			}
+			t.Run(dir+"/"+name, func(t *testing.T) {
+				raw, err := fs.ReadFile(os.DirFS("../fixtures/json-schema/proxy-adapter"), path.Join(dir, name))
+				if err != nil {
+					t.Fatal(err)
+				}
+				var line bytes.Buffer
+				if err := json.Compact(&line, raw); err != nil {
+					t.Fatal(err)
+				}
+				line.WriteByte('\n')
+				if _, err = DecodeFrame(line.Bytes(), now); (err == nil) != valid {
+					t.Fatalf("DecodeFrame error = %v, want valid = %v", err, valid)
+				}
+			})
+		}
+	}
+}
+
+func TestFrameBoundariesAndCorrelation(t *testing.T) {
+	now := time.Date(2026, 11, 8, 1, 0, 0, 0, time.UTC)
+	f := Frame{Major: 1, Minor: 0, RequestID: "r1", ProcessEpoch: "e1", Deadline: now.Add(time.Second), Method: Handshake, Payload: &Payload{Challenge: strings.Repeat("a", 32)}}
+	raw, _ := json.Marshal(f)
+	raw = append(raw, '\n')
+	if _, err := DecodeFrame(raw, now); err != nil {
+		t.Fatal(err)
+	}
+	for _, bad := range [][]byte{raw[:len(raw)-1], append(append([]byte{}, raw...), raw...), []byte(strings.Repeat("x", MaxFrameBytes+1))} {
+		if _, err := DecodeFrame(bad, now); err == nil {
+			t.Fatal("invalid boundary accepted")
+		}
+	}
+	f.Major = 2
+	if err := f.Validate(now); err == nil {
+		t.Fatal("major accepted")
+	}
+	f.Major = 1
+	f.Deadline = now
+	if err := f.Validate(now); err == nil {
+		t.Fatal("expiry accepted")
+	}
+}
+func TestCloseWindowAndEpoch(t *testing.T) {
+	now := time.Now()
+	if ValidateWindow(now, now.Add(31*time.Second), now) == nil {
+		t.Fatal("excessive lifetime")
+	}
+	req := Frame{Major: 1, RequestID: "r1", ProcessEpoch: "e1", Deadline: now.Add(time.Second), Method: Stop, Payload: &Payload{}}
+	reply := req
+	reply.Payload = nil
+	reply.Result = &Result{}
+	reply.ProcessEpoch = "e2"
+	if MatchResponse(req, reply, "", now) == nil {
+		t.Fatal("cross epoch accepted")
+	}
+}

package/proxypolicy/destination_test.go

@@ -0,0 +1,48 @@
+package proxypolicy
+
+import (
+	"net/netip"
+	"testing"
+)
+
+func TestMatchesDestination(t *testing.T) {
+	for _, tc := range []struct {
+		name, kind, value, host string
+		ips                     []netip.Addr
+		match, wantErr          bool
+	}{
+		{name: "domain case and terminal dot", kind: "domain", value: "example.invalid", host: "EXAMPLE.INVALID.", match: true},
+		{name: "suffix child", kind: "domain_suffix", value: "example.invalid", host: "child.example.invalid", match: true},
+		{name: "suffix label boundary", kind: "domain_suffix", value: "example.invalid", host: "notexample.invalid"},
+		{name: "CIDR any resolved address", kind: "cidr", value: "10.0.0.0/8", host: "example.invalid", ips: []netip.Addr{netip.MustParseAddr("192.0.2.1"), netip.MustParseAddr("10.1.2.3")}, match: true},
+		{name: "mapped IPv4 literal", kind: "cidr", value: "10.0.0.0/8", host: "::ffff:10.1.2.3", match: true},
+		{name: "CIDR nonmatch", kind: "cidr", value: "10.0.0.0/8", host: "192.0.2.1"},
+		{name: "missing resolution fails closed", kind: "cidr", value: "10.0.0.0/8", host: "example.invalid", wantErr: true},
+		{name: "process is untrusted", kind: "process_name", value: "browser", host: "example.invalid", wantErr: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			m := rule("r", "organization_required", tc.kind, tc.value, "reject").Matcher
+			got, err := MatchesDestination(m, tc.host, tc.ips)
+			if got != tc.match || (err != nil) != tc.wantErr {
+				t.Fatalf("got %v,%v", got, err)
+			}
+		})
+	}
+}
+func TestEvaluateMandatoryRejectPriority(t *testing.T) {
+	allow := rule("allow", "organization_required", "all", "", "direct")
+	deny := rule("deny", "protection", "domain_suffix", "example.invalid", "reject")
+	for _, rules := range [][]Rule{{allow, deny}, {deny, allow}} {
+		got, matched, err := EvaluateMandatory(rules, "x.example.invalid", nil)
+		if err != nil || !matched || got.Type != "reject" {
+			t.Fatalf("%+v %v %v", got, matched, err)
+		}
+	}
+	personal := rule("mine", "personal", "all", "", "reject")
+	if _, matched, err := EvaluateMandatory([]Rule{personal}, "example.invalid", nil); err != nil || matched {
+		t.Fatalf("personal became mandatory: %v %v", matched, err)
+	}
+	if _, _, err := EvaluateMandatory([]Rule{rule("process", "organization_required", "process_name", "browser", "direct")}, "example.invalid", nil); err == nil {
+		t.Fatal("untrusted mandatory process accepted")
+	}
+}

package/proxypolicy/narrow.go

@@ -0,0 +1,152 @@
+package proxypolicy
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"unicode/utf8"
+
+	api "github.com/opensoha/soha/contracts/gen/go/sohaapi"
+)
+
+// NarrowResult contains the effective structural subset and diagnostics for
+// references invalidated in this invocation. It is not an authorization grant.
+type NarrowResult struct {
+	Groups    []api.NetworkProxyGroup
+	Rules     []api.NetworkProxyRule
+	Conflicts []api.NetworkProxyRuleConflict
+}
+
+var narrowIdentifier = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`)
+
+// NarrowTargets preserves ordering and clones its inputs. It removes group
+// members outside allowedNodeIDs, clears a revoked selection without selecting
+// a replacement, and turns revoked node/empty-group references into reject.
+// Mandatory rules retain their source, matcher, order and enabled state.
+//
+// The caller verifies scope is a subset of its previous authorization, persists
+// a monotonic ceiling and validates inventory/credentials. ProjectionHash is the
+// published bundle template hash, not a per-device scope/lease hash; sharing that
+// hash is never permission to widen a previously narrowed scope.
+//
+// Effective Groups/Rules compose monotonically for S2 subset S1. Conflicts only
+// describe newly invalidated references: after node/group -> reject the original
+// target cannot be recovered. Recompute diagnostics from retained original
+// template/personal drafts, rather than guessing a target from an existing reject.
+func NarrowTargets(groups []api.NetworkProxyGroup, rules []api.NetworkProxyRule, allowedNodeIDs []string) (NarrowResult, error) {
+	invalid := func(err error) (NarrowResult, error) { return NarrowResult{}, err }
+	allowed := make(map[string]bool, len(allowedNodeIDs))
+	for _, id := range allowedNodeIDs {
+		if !narrowIdentifier.MatchString(id) || allowed[id] {
+			return invalid(errors.New("invalid or duplicate allowed node ID"))
+		}
+		allowed[id] = true
+	}
+	if len(groups) > 2048 || len(rules) > 10240 {
+		return invalid(errors.New("proxy policy quota exceeded"))
+	}
+	seenGroups := map[string]bool{}
+	for _, g := range groups {
+		if err := validateNarrowGroup(g); err != nil {
+			return invalid(err)
+		}
+		if seenGroups[g.GroupID] {
+			return invalid(errors.New("duplicate group ID"))
+		}
+		seenGroups[g.GroupID] = true
+	}
+	seenRules := map[string]bool{}
+	layers := map[string]int{}
+	for _, r := range rules {
+		if !narrowIdentifier.MatchString(r.RuleID) || seenRules[r.RuleID] {
+			return invalid(errors.New("invalid or duplicate rule ID"))
+		}
+		seenRules[r.RuleID] = true
+		layers[string(r.Source)]++
+		if layers[string(r.Source)] > 2048 {
+			return invalid(errors.New("rule layer quota exceeded"))
+		}
+		// Check shape before rewriting, including disabled rules. Inventory existence
+		// is intentionally not asserted: a missing group is a revoked reference.
+		targets := []Target(nil)
+		if r.Action.TargetID != "" {
+			if !narrowIdentifier.MatchString(r.Action.TargetID) {
+				return invalid(errors.New("invalid logical target ID"))
+			}
+			targets = append(targets, Target{ID: r.Action.TargetID, Kind: string(r.Action.Type)})
+		}
+		if err := ValidateRule(r, targets, true); err != nil {
+			return invalid(fmt.Errorf("rule %s: %w", r.RuleID, err))
+		}
+	}
+	out := NarrowResult{Groups: make([]api.NetworkProxyGroup, 0, len(groups)), Rules: make([]api.NetworkProxyRule, 0, len(rules)), Conflicts: []api.NetworkProxyRuleConflict{}}
+	keptGroups := map[string]bool{}
+	targets := make([]Target, 0, len(allowed)+len(groups))
+	for _, id := range allowedNodeIDs {
+		targets = append(targets, Target{ID: id, Kind: "node"})
+	}
+	for _, original := range groups {
+		g := original
+		g.NodeIDs = make([]string, 0, len(original.NodeIDs))
+		selectedKept := false
+		for _, id := range original.NodeIDs {
+			if allowed[id] {
+				g.NodeIDs = append(g.NodeIDs, id)
+				if id == g.SelectedNodeID {
+					selectedKept = true
+				}
+			}
+		}
+		if len(g.NodeIDs) == 0 {
+			continue
+		}
+		if !selectedKept {
+			g.SelectedNodeID = ""
+		}
+		if err := validateNarrowGroup(g); err != nil {
+			return invalid(err)
+		}
+		out.Groups = append(out.Groups, g)
+		keptGroups[g.GroupID] = true
+		targets = append(targets, Target{ID: g.GroupID, Kind: "group"})
+	}
+	for _, original := range rules {
+		r := original
+		revoked := string(r.Action.Type) == "node" && !allowed[r.Action.TargetID] || string(r.Action.Type) == "group" && !keptGroups[r.Action.TargetID]
+		if revoked {
+			r.Action = api.NetworkProxyRuleAction{Type: api.NetworkProxyRuleActionType("reject")}
+			// invalid_target has no masking rule. Self-reference identifies the rule
+			// requiring repair while satisfying the existing required conflict fields.
+			out.Conflicts = append(out.Conflicts, api.NetworkProxyRuleConflict{RuleID: r.RuleID, BlockingRuleID: r.RuleID, ReasonCode: api.NetworkProxyRuleConflictReasonCode("invalid_target")})
+		}
+		if err := ValidateRule(r, targets, true); err != nil {
+			return invalid(fmt.Errorf("narrowed rule %s: %w", r.RuleID, err))
+		}
+		out.Rules = append(out.Rules, r)
+	}
+	return out, nil
+}
+
+func validateNarrowGroup(g api.NetworkProxyGroup) error {
+	if !narrowIdentifier.MatchString(g.GroupID) || !utf8.ValidString(g.Label) || utf8.RuneCountInString(g.Label) < 1 || utf8.RuneCountInString(g.Label) > 128 || len(g.NodeIDs) > 128 {
+		return errors.New("invalid proxy group fields")
+	}
+	switch string(g.Type) {
+	case "select", "url_test", "fallback", "load_balance":
+	default:
+		return errors.New("unsupported proxy group type")
+	}
+	selected := g.SelectedNodeID == ""
+	for _, id := range g.NodeIDs {
+		if !narrowIdentifier.MatchString(id) {
+			return errors.New("invalid group node ID")
+		}
+		if id == g.SelectedNodeID {
+			selected = true
+		}
+	}
+	if !selected {
+		return errors.New("group selection is not a member")
+	}
+	return nil
+}