AG-57160 fix trusttunnel-client: add 'vpn_network_manager_acquire_tunnel_activity' to NetworkManager's API

* AG-57160 fix trusttunnel-client: add 'vpn_network_manager_set_tunnel_active' to NetworkManager's API

* use unique tokens for every event-loop instead of one global atomic_bool

* add info in development.md + comments in network_manager.h

Author: rsadikov01

.gitignore

@@ -1,5 +1,6 @@
 cmake-build-*/
 build/
+env/
 .idea/
 .vscode/
 .DS_Store

CHANGELOG.md

@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- Ownership-tracked process-wide tunnel state to fail closed when an outgoing socket cannot be protected from VPN routing while any tunnel is active.
+
 ### Changed
 
 ### Deprecated

DEVELOPMENT.md

@@ -303,6 +303,67 @@ To test local changes in the library when used as a Conan package dependency, fo
    Note:
     - If you have already exported the library in this way, the cached version must be purged: `conan remove -c vpn-libs/<commit_hash>`.
 
+## Integrating Tunnel Activity Tracking
+
+The library tracks whether a VPN TUN interface is active in the process to fail
+closed when an outgoing socket cannot be protected from being routed into the
+tunnel. Applications that create a TUN interface themselves (as opposed to
+using the built-in tunnels from `net/os_tunnel.h`) **must** register it with
+this API, otherwise the socket protection handlers have no way to distinguish
+"no tunnel" from "tunnel active but unprotected".
+
+### API overview
+
+- `vpn_network_manager_acquire_tunnel_activity()` — registers an active TUN
+  interface and returns a non-zero ownership token.
+- `vpn_network_manager_release_tunnel_activity(token)` — unregisters a TUN
+  interface previously registered with `acquire`. Invalid or already released
+  tokens are ignored, so duplicate releases are safe.
+- `vpn_network_manager_get_tunnel_active()` — returns `true` while at least one
+  TUN interface is registered.
+- `vpn_network_manager_set_outbound_interface(idx)` — sets the index of the
+  physical interface that outgoing sockets should be bound to. See below.
+
+### Integration checklist
+
+1. **Acquire when the TUN interface is created.** Call
+   `vpn_network_manager_acquire_tunnel_activity()` only after the TUN interface
+   has been successfully established (e.g. after the TUN fd has been opened),
+   and store the returned token. Do not acquire before the interface exists:
+   on failure there is nothing to release, and the token must not outlive the interface.
+
+2. **Release when the TUN interface is closed.** Call
+   `vpn_network_manager_release_tunnel_activity(token)` with the stored token
+   after the TUN interface (and all its duplicated descriptors) are closed.
+   Releasing earlier would allow sockets to fall back to the system default
+   route while the tunnel is still capturing it. Keep the token for the whole
+   lifetime of the interface.
+
+3. **Set the outbound interface before notifying about network changes.**
+   Call `vpn_network_manager_set_outbound_interface()` with the index of the
+   physical interface **before** notifying the running VPN instance with
+   `vpn_notify_network_change()`. The DNS handler restarts the system DNS proxy
+   on network changes and reads the current outbound interface at that moment.
+
+4. **Multiple TUN interfaces are supported.** Each interface acquires its own
+   token; the state stays active until the last token is released. Never reuse
+   a token for two interfaces, and never release a token owned by another
+   interface.
+
+5. **Platform equivalents of a bound interface.** On Android, sockets are
+   protected with `VpnService.protect(fd)` instead of an interface binding; the
+   application is responsible for routing its outgoing sockets through that
+   mechanism while the tunnel is active. On Apple, the built-in `AGTunnel`
+   registers the activity automatically.
+
+### Behavior
+
+While `vpn_network_manager_get_tunnel_active()` returns `true` and the outbound
+interface is zero (or stale), platform socket protection handlers reject
+outgoing sockets instead of letting them use the system default route. This
+prevents the VPN's own traffic from looping back into the TUN interface. The
+DNS proxy startup is also gated on the same condition on non-Android platforms.
+
 ## Companion Endpoint Repository
 
 Complementary endpoint implementation for the TrustTunnel VPN can be found in

core/src/dns_proxy_accessor.cpp

@@ -107,6 +107,13 @@ bool DnsProxyAccessor::start() {
         return false;
     }
 
