@opensoha/contracts 0.1.29 → 0.2.0

package/go.mod

@@ -1,9 +1,10 @@
-module github.com/opensoha/soha-contracts
+module github.com/opensoha/soha/contracts
 
-go 1.27.3
+go 1.27.4
 
 require (
 	github.com/google/uuid v1.6.0
+	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674
 	github.com/oapi-codegen/runtime v1.7.0
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
 	go.yaml.in/yaml/v3 v3.0.5
@@ -80,6 +81,7 @@ require (
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
 	github.com/mitchellh/reflectwalk v1.0.2 // indirect
+	github.com/moby/spdystream v0.5.1 // indirect
 	github.com/moby/term v0.5.2 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
@@ -122,6 +124,7 @@ require (
 	k8s.io/klog/v2 v2.140.0 // indirect
 	k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad // indirect
 	k8s.io/kubectl v0.37.1 // indirect
+	k8s.io/streaming v0.37.1 // indirect
 	oras.land/oras-go/v2 v2.6.2 // indirect
 	sigs.k8s.io/controller-runtime v0.25.2 // indirect
 	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect

package/go.sum

@@ -25,6 +25,8 @@ github.com/ProtonMail/go-crypto v1.5.2/go.mod h1:/RaSu30DaKO4RY+XdV/ACcCcZkGr7Ah
 github.com/RaveNoX/go-jsoncommentstrip v1.0.0/go.mod h1:78ihd09MekBnJnxpICcwzCMzGrKSKYe4AqU6PDYYpjk=
 github.com/apapsch/go-jsonmerge/v2 v2.0.0 h1:axGnT1gRIfimI7gJifB699GoE/oq+F2MU7Dml6nw9rQ=
 github.com/apapsch/go-jsonmerge/v2 v2.0.0/go.mod h1:lvDnEdqiQrp0O42VQGgmlKpxL1AP2+08jFMw88y4klk=
+github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
+github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
 github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so=
 github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
@@ -158,6 +160,8 @@ github.com/gorilla/handlers v1.5.2 h1:cLTUSsNkgcwhgRqvCNmdbRWG0A3N4F+M2nWKdScwyE
 github.com/gorilla/handlers v1.5.2/go.mod h1:dX+xVpaxdSw+q0Qek8SSsl3dfMk3jNddUkMzo0GtH0w=
 github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
 github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
+github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=
+github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
 github.com/gosuri/uitable v0.0.4 h1:IG2xLKRvErL3uhY6e1BylFzG+aJiwQviDDTfOKeKTpY=
 github.com/gosuri/uitable v0.0.4/go.mod h1:tKR86bXuXPZazfOTG1FIzvjIdXzd0mo4Vtn16vt0PJo=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 h1:5VipnvEpbqr2gA2VbM+nYVbkIF28c5ZQfqCBQ5g2xfk=
@@ -208,6 +212,8 @@ github.com/mitchellh/go-wordwrap v1.0.1 h1:TLuKupo69TCn6TQSyGxwI1EblZZEsQ0vMlAFQ
 github.com/mitchellh/go-wordwrap v1.0.1/go.mod h1:R62XHJLzvMFRBbcrT7m7WgmE1eOyTSsCt+hzestvNj0=
 github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ=
 github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw=
+github.com/moby/spdystream v0.5.1 h1:9sNYeYZUcci9R6/w7KDaFWEWeV4LStVG78Mpyq/Zm/Y=
+github.com/moby/spdystream v0.5.1/go.mod h1:xBAYlnt/ay+11ShkdFKNAG7LsyK/tmNBVvVOwrfMgdI=
 github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ=
 github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -415,6 +421,8 @@ k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad h1:oXImqH8mQNk7PmvzKhmN3d
 k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad/go.mod h1:0/mqHCVhlumdJ3BhCfnjSZQE037nAhNodh1/hK0T8/I=
 k8s.io/kubectl v0.37.1 h1:n1VCIntOJiX943uByXCThSZQmE+4v9jGS8S9u94/aHU=
 k8s.io/kubectl v0.37.1/go.mod h1:66cc4Bz8PxBTxlrHzBuzXEzGIytAnNasKQPeEcpuaV8=
+k8s.io/streaming v0.37.1 h1:TpzVfQeFuVndn2g9mFqxy1UcUYPwDzqjUmwR/IzJCWc=
+k8s.io/streaming v0.37.1/go.mod h1:APlJR26ZWRcVy5bIEj0QRrKUXROtBHPcxl2NT7EAzPU=
 k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3 h1:jVkFFVfXdXP74B/zbO3hM3hpSFD0xvhQ5U686DPurkE=
 k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3/go.mod h1:M2s5JB1lIYP3jzZdorPLHXIPJzt9vv2muW5a6L9DtNM=
 oras.land/oras-go/v2 v2.6.2 h1:N04RXngAp1LJKTG6ifz3xHPipasEkWr+hFmInja5YKo=

package/helmrelease/delivery.go

@@ -14,7 +14,7 @@ import (
 	"regexp"
 	"strings"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
 )
 
 const (

package/helmrelease/delivery_test.go

@@ -8,7 +8,7 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
 )
 
 func TestHelmDeliveryBoundaries(t *testing.T) {

package/helmrelease/initialization.go

@@ -1,6 +1,6 @@
 package helmrelease
 
-import "github.com/opensoha/soha-contracts/gen/go/sohaapi"
+import "github.com/opensoha/soha/contracts/gen/go/sohaapi"
 
 const InitializationCapability = "helm.initialize.v1"
 const InitializationProviderPrefix = "helm_initialize_v1."

package/helmrelease/result.go

@@ -3,7 +3,7 @@ package helmrelease
 import (
 	"errors"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
 )
 
 // ValidateCompletedResult binds completion to the frozen plan and native revision.

package/helmrelease/runtime/delivery.go

@@ -14,10 +14,10 @@ import (
 	"strings"
 	"time"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
-	"github.com/opensoha/soha-contracts/helmrelease"
-	contractresource "github.com/opensoha/soha-contracts/resource"
-	resourceruntime "github.com/opensoha/soha-contracts/resource/runtime"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/helmrelease"
+	contractresource "github.com/opensoha/soha/contracts/resource"
+	resourceruntime "github.com/opensoha/soha/contracts/resource/runtime"
 	"helm.sh/helm/v4/pkg/action"
 	"helm.sh/helm/v4/pkg/chart"
 	"helm.sh/helm/v4/pkg/chart/loader"

package/helmrelease/runtime/delivery_test.go

@@ -13,8 +13,8 @@ import (
 	"testing"
 	"time"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
-	"github.com/opensoha/soha-contracts/helmrelease"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/helmrelease"
 	"helm.sh/helm/v4/pkg/action"
 	"helm.sh/helm/v4/pkg/chart/common"
 	"helm.sh/helm/v4/pkg/chart/loader"

package/helmrelease/runtime/initialization.go

@@ -6,8 +6,8 @@ import (
 	"strings"
 	"sync"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
-	"github.com/opensoha/soha-contracts/helmrelease"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/helmrelease"
 	"helm.sh/helm/v4/pkg/action"
 	"helm.sh/helm/v4/pkg/kube"
 	helmreleasev1 "helm.sh/helm/v4/pkg/release/v1"

package/helmrelease/runtime/initialization_test.go

@@ -12,8 +12,8 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
-	"github.com/opensoha/soha-contracts/helmrelease"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/helmrelease"
 	"helm.sh/helm/v4/pkg/action"
 	"helm.sh/helm/v4/pkg/chart/common"
 	"helm.sh/helm/v4/pkg/kube"

package/helmrelease/runtime/values_upgrade.go

@@ -4,7 +4,7 @@ import (
 	"errors"
 	"fmt"
 
-	"github.com/opensoha/soha-contracts/helmrelease"
+	"github.com/opensoha/soha/contracts/helmrelease"
 	"helm.sh/helm/v4/pkg/action"
 	"helm.sh/helm/v4/pkg/release"
 	helmreleasev1 "helm.sh/helm/v4/pkg/release/v1"

package/helmrelease/values.go

@@ -7,7 +7,7 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
 )
 
 // MapImages returns a copy; mapping never changes a saved values configuration.

package/memory/memory-policy.schema.json

@@ -14,6 +14,10 @@
     "maximumTtlSeconds": { "type": "integer", "minimum": 1, "maximum": 31536000 },
     "minimumConfidence": { "type": "number", "minimum": 0, "maximum": 1 },
     "explicitWriteOnly": { "type": "boolean" },
-    "enabled": { "type": "boolean" }
+    "enabled": { "type": "boolean" },
+    "ownerId": { "type": "string", "readOnly": true, "description": "Server-bound owner; omitted for legacy global policies." },
+    "mode": { "type": "string", "enum": ["chat", "heya"], "description": "Server-bound mode; absent means legacy global policy." },
+    "readEnabled": { "type": "boolean", "description": "Inherits enabled when absent." },
+    "writeEnabled": { "type": "boolean", "description": "Inherits enabled when absent." }
   }
 }

package/memory/memory-record.schema.json

@@ -20,6 +20,10 @@
     "policyVersion": { "type": "string", "minLength": 1 },
     "status": { "enum": ["active", "expired", "deleted"] },
     "createdAt": { "type": "string", "format": "date-time" },
-    "deletedAt": { "type": "string", "format": "date-time" }
+    "deletedAt": { "type": "string", "format": "date-time" },
+    "syncStatus": { "type": "string", "readOnly": true, "enum": ["pending", "synced", "delete_pending", "deleted", "error", "disabled"], "description": "Server-owned synchronization state; omitted on legacy records." },
+    "quarantined": { "type": "boolean", "readOnly": true, "description": "Server-owned quarantine projection; absent or false means normal. Quarantined records retain their actual status and have syncStatus disabled. Client overrides are ignored." },
+    "quarantineReason": { "type": "string", "maxLength": 128, "readOnly": true, "description": "Safe server-owned reason code; excludes errors, addresses and fact contents. Client overrides are ignored." },
+    "sourceHashes": { "type": "object", "readOnly": true, "description": "Server-generated source receipt URI to lowercase SHA256 of authorized source content; never trust client hashes.", "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }
   }
 }

package/network/README.md

@@ -200,3 +200,82 @@ for telemetry.
 - A dedicated EAP issuer signs only client authentication certificates with a `network-eap` URI. EAP certificates cannot authenticate control or ingest requests. Without an issuer, issuance is unavailable. Existing runtime certificates are accepted for legacy EAP only when enrollment explicitly declares `radius-eap-tls-v1`; ordinary control credentials do not imply EAP permission.
 - Issuance is idempotent per runtime/request ID and CSR. Certificates start pending and cannot grant network access. After native installation and readback, activation atomically replaces the old EAP certificate under the parent runtime credential lock. A retired or expired parent invalidates every child. Replaying an older activation cannot revive it.
 - `admission.profiles` is delivered only to `eap-profile-v1` endpoints, with exact EAP server names, CA certificates, subject and the dedicated active EAP certificate fingerprint. Configuration export, installation, 802.1X connection and actual NAS enforcement are separate results.
+
+## Restricted TTLS/PAP authentication (B3-ADMISSION-v1)
+
+`radius-password-verifier.schema.json` owns the request/result for
+`POST /api/network-control/v1/runtimes/{runtimeId}/radius:verify-password`.
+Only a dedicated active NAS mTLS identity with `radius-ttls-pap-verifier-v1`
+and an allowed direct peer may call it. The NAS binding determines site scope.
+`passwordBase64` is standard canonical Base64 of 1–72 original password bytes;
+it is a secret transport encoding, never a hash or encryption. No passwords,
+encoded passwords or hashes enter runtime messages, logs, audits or queues.
+
+Success returns authentication only, with an opaque 256-bit receipt expiring in
+30 seconds. Core stores only its SHA-256 and runtime/NAS/site/station/subject/
+password-version binding. NAS authorization uses `eap-ttls-pap` plus the receipt;
+it cannot supply a device ID. Consumption is transactional and one-use across
+authorization requests; retrying the same authorization request returns its
+existing result without extending validity. Wrong scope, expiry, changed password,
+disabled account or newly required MFA fails closed. Success is still subject
+to current policy and the restricted profile ceiling. Legacy `password-compatible`
+is a trust classification, never proof of TTLS authentication.
+
+Password verification refuses accounts requiring MFA or configured interactive
+checks, disabled local password login, unavailable protection state, lockouts
+or exhausted persistent NAS/source/principal budgets. It issues no login token.
+Unknown accounts and wrong passwords share the generic authentication failure.
+
+Admission profiles and NAS server trust add `eapMethod` (`tls` by default, or
+`ttls`), with `innerMethod: pap` and `credentialSource: user-input` required only
+for TTLS. TTLS profiles never carry a client certificate fingerprint or password
+reference. Server names and CA validation remain mandatory. A TTLS endpoint must
+advertise `radius-eap-ttls-pap-v1`; PEAP is unsupported without a compatible backend.
+`profileRevision` is a secret-free normalized profile SHA-256.
+
+Endpoints advertising `eap-certificate-lifecycle-v1` bind activation to the issue
+`requestId`, `profileId` and `profileRevision`. `eap.certificate.revoke.request`
+uses `eap:revoke`, binds the owning endpoint and certificate fingerprint, and is
+idempotent. Revocation also requests withdrawal of matching online sessions.
+Native installation, certificate activation, NAS authentication and data-plane
+enforcement remain distinct outcomes.
+
+The verifier HTTP success body is a strict FreeRADIUS attribute map:
+`control:Tmp-String-4` contains the receipt and `control:Tmp-String-5` the subject.
+Each attribute uses `op: ":="`, `do_xlat: false`, and one `value` string.
+Authentication failure is HTTP 401 with no body; no account-specific reason
+appears on this transport. The schema's `Result` definition describes internal
+application semantics; `RADIUSSuccess` describes the HTTP 200 wire body.
+
+The verifier's `login` is the exact Soha subject ID from the trusted profile
+identity, not an email or username alias. Core resolves it by account ID only
+and binds the resulting receipt to that same subject. User-supplied alias
+resolution must not redirect an enrolled profile to another account.
+
+## Managed RADIUS pools (RT04-RAD-C1)
+
+`radius-runtime.schema.json` owns pool/member, approved configuration references,
+control leases, native State acknowledgements and the managed NAS runtime proof.
+Management uses `/network-access/radius-pools`; members use the dedicated mTLS
+`/api/network-control/v1/radius-runtimes/{runtimeID}/control` GET and its
+`/control/receipt` POST. GET requires exactly one `memberId` and `processEpoch`.
+
+Pool logical runtime IDs use reserved `radius-pool:` identities and cannot enroll.
+Each installed member has an independent `radius-member:` identity and current
+credential. Managed resolution takes precedence over legacy exact NAS matching;
+stale members and logical IDs cannot fall through. NAS authorization and TTLS
+verification require the current `runtimeProof` for managed members. External
+NAS callers retain their exact binding and must not provide a managed proof.
+
+`runProcess` and `acceptNewAuthentications` are independent. Bootstrap can run
+a child while new traffic is refused. `stateCountKnown: true` requires an explicit
+non-null `activeStates` (including zero); unknown counts omit that field.
+`processStopped: true` requires known zero, ready=false and no new acceptance,
+but does not require live hooks. Lease/configuration expiry and drain updates
+never extend an existing State hard bound. Unknown State cannot permit scaling;
+only a bounded known-zero drain or exact owned-child stop/wait proof can do so.
+
+Every member publishes an installer-approved endpoint for explicit NAS primary/
+backup configuration. Pod readiness is not traffic readiness, endpoints are not
+a UDP round-robin service, and scaling does not move EAP State or change NAS
+configuration. Configuration materials contain approved `secretref:` values only.

package/network/network-ingest-event.schema.json

@@ -421,8 +421,11 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["engine", "uptimeSeconds", "uploadTotal", "downloadTotal"],
+      "dependentRequired": { "processEpoch": ["sampleSequence"], "sampleSequence": ["processEpoch"] },
       "properties": {
-        "engine": { "enum": ["mihomo", "sing-box", "v2ray"] },
+        "engine": { "enum": ["mihomo", "sing-box", "v2ray", "external"] },
+        "processEpoch": {"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},
+        "sampleSequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
         "uptimeSeconds": { "type": "integer", "minimum": 0 },
         "uploadTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
         "downloadTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },