From e9cd8328285a6f34dbb9fb9804ad0bde03c79275 Mon Sep 17 00:00:00 2001
From: Edison Jwa <me@edison.network>
Date: Sun, 7 Jun 2026 23:09:34 +0900
Subject: [PATCH] docs(macos): clarify network.server entitlement justification

Oracle re-review nit on PR #27: cite Apple's App Sandbox semantics
explicitly. The macOS sandbox classifies any UDP bind() against a
local port as a 'server' operation (covered by network.server),
even when the socket is only used to sendto() a remote peer. This
is the bind()-then-sendto() pattern tokio's UdpSocket uses
internally for tsclientlib's outbound voice traffic. Correct the
sandbox log line to the actual deny string ('Sandbox: ... deny(1)
network-bind') and reference Apple's entitlement reference wording.
---
 .../macos/Runner/Release.entitlements         | 20 ++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/apps/chanora_flutter/macos/Runner/Release.entitlements b/apps/chanora_flutter/macos/Runner/Release.entitlements
index f4614b6..5f4c7e7 100644
--- a/apps/chanora_flutter/macos/Runner/Release.entitlements
+++ b/apps/chanora_flutter/macos/Runner/Release.entitlements
@@ -3,13 +3,19 @@
 <plist version="1.0">
 <dict>
 	<!-- Release builds omit cs.allow-jit (Flutter hot-reload only). They keep
-	     network.server because the macOS App Sandbox treats every UDP bind()
-	     - including the ephemeral 0.0.0.0:0 that tsclientlib's
-	     tokio::net::UdpSocket::bind() issues for outbound traffic - as a
-	     server operation. Without this entitlement UdpSocket::bind fails
-	     with EPERM (sandbox_init: 'network-outbound deny') and the TS3
-	     connect never starts. network.client alone is insufficient because
-	     it gates connect()-style flows, not bind()-then-sendto. -->
+	     network.server because the macOS App Sandbox classifies UDP bind()
+	     against a local port - including the ephemeral 0.0.0.0:0 that
+	     tsclientlib's tokio::net::UdpSocket::bind() issues for outbound
+	     voice traffic - as a server operation that requires
+	     com.apple.security.network.server, regardless of whether the
+	     socket is later used only to sendto() a remote peer. Without it,
+	     bind() returns EPERM and the sandbox log records
+	     "Sandbox: chanora(...) deny(1) network-bind". network.client
+	     alone gates outbound connect()-style flows (TCP, connected UDP)
+	     and is insufficient for the bind()-then-sendto() pattern Tokio's
+	     UdpSocket uses. See Apple's App Sandbox entitlement reference:
+	     "Network Server" covers any process that listens on, or binds
+	     to, a network port. -->
 	<key>com.apple.security.app-sandbox</key>
 	<true/>
 	<key>com.apple.security.network.client</key>