Add Network Door, Mesh Door, BYOM, and native assistant contracts

docs/contract-additions/README.md

@@ -5,6 +5,7 @@ This directory contains discoverability notes for additive SourceOS/SociOS contr
 | Addition | Purpose | Key schemas |
 |---|---|---|
 | [Agent Machine Local Data Plane and TopoLVM Mount Contracts](agent-machine-local-data-plane.md) | Defines safe local workspace mounts for Agent Machine and maps the same logical contract to TopoLVM-backed node-local persistent volumes in cluster mode. | `AgentMachineLocalDataPlane`, `AgentMachineMountPolicy`, `TopoLVMPlacementProfile` |
+| [Network, Mesh, BYOM, and Native Assistant Door Contracts](network-assistant-model-doors.md) | Defines enterprise/user network profiles, firewall bindings, service-mesh bindings, BYOM model endpoints, and native assistant bridges such as Apple App Intents/Siri/Shortcuts-style integrations. | `NetworkAccessProfile`, `FirewallBindingProfile`, `MeshBindingProfile`, `ExternalModelProviderProfile`, `NativeAssistantBridgeProfile` |
 
 ## Rules for additions
 

docs/contract-additions/network-assistant-model-doors.md

@@ -0,0 +1,110 @@
+# Network, Mesh, BYOM, and Native Assistant Door contracts
+
+This contract addition defines the SourceOS boundary for enterprise networking, user firewalls, service mesh integrations, bring-your-own-model endpoints, and native assistant bridges such as Apple App Intents/Siri/Shortcuts.
+
+## Why this exists
+
+Enterprise customers need SourceOS Agent Machine, Office Plane, Local Model Door, and external model routing to respect corporate firewall and service-mesh policy. Individual users also need their own local firewall and model-provider profiles.
+
+These cannot be ambient privileges. Network and assistant integrations must be declared as profiles and connected to evidence, model routing, policy, and consent.
+
+## New schema types
+
+| Schema | Purpose |
+|---|---|
+| `NetworkAccessProfile.json` | Precedence-aware user/enterprise/device/workspace network policy stack. |
+| `FirewallBindingProfile.json` | Host, user, enterprise, and cluster firewall binding plan/import profile. |
+| `MeshBindingProfile.json` | Istio/Admiral/Linkerd/Cilium/Kubernetes mesh-policy binding profile. |
+| `ExternalModelProviderProfile.json` | BYOM and enterprise model endpoint profile, including endpoint, auth reference, firewall/mesh refs, and route policy. |
+| `NativeAssistantBridgeProfile.json` | Native assistant integration profile for Apple App Intents/Siri/Shortcuts, Android, Windows, browser extensions, and future host/device bridges. |
+
+## Profile separation
+
+SourceOS must support multiple simultaneous network profiles:
+
+- corporate firewall profile;
+- workspace profile;
+- device profile;
+- user firewall profile;
+- agent/workload profile;
+- model-provider profile.
+
+Default precedence should be:
+
+```text
+enterprise -> workspace -> device -> user -> agent -> model-provider
+```
+
+A user profile may be stricter than enterprise policy, but must not override enterprise denies.
+
+## Firewall and mesh posture
+
+Mesh policy and firewall policy are complementary.
+
+Istio egress gateways route traffic through mesh-controlled exit points and allow monitoring/routing policy on traffic leaving the mesh. However, mesh sidecars can be bypassed unless external enforcement such as network policy or firewall controls prevent non-gateway egress. Therefore SourceOS models both:
+
+```text
+MeshBindingProfile + FirewallBindingProfile
+```
+
+## BYOM posture
+
+Bring-your-own-model endpoints are first-class provider profiles. They can represent user-private endpoints, enterprise-private endpoints, or cloud model providers.
+
+Rules:
+
+- endpoint auth is always a reference, never an inline token;
+- prompt egress is denied by default unless policy allows it;
+- training use is denied by default;
+- hosted fallback requires model-router and network-policy approval;
+- provider route decisions emit evidence.
+
+## Native assistant posture
+
+Apple integration should use App Intents/App Shortcuts style surfaces, not raw Siri plumbing. SourceOS capabilities should be exposed as declared intents such as:
+
+- open workroom;
+- create office artifact;
+- summarize;
+- route local model;
+- inspect evidence;
+- hand off to Agent Machine.
+
+Native assistant bridges must remain policy-gated:
+
+- local-only by default;
+- no prompt egress by default;
+- no raw app database access;
+- no side effects without confirmation;
+- cross-device handoff disabled unless explicitly granted;
+- prompt evidence should be hash-only/redacted.
+
+## Examples
+
+| Example | Purpose |
+|---|---|
+| `examples/network_access_profile.enterprise_and_user.json` | Enterprise and user profile stack with precedence. |
+| `examples/firewall_binding_profile.macos_lulu_user.json` | macOS user firewall planning profile for LuLu-style outbound control. |
+| `examples/firewall_binding_profile.enterprise_gateway.json` | Enterprise gateway firewall import/enforcement profile. |
+| `examples/mesh_binding_profile.istio_admiral_enterprise.json` | Istio/Admiral-style enterprise mesh egress profile. |
+| `examples/external_model_provider_profile.byom_openai_compatible.json` | User BYOM OpenAI-compatible endpoint profile. |
+| `examples/native_assistant_bridge_profile.apple_app_intents.json` | Apple App Intents/Siri/Shortcuts-style native bridge profile. |
+
+## Implementation owners
+
+| Repo | Role |
+|---|---|
+| `SourceOS-Linux/sourceos-spec` | Canonical network/firewall/mesh/BYOM/native assistant contracts. |
+| `SourceOS-Linux/sourceos-devtools` | Future `sourceosctl network ...` and `sourceosctl native-assistant ...` probe/plan surface. |
+| `SocioProphet/model-router` | Route external model providers and BYOM endpoints under local/enterprise policy. |
+| `SocioProphet/agentplane` | Network/model-provider/native-assistant evidence. |
+| `SocioProphet/sociosphere` | Topology validation and dependency direction. |
+| `SociOS-Linux/socios` | Opt-in orchestration where network/model/native assistant flows touch personalization workflows. |
+| `SocioProphet/guardrail-fabric` | Policy decision/evidence authority for prompt egress and side effects. |
+
+## Non-goals
+
+- Do not vendor Istio, Admiral, LuLu, Cilium, or enterprise firewall implementation here.
+- Do not store firewall credentials, VPN secrets, API keys, or model-provider tokens.
+- Do not claim a mesh policy alone prevents bypass; firewall/network policy must be modeled too.
+- Do not expose raw Apple app databases, Photos libraries, Notes stores, mail stores, browser profiles, keychains, or token stores by default.

