@push.rocks/smartvpn 1.21.0 → 2.0.0

package/notices/valuable-license.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2021 Valuable Contributors
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartvpn",
-  "version": "1.21.0",
+  "version": "2.0.0",
   "private": false,
   "description": "A VPN solution with TypeScript control plane and Rust data plane daemon",
   "type": "module",
@@ -25,20 +25,22 @@
   "dependencies": {
     "@push.rocks/smartnftables": "1.2.0",
     "@push.rocks/smartpath": "^6.0.0",
-    "@push.rocks/smartrust": "^1.4.0"
+    "@push.rocks/smartrust": "^2.0.0"
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsrun": "^2.0.4",
-    "@git.zone/tsrust": "^1.4.1",
-    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.9.1"
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tsrust": "^1.11.0",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.4.1"
   },
   "files": [
     "ts/**/*",
     "dist_ts/**/*",
     "dist_rust/**/*",
     "assets/**/*",
+    "notices/**/*",
+    "third-party-notices.md",
     "readme.md",
     "license.md"
   ],

package/readme.hints.md

@@ -1,8 +1,74 @@
 # smartvpn hints
 
+## Musl distribution and qualification checkpoint (2026-09-07)
+
+- Rust 1.95.0 produces locked, remapped Linux amd64/arm64 musl artifacts. Both
+  passed ELF architecture/static-link/no-glibc checks. ARM64 management startup
+  and confirmed termination passed under QEMU, not privileged ARM64 hardware.
+- The exact amd64 SHA-256 `9dae4722a783f8de4ce2c5066eff1bf5d6ebde48750aaf3e96ad4e0374e153a3`
+  passed the dedicated serve.zone/testing KVM scenario: real WS/Noise + Linux
+  managed TUN split routes, directed allow/deny, reconnect, natural revocation,
+  partial route-conflict rollback, empty restart and child termination. Cleanup
+  joined, removed owned namespaces, and preserved VM DNS and default routes.
+  The VM is shut off. WSS/private CA, IPv6 workload traffic, privileged ARM64,
+  standalone kernel modes and Pallet/Cloudly production integration remain unqualified.
+- Verification passed 109 TypeScript tests, all source/test type checks, 255 musl
+  Rust unit tests, three Rust integrations, and the separate 181-second WireGuard
+  expiry test. Build/test invocations must remain sequential because tsrust
+  replaces dist_rust. Cargo tests using their separate target tree may run alongside.
+- Release tooling was committed separately. The complete Cargo/compiler/runtime
+  notice index is `third-party-notices.md`, with hashed inputs and all 278 locked
+  registry packages in `notices/inventory.json`. Tests enforce coverage and payload
+  inclusion. Redistribution of the unchanged tun 0.7.22/WTFPL dependency was
+  explicitly approved on 2026-09-07; this is not a production deployment approval.
+
+The authority notes below retain earlier development checkpoints. Qualification
+claims above supersede their historical managed-TUN test gaps, not the remaining
+standalone-kernel or production-integration limitations.
+
+## Authority prerequisites (2026-09-07)
+
+- The Rust managed_network compiler validates complete schema-v1 declarations before active effects. Managed ClientRegistry retains the lifetime binding, applied snapshot and exact pending candidate/pool/affected set. Admissible stamps quarantine affected nodes under the native/WG admission gate; raw entry/stamp reads are not admission. Server-owned serialized reconcile joins cancelled sessions outside the gate. With WG, the loop prepares replacements then swaps peer crypto, candidate registry and exact pool synchronously under the registry gate; failures retain quarantine and only exact-target retry. Without WG the same commit runs in the tracked apply owner. Equal canonical replay preserves sessions; per-node effective authority includes directed grants, not only route unions.
+- Public reconcileManagedNetwork/getManagedNetworkStatus/getManagedNodeProjection IPC is typed on both sides. Managed mode has no hub host-network effects and no standalone writer. Unix apply releases the outer VpnServer mutex before awaiting; status from a second connection remains available, and dropping a requester does not cancel the tracked operation. Regressions cover actual native/WG workload relay and MTUs, denied domains, unchanged owners, failed preparation/retry, direct raw-WG writer rejection, address/key reuse, disconnected IPC and whole-server drain.
+- Native managed assignment validates bounded canonical owned/remote prefixes and reports live authority/lifetime/revision through client status. Native Linux managed_tunnel uses the published rtnetlink API, exclusive ACKed route adds and a kernel-allocated nonpersistent /32 TUN. The netlink future is polled inline; no detached shell/route task or route-conflict reuse. Closing the owned FD removes associated routes, as documented at https://docs.kernel.org/networking/tuntap.html. Actual WS/QUIC peer addresses guard against capturing the hub connection. Pure preflight tests run without host effects; privileged rollback/default-route/DNS qualification remains outstanding. Exact upstream notices for the unmodified Linux netlink crates ship under assets/**/* and passed license review.
+- Registry candidates are validated before any index mutation. Updates operate on a detached copy, reject ID/key/IP conflicts and malformed expiry/IPv4 assignments, and preserve the original record and indexes on failure. Malformed expiry also fails closed when checked outside the registry.
+- Create/update settings now deserialize a complete detached candidate instead of silently clearing malformed security, filtering bad tags or truncating integers. Unknown/server-owned mutation fields reject explicitly; omitted fields are preserved, null clears optional settings, and a security object replaces the previous complete object. Shared ACL parsing preserves IPv4 exact/CIDR/wildcard/range syntax for both validation and matching. Startup validates preloaded client settings, connection block lists and destination policy before host effects. Rust and real daemon IPC regressions cover rejected updates/creates, allocation preservation, policy typos and null/VLAN invariants. This is input validation, not live-session or queued-packet revocation.
+- ClientEntry, ClientSecurity and DestinationPolicyConfig omit absent optional fields when serializing, matching the public TypeScript output types; explicit null remains accepted for patch clearing. Registry admission consumes deprecated tags into serverDefinedClientTags and rejects both-populated aliases, so clearing and reimport cannot resurrect stale tags. No recursive JSON output shim is used.
+- Native Noise admission captures a process-local record incarnation/revision and checks it again after the handshake response send, before local connection admission. Every successful registry mutation changes the revision; remove/recreate gets a new incarnation, even with identical keys. Invalid updates preserve the stamp. Registry guards are released before network sends, including unauthorized responses. Real Noise plus a controlled send barrier covers disable, disable/re-enable, remove/recreate, key rotation, expiry/policy edits and failed edits; WS/QUIC share this handler.
+- Rate-limit unit tests use controlled Instant values through the same private consumption/refill path as production. The previous immediate-empty assertion was invalid at 1 MB/s: one microsecond refills a byte, and it failed under build load. Production still samples Instant::now; no test clock, sleeps or scheduler assumptions enter the runtime.
+- IP pools require canonical network CIDRs and usable ranges; explicit reservations may be outside the dynamic range but not outside the subnet or on its network/gateway/broadcast addresses. Allocation is bounded, including a fully reserved pool and `/0`. `release_owned` compares an opaque reservation owner before release; callers that outlive records must use incarnation tokens, not reusable client IDs.
+- Runtime address reservations now belong to registry incarnations, not reusable IDs or connections. Startup reserves all explicit registry and raw WG addresses before sorted dynamic allocation. Native admission verifies and uses the registry assignment; disconnect and registered WG peer removal retain it. Record removal disables/cancels, joins transports, reconciles the exact WG revision, then releases only the matching reservation. Failed create rollback rejects a changed revision, and failed rotation never restores old keys.
+- LiveClients/ClientSession/SessionGuard owns one volatile generation across WS/QUIC and integrated WG. Admission counts the inline protocol lifetime before publishing its route. Cancellation closes task admission; reconnect joins predecessors outside registry/ownership locks. Protocol I/O and crypto drop before the guard token, and WG relays belong to both session and server trackers. Exact Arc identity fences stale route cleanup and merged WG returns. Raw WG control IDs use the full public key and a separate internal namespace; ambiguous control names reject without cancelling either owner.
+- Native/WG idle expiry and registry mutations drain transport owners. WG disconnect resets BoringTun with a nonreused 24-bit peer index and retains configured peer settings. The WG loop interrupts blocked forwarding when a WG owner needs retirement; stale notifications from completed native takeovers must not drop the new WG session's first packet. Integrated UDP sends are nonblocking/best-effort, so send-buffer pressure cannot block other peers' revocation.
+- Registered tunnel packets require exact-length, checksummed IPv4 headers and their authenticated assigned source. Outer connection ACLs and inner destination ACLs are separate. Hybrid forwarding uses the immutable session's useHostIp setting, not a packet-source lookup. Raw WG IPv6 remains kernel/testing only, never reinterpreted by IPv4 socket/bridge engines.
+- Regressions cover address collision/reuse, joined native and real-UDP WG mutations, WS/QUIC socket takeover, cross-transport takeover with never-sent old ciphertext, idle expiry, stale cleanup/returns, unpolled descendants, raw peer reservations, source spoofing, malformed packets and failed reconciliation ownership. No publication or serve.zone production adoption is implied by this transport checkpoint.
+- AuthenticatedPacket now carries ClientSession plus a tracked queued-work lifetime through socket/bridge queues. NatDispatcher selects a separate session-owned smoltcp stack; queued work, flow tasks/readers and replies no longer resolve a mutable registry/IP route. A reproduced registry-lock fail-open is removed: destination policy and PROXY metadata use the authenticated owner. Bridge writes observe current-client cancellation and broadcast shared retirement, so an unrelated blocked TAP write cannot indefinitely hold another client's queued stop token.
+- NatFlow Arc identity fences TCP/UDP tuple reuse and owns a cancellation tracker plus a capacity lease. Each flow task/reader is enrolled with flow, client and server owners. Late task/message references retain the lease. Limits are 256 engines, 1,024 flow incarnations, and 128 flows/client by default (security.maxConnections may override the per-client limit). Packet/message queues are bounded. The existing smoltcp build has no fragment reassembly; IPv4 fragments, invalid TCP/UDP headers/checksums and bad lengths reject before flow allocation.
+- A reproduced UDP demultiplexing defect sent different source-port flows through the first socket bound to their shared destination. There is now one smoltcp UDP listener per destination in each client stack; received endpoint metadata selects the exact flow. External UDP sockets are connected to their target, filtering unrelated senders. Tests cover real multi-client UDP/replies, same-target source-port isolation, full TCP packet handshake plus real bidirectional stream traffic, server/client revocation, stale tuple messages, queue drain, capacity retention and PROXY identity under registry lock.
+- Server MTU enforcement now treats config as inner IP bytes (576..65472), rejects invalid input before startup effects, and checks authenticated ingress plus native/WG return encryption. A configured 1200 previously became 1121, and 1500-byte ingress previously passed a 1420-byte limit; both regressions were reproduced. Eligible DF packets get rate-limited IPv4 fragmentation-needed feedback from the owned gateway/bridge IP through the exact session. Malformed/error/fragment/multicast/broadcast packets do not provoke feedback; unavailable feedback never permits oversize. Real Noise and UDP/WG tests cover feedback, exact-limit admission and oversized return rejection. Counters distinguish drops from queued (not confirmed-sent) ICMP. This is not fragmentation/reassembly or outer path-MTU discovery.
+- Native client MTU regressions reproduced acceptance of a 1200-byte packet despite a local 1100-byte ceiling, and fabricated getMtuInfo values both connected and disconnected. A required authenticated ClientHello now carries the local ceiling; the server pins the negotiated minimum on ClientSession and its smoltcp stack. Typed assignments include the actual subnet, reject missing/invalid values before TUN setup and remove guessed /24/MTU defaults. Real WS/QUIC tests cover negotiated return admission; real Noise plus unprivileged packet-I/O fixtures cover both client directions, exact-limit traffic, owned IPv4 feedback and retirement. The TCP NAT fixture exchanges 4KB while asserting every return packet respects the smaller session ceiling. Nullable MTU reporting describes actual native runtime ownership, not outer-path estimates; failed or short TUN feedback writes never count as sent. Both native endpoints must upgrade together.
+- WireGuard's public flat config previously failed Rust deserialization with missing privateKey; the owning Rust input now consumes wgPrivateKey/serverPublicKey/wgAddress/wgEndpoint and requires nonempty wgAllowedIps, with no nested-peer adapter. Actual address/prefix/keys/MTU/AllowedIPs validate before TUN effects; route CIDRs normalize host bits, the configured prefix supplies netmask, and hostname resolution selects a matching UDP family. Explicit testing mode owns no TUN/routes; WG's existing default remains tun. Real UDP/BoringTun client-loop tests cover a complete handshake, bidirectional MTU admission, malformed/checksum and AllowedIPs source/destination rejection, exact-limit traffic, owned IPv4 feedback, short/blocked device writes, EOF retirement and actual UDP-port release. MTU IPC reports live local ownership, resets on reconnect, and remains null when inactive. Standard WireGuard framing and first-authorized-packet connection semantics are unchanged; connectedSince is now RFC3339.
+- Managed snapshots now own hub policy and transport handover. Standalone kernel cleanup/partial-setup rollback and privileged managed host-network qualification remain outstanding. Raw WG IPv6 remains kernel/testing-only; oversized IPv6 drops without inventing an owned IPv6 router for feedback. No checkpoint retracts traffic already handed to an external network/kernel or proves production managed-network readiness.
+- Return-queue baseline reproduced plaintext remaining available after session.stop acknowledged with no running consumer. ReturnQueues registers bounded per-session and shared WG queues with one LiveClients owner; queued ReturnPacket payloads retain destination and optional source join tokens. Either generation's cancellation purges every matching queue without consumer progress; dequeued writes observe both cancellation sources. Foreign runtime queues/relay origins reject. Native cancellation after encryption retires the destination stream because Noise's implicit nonce and partial frame cannot safely be continued; a real Noise blocked-write/reconnect test covers it. Real UDP/WG shared relay, multi-thread enqueue/revoke, either-owner purge/join and backpressure regressions cover the foundation now used by managed relay.
+- BoringTun 0.7's encapsulate copies plaintext into a private queue when the current crypto session is absent; its timer removes that session after 180 seconds, before connection expiry. A regression reproduced revoked source plaintext escaping that queue after rekey. Integrated WG returns now check the public time_since_last_handshake Option under the same exclusive synchronous crypto owner: None drops/counts the application packet and requests a handshake without submitting plaintext. Some reflects the exact current-session slot used by encapsulate, not an age heuristic. The deterministic key-reset regression exercises rekey and proves the drained source cannot emit later while fresh destination returns still work. Explicit wall-clock qualification: `cargo test --manifest-path rust/Cargo.toml --lib return_crypto_timer_expiry_cannot_queue_plaintext_past_source_revocation -- --ignored`; it takes 181 seconds because BoringTun owns its clock. No dependency patch, timer override or networking privilege is used.
+- Native client disconnect previously acknowledged a five-second timeout while a deliberately blocked packet write remained alive; the real packet-loop regression reproduced it. Native and WG clients now retain RuntimeTasks ownership and task handles. Disconnect cancels blocked I/O and awaits destruction; native route finalization stays outside packet cancellation, and native monitors retire on natural exit or panic through an exit guard. Task panic is reported as failure, not successful disconnect. Failed native/WG connection attempts reset false startup state. Tests cover blocked native packet I/O plus real keepalive destruction, native failed-connect retry, natural exit/panic, owned WG UDP socket release/panic, and actual WS/QUIC disconnect/reconnect. Full privileged client TUN/route qualification remains outstanding.
+- Native and WireGuard client configs now form a discriminated union. Native configs require Noise keys; WireGuard configs require their own key/address/endpoint. The published `IVpnClientConfig` name remains available as the same union, while generated native bundles retain their narrower required-key type.
+- Native unit tests are in the Cargo library target: `cargo test --lib` runs them. `cargo test --bin smartvpn_daemon` runs zero unit tests and is not a substitute.
+- Facades consume published Smartrust 2.0's confirmed termination instead of fire-and-forget kill or a local timeout-as-success. Await all stop calls; server teardown drains startup and policy-health work, retains failed cleanup ownership, and requires a remote stop acknowledgement before removing socket-managed TUN policy. Whole-server packet task drain is now implemented below; per-client revocation and kernel-resource rollback still require qualification before publication as managed-network support.
+- Rust server work shares an admission-fenced RuntimeTasks owner using tokio-util TaskTracker/CancellationToken. Stop cancels and drains listeners, pre-authentication/packet handlers, WG return relays, NAT flow tasks and their readers before clearing forwarding state; QUIC completes protocol shutdown. Loopback regressions check WS/QUIC/WG listener teardown and real bidirectional TCP/UDP socket traffic through the NAT bridge tasks. These are lifecycle tests, not complete authenticated packet-to-NAT policy tests. Startup waits for listener readiness and merges preloaded WG definitions before readiness, rejecting conflicting assignments and excluding disabled/expired registered keys. Existing kernel route/NAT cleanup helpers still swallow command failures, and partial host-network setup needs transactional cleanup; no privileged network test or production adoption has occurred.
+- Run build and test commands sequentially: the current tsrust replaces `dist_rust` during every build, so overlapping builds can race test daemon discovery. A pre-ready child failure during overlapping verification was not attributable after stderr was discarded; focused and full sequential reruns passed. The facades now forward `stderr` for callers to capture diagnostics without automatic logging.
+
 ## Static Rust Binaries
 
