@opensoha/contracts 0.1.16 → 0.1.18

package/network/README.md

@@ -0,0 +1,156 @@
+# Network contract semantics
+
+The JSON Schemas in this directory define strict serialized shapes. Every
+consumer must also enforce the cross-field rules below before using a message
+for authorization, routing, firewall configuration or accounting.
+
+## Runtime messages
+
+- Runtime mTLS certificates carry exactly one Soha URI SAN:
+  `spiffe://opensoha.local/network-control/{runtimeKind}/{runtimeId}`.
+  Ingest certificates use the separate scope
+  `spiffe://opensoha.local/network-ingest/{producerKind}/{producerId}` and may
+  not be reused for control. The body identity is only a consistency check.
+- `devicePublicKey` is one PKIX `PUBLIC KEY` PEM block and must match the
+  public key of the authenticated enrollment certificate.
+- A runtime advertising the `wireguard` capability must submit exactly one
+  WireGuard public key during enrollment. The corresponding private key is
+  generated and retained in runtime-local protected storage. Re-enrollment
+  advances the credential/key generation and retires the prior public key.
+- Reject a message when `expiresAt` is not later than `occurredAt` or is
+  already expired.
+- Parse every CIDR with the platform standard library, require canonical
+  network form, and reject anything not accepted by `netip.ParsePrefix` or an
+  equivalent parser. `network-runtime/v1alpha1` carries IPv4 CIDRs only.
+- Resolve `runtimeId` to the authenticated runtime credential. Never trust the
+  body to select another runtime.
+- Accept `nas.*` messages only from or for a runtime whose registered kind is
+  `nas`; the authenticated runtime must also match the active NAS binding for
+  `payload.nasId` and its site.
+- Treat `nas.authorization.request` as authorization input only. It never
+  carries a password, EAP exchange, RADIUS packet or shared secret. The
+  `password-compatible` method is lower trust than `eap-tls` and policy may
+  only preserve or reduce its access profile.
+- For `eap-tls`, resolve the certificate's canonical serial plus authority key
+  identifier to one active endpoint credential and derive `deviceId` from that
+  credential. Match `subjectId` to the credential; treat `stationId` only as
+  NAS evidence, never as device identity. Password-compatible requests identify
+  the device explicitly and may not claim client-certificate binding fields.
+- Emit RADIUS attributes only for an allow decision. The NAS adapter maps
+  `vlanId`, `filterId` and `sessionTimeoutSeconds` to standard RADIUS
+  attributes; vendor-specific attributes stay outside this contract.
+- Match authorization result `requestId`, session command result `commandId`
+  and `sessionId` to the outstanding request or command before changing state.
+- Copy the Soha authorization `sessionId` into the standard RADIUS `Class`
+  reply attribute and require NAS accounting to echo it as `sessionId` when
+  available. Session commands repeat the bound `subjectId` and `deviceId` so
+  the adapter can target CoA/Disconnect without querying management APIs.
+- If a requested CoA is unsupported, issue a disconnect command when the NAS
+  binding supports it; otherwise fail closed and record the unsupported
+  enforcement result.
+- For endpoint desired state, require every lease `deviceId` to match the
+  enrolled device bound to `runtimeId`.
+- Require all leases in one desired state to belong to the expected session
+  and subject/device binding.
+- Require lease `expiresAt` to be later than `issuedAt`, no later than the
+  enclosing message/configuration validity, and within the configured maximum
+  lease TTL.
+- Apply only monotonically newer configuration versions. A rollback is a new
+  version whose content intentionally references a prior snapshot.
+- Treat `runtimeIntervals` as optional scheduling guidance for backward
+  compatibility. When present, both heartbeat and configuration polling use
+  the same 30–300 second bounds; clients apply local ±20% jitter.
+- Accept `vpn.connect.request` only from an enrolled endpoint bound to the
+  requested device. The selected site, NetworkSpace, gateway and NetworkLease
+  must all be active and authorized by the loaded policy snapshot.
+- `vpn.connect.request.gatewayId` only selects an ingress gateway; it never
+  expands the requested site, NetworkSpace, resource or policy scope. When it
+  is omitted, the control plane may select an eligible gateway using the same
+  authorization checks.
+- A gateway without `hubGatewayId` is a topology root. A gateway with
+  `hubGatewayId` is a routed spoke of that active root. Spokes may not point to
+  another spoke, use SNAT, or form direct spoke-to-spoke peers; traffic between
+  spokes transits the root.
+- Every `advertisedCidrs` entry must be canonical, belong to an active
+  NetworkSpace at that gateway's site, and not overlap another active site or
+  gateway overlay prefix. A site link is transport authorization, not user or
+  resource authorization.
+- WireGuard `allowedIPs` on an endpoint peer identify only that endpoint's
+  overlay address. A site peer may additionally carry the explicit overlay and
+  advertised prefixes of the remote topology members reachable through that
+  peer. Endpoint split routes still come only from active leases, and the
+  `0.0.0.0/0` default route is outside v1alpha1.
+- Gateway firewall evaluation is ordered and default-deny. An exact active
+  ResourceLease allow precedes the matching ProtectedSet deny, which in turn
+  precedes a broader NetworkLease allow. Site-link rules carry
+  `siteLinkRuntimeId` plus an explicit direction and expire with the peer
+  credential; raw site LAN sources remain blocked from protected destinations.
+- `routingMode=routed` requires the site LAN to route the overlay CIDR back to
+  the gateway. `routingMode=snat` is an explicit deployment fallback and does
+  not broaden any lease or firewall rule.
+- Treat `credentialReference` only as an opaque runtime-local `secretref:`
+  identifier. It is never dereferenced by an untrusted caller and never
+  written to logs, telemetry or public responses.
+- Validate ProtectedSet before NetworkLease coverage. A broad network lease
+  cannot authorize a protected resource without a valid ResourceLease.
+
+## Managed VPN selection
+
+- Endpoint capability `managed-vpn-v1` enables the additive
+  `vpn.managed.prepare.*` and `vpn.managed.connect.*` messages. Legacy explicit
+  scope requests retain their existing contract; absent managed capability
+  never means implicit permission to use `external_vpn`.
+- Managed requests carry a short-lived intent ID/token bound to the enrolled
+  endpoint, authenticated user, published profile and selection-policy revisions.
+  The server resolves mode, site, space and resources; a caller cannot override
+  them. Prepare validates but does not consume the intent. A successful connection
+  consumes it atomically with the session and leases; replays cannot create a
+  second session. Tokens never enter audit logs or telemetry.
+- Manual selection stays on the requested gateway unless the published policy
+  explicitly permits manual-to-auto fallback. Auto only ranks gateways that
+  reach the same authorized target scope. Final admission rechecks topology,
+  live credentials, policy and capacity under the connection transaction.
+- Probe descriptors are authoritative control responses, bounded to 32 gateways,
+  10 samples, four concurrent requests and three seconds per request. Only fixed
+  HTTPS `/vpn/probe` targets are permitted; redirects and arbitrary caller URLs
+  are rejected. Gateway capability `vpn-probe-v1` enables `vpnProbe` verification
+  configuration. Probe tokens are endpoint- and gateway-bound and expire quickly.
+- HTTPS RTT is entrance-probe latency, not WireGuard or application RTT. A failed
+  HTTPS sample is a failed probe, not evidence of packet loss. Missing or expired
+  samples are unknown, never zero latency.
+- Gateway capability `vpn-metrics-v1` enables endpoint-peer `sessionId` and
+  `vpnProfileId` metadata. Site-link peers do not carry VPN user-session statistics.
+
+## Ingest batches
+
+- Authenticate `producerId` from the transport credential; do not trust the
+  body to select another producer.
+- Deduplicate by `(producerId, event.id)` for the retention window. Exact
+  duplicate objects are rejected by schema, but duplicates with changed
+  payloads must also be rejected.
+- Accept out-of-order `sequence` values as telemetry while recording gaps and
+  regressions. Sequence never changes authorization.
+- Require flow `windowEndedAt` to be later than `windowStartedAt` and
+  `deniedConnections <= connections`.
+- Reject events outside the configured clock-skew and retention window.
+- Enforce HTTP body, decompressed body, event-count and per-producer rate
+  limits before persistence.
+- Accounting and flow events are observability input only. They cannot create,
+  renew, broaden or revoke a NetworkLease or ResourceLease.
+- `vpn.probe.batch` is endpoint-only and binds the intent, profile revision,
+  selection-policy revision, network epoch and measurement window. A successful
+  RTT sample count cannot exceed the number sent. Selection accepts only samples
+  from the intent's enrolled endpoint and approved candidate set.
+- `vpn.tunnel.stats` is gateway-only. Upload is the ingress gateway's endpoint-peer
+  received-byte delta; download is its transmitted-byte delta. Session, endpoint,
+  profile, ingress gateway and counter epoch identify the sample. Exclude transit
+  site-link peers and never sum endpoint copies into gateway-authoritative totals.
+- `vpn.gateway.health` is gateway-only, carries observed runtime readiness and
+  endpoint-peer count, and is not an administrator-supplied health override.
+- VPN aggregate queries enforce trusted session/gateway bindings and authorized
+  scope before aggregation. Counters reset with a new epoch; absent data stays
+  absent. Quantiles must come from samples, not averages of per-gateway quantiles.
+
+Consumers must cover these rules with deterministic tests. Failure is
+fail-closed for control messages and bounded reject/drop-with-counter behavior
+for telemetry.

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

