From aae1992cf3fece4d965e8284b9967e2039f506c0 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 11:46:50 -0400 Subject: [PATCH 1/6] Add Network Door and Native Assistant Door CLI helpers --- sourceosctl/commands/network.py | 194 ++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 sourceosctl/commands/network.py diff --git a/sourceosctl/commands/network.py b/sourceosctl/commands/network.py new file mode 100644 index 0000000..51b32fc --- /dev/null +++ b/sourceosctl/commands/network.py @@ -0,0 +1,194 @@ +"""Network Door and Native Assistant Door helpers. + +These commands are non-mutating. They render profile plans and evidence-shaped +summaries for enterprise/user network policy, firewalls, mesh bindings, BYOM +providers, and native assistant bridges. They do not modify firewall rules, +install mesh components, contact model providers, or invoke native assistants. +""" + +from __future__ import annotations + +import datetime as _dt +import hashlib +import json +import platform +import sys +from pathlib import Path +from typing import Any, Dict + + +NETWORK_PROFILE_REF = "urn:srcos:network-access-profile:enterprise-and-user-default" +USER_FIREWALL_REF = "urn:srcos:firewall-binding-profile:macos-lulu-user-default" +ENTERPRISE_FIREWALL_REF = "urn:srcos:firewall-binding-profile:enterprise-gateway-default" +ISTIO_MESH_REF = "urn:srcos:mesh-binding-profile:istio-egress-default" +BYOM_PROVIDER_REF = "urn:srcos:external-model-provider-profile:user-openai-compatible" +APPLE_APP_INTENTS_REF = "urn:srcos:native-assistant-bridge-profile:apple-app-intents-default" + + +def _print_json(payload: Dict[str, Any]) -> int: + print(json.dumps(payload, indent=2, sort_keys=True)) + return 0 + + +def _hash_text(value: str | None) -> str | None: + if value is None: + return None + return "sha256:" + hashlib.sha256(value.encode("utf-8")).hexdigest() + + +def doctor(args) -> int: + """Inspect host networking posture without changing anything.""" + return _print_json( + { + "type": "NetworkDoorDoctor", + "capturedAt": _dt.datetime.now(_dt.timezone.utc).isoformat(), + "host": { + "system": platform.system(), + "machine": platform.machine(), + }, + "contracts": { + "networkAccessProfileRef": NETWORK_PROFILE_REF, + "userFirewallBindingRef": USER_FIREWALL_REF, + "enterpriseFirewallBindingRef": ENTERPRISE_FIREWALL_REF, + "meshBindingRef": ISTIO_MESH_REF, + "byomProviderRef": BYOM_PROVIDER_REF, + "nativeAssistantBridgeRef": APPLE_APP_INTENTS_REF, + }, + "policy": { + "mutatesFirewall": False, + "installsMesh": False, + "contactsExternalProvider": False, + "invokesNativeAssistant": False, + "defaultEgress": "deny", + }, + } + ) + + +def plan(args) -> int: + """Render a non-mutating network route plan.""" + destination = args.destination or "model-provider" + destination_hash = _hash_text(destination) + provider_ref = args.model_provider_ref or BYOM_PROVIDER_REF + profile_ref = args.network_profile_ref or NETWORK_PROFILE_REF + mesh_ref = args.mesh_binding_ref if args.mesh else None + firewall_refs = [USER_FIREWALL_REF] + if args.enterprise: + firewall_refs.insert(0, ENTERPRISE_FIREWALL_REF) + decision = "deny" if not args.allow_listed else "allow-with-policy" + return _print_json( + { + "type": "NetworkDoorPlan", + "capturedAt": _dt.datetime.now(_dt.timezone.utc).isoformat(), + "scope": args.scope, + "destinationHash": destination_hash, + "destinationStored": False, + "decision": decision, + "networkAccessProfileRef": profile_ref, + "firewallBindingRefs": firewall_refs, + "meshBindingRef": mesh_ref, + "modelProviderRef": provider_ref, + "enterpriseProfileEnabled": args.enterprise, + "userProfileEnabled": True, + "policy": { + "enterprisePrecedence": True, + "userCanBeStricter": True, + "promptEgressDefault": "deny", + "hostedFallbackRequiresPolicy": True, + }, + "evidence": { + "emitNetworkDecision": True, + "emitFirewallBinding": True, + "emitMeshBinding": bool(mesh_ref), + "emitModelProviderRoute": True, + "redactDestinationPath": True, + }, + } + ) + + +def provider_plan(args) -> int: + """Render BYOM/external model provider profile plan without contacting it.""" + return _print_json( + { + "type": "ExternalModelProviderPlan", + "capturedAt": _dt.datetime.now(_dt.timezone.utc).isoformat(), + "providerRef": args.provider_ref or BYOM_PROVIDER_REF, + "providerClass": args.provider_class, + "owner": args.owner, + "networkAccessProfileRef": args.network_profile_ref or NETWORK_PROFILE_REF, + "firewallBindingRef": args.firewall_binding_ref or USER_FIREWALL_REF, + "meshBindingRef": args.mesh_binding_ref, + "contactsProvider": False, + "storesPrompt": False, + "storesCompletion": False, + "promptEgressDefault": "allow-with-policy" if args.allow_egress else "deny", + "authInline": False, + "authRefRequired": True, + "evidence": { + "emitRouteDecision": True, + "emitNetworkDecision": True, + "emitProviderHealth": True, + "promptHashOnly": True, + }, + } + ) + + +def native_assistant_plan(args) -> int: + """Render a native assistant bridge plan without invoking host assistant APIs.""" + return _print_json( + { + "type": "NativeAssistantBridgePlan", + "capturedAt": _dt.datetime.now(_dt.timezone.utc).isoformat(), + "bridgeRef": args.bridge_ref or APPLE_APP_INTENTS_REF, + "platform": args.platform, + "bridgeClass": args.bridge_class, + "operation": args.operation, + "invokesAssistant": False, + "promptHash": _hash_text(args.prompt) if args.prompt else None, + "promptStored": False, + "requiresUserConfirmation": args.operation not in {"open-workroom", "inspect-evidence"}, + "networkAccessProfileRef": args.network_profile_ref or NETWORK_PROFILE_REF, + "modelRouteBindingRef": args.model_route_binding_ref, + "policy": { + "localOnlyDefault": True, + "allowPromptEgress": False, + "allowCrossDeviceHandoff": bool(args.allow_cross_device), + "allowPersonalContextRead": False, + "allowSideEffectsWithoutConfirmation": False, + "rawAppDatabaseAccessAllowed": False, + }, + "evidence": { + "emitAssistantInvocation": True, + "emitUserConfirmation": True, + "emitRouteDecision": True, + "emitNativeBridgeReceipt": True, + "redactPromptText": True, + }, + } + ) + + +def evidence_inspect(args) -> int: + path = Path(args.path) + if not path.exists(): + print(f"error: evidence file not found: {path}", file=sys.stderr) + return 1 + try: + payload = json.loads(path.read_text()) + except json.JSONDecodeError as exc: + print(f"error: invalid JSON: {exc}", file=sys.stderr) + return 1 + return _print_json( + { + "path": str(path), + "type": payload.get("type"), + "decision": payload.get("decision"), + "destinationStored": payload.get("destinationStored"), + "promptStored": payload.get("promptStored"), + "networkAccessProfileRef": payload.get("networkAccessProfileRef"), + "modelProviderRef": payload.get("modelProviderRef"), + "bridgeRef": payload.get("bridgeRef"), + } + ) From f92a57ec08861a986fcefa345d20c7a7eeb4aeb6 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 11:49:15 -0400 Subject: [PATCH 2/6] Add command parsers for network and native assistant helpers --- sourceosctl/commands/network.py | 66 +++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/sourceosctl/commands/network.py b/sourceosctl/commands/network.py index 51b32fc..f17309c 100644 --- a/sourceosctl/commands/network.py +++ b/sourceosctl/commands/network.py @@ -8,6 +8,7 @@ from __future__ import annotations +import argparse import datetime as _dt import hashlib import json @@ -192,3 +193,68 @@ def evidence_inspect(args) -> int: "bridgeRef": payload.get("bridgeRef"), } ) + + +def build_network_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(prog="sourceosctl network", description="SourceOS Network Door helpers") + sub = parser.add_subparsers(dest="network_command", required=True) + + doctor_p = sub.add_parser("doctor", help="Inspect network contract posture") + doctor_p.set_defaults(func=doctor) + + plan_p = sub.add_parser("plan", help="Render non-mutating network route plan") + plan_p.add_argument("--scope", default="workspace", choices=["user", "enterprise", "device", "workspace", "agent-machine", "cluster"]) + plan_p.add_argument("--destination", default=None, help="Destination label/domain; output stores only hash") + plan_p.add_argument("--enterprise", action="store_true", default=False, help="Include enterprise firewall precedence") + plan_p.add_argument("--mesh", action="store_true", default=False, help="Include mesh binding reference") + plan_p.add_argument("--allow-listed", action="store_true", default=False, help="Model as allow-listed by policy") + plan_p.add_argument("--network-profile-ref", default=None) + plan_p.add_argument("--mesh-binding-ref", default=ISTIO_MESH_REF) + plan_p.add_argument("--model-provider-ref", default=BYOM_PROVIDER_REF) + plan_p.set_defaults(func=plan) + + provider_p = sub.add_parser("provider", help="Render external/BYOM model provider plan") + provider_p.add_argument("--provider-ref", default=BYOM_PROVIDER_REF) + provider_p.add_argument("--provider-class", default="openai-compatible") + provider_p.add_argument("--owner", default="user", choices=["user", "enterprise", "workspace", "tenant", "device"]) + provider_p.add_argument("--network-profile-ref", default=NETWORK_PROFILE_REF) + provider_p.add_argument("--firewall-binding-ref", default=USER_FIREWALL_REF) + provider_p.add_argument("--mesh-binding-ref", default=None) + provider_p.add_argument("--allow-egress", action="store_true", default=False) + provider_p.set_defaults(func=provider_plan) + + evidence_p = sub.add_parser("evidence", help="Network evidence helpers") + evidence_sub = evidence_p.add_subparsers(dest="network_evidence_command", required=True) + evidence_inspect_p = evidence_sub.add_parser("inspect", help="Inspect Network Door evidence JSON") + evidence_inspect_p.add_argument("path") + evidence_inspect_p.set_defaults(func=evidence_inspect) + return parser + + +def build_native_assistant_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(prog="sourceosctl native-assistant", description="SourceOS Native Assistant Bridge helpers") + sub = parser.add_subparsers(dest="native_assistant_command", required=True) + + plan_p = sub.add_parser("plan", help="Render non-mutating native assistant bridge plan") + plan_p.add_argument("--bridge-ref", default=APPLE_APP_INTENTS_REF) + plan_p.add_argument("--platform", default="macos", choices=["macos", "ios", "ipados", "watchos", "visionos", "android", "windows", "linux", "browser", "cross-device"]) + plan_p.add_argument("--bridge-class", default="apple-app-intents", choices=["apple-app-intents", "apple-shortcuts", "apple-foundation-models", "android-intents", "windows-shell", "browser-extension", "native-messaging", "mcp", "other"]) + plan_p.add_argument("--operation", default="open-workroom", choices=["open-workroom", "create-office-artifact", "summarize", "route-local-model", "handoff-to-agent-machine", "inspect-evidence", "search-workspace", "create-reminder", "create-note", "share-artifact", "other"]) + plan_p.add_argument("--prompt", default=None, help="Optional request text; output stores only hash") + plan_p.add_argument("--allow-cross-device", action="store_true", default=False) + plan_p.add_argument("--network-profile-ref", default=NETWORK_PROFILE_REF) + plan_p.add_argument("--model-route-binding-ref", default="urn:socioprophet:model-router-binding:demo-user-local-llama32") + plan_p.set_defaults(func=native_assistant_plan) + return parser + + +def network_main(argv: list[str] | None = None) -> int: + parser = build_network_parser() + args = parser.parse_args(argv) + return args.func(args) or 0 + + +def native_assistant_main(argv: list[str] | None = None) -> int: + parser = build_native_assistant_parser() + args = parser.parse_args(argv) + return args.func(args) or 0 From 9a0905c63e8f54cf795a5a32917abdb19435ae71 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 11:49:50 -0400 Subject: [PATCH 3/6] Route network and native-assistant command groups from sourceosctl entrypoint --- bin/sourceosctl | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/bin/sourceosctl b/bin/sourceosctl index f0cad7f..583bf73 100755 --- a/bin/sourceosctl +++ b/bin/sourceosctl @@ -6,6 +6,19 @@ import os # Allow running directly from the repo root without installing. sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +# Lightweight plugin routing for newer command groups while keeping the core +# argparse surface stable. These command groups are non-mutating plan/probe +# surfaces and own their own subparsers. +if len(sys.argv) > 1 and sys.argv[1] == "network": + from sourceosctl.commands.network import network_main + + sys.exit(network_main(sys.argv[2:])) + +if len(sys.argv) > 1 and sys.argv[1] == "native-assistant": + from sourceosctl.commands.network import native_assistant_main + + sys.exit(native_assistant_main(sys.argv[2:])) + from sourceosctl.cli import main sys.exit(main()) From 463adfc40386a2ab308e877fd9e39127cdc7a051 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 11:53:00 -0400 Subject: [PATCH 4/6] Add Network Door and Native Assistant Door tests --- tests/test_network_cli.py | 106 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 tests/test_network_cli.py diff --git a/tests/test_network_cli.py b/tests/test_network_cli.py new file mode 100644 index 0000000..670f6d3 --- /dev/null +++ b/tests/test_network_cli.py @@ -0,0 +1,106 @@ +"""Unit tests for sourceosctl Network Door and Native Assistant Door commands.""" + +import json +import os +import pathlib +import sys +import tempfile +import unittest + +_REPO_ROOT = pathlib.Path(__file__).parent.parent +sys.path.insert(0, str(_REPO_ROOT)) + +from sourceosctl.commands import network + + +class TestNetworkDoorCommands(unittest.TestCase): + def test_network_doctor(self): + self.assertEqual(network.network_main(["doctor"]), 0) + + def test_network_plan_default_deny_hashes_destination(self): + self.assertEqual( + network.network_main([ + "plan", + "--destination", + "models.enterprise.example", + ]), + 0, + ) + + def test_network_plan_enterprise_mesh_allow_listed(self): + self.assertEqual( + network.network_main([ + "plan", + "--enterprise", + "--mesh", + "--allow-listed", + "--destination", + "models.enterprise.example", + ]), + 0, + ) + + def test_network_provider_plan_byom(self): + self.assertEqual( + network.network_main([ + "provider", + "--provider-class", + "openai-compatible", + "--owner", + "user", + ]), + 0, + ) + + def test_network_evidence_inspect_valid(self): + payload = { + "type": "NetworkDoorPlan", + "decision": "deny", + "destinationStored": False, + "networkAccessProfileRef": "urn:srcos:network-access-profile:enterprise-and-user-default", + "modelProviderRef": "urn:srcos:external-model-provider-profile:user-openai-compatible", + } + with tempfile.NamedTemporaryFile(suffix=".json", mode="w", delete=False) as handle: + json.dump(payload, handle) + tmp_path = handle.name + try: + self.assertEqual(network.network_main(["evidence", "inspect", tmp_path]), 0) + finally: + os.unlink(tmp_path) + + def test_network_evidence_inspect_missing(self): + self.assertEqual(network.network_main(["evidence", "inspect", "/nonexistent/network.json"]), 1) + + def test_native_assistant_plan_default(self): + self.assertEqual(network.native_assistant_main(["plan"]), 0) + + def test_native_assistant_plan_hashes_prompt(self): + self.assertEqual( + network.native_assistant_main([ + "plan", + "--operation", + "create-office-artifact", + "--prompt", + "create a local report", + ]), + 0, + ) + + def test_native_assistant_plan_cross_device_flag(self): + self.assertEqual( + network.native_assistant_main([ + "plan", + "--platform", + "cross-device", + "--bridge-class", + "mcp", + "--operation", + "handoff-to-agent-machine", + "--allow-cross-device", + ]), + 0, + ) + + +if __name__ == "__main__": + unittest.main() From d9a4ed32963d299ab0fb56f9a0bbdd5862cbd361 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 11:54:19 -0400 Subject: [PATCH 5/6] Document Network Door and Native Assistant Door CLI boundary --- .../network-native-assistant-door.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/integration/network-native-assistant-door.md diff --git a/docs/integration/network-native-assistant-door.md b/docs/integration/network-native-assistant-door.md new file mode 100644 index 0000000..71eee8b --- /dev/null +++ b/docs/integration/network-native-assistant-door.md @@ -0,0 +1,73 @@ +# Network Door and Native Assistant Door CLI boundary + +This slice adds non-mutating SourceOS operator surfaces for the contract family defined in `SourceOS-Linux/sourceos-spec`: + +- `NetworkAccessProfile` +- `FirewallBindingProfile` +- `MeshBindingProfile` +- `ExternalModelProviderProfile` +- `NativeAssistantBridgeProfile` + +The implementation is intentionally a plan/probe surface. It does not modify firewall state, install service mesh components, contact model providers, start model calls, invoke Siri/App Intents/native assistant APIs, or change host networking. + +## Command surface + +```bash +sourceosctl network doctor +sourceosctl network plan --destination models.enterprise.example +sourceosctl network plan --enterprise --mesh --allow-listed --destination models.enterprise.example +sourceosctl network provider --provider-class openai-compatible --owner user +sourceosctl network evidence inspect ./network-evidence.json + +sourceosctl native-assistant plan +sourceosctl native-assistant plan --operation create-office-artifact --prompt 'draft a local report' +sourceosctl native-assistant plan --platform cross-device --bridge-class mcp --operation handoff-to-agent-machine --allow-cross-device +``` + +## Boundary + +| Surface | Owns | Does not own | +|---|---|---| +| `sourceosctl network ...` | Local rendering of network/firewall/mesh/BYOM route plans and evidence-shaped summaries. | Firewall mutation, mesh installation, VPN/proxy configuration, model-provider calls, credential storage. | +| `sourceosctl native-assistant ...` | Local rendering of native assistant bridge plans and evidence-shaped summaries. | Apple App Intents implementation, Siri invocation, Shortcuts execution, Android/Windows assistant APIs, cross-device transport. | + +## Policy posture + +- Default egress is `deny`. +- Destination text is represented as a SHA-256 hash in route plans. +- BYOM provider auth is always represented as a reference; credentials are never inlined. +- Enterprise firewall rules have precedence over user allow rules. +- User firewall profiles may be stricter than enterprise policy. +- Mesh binding and firewall binding are complementary, not interchangeable. +- Native assistant bridge calls are local-only by default. +- Prompt egress is denied by default. +- Cross-device handoff is disabled unless explicitly requested. +- Raw app database access is denied. +- Side effects require user confirmation in the bridge plan. + +## Implementation owner split + +| Repo | Role | +|---|---| +| `SourceOS-Linux/sourceos-spec` | Canonical Network/Mesh/BYOM/Native Assistant Door contracts. | +| `SourceOS-Linux/sourceos-devtools` | Local non-mutating `sourceosctl` probe and plan surface. | +| `SocioProphet/model-router` | Runtime route decisions for local, personal, hosted, enterprise, and BYOM model targets. | +| `SocioProphet/agentplane` | Evidence records when network/provider/native bridge plans participate in governed runs. | +| `SocioProphet/guardrail-fabric` | Policy decisions for prompt egress, hosted fallback, native assistant side effects, and external provider access. | +| `SocioProphet/sociosphere` | Topology validation and cross-repo dependency direction. | + +## Current non-goals + +- Do not vendor Istio, Admiral, LuLu, Cilium, or enterprise firewalls here. +- Do not modify host firewall state from this slice. +- Do not install or configure mesh control planes from this slice. +- Do not store or print provider credentials. +- Do not invoke native assistant APIs. +- Do not expose raw Apple Notes, Photos, mail stores, browser profiles, keychains, token stores, or security-material directories by default. + +## Next implementation lanes + +1. Add AgentPlane evidence schemas for `NetworkDoorPlanEvidence`, `ExternalModelProviderRouteEvidence`, and `NativeAssistantBridgeEvidence`. +2. Add model-router BYOM profile consumption and policy checks against `ExternalModelProviderProfile`. +3. Add AgentTerm `/network`, `/byom`, and `/native-assistant` event surfaces. +4. Add Homebrew formula tests for `sourceosctl network doctor` and `sourceosctl native-assistant plan`. From 24b227221b94e7aed47e2ba8886fd68e30523da4 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 11:55:32 -0400 Subject: [PATCH 6/6] Document Network Door and Native Assistant Door CLI commands --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 76f4656..101258c 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ It should contain: - lab/profile selection utilities; - local model-service client helpers; - model-router client utilities; +- Network Door, Firewall Door, Mesh Door, BYOM provider, and Native Assistant Door plan/probe helpers; - guardrail/eval/evidence helpers; - agent sandbox/run helpers; - Local Model Door runtime detection and route planning helpers; @@ -35,7 +36,10 @@ It should not contain: - model-router backend; - web control plane backend; - SourceOS image build state; -- secrets, tokens, credentials, private keys, or device-specific enrollment secrets. +- secrets, tokens, credentials, private keys, or device-specific enrollment secrets; +- firewall mutation engines; +- service mesh installers; +- native assistant runtime adapters. ## sourceosctl CLI @@ -66,6 +70,11 @@ sourceosctl [--version] [] [options] | `sourceosctl local-model plan --profile local-llama32-1b` | Render local model runtime plan without installing or running models | | `sourceosctl local-model route --task-class office-assist` | Render hash-only model route decision under local-first policy | | `sourceosctl local-model evidence inspect ` | Inspect local model route evidence JSON | +| `sourceosctl network doctor` | Inspect Network Door contract posture without changing firewall, mesh, or provider state | +| `sourceosctl network plan --destination