-- The Rust binaries in `dist_rust/` are statically linked (static-pie) via `"static": true` in the `@git.zone/tsrust` block of `.smartconfig.json` (tsrust >= 1.4.1). They run on both glibc (Debian/Ubuntu) and musl (Alpine) systems.
-- tsrust injects `RUSTFLAGS="-C target-feature=+crt-static"` only into its own per-target cargo invocations and verifies the result (no `PT_INTERP` ELF header). Keep `rust/.cargo/config.toml` free of `rustflags` entries: the injected env variable would replace them, and a repo-wide `rustflags` would also break plain `cargo test`/`cargo check` (proc-macros cannot build with `+crt-static` on linux-gnu without an explicit `--target`).
+- The Rust binaries in `dist_rust/` use explicit `linux_amd64_musl` and
+  `linux_arm64_musl` targets. tsrust 1.11 verifies static linking and writes
+  hash-bound provenance sidecars. The runtime chooses these exact filenames;
+  explicit SMARTVPN_RUST_BINARY selections never fall through to discovery.
+- Target-specific Cargo CC settings require genuine musl headers for ring and
+  mimalloc. Final linking uses native/cross GCC drivers with Rust's self-contained
+  musl libraries; standalone musl-gcc specs add PT_INTERP even for static PIE and
+  are unsuitable as that final linker. Do not add repository-wide crt-static flags
+  that also affect untargeted host proc-macros.
 - `pnpm run test:rust` runs the Rust unit tests; plain `cargo test` in `rust/` works as well.
