@push.rocks/smartvpn 2.0.0 → 2.2.0

package/third-party-notices.md

@@ -22,7 +22,7 @@ locked, feature-inactive packages are covered by these supplemental MIT notices:
 - [valuable 0.1.1](./notices/valuable-license.txt), from
   [its pinned upstream LICENSE](https://github.com/tokio-rs/valuable/blob/9efc29b6e58cef28f6566a47aa7e142a55fead77/LICENSE).
 
-Together these cover all 278 locked registry packages, conservatively including
+Together these cover all 278 locked external packages, conservatively including
 build-only and target-inactive dependencies. Listing a package does not mean it
 is linked into either Linux executable. MIT is preferred where offered as an
 alternative; other selected terms include Apache-2.0, BSD, ISC, Unicode-3.0,
@@ -30,6 +30,12 @@ CDLA-Permissive-2.0 and the existing tun 0.7.22 dependency's WTFPL.
 The exact package versions, declared license expressions and reviewed file hashes
 are recorded in [inventory.json](./notices/inventory.json).
 
+The managed kernel inventory uses the published `netlink-proto` 0.13.1 fork at
+`bcbbfbba7485857c3b1f9fd5f6d99d597a334ab0` from
+[push.rocks/netlink-proto](https://code.foss.global/push.rocks/netlink-proto).
+Its exact MIT notice is included in the generated inventory and supplemental
+route notices; the original 0.13.0 attribution is retained there as well.
+
 The [additional MIT source attributions](./notices/mit-source-attributions.txt)
 retain cesu8 1.1.0's Rust Project/Eric Kidd source headers and siphasher 1.0.2's
 Rust Project/Frank Denis `COPYING` attribution, together with the selected MIT terms.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartvpn',
-  version: '2.0.0',
+  version: '2.2.0',
   description: 'A VPN solution with TypeScript control plane and Rust data plane daemon'
 }

package/ts/smartvpn.classes.vpnbridge.ts

@@ -3,8 +3,9 @@ import * as paths from './smartvpn.paths.js';
 import type {
   TVpnTransportOptions,
   IVpnTransportSocket,
+  IVpnManagedRuntimeInvalidation,
 } from './smartvpn.interfaces.js';
-import type { TCommandMap } from '@push.rocks/smartrust';
+import type { TCommandMap, IRustBridgeDisconnectedEvent } from '@push.rocks/smartrust';
 
 /**
  * Shared bridge wrapper around smartrust RustBridge.
@@ -19,25 +20,45 @@ export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.Eve
     transport: TVpnTransportOptions;
     mode: 'client' | 'server';
     binaryName?: string;
+    networkNamespaceFd?: number;
   }) {
     super();
 
+    const namespaceFd = options.networkNamespaceFd;
+    if (namespaceFd !== undefined) {
+      if (plugins.os.platform() !== 'linux' || options.mode !== 'client' || options.transport.transport !== 'stdio') {
+        throw new Error('VpnBridge networkNamespaceFd requires a Linux stdio client');
+      }
+      if (!Number.isInteger(namespaceFd) || namespaceFd < 0 || namespaceFd > 0x7fff_ffff) {
+        throw new Error('VpnBridge networkNamespaceFd must be a non-negative native descriptor');
+      }
+    }
     const binaryName = options.binaryName || 'smartvpn_daemon';
-    this.transportOptions = options.transport;
+    if (options.transport.transport === 'stdio' && options.transport.binaryPath !== undefined
+      && (typeof options.transport.binaryPath !== 'string' || !plugins.path.isAbsolute(options.transport.binaryPath))) {
+      throw new Error('VpnBridge binaryPath must be an absolute executable path');
+    }
+    // Keep the validated process transport stable even if the caller edits its options.
+    this.transportOptions = { ...options.transport };
     this.mode = options.mode;
 
     this.bridge = new plugins.smartrust.RustBridge<TCommands>({
       binaryName,
       binaryPath: options.transport.transport === 'stdio'
-        ? paths.getBinaryPath(binaryName)
+        ? options.transport.binaryPath ?? paths.getBinaryPath(binaryName)
         : undefined,
       localPaths: [],
       searchSystemPath: false,
-      cliArgs: ['--management', '--mode', this.mode],
+      cliArgs: ['--management', '--mode', this.mode,
+        ...(namespaceFd === undefined ? [] : ['--network-namespace-fd', '3'])],
+      inheritedFileDescriptors: namespaceFd === undefined ? undefined : [namespaceFd],
       maxPayloadSize: 10 * 1024 * 1024, // 10 MB
     });
 
     // Forward events from inner bridge
+    this.bridge.on('disconnected', (event: IRustBridgeDisconnectedEvent) => {
+      this.emit('disconnected', event);
+    });
     this.bridge.on('exit', (code: number | null, signal: string | null) => {
       this.emit('exit', code, signal);
     });
@@ -50,6 +71,9 @@ export class VpnBridge<TCommands extends TCommandMap> extends plugins.events.Eve
 
     // Forward management events from the daemon
     // smartrust emits 'management:<eventName>' for unsolicited events
+    this.bridge.on('management:managed-runtime-invalidated', (data: IVpnManagedRuntimeInvalidation) => {
+      this.emit('managed-runtime-invalidated', data);
+    });
     this.bridge.on('management:status', (data: any) => {
       this.emit('status', data);
     });

package/ts/smartvpn.classes.vpnclient.ts

@@ -7,6 +7,9 @@ import type {
   IVpnStatistics,
   IVpnConnectionQuality,
   IVpnMtuInfo,
+  IVpnConnectionResult,
+  IVpnManagedRuntime,
+  IVpnManagedRuntimeInvalidation,
   TVpnClientCommands,
 } from './smartvpn.interfaces.js';
 
@@ -16,6 +19,9 @@ import type {
 export class VpnClient extends plugins.events.EventEmitter {
   private bridge: VpnBridge<TVpnClientCommands>;
   private options: IVpnClientOptions;
+  private bridgeEpoch = 0;
+  private managedGeneration?: string;
+  private lastInvalidatedGeneration?: string;
 
   constructor(options: IVpnClientOptions) {
     super();
@@ -23,18 +29,46 @@ export class VpnClient extends plugins.events.EventEmitter {
     this.bridge = new VpnBridge<TVpnClientCommands>({
       transport: options.transport,
       mode: 'client',
+      networkNamespaceFd: options.networkNamespaceFd,
     });
 
     // Forward bridge events
+    this.bridge.on('disconnected', () => {
+      this.invalidateBridge('Client transport disconnected');
+    });
     this.bridge.on('exit', (code: number | null, signal: string | null) => {
+      this.invalidateBridge('Client bridge exited');
       this.emit('exit', { code, signal });
     });
     this.bridge.on('reconnected', () => {
+      this.invalidateBridge('Client bridge reconnected');
       this.emit('reconnected');
     });
     this.bridge.on('stderr', (line: string) => {
       this.emit('stderr', line);
     });
+    this.bridge.on('managed-runtime-invalidated', (event: IVpnManagedRuntimeInvalidation) => {
+      this.invalidateGeneration(event);
+    });
+  }
+
+  private invalidateGeneration(event: IVpnManagedRuntimeInvalidation): void {
+    if (this.lastInvalidatedGeneration === event.generation) return;
+    this.lastInvalidatedGeneration = event.generation;
+    if (this.managedGeneration === event.generation) this.managedGeneration = undefined;
+    this.emit('managed-runtime-invalidated', event);
+  }
+
+  private invalidateBridge(reason: string): void {
+    this.bridgeEpoch++;
+    if (this.managedGeneration) this.invalidateGeneration({ generation: this.managedGeneration, reason });
+  }
+
+  private checkObservation(runtime: IVpnManagedRuntime, epoch: number, generation?: string): void {
+    if (epoch !== this.bridgeEpoch || runtime.generation === this.lastInvalidatedGeneration
+      || (generation !== undefined && runtime.generation !== generation)) {
+      throw new Error('Managed runtime retired during the operation');
+    }
   }
 
   /**
@@ -47,12 +81,30 @@ export class VpnClient extends plugins.events.EventEmitter {
   /**
    * Connect to the VPN server using the provided config.
    */
-  public async connect(config?: IVpnClientConfig): Promise<{ assignedIp: string }> {
+  public async connect(config?: IVpnClientConfig): Promise<IVpnConnectionResult> {
     const cfg = config || this.options.config;
     if (!cfg) {
       throw new Error('VpnClient.connect: no config provided');
     }
-    return this.bridge.sendCommand('connect', { config: cfg });
+    const epoch = this.bridgeEpoch;
+    const result = await this.bridge.sendCommand('connect', { config: cfg });
+    if (result.managedRuntime) {
+      this.checkObservation(result.managedRuntime, epoch);
+      this.managedGeneration = result.managedRuntime.generation;
+    }
+    return result;
+  }
+
+  /** Inspect the retained native TUN, its exact IPv4 /32 and split routes.
+   * Requires the connection's generation and fails after retirement/reconnect. */
+  public async inspectManagedRuntime(generation: string): Promise<IVpnManagedRuntime> {
+    if (typeof generation !== 'string' || !/^[a-f0-9]{32}$/.test(generation)) {
+      throw new Error('Managed runtime generation must be a native 128-bit identifier');
+    }
+    const epoch = this.bridgeEpoch;
+    const result = await this.bridge.sendCommand('inspectManagedRuntime', { generation });
+    this.checkObservation(result, epoch, generation);
+    return result;
   }
 
   /**
@@ -95,6 +147,7 @@ export class VpnClient extends plugins.events.EventEmitter {
    * Stop the daemon bridge and wait for confirmed ownership release.
    */
   public async stop(): Promise<void> {
+    this.invalidateBridge('Client stop requested');
     await this.bridge.stop();
   }
 

package/ts/smartvpn.interfaces.ts

@@ -4,6 +4,9 @@
 
 export interface IVpnTransportStdio {
   transport: 'stdio';
+  /** Exact caller-verified executable. Overrides environment/package lookup;
+   * invalid paths fail without falling through to another executable. */
+  binaryPath?: string;
 }
 
 export interface IVpnTransportSocket {
@@ -88,6 +91,10 @@ export type IVpnClientConfig = TVpnClientConfig;
 export interface IVpnClientOptions {
   transport: TVpnTransportOptions;
   config?: IVpnClientConfig;
+  /** Linux stdio only. Caller-owned network namespace FD, retained through every spawn.
+   * The complete native client enters before threads, sockets, TUN or readiness.
+   * The caller owns namespace creation, underlay routing, DNS and packet policy. */
+  networkNamespaceFd?: number;
 }
 
 // ============================================================================
@@ -484,7 +491,8 @@ export interface IWgPeerInfo {
 // ============================================================================
 
 export type TVpnClientCommands = {
-  connect: { params: { config: IVpnClientConfig }; result: { assignedIp: string } };
+  connect: { params: { config: IVpnClientConfig }; result: IVpnConnectionResult };
+  inspectManagedRuntime: { params: { generation: string }; result: IVpnManagedRuntime };
   disconnect: { params: Record<string, never>; result: void };
   getStatus: { params: Record<string, never>; result: IVpnStatus };
   getStatistics: { params: Record<string, never>; result: IVpnStatistics };
@@ -591,6 +599,39 @@ export interface IManagedNetworkBinding {
   nodeId: string;
 }
 
+export interface IVpnConnectionResult {
+  assignedIp: string;
+  /** Present only for an authenticated native managed connection with a real TUN. */
+  managedRuntime?: IVpnManagedRuntime;
+}
+
+/** A fresh observation of a retained native lifetime, never a transferable or
+ * restorable capability. The caller retains VpnClient and listens for invalidation.
+ * IPv6, namespace-wide policy/rules, underlay and firewall remain caller-owned. */
+export interface IVpnManagedRuntime {
+  schemaVersion: 1;
+  generation: string;
+  namespace: { device: string; inode: string };
+  link: {
+    interfaceIndex: number;
+    interfaceName: string;
+    interfaceKind: 'tun';
+    linkIndex: number;
+    mtu: number;
+    address: string;
+    prefixLength: 32;
+  };
+  remoteIp: string;
+  assignment: IManagedNetworkAssignment;
+}
+
+/** Stop using this generation immediately. This event is not a joined cleanup,
+ * conntrack drain, or allocation-reuse acknowledgement. */
+export interface IVpnManagedRuntimeInvalidation {
+  generation: string;
+  reason: string;
+}
+
 export interface IManagedNodeConfig {
   /** Caller-owned control address with /32; local workload prefixes are not hub routes. */
   address: string;
@@ -628,6 +669,7 @@ export interface IVpnServiceUnit {
 // ============================================================================
 
 export interface IVpnEventMap {
+  'managed-runtime-invalidated': IVpnManagedRuntimeInvalidation;
   'status': IVpnStatus;
   'error': { message: string; code?: string };
   'client-connected': IVpnClientInfo;

package/readme.hints.md

@@ -1,74 +0,0 @@
-# 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/` 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 with `file` and `readelf` against the `_musl` artifacts. Regression
-  tests reject PT_INTERP, DT_NEEDED, wrong machine identifiers and glibc signatures.

package/readme.plan.md

@@ -1,253 +0,0 @@
-# PROXY Protocol v2 Support for SmartVPN WebSocket Transport
-
-## Context
-
-SmartVPN's WebSocket transport is designed to sit behind reverse proxies (Cloudflare, HAProxy, SmartProxy). The recently added ACL engine has `ipAllowList`/`ipBlockList` per client, but without PROXY protocol support the server only sees the proxy's IP — not the real client's. This makes source-IP ACLs useless behind a proxy.
-
-PROXY protocol v2 solves this by letting the proxy prepend a binary header with the real client IP/port before the WebSocket upgrade.
-
----
-
-## Design
-
-### Two-Phase ACL with Real Client IP
-
-```
-TCP accept → Read PP v2 header → Extract real IP
-  │
-  ├─ Phase 1 (pre-handshake): Check server-level connectionIpBlockList → reject early
-  │
-  ├─ WebSocket upgrade → Noise IK handshake → Client identity known
-  │
-  └─ Phase 2 (post-handshake): Check per-client ipAllowList/ipBlockList → reject if denied
-```
-
-- **Phase 1**: Server-wide block list (`connectionIpBlockList` on `IVpnServerConfig`). Rejects before any crypto work. Protects server resources.
-- **Phase 2**: Per-client ACL from `IClientSecurity.ipAllowList`/`ipBlockList`. Applied after the Noise IK handshake identifies the client.
-
-### No New Dependencies
-
-PROXY protocol v2 is a fixed-format binary header (16-byte signature + variable address block). Manual parsing (~80 lines) follows the same pattern as `codec.rs`. No crate needed.
-
-### Scope: WebSocket Only
-
-- **WebSocket**: Needs PP v2 (sits behind reverse proxies)
-- **QUIC**: Direct UDP, just use `conn.remote_address()`
-- **WireGuard**: Direct UDP, uses boringtun peer tracking
-
----
-
-## Implementation
-
-### Phase 1: New Rust module `proxy_protocol.rs`
-
-**New file: `rust/src/proxy_protocol.rs`**
-
-PP v2 binary format:
-```
-Bytes 0-11:   Signature  \x0D\x0A\x0D\x0A\x00\x0D\x0A\x51\x55\x49\x54\x0A
-Byte 12:      Version (high nibble = 0x2) | Command (low nibble: 0x0=LOCAL, 0x1=PROXY)
-Byte 13:      Address family | Protocol (0x11 = IPv4/TCP, 0x21 = IPv6/TCP)
-Bytes 14-15:  Address data length (big-endian u16)
-Bytes 16+:    IPv4: 4 src_ip + 4 dst_ip + 2 src_port + 2 dst_port (12 bytes)
-              IPv6: 16 src_ip + 16 dst_ip + 2 src_port + 2 dst_port (36 bytes)
-```
-
-```rust
-pub struct ProxyHeader {
-    pub src_addr: SocketAddr,
-    pub dst_addr: SocketAddr,
-    pub is_local: bool,  // LOCAL command = health check probe
-}
-
-/// Read and parse a PROXY protocol v2 header from a TCP stream.
-/// Reads exactly the header bytes — the stream is clean for WS upgrade after.
-pub async fn read_proxy_header(stream: &mut TcpStream) -> Result<ProxyHeader>
-```
-
-- 5-second timeout on header read (constant `PROXY_HEADER_TIMEOUT`)
-- Validates 12-byte signature, version nibble, command type
-- Parses IPv4 and IPv6 address blocks
-- LOCAL command returns `is_local: true` (caller closes connection gracefully)
-- Unit tests: valid IPv4/IPv6 headers, LOCAL command, invalid signature, truncated data
-
-**Modify: `rust/src/lib.rs`** — add `pub mod proxy_protocol;`
-
-### Phase 2: Server config + client info fields
-
-**File: `rust/src/server.rs` — `ServerConfig`**
-
-Add:
-```rust
-/// Enable PROXY protocol v2 parsing on WebSocket connections.
-/// SECURITY: Must be false when accepting direct client connections.
-pub proxy_protocol: Option<bool>,
-/// Server-level IP block list — applied at TCP accept time, before Noise handshake.
-pub connection_ip_block_list: Option<Vec<String>>,
-```
-
-**File: `rust/src/server.rs` — `ClientInfo`**
-
-Add:
-```rust
-/// Real client IP:port (from PROXY protocol header or direct TCP connection).
-pub remote_addr: Option<String>,
-```
-
-### Phase 3: ACL helper
-
-**File: `rust/src/acl.rs`**
-
-Add a public function for the server-level pre-handshake check:
-```rust
-/// Check whether a connection source IP is in a block list.
-pub fn is_connection_blocked(ip: Ipv4Addr, block_list: &[String]) -> bool {
-    ip_matches_any(ip, block_list)
-}
-```
-
-(Keeps `ip_matches_any` private; exposes only the specific check needed.)
-
-### Phase 4: WebSocket listener integration
-
-**File: `rust/src/server.rs` — `run_ws_listener()`**
-
-Between `listener.accept()` and `transport::accept_connection()`:
-
-```rust
-// Determine real client address
-let remote_addr = if state.config.proxy_protocol.unwrap_or(false) {
-    match proxy_protocol::read_proxy_header(&mut tcp_stream).await {
-        Ok(header) if header.is_local => {
-            // Health check probe — close gracefully
-            return;
-        }
-        Ok(header) => {
-            info!("PP v2: real client {} -> {}", header.src_addr, header.dst_addr);
-            Some(header.src_addr)
-        }
-        Err(e) => {
-            warn!("PP v2 parse failed from {}: {}", tcp_addr, e);
-            return; // Drop connection
-        }
-    }
-} else {
-    Some(tcp_addr) // Direct connection — use TCP SocketAddr
-};
-
-// Pre-handshake server-level block list check
-if let (Some(ref block_list), Some(ref addr)) = (&state.config.connection_ip_block_list, &remote_addr) {
-    if let std::net::IpAddr::V4(v4) = addr.ip() {
-        if acl::is_connection_blocked(v4, block_list) {
-            warn!("Connection blocked by server IP block list: {}", addr);
-            return;
-        }
-    }
-}
-
-// Then proceed with WS upgrade + handle_client_connection as before
-```
-
-Key correctness note: `read_proxy_header` reads *exactly* the PP header bytes via `read_exact`. The `TcpStream` is then in a clean state for the WS HTTP upgrade. No buffered wrapper needed.
-
-### Phase 5: Update `handle_client_connection` signature
-
-**File: `rust/src/server.rs`**
-
-Change signature:
-```rust
-async fn handle_client_connection(
-    state: Arc<ServerState>,
-    mut sink: Box<dyn TransportSink>,
-    mut stream: Box<dyn TransportStream>,
-    remote_addr: Option<std::net::SocketAddr>,  // NEW
-) -> Result<()>
-```
-
-After Noise IK handshake + registry lookup (where `client_security` is available), add connection-level per-client ACL:
-
-```rust
-if let (Some(ref sec), Some(addr)) = (&client_security, &remote_addr) {
-    if let std::net::IpAddr::V4(v4) = addr.ip() {
-        if acl::is_connection_blocked(v4, sec.ip_block_list.as_deref().unwrap_or(&[])) {
-            anyhow::bail!("Client {} connection denied: source IP {} blocked", registered_client_id, addr);
-        }
-        if let Some(ref allow) = sec.ip_allow_list {
-            if !allow.is_empty() && !acl::is_ip_allowed(v4, allow) {
-                anyhow::bail!("Client {} connection denied: source IP {} not in allow list", registered_client_id, addr);
-            }
-        }
-    }
-}
-```
-
-Populate `remote_addr` when building `ClientInfo`:
-```rust
-remote_addr: remote_addr.map(|a| a.to_string()),
-```
-
-### Phase 6: QUIC listener — pass remote addr through
-
-**File: `rust/src/server.rs` — `run_quic_listener()`**
-
-QUIC doesn't use PROXY protocol. Just pass `conn.remote_address()` through:
-```rust
-let remote = conn.remote_address();
-// ...
-handle_client_connection(state, Box::new(sink), Box::new(stream), Some(remote)).await
-```
-
-### Phase 7: TypeScript interface updates
-
-**File: `ts/smartvpn.interfaces.ts`**
-
-Add to `IVpnServerConfig`:
-```typescript
-/** Enable PROXY protocol v2 on incoming WebSocket connections.
- *  Required when behind a reverse proxy that sends PP v2 headers. */
-proxyProtocol?: boolean;
-/** Server-level IP block list — applied at TCP accept time, before Noise handshake. */
-connectionIpBlockList?: string[];
-```
-
-Add to `IVpnClientInfo`:
-```typescript
-/** Real client IP:port (from PROXY protocol or direct TCP). */
-remoteAddr?: string;
-```
-
-### Phase 8: Tests
-
-**Rust unit tests in `proxy_protocol.rs`:**
-- `parse_valid_ipv4_header` — construct a valid PP v2 header with known IPs, verify parsed correctly
-- `parse_valid_ipv6_header` — same for IPv6
-- `parse_local_command` — health check probe returns `is_local: true`
-- `reject_invalid_signature` — random bytes rejected
-- `reject_truncated_header` — short reads fail gracefully
-- `reject_v1_header` — PROXY v1 text format rejected (we only support v2)
-
-**Rust unit tests in `acl.rs`:**
-- `is_connection_blocked` with various IP patterns
-
-**TypeScript tests:**
-- Config validation accepts `proxyProtocol: true` + `connectionIpBlockList`
-
----
-
-## Key Files to Modify
-
-| File | Changes |
-|------|---------|
-| `rust/src/proxy_protocol.rs` | **NEW** — PP v2 parser + tests |
-| `rust/src/lib.rs` | Add `pub mod proxy_protocol;` |
-| `rust/src/server.rs` | `ServerConfig` + `ClientInfo` fields, `run_ws_listener` PP integration, `handle_client_connection` signature + connection ACL, `run_quic_listener` pass-through |
-| `rust/src/acl.rs` | Add `is_connection_blocked` public function |
-| `ts/smartvpn.interfaces.ts` | `proxyProtocol`, `connectionIpBlockList`, `remoteAddr` |
-
----
-
-## Verification
-
-1. `cargo test` — all existing 121 tests + new PP parser tests pass
-2. `pnpm test` — all 79 TS tests pass (no PP in test setup, just config validation)
-3. Manual: `socat` or test harness to send a PP v2 header before WS upgrade, verify server logs real IP