examples/external_model_provider_profile.byom_openai_compatible.json

@@ -0,0 +1,36 @@
+{
+  "id": "urn:srcos:external-model-provider-profile:user-openai-compatible",
+  "type": "ExternalModelProviderProfile",
+  "specVersion": "2.2.0",
+  "name": "User BYOM OpenAI-compatible endpoint",
+  "providerClass": "openai-compatible",
+  "owner": "user",
+  "endpoint": {
+    "baseUrlRef": "secret://user/model-provider/base-url",
+    "authRef": "secret://user/model-provider/api-key",
+    "tlsPolicyRef": "urn:srcos:tls-policy:user-model-provider-default",
+    "networkAccessProfileRef": "urn:srcos:network-access-profile:enterprise-and-user-default",
+    "firewallBindingRef": "urn:srcos:firewall-binding-profile:macos-lulu-user-default",
+    "meshBindingRef": null
+  },
+  "routing": {
+    "modelRouterBindingRef": "urn:socioprophet:model-router-binding:demo-user-local-llama32",
+    "taskClasses": ["summarization", "rewrite", "office-assist", "complex-reasoning"],
+    "fallbackOrder": ["local-llama32-1b", "local-llama32-3b", "user-openai-compatible"],
+    "hostedFallbackRequiresPolicy": true
+  },
+  "policy": {
+    "promptEgressDefault": "allow-with-policy",
+    "storePrompts": false,
+    "storeCompletions": false,
+    "allowTrainingUse": false,
+    "requiresDpaOrEnterpriseTerms": false,
+    "requiresUserConsentForPersonalData": true
+  },
+  "evidence": {
+    "emitRouteDecision": true,
+    "emitNetworkDecision": true,
+    "emitProviderHealth": true,
+    "promptHashOnly": true
+  }
+}

examples/firewall_binding_profile.enterprise_gateway.json