+#ifndef __ANDROID__
+    if (vpn_network_manager_get_tunnel_active() && vpn_network_manager_get_outbound_interface() == 0) {
+        log_accessor(this, err, "Cannot start DNS proxy without an outbound interface while tunnel is active");
+        return false;
+    }
+#endif // __ANDROID__
+
     m_dns_proxy = std::make_unique<dns::DnsProxy>();
     auto [ok, msg] = m_dns_proxy->init(make_dns_proxy_settings(m_parameters),
             {

net/CMakeLists.txt

@@ -121,3 +121,4 @@ add_live_test(test_locations_pinger_runner "${TEST_DIR}" "${TEST_EXTRA_INCLUDES}
 add_unit_test(test_dns_utils "${TEST_DIR}" "${TEST_EXTRA_INCLUDES}" TRUE TRUE)
 add_unit_test(test_tls_serialize "${TEST_DIR}" "${TEST_EXTRA_INCLUDES}" TRUE TRUE)
 add_unit_test(test_net_utils "${TEST_DIR}" "${TEST_EXTRA_INCLUDES}" TRUE TRUE)
+add_unit_test(test_network_manager "${TEST_DIR}" "${TEST_EXTRA_INCLUDES}" TRUE TRUE)

net/include/net/network_manager.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <cstdint>
 #include <string>
 #include <vector>
 
@@ -64,4 +65,32 @@ extern "C" WIN_EXPORT void vpn_network_manager_set_outbound_interface(uint32_t i
  */
 uint32_t vpn_network_manager_get_outbound_interface();
 
+using VpnTunnelActivityToken = uint64_t;
+
+/** Invalid tunnel activity token. */
+constexpr VpnTunnelActivityToken VPN_TUNNEL_ACTIVITY_TOKEN_INVALID = 0;
+
+/**
+ * Register an active VPN TUN interface in this process.
+ *
+ * While at least one TUN interface is active, outgoing connections must not use the system default route: platform
+ * socket protection handlers must fail if no outbound interface or equivalent platform protection is available.
+ * The returned ownership token must be released exactly once with
+ * `vpn_network_manager_release_tunnel_activity()` after the TUN interface is closed.
+ *
+ * @return A non-zero ownership token.
+ */
+extern "C" WIN_EXPORT VpnTunnelActivityToken vpn_network_manager_acquire_tunnel_activity();
+
+/**
+ * Unregister an active VPN TUN interface previously registered with `vpn_network_manager_acquire_tunnel_activity()`.
+ * Invalid or already released tokens are ignored.
+ */
+extern "C" WIN_EXPORT void vpn_network_manager_release_tunnel_activity(VpnTunnelActivityToken token);
+
+/**
+ * Check whether a VPN TUN interface is active in this process.
+ */
+bool vpn_network_manager_get_tunnel_active();
+
 } // namespace ag

net/include/net/os_tunnel.h

@@ -15,6 +15,7 @@
 #include "common/error.h"
 #include "common/socket_address.h"
 #include "common/utils.h"
+#include "net/network_manager.h"
 #include "vpn/platform.h"
 #include "vpn/utils.h"
 
@@ -198,6 +199,9 @@ class VpnOsTunnel {
     VpnOsTunnel &operator=(VpnOsTunnel &&) = delete;
 
 protected:
+    void mark_tunnel_active();
+    void clear_tunnel_active();
+
     void init_settings(const VpnOsTunnelSettings *settings) {
         m_settings.reset(vpn_os_tunnel_settings_clone(settings));
     }
@@ -206,6 +210,7 @@ class VpnOsTunnel {
     uint32_t m_if_index = 0;
     bool m_system_dns_setup_success = false;
     bool m_ipv6_available = false;
+    VpnTunnelActivityToken m_tunnel_activity_token = VPN_TUNNEL_ACTIVITY_TOKEN_INVALID;
 };
 
 #ifdef __linux__

net/src/network_manager.cpp

@@ -2,6 +2,7 @@
 
 #include <atomic>
 #include <mutex>
+#include <unordered_set>
 #include <utility>
 
 #include "common/cache.h"
@@ -28,6 +29,10 @@ static struct NetworkManagerHolder {
     std::mutex guard;
     ag::LruTimeoutCache<std::string, bool> app_domain_cache;
     std::atomic<uint32_t> outbound_interface = 0;
+    std::mutex tunnel_activity_guard;
+    std::unordered_set<VpnTunnelActivityToken> tunnel_activity_tokens;
+    VpnTunnelActivityToken next_tunnel_activity_token = 1;
+    std::atomic_size_t tunnel_activity_count = 0;
 
     NetworkManagerHolder()
             : app_domain_cache(DEFAULT_CACHE_SIZE, std::chrono::minutes(10)) {
@@ -81,4 +86,36 @@ uint32_t vpn_network_manager_get_outbound_interface() {
     return g_network_manager_holder.outbound_interface;
 }
 
+VpnTunnelActivityToken vpn_network_manager_acquire_tunnel_activity() {
+    std::scoped_lock l(g_network_manager_holder.tunnel_activity_guard);
+    VpnTunnelActivityToken token;
+    do {
+        token = g_network_manager_holder.next_tunnel_activity_token++;
+    } while (token == VPN_TUNNEL_ACTIVITY_TOKEN_INVALID
+            || g_network_manager_holder.tunnel_activity_tokens.contains(token));
+
+    g_network_manager_holder.tunnel_activity_tokens.insert(token);
+    g_network_manager_holder.tunnel_activity_count = g_network_manager_holder.tunnel_activity_tokens.size();
+    dbglog(g_logger, "Tunnel activity acquired, active owners: {}",
+            g_network_manager_holder.tunnel_activity_tokens.size());
+    return token;
+}
+
+void vpn_network_manager_release_tunnel_activity(VpnTunnelActivityToken token) {
+    std::scoped_lock l(g_network_manager_holder.tunnel_activity_guard);
+    if (token == VPN_TUNNEL_ACTIVITY_TOKEN_INVALID
+            || g_network_manager_holder.tunnel_activity_tokens.erase(token) == 0) {
+        warnlog(g_logger, "Ignoring invalid or already released tunnel activity token");
+        return;
+    }
+
+    g_network_manager_holder.tunnel_activity_count = g_network_manager_holder.tunnel_activity_tokens.size();
+    dbglog(g_logger, "Tunnel activity released, active owners: {}",
+            g_network_manager_holder.tunnel_activity_tokens.size());
+}
+
+bool vpn_network_manager_get_tunnel_active() {
+    return g_network_manager_holder.tunnel_activity_count != 0;
+}
+
 } // namespace ag

net/src/os_tunnel.cpp

@@ -1,6 +1,7 @@
 #include <vector>
 
 #include "common/utils.h"
+#include "net/network_manager.h"
 #include "net/os_tunnel.h"
 #include "net/utils.h"
 
@@ -22,6 +23,19 @@ static constexpr std::string_view DEFAULT_IPV4_ROUTE = "0.0.0.0/0";
 static constexpr std::string_view DEFAULT_IPV6_ROUTE = "::/0";
 static constexpr std::string_view DEFAULT_IPV6_ROUTE_UNICAST = "2000::/3";
 
+void ag::VpnOsTunnel::mark_tunnel_active() {
+    if (m_tunnel_activity_token == VPN_TUNNEL_ACTIVITY_TOKEN_INVALID) {
+        m_tunnel_activity_token = vpn_network_manager_acquire_tunnel_activity();
+    }
+}
+
+void ag::VpnOsTunnel::clear_tunnel_active() {
+    if (m_tunnel_activity_token != VPN_TUNNEL_ACTIVITY_TOKEN_INVALID) {
+        vpn_network_manager_release_tunnel_activity(m_tunnel_activity_token);
+        m_tunnel_activity_token = VPN_TUNNEL_ACTIVITY_TOKEN_INVALID;
+    }
+}
+
 void ag::tunnel_utils::split_default_route(std::vector<ag::CidrRange> &routes, ag::CidrRange route) {
     for (size_t idx = 0; idx < routes.size(); ++idx) {
         if (routes[idx] == route) {

net/src/os_tunnel_linux.cpp

@@ -81,6 +81,7 @@ ag::VpnError ag::VpnLinuxTunnel::init(const ag::VpnOsTunnelSettings *settings, s
         return {-1, "Failed to init tunnel"};
     }
     setup_if();
+    mark_tunnel_active();
 
     if (managed_routing) {
         m_sport_supported = check_sport_rule_support();
@@ -108,6 +109,7 @@ void ag::VpnLinuxTunnel::deinit() {
         teardown_routes(TABLE_ID);
     }
     m_system_dns_setup_success = false;
+    clear_tunnel_active();
 }
 
 evutil_socket_t ag::VpnLinuxTunnel::get_fd() {