@@ -0,0 +1,415 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/network/network-ingest-event.schema.json",
+  "title": "OpenSoha Network Ingest Event Batch",
+  "description": "Strict bounded telemetry batches for runtime heartbeat, RADIUS Accounting, flow aggregates and connection summaries. Ingest events are not authorization facts.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "batchId", "producerId", "producerKind", "sentAt", "events"],
+  "properties": {
+    "schemaVersion": { "const": "network-ingest/v1alpha1" },
+    "batchId": { "$ref": "#/$defs/Identifier" },
+    "producerId": { "$ref": "#/$defs/Identifier" },
+    "producerKind": { "enum": ["endpoint", "gateway", "freeradius", "network-control"] },
+    "sentAt": { "type": "string", "format": "date-time" },
+    "events": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1000,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/Event" }
+    }
+  },
+  "$defs": {
+    "VPNProbeBatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "intentId",
+        "profileId",
+        "profileRevision",
+        "selectionPolicyRevision",
+        "batchId",
+        "networkEpoch",
+        "windowStartedAt",
+        "windowEndedAt",
+        "results"
+      ],
+      "properties": {
+        "intentId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "profileId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "profileRevision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "selectionPolicyRevision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "batchId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "networkEpoch": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "windowStartedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "windowEndedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "results": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "gatewayId",
+              "sentCount",
+              "rttSamplesMs"
+            ],
+            "properties": {
+              "gatewayId": {
+                "$ref": "#/$defs/Identifier"
+              },
+              "sentCount": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 10
+              },
+              "rttSamplesMs": {
+                "type": "array",
+                "minItems": 0,
+                "maxItems": 10,
+                "items": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 10000
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "VPNTunnelStats": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sessionId",
+        "profileId",
+        "gatewayId",
+        "endpointRuntimeId",
+        "epoch",
+        "windowStartedAt",
+        "windowEndedAt",
+        "uploadBytes",
+        "downloadBytes"
+      ],
+      "properties": {
+        "sessionId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "profileId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "gatewayId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "endpointRuntimeId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "epoch": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "windowStartedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "windowEndedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "uploadBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "downloadBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "lastHandshakeAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "VPNGatewayHealth": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "gatewayId",
+        "ready",
+        "activeEndpointPeers",
+        "configurationVersion",
+        "observedAt"
+      ],
+      "properties": {
+        "gatewayId": {
+          "$ref": "#/$defs/Identifier"
+        },
+        "ready": {
+          "type": "boolean"
+        },
+        "activeEndpointPeers": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1000000
+        },
+        "configurationVersion": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "observedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "Identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "Event": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "sequence", "occurredAt", "payload"],
+      "properties": {
+        "id": { "$ref": "#/$defs/Identifier" },
+        "type": {
+          "enum": [
+            "vpn.probe.batch",
+            "vpn.tunnel.stats",
+            "vpn.gateway.health",
+            "runtime.heartbeat",
+            "radius.accounting",
+            "network.flow.aggregate",
+            "network.connection.summary",
+            "proxy.flow.aggregate"
+          ]
+        },
+        "sequence": { "type": "integer", "minimum": 0 },
+        "occurredAt": { "type": "string", "format": "date-time" },
+        "payload": {
+          "oneOf": [
+            { "$ref": "#/$defs/VPNProbeBatch" },
+            { "$ref": "#/$defs/VPNTunnelStats" },
+            { "$ref": "#/$defs/VPNGatewayHealth" },
+            { "$ref": "#/$defs/Heartbeat" },
+            { "$ref": "#/$defs/RadiusAccounting" },
+            { "$ref": "#/$defs/FlowAggregate" },
+            { "$ref": "#/$defs/ConnectionSummary" },
+            { "$ref": "#/$defs/ProxyFlowAggregate" }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "vpn.probe.batch"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "properties": {
+              "payload": {
+                "$ref": "#/$defs/VPNProbeBatch"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "vpn.tunnel.stats"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "properties": {
+              "payload": {
+                "$ref": "#/$defs/VPNTunnelStats"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "vpn.gateway.health"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "properties": {
+              "payload": {
+                "$ref": "#/$defs/VPNGatewayHealth"
+              }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "runtime.heartbeat" } }, "required": ["type"] },
+          "then": { "properties": { "payload": { "$ref": "#/$defs/Heartbeat" } } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "radius.accounting" } }, "required": ["type"] },
+          "then": { "properties": { "payload": { "$ref": "#/$defs/RadiusAccounting" } } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "network.flow.aggregate" } }, "required": ["type"] },
+          "then": { "properties": { "payload": { "$ref": "#/$defs/FlowAggregate" } } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "network.connection.summary" } }, "required": ["type"] },
+          "then": { "properties": { "payload": { "$ref": "#/$defs/ConnectionSummary" } } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "proxy.flow.aggregate" } }, "required": ["type"] },
+          "then": { "properties": { "payload": { "$ref": "#/$defs/ProxyFlowAggregate" } } }
+        }
+      ]
+    },
+    "Heartbeat": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "configurationVersion", "policyVersion", "uptimeSeconds"],
+      "properties": {
+        "status": { "enum": ["healthy", "degraded", "unhealthy"] },
+        "configurationVersion": { "type": "integer", "minimum": 0 },
+        "policyVersion": { "type": "integer", "minimum": 0 },
+        "uptimeSeconds": { "type": "integer", "minimum": 0 },
+        "diagnostics": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 128 }
+        }
+      }
+    },
+    "RadiusAccounting": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["statusType", "accountingSessionId", "nasId", "sessionTimeSeconds"],
+      "properties": {
+        "statusType": { "enum": ["start", "interim-update", "stop", "accounting-on", "accounting-off"] },
+        "accountingSessionId": { "$ref": "#/$defs/Identifier" },
+        "sessionId": { "$ref": "#/$defs/Identifier" },
+        "nasId": { "$ref": "#/$defs/Identifier" },
+        "nasPortId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "userId": { "$ref": "#/$defs/Identifier" },
+        "deviceId": { "$ref": "#/$defs/Identifier" },
+        "sessionTimeSeconds": { "type": "integer", "minimum": 0 },
+        "inputOctets": { "type": "integer", "minimum": 0 },
+        "outputOctets": { "type": "integer", "minimum": 0 },
+        "inputPackets": { "type": "integer", "minimum": 0 },
+        "outputPackets": { "type": "integer", "minimum": 0 },
+        "terminationCause": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    },
+    "FlowAggregate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "windowStartedAt",
+        "windowEndedAt",
+        "sessionId",
+        "resourceId",
+        "direction",
+        "protocol",
+        "bytes",
+        "packets",
+        "connections",
+        "deniedConnections"
+      ],
+      "properties": {
+        "windowStartedAt": { "type": "string", "format": "date-time" },
+        "windowEndedAt": { "type": "string", "format": "date-time" },
+        "sessionId": { "$ref": "#/$defs/Identifier" },
+        "resourceId": { "$ref": "#/$defs/Identifier" },
+        "direction": { "enum": ["ingress", "egress"] },
+        "protocol": { "enum": ["tcp", "udp", "icmp", "other"] },
+        "bytes": { "type": "integer", "minimum": 0 },
+        "packets": { "type": "integer", "minimum": 0 },
+        "connections": { "type": "integer", "minimum": 0 },
+        "deniedConnections": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ConnectionSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionId", "resourceId", "protocol", "destinationPort", "state", "reasonCode"],
+      "properties": {
+        "sessionId": { "$ref": "#/$defs/Identifier" },
+        "resourceId": { "$ref": "#/$defs/Identifier" },
+        "protocol": { "enum": ["tcp", "udp", "icmp", "other"] },
+        "destinationPort": { "type": "integer", "minimum": 0, "maximum": 65535 },
+        "state": { "enum": ["opened", "closed", "denied"] },
+        "reasonCode": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    },
+    "ProxyFlowAggregate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "windowStartedAt",
+        "windowEndedAt",
+        "engine",
+        "profileId",
+        "profileRevision",
+        "mode",
+        "selectedProxy",
+        "uploadBytes",
+        "downloadBytes",
+        "activeConnections"
+      ],
+      "properties": {
+        "windowStartedAt": { "type": "string", "format": "date-time" },
+        "windowEndedAt": { "type": "string", "format": "date-time" },
+        "engine": { "const": "mihomo" },
+        "profileId": { "$ref": "#/$defs/Identifier" },
+        "profileRevision": { "type": "integer", "minimum": 1 },
+        "mode": { "enum": ["managed_follow", "app_subscription"] },
+        "selectedProxy": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "uploadBytes": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
+        "downloadBytes": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 },
+        "activeConnections": { "type": "integer", "minimum": 0, "maximum": 1000000 }
+      }
+    }
+  }
+}