@@ -0,0 +1,39 @@
+{
+  "id": "urn:srcos:firewall-binding-profile:enterprise-gateway-default",
+  "type": "FirewallBindingProfile",
+  "specVersion": "2.2.0",
+  "name": "Enterprise gateway firewall binding for SourceOS workloads",
+  "bindingClass": "enterprise-gateway",
+  "mode": "import-only",
+  "owner": "enterprise",
+  "precedence": 0,
+  "conflictPolicy": "enterprise-wins",
+  "rules": [
+    {
+      "ruleId": "allow-enterprise-model-endpoint",
+      "direction": "egress",
+      "decision": "allow",
+      "subject": "sourceos-agent-machine-workloads",
+      "destination": "models.enterprise.example",
+      "ports": [443],
+      "protocols": ["tcp", "https"],
+      "reason": "Enterprise-approved private model endpoint."
+    },
+    {
+      "ruleId": "deny-unapproved-model-egress",
+      "direction": "egress",
+      "decision": "deny",
+      "subject": "sourceos-agent-machine-workloads",
+      "destination": "unapproved-external-model-providers",
+      "ports": [443],
+      "protocols": ["tcp", "https"],
+      "reason": "Corporate firewall owns external model egress approval."
+    }
+  ],
+  "evidence": {
+    "emitRulePlan": true,
+    "emitAppliedRuleReceipt": true,
+    "emitDeniedConnectionReceipt": true,
+    "redactDestinations": true
+  }
+}

examples/firewall_binding_profile.macos_lulu_user.json

@@ -0,0 +1,39 @@
+{
+  "id": "urn:srcos:firewall-binding-profile:macos-lulu-user-default",
+  "type": "FirewallBindingProfile",
+  "specVersion": "2.2.0",
+  "name": "macOS user firewall binding for SourceOS local tools",
+  "bindingClass": "macos-lulu",
+  "mode": "plan",
+  "owner": "user",
+  "precedence": 50,
+  "conflictPolicy": "most-restrictive-wins",
+  "rules": [
+    {
+      "ruleId": "allow-local-ollama",
+      "direction": "egress",
+      "decision": "allow",
+      "subject": "sourceosctl",
+      "destination": "127.0.0.1",
+      "ports": [11434],
+      "protocols": ["tcp", "http"],
+      "reason": "Allow local model runtime probe without external network egress."
+    },
+    {
+      "ruleId": "ask-external-model-provider",
+      "direction": "egress",
+      "decision": "ask",
+      "subject": "sourceosctl",
+      "destination": "external-model-provider",
+      "ports": [443],
+      "protocols": ["tcp", "https"],
+      "reason": "External model provider access is user-visible and policy-gated."
+    }
+  ],
+  "evidence": {
+    "emitRulePlan": true,
+    "emitAppliedRuleReceipt": true,
+    "emitDeniedConnectionReceipt": true,
+    "redactDestinations": true
+  }
+}

examples/mesh_binding_profile.istio_admiral_enterprise.json

@@ -0,0 +1,36 @@
+{
+  "id": "urn:srcos:mesh-binding-profile:istio-egress-default",
+  "type": "MeshBindingProfile",
+  "specVersion": "2.2.0",
+  "name": "Istio/Admiral-style enterprise mesh egress binding",
+  "meshClass": "admiral-istio",
+  "scope": "enterprise",
+  "traffic": {
+    "egressMode": "egress-gateway",
+    "ingressMode": "gateway",
+    "allowedHosts": [
+      "models.enterprise.example",
+      "registry.enterprise.example",
+      "updates.enterprise.example"
+    ],
+    "deniedHosts": ["*"],
+    "mtlsRequired": true,
+    "externalModelEgressAllowed": false
+  },
+  "identity": {
+    "serviceAccountRef": "system:serviceaccount:sourceos:agent-machine-runner",
+    "spiffeIdRef": "spiffe://enterprise.example/sourceos/agent-machine-runner",
+    "workloadSelector": "app=sourceos-agent-machine",
+    "agentRegistryRef": "urn:socioprophet:agent-registry:agent-machine-runner"
+  },
+  "policyRefs": [
+    "urn:srcos:network-access-profile:enterprise-and-user-default",
+    "urn:srcos:firewall-binding-profile:enterprise-gateway-default"
+  ],
+  "evidence": {
+    "emitTrafficDecision": true,
+    "emitMeshPolicyRef": true,
+    "emitMtlsStatus": true,
+    "emitEgressGatewayReceipt": true
+  }
+}

examples/native_assistant_bridge_profile.apple_app_intents.json