-- Verify linkage manually with `ldd dist_rust/<binary>_linux_amd64` → "statically linked".
+- Verify linkage with `file` and `readelf` against the `_musl` artifacts. Regression
+  tests reject PT_INTERP, DT_NEEDED, wrong machine identifiers and glibc signatures.

package/readme.md

@@ -14,7 +14,7 @@ A high-performance VPN solution with a **TypeScript control plane** and a **Rust
 - 🔀 **Hybrid mode**: per-client routing — some clients bridge to the LAN, others use userspace NAT, all on the same server
 - 🏷️ **VLAN support**: assign individual clients to 802.1Q VLANs on the bridge
 - 🎯 **Destination routing policy**: force-target, block, or allow traffic per destination with nftables integration
-- ⚡ **Handshake-driven WireGuard state**: peers appear as "connected" only after a successful WireGuard handshake, and auto-disconnect on idle timeout
+- ⚡ **Authenticated WireGuard state**: peers appear as "connected" after their first authenticated, source-authorized tunnel packet, and auto-disconnect on idle timeout
 
 ## Issue Reporting and Security
 
@@ -124,6 +124,53 @@ console.log(`Connected! VPN IP: ${assignedIp}`);
 
 ## Features ✨
 
+### Confirmed bridge shutdown
+
+Always await `client.stop()`, `server.stop()` or `bridge.stop()` before replacing
+an owned worker. These use Smartrust's confirmed termination API; a timeout is
+not treated as successful shutdown. In stdio mode they wait for child exit and
+stdio closure. In socket mode they confirm the local IPC connection has closed,
+not that the externally supervised daemon process has exited.
+
+`server.stop()` drains an in-flight start and firewall health check before
+cleaning up its policy resources. Cleanup errors reject and retain ownership
+for an explicit retry. If a socket-connected facade installed TUN policy, it
+first requires the managed server's `stop` acknowledgement before closing IPC
+and removing that policy. A socket connection without owned policy only closes
+IPC; use `stopServer()` explicitly to request remote listener shutdown.
+
+```typescript
+await client.stop();
+await server.stop();
+```
+
+This bridge lifecycle guarantee is separate from per-client packet/session
+revocation inside the running Rust daemon; see `readme.hints.md` for the current
+managed-network qualification boundaries.
+
+The Rust server now waits for configured listeners and initial WireGuard peers
+before acknowledging startup. A listener startup failure shuts down the owned
+runtime. `stopServer()` cancels and drains server-owned packet tasks, including
+pre-authentication connections, WireGuard return relays, and NAT socket readers;
+QUIC also closes its connections and waits for protocol shutdown. Per-client
+transport and queued forwarding teardown are described below. Transactional
+rollback of standalone kernel network setup remains outstanding; the isolated
+managed-client qualification below does not establish that guarantee for other modes.
+When a raw WireGuard declaration uses a registered client's key, its `allowedIps`
+must be exactly that client's assigned `/32`. Raw peers without a matching client
+registry entry retain their separately configured prefix lists.
+
+### Client runtime shutdown
+
+Always await `client.disconnect()`: it cancels and joins the native/WireGuard
+packet runtime before returning, including the native keepalive monitor. A blocked
+write cannot turn a timeout into a successful disconnect. Failed connection
+attempts clear their startup state; unexpected packet-task panics remain errors.
+Packet-loop exit clears connection and MTU metadata; native clients also retire
+their monitor before reconnect can reuse the client. Dropping the Rust client requests cancellation but
+cannot provide an awaited cleanup guarantee. Linux native managed-client TUN
+cleanup is qualified below; standalone native/WireGuard host-route cleanup is not.
+
 ### 🔐 Enterprise Authentication (Noise IK)
 
 Every client authenticates with a **Noise IK handshake** (`Noise_IK_25519_ChaChaPoly_BLAKE2s`). The server verifies the client's static public key against its registry — unauthorized clients are rejected before any data flows.