package/network/network-radius-accounting.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/network/network-radius-accounting.schema.json",
+  "title": "OpenSoha FreeRADIUS Accounting Adapter Request",
+  "description": "A strict credential-free request converted by soha-ingest into one canonical radius.accounting event.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "eventTimestamp",
+    "statusType",
+    "accountingSessionId",
+    "nasId",
+    "sessionTimeSeconds"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "network-radius-accounting/v1alpha1" },
+    "eventTimestamp": { "type": "integer", "minimum": 1, "maximum": 253402300799 },
+    "statusType": { "enum": ["start", "interim-update", "stop", "accounting-on", "accounting-off"] },
+    "accountingSessionId": { "$ref": "#/$defs/Identifier" },
+    "sessionId": { "$ref": "#/$defs/Identifier" },
+    "nasId": { "$ref": "#/$defs/Identifier" },
+    "nasPortId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "userId": { "$ref": "#/$defs/Identifier" },
+    "deviceId": { "$ref": "#/$defs/Identifier" },
+    "sessionTimeSeconds": { "type": "integer", "minimum": 0 },
+    "inputOctets": { "type": "integer", "minimum": 0 },
+    "outputOctets": { "type": "integer", "minimum": 0 },
+    "inputPackets": { "type": "integer", "minimum": 0 },
+    "outputPackets": { "type": "integer", "minimum": 0 },
+    "terminationCause": { "type": "string", "minLength": 1, "maxLength": 128 }
+  },
+  "$defs": {
+    "Identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    }
+  }
+}