@@ -0,0 +1,69 @@
+{
+  "id": "urn:srcos:native-assistant-bridge-profile:apple-app-intents-default",
+  "type": "NativeAssistantBridgeProfile",
+  "specVersion": "2.2.0",
+  "name": "Apple App Intents bridge for SourceOS workrooms",
+  "platform": "macos",
+  "bridgeClass": "apple-app-intents",
+  "capabilities": [
+    {
+      "capabilityId": "open-workroom",
+      "operation": "open-workroom",
+      "defaultDecision": "allow-readonly",
+      "requiresUserConfirmation": false,
+      "requiresNetworkProfileRef": null,
+      "requiresModelRouteBindingRef": null,
+      "requiresAgentRegistryGrantRef": null
+    },
+    {
+      "capabilityId": "create-office-artifact",
+      "operation": "create-office-artifact",
+      "defaultDecision": "ask",
+      "requiresUserConfirmation": true,
+      "requiresNetworkProfileRef": "urn:srcos:network-access-profile:enterprise-and-user-default",
+      "requiresModelRouteBindingRef": "urn:socioprophet:model-router-binding:demo-user-local-llama32",
+      "requiresAgentRegistryGrantRef": null
+    },
+    {
+      "capabilityId": "route-local-model",
+      "operation": "route-local-model",
+      "defaultDecision": "allow-with-policy",
+      "requiresUserConfirmation": true,
+      "requiresNetworkProfileRef": "urn:srcos:network-access-profile:enterprise-and-user-default",
+      "requiresModelRouteBindingRef": "urn:socioprophet:model-router-binding:demo-user-local-llama32",
+      "requiresAgentRegistryGrantRef": null
+    }
+  ],
+  "policy": {
+    "localOnlyDefault": true,
+    "allowPromptEgress": false,
+    "allowCrossDeviceHandoff": false,
+    "allowPersonalContextRead": false,
+    "allowSideEffectsWithoutConfirmation": false,
+    "allowedAppSurfaces": ["Shortcuts", "Spotlight", "Siri", "Widgets"],
+    "deniedAppSurfaces": ["raw-mail-store", "raw-notes-db", "photos-library", "keychain", "browser-profiles"]
+  },
+  "dataBoundary": {
+    "allowedRefs": [
+      "prophet-workspace://workrooms",
+      "sourceos-office://workspace/output",
+      "agentplane://evidence"
+    ],
+    "deniedRefs": [
+      "whole-home",
+      "raw-app-stores",
+      "keychain",
+      "browser-profiles",
+      "security-material-directories"
+    ],
+    "rawAppDatabaseAccessAllowed": false,
+    "promptHashOnlyEvidence": true
+  },
+  "evidence": {
+    "emitAssistantInvocation": true,
+    "emitUserConfirmation": true,
+    "emitRouteDecision": true,
+    "emitNativeBridgeReceipt": true,
+    "redactPromptText": true
+  }
+}

examples/network_access_profile.enterprise_and_user.json

@@ -0,0 +1,52 @@
+{
+  "id": "urn:srcos:network-access-profile:enterprise-and-user-default",
+  "type": "NetworkAccessProfile",
+  "specVersion": "2.2.0",
+  "name": "Enterprise and user network policy stack",
+  "scope": "workspace",
+  "defaultDecision": "deny",
+  "precedence": ["enterprise", "workspace", "device", "user", "agent", "model-provider"],
+  "profiles": [
+    {
+      "profileId": "enterprise-primary-egress",
+      "profileClass": "corporate-firewall",
+      "priority": 0,
+      "defaultEgress": "allow-listed",
+      "allowDomains": [
+        "models.enterprise.example",
+        "registry.enterprise.example",
+        "updates.enterprise.example"
+      ],
+      "denyDomains": ["*"],
+      "allowCidrs": ["10.0.0.0/8", "172.16.0.0/12"],
+      "denyCidrs": [],
+      "proxyRef": "urn:srcos:proxy:enterprise-primary",
+      "firewallBindingRef": "urn:srcos:firewall-binding-profile:enterprise-gateway-default",
+      "meshBindingRef": "urn:srcos:mesh-binding-profile:istio-egress-default",
+      "modelProviderRefs": ["urn:srcos:external-model-provider-profile:enterprise-openai-compatible"],
+      "notes": "Enterprise network profile has higher precedence than user profile."
+    },
+    {
+      "profileId": "user-local-firewall",
+      "profileClass": "user-firewall",
+      "priority": 50,
+      "defaultEgress": "allow-with-prompt",
+      "allowDomains": ["localhost", "127.0.0.1"],
+      "denyDomains": [],
+      "allowCidrs": ["127.0.0.0/8"],
+      "denyCidrs": [],
+      "proxyRef": null,
+      "firewallBindingRef": "urn:srcos:firewall-binding-profile:macos-lulu-user-default",
+      "meshBindingRef": null,
+      "modelProviderRefs": ["urn:srcos:external-model-provider-profile:user-openai-compatible"],
+      "notes": "User profile can be stricter than enterprise policy but cannot override enterprise deny rules."
+    }
+  ],
+  "evidence": {
+    "emitNetworkDecision": true,
+    "emitFirewallBinding": true,
+    "emitMeshBinding": true,
+    "emitModelProviderRoute": true,
+    "redactDestinationPath": true
+  }
+}