@@ -164,7 +211,7 @@ console.log(stats.totalConnectionsQuic);
 console.log(stats.totalConnectionsWireguard);
 ```
 
-**WireGuard connection state is handshake-driven** — registered WireGuard peers do NOT appear as "connected" until their first successful WireGuard handshake completes. They automatically disconnect after 180 seconds of inactivity or when boringtun reports `ConnectionExpired`. This matches how WebSocket/QUIC clients behave: they appear on connection and disappear on disconnect.
+**WireGuard connection state follows authenticated tunnel traffic** — a configured peer has no live return route until its first authenticated, source-authorized tunnel packet. Handshake or keepalive traffic alone does not admit a packet session. Peers disconnect after 180 seconds of inactivity, registry expiry, or when boringtun reports `ConnectionExpired`. Disconnect retains the configured peer but resets its cryptographic state, so subsequent traffic requires a fresh handshake. Raw peer connection IDs use `wg-` followed by the full public key.
 
 ### 🛡️ ACL Engine (SmartProxy-Aligned)
 
@@ -313,7 +360,61 @@ The **userspace NAT** mode extracts destination IP/port from IP packets, opens a
 
 The **bridge** mode assigns VPN clients IPs from a real LAN subnet instead of a virtual VPN subnet. Clients appear as if they're directly on the physical network — perfect for remote access to home labs, office networks, or IoT devices.
 
-The **hybrid** mode runs both engines simultaneously with a **per-client routing table**. Each client's `useHostIp` flag determines whether its packets go through the bridge (L2, LAN IP) or socket NAT (userspace, VPN IP). This is ideal when most clients need internet NAT but some need direct LAN access.
+The **hybrid** mode runs both engines simultaneously. Each authenticated session's `useHostIp` setting determines whether its packets go through the bridge or socket NAT; routing does not look up identity from the packet source.
+
+### Inner packet MTU
+
+`mtu` means inner IP bytes, not the outer network link MTU. It defaults to 1420
+and must be an integer from 576 through 65472, leaving room for the supported
+Noise and WireGuard framing. Larger previous values now reject before startup
+effects. The server uses this same ceiling for its TUN/TAP, userspace stack and
+native assignment; it does not subtract an estimated encapsulation overhead.
+
+Native clients now send their receive ceiling inside the authenticated Noise IK
+handshake. The server retains `min(server MTU, client MTU)` on that session,
+advertises it with the actual assignment subnet, and applies it to ingress,
+return encryption and the session's userspace TCP stack. Client configuration
+defaults to 1420; the client uses the negotiated ceiling unchanged for its TUN
+and both packet directions. Assignment fields must be valid before device setup;
+there is no guessed `/24`, gateway or MTU fallback. This changes the native wire
+contract: both ends must be upgraded together. Standard WireGuard framing is unchanged.
+
+Eligible oversized outbound client IPv4 packets receive feedback through the
+client TUN using its assigned address and subnet. An incomplete or failed device
+write is an error, never counted as successful feedback or retried as a second
+packet. Oversized inbound packets are discarded before TUN writes.
+
+WireGuard clients use the public flat `wgPrivateKey`, `serverPublicKey`,
+`wgAddress`, `wgAddressPrefix`, `wgEndpoint` and nonempty `wgAllowedIps` fields.
+The old Rust-only nested `peer` input is removed, with no translation fallback.
+Addresses, prefixes, keys, endpoint and MTU validate before TUN setup. The configured
+prefix supplies the device netmask; AllowedIPs route networks are canonicalized.
+`forwardingMode: 'testing'` creates no TUN or routes; the existing WireGuard default
+remains `'tun'` (native defaults to `'testing'`). Endpoint hostnames resolve in Rust.
+AllowedIPs authorizes decrypted source addresses and outbound destinations, after
+validating IP headers. The local configured MTU applies unchanged in both directions;
+standard WireGuard has no native SmartVPN MTU negotiation.
+
+`client.getMtuInfo()` now reports the live native or WireGuard runtime, or `null` when inactive.
+`tunMtu` is `null` in testing mode because no interface exists; unmeasured
+`linkMtu` and `overheadBytes` are also `null`. Counters belong to the current
+connection and `icmpTooBigSent` counts only complete TUN writes. These nullable
+results replace the previous hard-coded values.
+
+Authenticated native and integrated WireGuard packets are size-checked after
+source/ACL/rate admission and before forwarding. Return packets are checked before
+encryption. Oversized packets are dropped even when no safe error can be sent.
+Eligible IPv4 DF packets receive a bounded fragmentation-needed response from the
+owned tunnel gateway or bridge host address, through their exact session. Invalid
+headers, ICMP errors, noninitial fragments, multicast and known broadcasts do not
+generate errors. Feedback is limited to 10 packets/second with a burst of 10 per
+server; internal accounting distinguishes dropped packets from feedback queued.
+
+This is an inner admission ceiling, not IP fragmentation/reassembly or measured
+path-MTU discovery. Raw WG IPv6 remains kernel/testing-only and oversized IPv6 is
+dropped without fabricating an IPv6 router address. Standalone host-network
+cleanup and privileged WireGuard TUN qualification remain outstanding; the
+unprivileged packet fixtures do not establish host readiness for those modes.
 
 ### 🏠 Per-Client Bridge & VLAN Settings
 
@@ -365,7 +466,7 @@ VLAN support uses Linux bridge VLAN filtering — each client's TAP port gets ta
 - **Adaptive keepalives**: Interval adjusts based on link health (60s → 30s → 10s)
 - **Per-client rate limiting**: Token bucket with configurable bytes/sec and burst
 - **Dead-peer detection**: 180s inactivity timeout (all transports)
-- **MTU management**: Automatic overhead calculation (IP+TCP+WS+Noise = 79 bytes)
+- **MTU management**: Enforced inner packet ceilings and live counters; unmeasured outer-path values remain null
 - **Per-transport stats**: Active client and total connection counts broken down by websocket, QUIC, and WireGuard
 
 ### 🏷️ Client Tags (Trusted vs Informational)
@@ -396,6 +497,83 @@ await client.connect({
 
 The server acts as a **hub** — one API to manage all clients:
 
+`createClient()` accepts `IClientCreateOptions` with a required `clientId`;
+`updateClient()` accepts `TClientUpdateOptions`. Both reject unknown fields,
+server-owned identity/key/address fields, malformed security, invalid IPv4 ACL
+patterns, out-of-range integers and invalid VLAN combinations. Rejected settings
+do not change the registry or consume a new address. `forceTarget` requires an
+explicit IPv4 target; malformed policies are also rejected at server startup.
+
+Omitting an update field preserves it; explicit `null` clears an optional setting.
+Responses omit absent optional fields (including nested security/policy fields),
+matching the TypeScript interfaces; `null` is a clearing input, not an output value.
+A supplied `security` object replaces the whole security object, not individual
+nested fields. Clear `forceVlan` together with `vlanId`; an enabled VLAN requires
+an ID from 1 to 4094. Use `serverDefinedClientTags`; the shipped deprecated `tags`
+input remains accepted, but supplying both names is rejected as ambiguous.
+Preloaded entries also reject both populated tag fields; accepted old tags are
+consumed into the canonical field and are not retained in registry output.
+Input validation is separate from transport ownership and queued forwarding
+revocation; the runtime ownership rules below apply after successful admission.
+
+Native WebSocket/QUIC handshakes also recheck the exact registry incarnation and
+revision after sending the Noise response, before local admission. A successful
+update, disable/re-enable or remove/recreate invalidates an in-flight handshake;
+a rejected update does not. Network response writes do not hold the registry
+lock.
+
+Native and integrated WireGuard transports share one live session owner per
+registered client. Authenticated reconnect cancels and joins the previous
+transport generation before admitting its replacement. Disconnect, successful
+settings changes, disable, expiry, removal and key rotation retire the old
+transport and its WireGuard return relay. Queued WireGuard returns carry their
+original session identity and cannot target a replacement. Failed key-rotation
+reconciliation does not restore old credentials; inspect the registry and retry
+the operation to obtain fresh credentials.
+
+Registry assignments are reserved before listeners start and reused unchanged
+across native/WireGuard connections. Disconnect retains that reservation; record
+removal releases it only after transport teardown. Explicit assignments, including
+raw WireGuard reservations, precede dynamic allocation. A failed create cannot
+release an address belonging to a concurrent registry revision or recreated record.
+Decrypted registered-client packets must have a valid IPv4 header and exactly the
+assigned source address. Connection ACLs use the outer transport endpoint;
+destination ACLs use the inner packet destination. Runtime rate-limit adjustments
+apply to the current session only; use registry security settings for reconnects.
+
+Socket and bridge forwarding queues retain authenticated session ownership until
+their packet work is destroyed. Socket mode gives each session its own smoltcp
+stack; policy and PROXY identity come from that captured session, never a mutable
+registry lookup by packet source. Its TCP/UDP flows and socket readers are joined
+on revocation, and replies return only to their original owner. Flow incarnations
+also fence late responses when a tuple is reused. UDP flows sharing a destination
+are selected by received source endpoint, and real UDP sockets accept replies only
+from their configured target.
+
+Return queues are also generation-owned: cancellation purges queued payloads
+without waiting for a consumer, including WireGuard's shared return queue.
+Dequeued packets retain their destination lifetime, and internal relay packets
+retain their source lifetime too, until I/O finishes or the payload is destroyed.
+An interrupted native ciphertext write retires that destination tunnel rather
+than continuing a partially written frame or an advanced Noise nonce sequence.
+WireGuard returns require a current encryption session. While rekeying without
+one, application packets are dropped and counted; only a handshake is requested,
+so plaintext cannot escape owner cancellation through BoringTun's private queue.
+Queues are bounded (256 per session, 1024 for shared WG returns); full or closed
+queues reject admission. Managed relay uses these same two-owner lifetimes.
+
+Socket NAT is bounded to 256 active engines and 1,024 flow incarnations per server
+dispatcher. The per-client default is 128 TCP/UDP flows combined; a registered
+client's `security.maxConnections` overrides that local limit without bypassing
+the global cap. Late task/message references retain capacity until destroyed.
+Protocol and dispatch queues are bounded. This IPv4 userspace build does not
+reassemble fragments and rejects them before creating flows.
+
+These guarantees cover daemon-owned work, not traffic already handed to an
+external network or kernel. Managed relay is described below. Transactional cleanup
+and privileged qualification of standalone kernel modes remain outstanding;
+packet fixtures do not prove production network readiness.
+
 ```typescript
 // Create (generates keys, assigns IP, returns config bundle)
 const bundle = await server.createClient({ clientId: 'bob-phone' });
@@ -424,6 +602,108 @@ const wgConf = await server.exportClientConfig('bob-phone', 'wireguard');
 await server.removeClient('bob-phone');
 ```
 
+### Caller-owned managed networks
+
+`forwardingMode: 'managed'` is an exclusive IPv4 node relay. The hub creates no
+TUN, NAT, bridge or host routes. Start it with a fixed `subnet` and required
+`managedAuthorityId`, then call `reconcileManagedNetwork(snapshot)`. Cloudly (or
+another trusted controller) owns durable node IDs, keys, control addresses,
+workload prefixes and policy; SmartVPN owns volatile enforcement, not persistence.
+Protect the management IPC endpoint: the authority ID is a binding, not a credential.
+
+```typescript
+import type { IManagedNetworkSnapshot } from '@push.rocks/smartvpn';
+
+const snapshot: IManagedNetworkSnapshot = {
+  schemaVersion: 1,
+  authorityId: 'cloudly',
+  revision: 1,
+  nodes: [{
+    nodeId: 'worker-a',
+    publicKey: '<caller-owned-noise-public-key-base64>',
+    controlAddress: '10.88.0.2',
+    controlPolicyDomain: 'control',
+    enabled: true,
+    workloadPrefixes: [{ cidr: '10.90.0.0/24', policyDomain: 'task.vc' }],
+  }],
+  grants: [], // Absent grants deny, including within the same domain.
+};
+const applied = await server.reconcileManagedNetwork(snapshot);
+const status = await server.getManagedNetworkStatus();
+const projection = await server.getManagedNodeProjection('worker-a');
+```
+
+Snapshots are complete replacements. Canonical array order makes exact replay
+idempotent; stale revisions and conflicting equal revisions reject. Revisions
+are positive JSON-safe integers scoped to `lifetimeId`. Every daemon restart
+starts empty and requires the caller to reconcile its current durable state.
+Node keys must be unique canonical/contributory X25519 keys, including across
+Noise and WireGuard. Control addresses are exact usable hosts in the fixed subnet;
+workload prefixes cannot overlap that subnet or any other owned prefix.
+
+Grants are explicit `(sourceDomain, destinationDomain)` pairs. They neither imply
+same-domain permission nor reverse/reply permission. Different workload prefixes
+on one node may belong to different domains. Disabled, expired, missing, offline
+or denied destinations drop without host fallback. Traffic that never crosses
+the hub needs local enforcement by the node executor; local workload prefixes
+are never routed back to the hub merely because a grant involves them.
+
+Invalid preparation preserves active authority. A valid change quarantines and
+cancels only affected node generations, joins their packet work, prepares WG
+crypto and commits the whole snapshot atomically before acknowledging. Unchanged
+nodes keep their sessions. A post-drain failure leaves `state: 'failed'`, its
+`pendingRevision` and bounded `lastError`; old affected admission stays closed.
+Only the exact pending snapshot can retry. An IPC timeout or disconnected caller
+does not cancel the process-owned operation. Inspect status and replay that exact
+target; never assume a timed-out request did not commit. Separate Unix IPC
+connections can inspect status while apply drains; stdio remains sequential.
+
+Standalone create/update/remove/enable/disable/rotate/disconnect/rate-limit and
+raw WG-peer mutations reject in managed mode, including direct WG-loop commands.
+Standalone startup clients, raw peers, DNS, NAT, bridge and destination-routing
+configuration reject before effects. Managed WireGuard requires an explicit
+`serverEndpoint` and starts without peers until reconciliation.
+
+Native clients opt in with `managedNetwork: { authorityId: 'cloudly', nodeId: 'worker-a' }`.
+Missing, unexpected or differently bound managed assignments reject before host
+effects; a managed client cannot downgrade to a standalone subnet assignment.
+Native encrypted assignments carry schema, node/authority/lifetime/revision,
+local ownership and remote outgoing routes. Client `getStatus().managedNetwork`
+reports only the live validated assignment and clears on retirement. Native Linux
+TUN setup uses a fresh nonpersistent /32 device with strict exclusive route adds,
+not shell commands or route-conflict suppression. Preflight rejects malformed,
+overlapping, default, local-prefix and active-hub-endpoint capture. The netlink
+owner is polled inline; failure/cancellation drops the device and its owned routes.
+No DNS or default-route mutation is requested; native `forwardingMode: 'testing'`
+has no host effects. Managed TUN requires Linux.
+
+The Linux amd64 musl build passed the isolated `serve.zone/testing` VM scenario:
+real WS/Noise transport and TUN workload traffic between nodes connected only to
+the hub, directed allow/deny, reconnect, natural revocation, partial route-conflict
+rollback, empty-authority restart, and child termination. Cleanup removed owned
+namespaces and preserved DNS and IPv4/IPv6 default routes. This qualification
+does not cover WSS/private CAs, IPv6 workload traffic, privileged ARM64 networking,
+standalone kernel modes, or Pallet/Cloudly production integration.
+
+WireGuard has no assignment channel. `getManagedNodeProjection(nodeId)` returns
+the applied control `/32`, per-prefix domains, outgoing destinations, incoming
+sources, MTU and optional public WG configuration, never a private key. Client
+WG AllowedIPs is the union of remote outgoing/incoming prefixes plus the hub's
+MTU-feedback gateway `/32`; the hub independently enforces direction. Server WG
+AllowedIPs contains the node's owned source prefixes. Authenticated WG keepalive
+confirmation admits receive-only managed nodes without an inner probe. Projection
+`ready` means applied/admissible configuration, not connectivity, node installation
+or deployment readiness; disabled, absent and quarantined nodes return no config.
+The controller must apply WG projections through its owned node runtime.
+
+Bounds are 1,024 nodes, 128 workload prefixes per node, 16,384 owned prefixes,
+16,384 grants, 128-byte IDs, 1,024 routes per node per direction, and 262,144 total
+projected routes/grants. Managed relay enforces both live negotiated MTUs and
+returns eligible IPv4 fragmentation-needed feedback to the exact source owner.
+The complete [third-party notice index](./third-party-notices.md) covers the locked
+Cargo graph and statically linked compiler/runtime components. Keep its accompanying
+notice files with separately redistributed executables.
+
 ### 📝 WireGuard Config Generation
 
 Generate standard `.conf` files for any WireGuard client:
@@ -493,6 +773,7 @@ client.on('exit', ({ code, signal }) => { /* daemon process exited */ });
 |-------|-----------|---------|
 | `exit` | Both | `{ code, signal }` — daemon process exited |
 | `reconnected` | Both | `void` — socket transport reconnected |
+| `stderr` | Both | `string` — daemon diagnostic line, forwarded without automatic logging |
 
 For connection state and telemetry, use `getStatus()`, `getStatistics()`, `listClients()`, and `getClientTelemetry()`.
 
@@ -532,6 +813,8 @@ For connection state and telemetry, use `getStatus()`, `getStatistics()`, `listC
 | Command | Description |
 |---------|-------------|
 | `start` / `stop` | Start/stop the VPN listener |
+| `reconcileManagedNetwork` | Validate, drain and atomically apply a complete managed snapshot |
+| `getManagedNetworkStatus` / `getManagedNodeProjection` | Authority/lifetime/revision status and caller-applied node configuration |
 | `createClient` | Generate keys, assign IP, return config bundle |
 | `removeClient` / `getClient` / `listRegisteredClients` | Client registry CRUD |
 | `updateClient` / `enableClient` / `disableClient` | Modify client state |
@@ -615,6 +898,31 @@ All frames use `[type:1B][length:4B][payload:NB]` with a 64KB max payload:
 
 ## Development 🛠️
 
+### Native binary selection and build prerequisites
+
+The package builds `smartvpn_daemon_linux_amd64_musl` and
+`smartvpn_daemon_linux_arm64_musl` with the pinned Rust 1.95.0 toolchain and
+locked Cargo dependencies. Both targets require genuine musl C toolchains for
+the native `ring` and `mimalloc` dependencies. Put `x86_64-linux-musl-gcc` and
+`aarch64-linux-musl-gcc` on `PATH` before building or testing; GNU libc headers
+are not a substitute. The existing build and test commands remain unchanged.
+
+In stdio mode the bridge selects exactly the bundled executable for Linux x64
+or arm64. `SMARTVPN_RUST_BINARY` selects an explicit development executable on
+any supported native build platform. Missing, non-executable, and empty explicit
+selections fail: there is no fallback to old GNU artifacts, the current working
+directory's Rust builds, platform packages, or a daemon found on `PATH`.
+Other platforms must provide that explicit executable. Socket transport connects
+to an independently managed daemon and does not require a local binary.
+
+For an unprivileged build host, musl's upstream `musl-gcc` wrappers can provide
+the C toolchains using existing native and cross GCC compilers. Build musl 1.2.5
+in separate disposable prefixes for each architecture, with `--disable-shared`
+and an explicitly prefix-local `--syslibdir`. Use the two musl security patches
+from [Rust 1.95.0's build recipe](https://github.com/rust-lang/rust/blob/1.95.0/src/ci/docker/scripts/musl-toolchain.sh).
+Expose the generated wrappers under the target-specific names above; never
+install a replacement libc or dynamic linker into the host's system directories.
+
 ```bash
 # Install dependencies
 pnpm install
@@ -674,7 +982,7 @@ smartvpn/
 │       └── reconnect.rs        # Exponential backoff + session tokens
 ├── test/                       # Test files
 ├── dist_ts/                    # Compiled TypeScript
-└── dist_rust/                  # Cross-compiled binaries (linux amd64 + arm64)
+└── dist_rust/                  # Static musl binaries (Linux amd64 + arm64)
 ```
 
 ## License and Legal Information