@push.rocks/smartvpn 1.22.0 → 2.1.0

package/ts/smartvpn.interfaces.ts

@@ -21,18 +21,18 @@ export type TVpnTransportOptions = IVpnTransportStdio | IVpnTransportSocket;
 // Client configuration
 // ============================================================================
 
-export interface IVpnClientConfig {
+interface IVpnClientConfigBase {
   /** Server WebSocket URL, e.g. wss://vpn.example.com/tunnel */
-  serverUrl: string;
+  serverUrl?: string;
   /** Server's static public key (base64) for Noise IK handshake */
   serverPublicKey: string;
   /** Client's Noise IK private key (base64) — required for SmartVPN native transport */
-  clientPrivateKey: string;
+  clientPrivateKey?: string;
   /** Client's Noise IK public key (base64) — for reference/display */
-  clientPublicKey: string;
+  clientPublicKey?: string;
   /** Optional DNS servers to use while connected */
   dns?: string[];
-  /** Optional MTU for the TUN device */
+  /** Inner TUN MTU in whole IP bytes, 576..65472 (default: 1420); not outer link MTU. */
   mtu?: number;
   /** Keepalive interval in seconds (default: 30) */
   keepaliveIntervalSecs?: number;
@@ -41,7 +41,7 @@ export interface IVpnClientConfig {
   /** For QUIC: SHA-256 hash of server certificate (base64) for cert pinning */
   serverCertHash?: string;
   /** Forwarding mode: 'tun' (TUN device, requires root) or 'testing' (no TUN).
-   *  Default: 'testing'. */
+   *  Default: native 'testing', WireGuard 'tun'. */
   forwardingMode?: 'tun' | 'testing';
   /** WireGuard: client private key (base64, X25519) */
   wgPrivateKey?: string;
@@ -61,9 +61,37 @@ export interface IVpnClientConfig {
   clientDefinedClientTags?: string[];
 }
 
+/** Native transports authenticate with Noise IK, independently of WireGuard. */
+export interface IVpnNativeClientConfig extends IVpnClientConfigBase {
+  /** Explicit managed opt-in. Rejects a missing or differently bound server assignment. */
+  managedNetwork?: IManagedNetworkBinding;
+  transport?: 'auto' | 'websocket' | 'quic';
+  serverUrl: string;
+  clientPrivateKey: string;
+  clientPublicKey: string;
+}
+
+/** WireGuard uses its own key and address; Noise credentials are not required. */
+export interface IVpnWireguardClientConfig extends IVpnClientConfigBase {
+  transport: 'wireguard';
+  wgPrivateKey: string;
+  wgAddress: string;
+  wgEndpoint: string;
+  /** Explicit peer source/destination routing authority. Must not be empty. */
+  wgAllowedIps: string[];
+}
+
+export type TVpnClientConfig = IVpnNativeClientConfig | IVpnWireguardClientConfig;
+/** Retains the published config type name; both names enforce the transport union. */
+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;
 }
 
 // ============================================================================
@@ -85,7 +113,7 @@ export interface IVpnServerConfig {
   subnet: string;
   /** DNS servers pushed to clients */
   dns?: string[];
-  /** MTU for TUN device */
+  /** Inner TUN/forwarding packet ceiling in whole IP bytes, 576..65472 (default: 1420). */
   mtu?: number;
   /** Keepalive interval in seconds (default: 30) */
   keepaliveIntervalSecs?: number;
@@ -93,8 +121,10 @@ export interface IVpnServerConfig {
   enableNat?: boolean;
   /** Forwarding mode: 'tun' (kernel TUN, requires root), 'socket' (userspace NAT),
    *  'bridge' (L2 bridge to host LAN), 'hybrid' (per-client socket+bridge),
-   *  or 'testing' (monitoring only). Default: 'testing'. */
-  forwardingMode?: 'tun' | 'socket' | 'bridge' | 'hybrid' | 'testing';
+   *  'managed' (caller-owned node relay without host networking), or 'testing'. Default: 'testing'. */
+  forwardingMode?: 'tun' | 'socket' | 'bridge' | 'hybrid' | 'testing' | 'managed';
+  /** Required in managed mode. Bound to this process lifetime; not an authentication credential. */
+  managedAuthorityId?: string;
   /** Default rate limit for new clients (bytes/sec). Omit for unlimited. */
   defaultRateLimitBytesPerSec?: number;
   /** Default burst size for new clients (bytes). Omit for unlimited. */
@@ -196,6 +226,8 @@ export type TVpnConnectionState =
   | 'error';
 
 export interface IVpnStatus {
+  /** Authenticated native assignment for this connection, absent after retirement. */
+  managedNetwork?: IManagedNetworkAssignment;
   state: TVpnConnectionState;
   assignedIp?: string;
   serverAddr?: string;
@@ -276,11 +308,16 @@ export interface IVpnConnectionQuality {
 // ============================================================================
 
 export interface IVpnMtuInfo {
-  tunMtu: number;
+  /** Actual inner TUN ceiling; null in testing mode because no TUN exists. */
+  tunMtu: number | null;
+  /** Enforced inner packet ceiling, not an estimated outer path MTU. */
   effectiveMtu: number;
-  linkMtu: number;
-  overheadBytes: number;
+  /** Null when the transport has not measured the outer link. */
+  linkMtu: number | null;
+  /** Null when the transport has not measured encapsulation overhead. */
+  overheadBytes: number | null;
   oversizedPacketsDropped: number;
+  /** Feedback packets successfully written to the client TUN, not just generated. */
   icmpTooBigSent: number;
 }
 
@@ -384,6 +421,21 @@ export interface IClientEntry {
   vlanId?: number;
 }
 
+/** Admin-writable settings. Omission preserves a setting; null clears it.
+ * Identity, keys, assignment and client-reported tags have separate owners.
+ * A supplied security object replaces the complete previous security object. */
+export type TClientUpdateOptions = {
+  [TField in keyof Omit<
+    IClientEntry,
+    'clientId' | 'publicKey' | 'wgPublicKey' | 'assignedIp' | 'clientDefinedClientTags'
+  >]?: IClientEntry[TField] | null;
+};
+
+/** Creation generates server-owned keys and assignment; clientId is required. */
+export interface IClientCreateOptions extends TClientUpdateOptions {
+  clientId: string;
+}
+
 /**
  * Complete client config bundle — returned by createClient() and rotateClientKey().
  * Contains everything the client needs to connect.
@@ -392,7 +444,7 @@ export interface IClientConfigBundle {
   /** The server-side client entry */
   entry: IClientEntry;
   /** Ready-to-use SmartVPN client config (typed object) */
-  smartvpnConfig: IVpnClientConfig;
+  smartvpnConfig: IVpnNativeClientConfig;
   /** Ready-to-use WireGuard .conf file content (string) */
   wireguardConfig: string;
   /** Client's private keys (ONLY returned at creation time, not stored server-side) */
@@ -441,10 +493,13 @@ export type TVpnClientCommands = {
   getStatus: { params: Record<string, never>; result: IVpnStatus };
   getStatistics: { params: Record<string, never>; result: IVpnStatistics };
   getConnectionQuality: { params: Record<string, never>; result: IVpnConnectionQuality };
-  getMtuInfo: { params: Record<string, never>; result: IVpnMtuInfo };
+  getMtuInfo: { params: Record<string, never>; result: IVpnMtuInfo | null };
 };
 
 export type TVpnServerCommands = {
+  reconcileManagedNetwork: { params: { snapshot: IManagedNetworkSnapshot }; result: IManagedNetworkStatus };
+  getManagedNetworkStatus: { params: Record<string, never>; result: IManagedNetworkStatus };
+  getManagedNodeProjection: { params: { nodeId: string }; result: IManagedNodeProjection };
   start: { params: { config: IVpnServerConfig }; result: void };
   stop: { params: Record<string, never>; result: void };
   getStatus: { params: Record<string, never>; result: IVpnStatus };
@@ -460,11 +515,11 @@ export type TVpnServerCommands = {
   removeWgPeer: { params: { publicKey: string }; result: void };
   listWgPeers: { params: Record<string, never>; result: { peers: IWgPeerInfo[] } };
   // Client Registry (Hub) commands
-  createClient: { params: { client: Partial<IClientEntry> }; result: IClientConfigBundle };
+  createClient: { params: { client: IClientCreateOptions }; result: IClientConfigBundle };
   removeClient: { params: { clientId: string }; result: void };
   getClient: { params: { clientId: string }; result: IClientEntry };
   listRegisteredClients: { params: Record<string, never>; result: { clients: IClientEntry[] } };
-  updateClient: { params: { clientId: string; update: Partial<IClientEntry> }; result: void };
+  updateClient: { params: { clientId: string; update: TClientUpdateOptions }; result: void };
   enableClient: { params: { clientId: string }; result: void };
   disableClient: { params: { clientId: string }; result: void };
   rotateClientKey: { params: { clientId: string }; result: IClientConfigBundle };
@@ -472,6 +527,94 @@ export type TVpnServerCommands = {
   generateClientKeypair: { params: Record<string, never>; result: IVpnKeypair };
 };
 
+/** Complete schema-v1 authority. No patch semantics or implicit/reverse grants. */
+export interface IManagedNetworkSnapshot {
+  schemaVersion: 1;
+  authorityId: string;
+  /** Positive JSON-safe integer, monotonically increasing within the server lifetime. */
+  revision: number;
+  nodes: IManagedNetworkNode[];
+  grants: IManagedNetworkGrant[];
+}
+
+export interface IManagedNetworkNode {
+  nodeId: string;
+  publicKey: string;
+  wgPublicKey?: string;
+  controlAddress: string;
+  controlPolicyDomain: string;
+  enabled: boolean;
+  expiresAt?: string;
+  workloadPrefixes: IManagedNetworkPrefix[];
+}
+
+export interface IManagedNetworkPrefix {
+  cidr: string;
+  policyDomain: string;
+}
+
+export interface IManagedNetworkGrant {
+  sourceDomain: string;
+  destinationDomain: string;
+}
+
+export interface IManagedNetworkStatus {
+  authorityId: string;
+  lifetimeId: string;
+  state: 'idle' | 'applying' | 'failed';
+  appliedRevision: number | null;
+  pendingRevision: number | null;
+  stage: 'draining' | 'preparingTransport' | null;
+  lastError: string | null;
+}
+
+export interface IManagedNodeProjection {
+  schemaVersion: 1;
+  authorityId: string;
+  lifetimeId: string;
+  appliedRevision: number | null;
+  nodeId: string;
+  /** Configuration is applied/admissible, not proof of connectivity or host readiness. */
+  ready: boolean;
+  config: IManagedNodeConfig | null;
+}
+
+export interface IManagedNetworkAssignment {
+  schemaVersion: 1;
+  authorityId: string;
+  lifetimeId: string;
+  appliedRevision: number;
+  nodeId: string;
+  ownedPrefixes: string[];
+  /** Remote destinations only; never local workload prefixes or a default route. */
+  routes: string[];
+}
+
+export interface IManagedNetworkBinding {
+  authorityId: string;
+  nodeId: string;
+}
+
+export interface IManagedNodeConfig {
+  /** Caller-owned control address with /32; local workload prefixes are not hub routes. */
+  address: string;
+  gateway: string;
+  ownedPrefixes: IManagedNetworkPrefix[];
+  outgoingRoutes: string[];
+  incomingSources: string[];
+  mtu: number;
+  wireguard: IManagedWireGuardProjection | null;
+}
+
+export interface IManagedWireGuardProjection {
+  publicKey: string;
+  serverPublicKey: string;
+  endpoint: string;
+  /** Union of remote outgoing/incoming prefixes plus hub MTU-feedback gateway /32.
+   *  The hub still enforces directed grants. Never includes local workload prefixes. */
+  allowedIps: string[];
+}
+
 // ============================================================================
 // Installer
 // ============================================================================

package/ts/smartvpn.paths.ts

@@ -4,3 +4,22 @@ export const packageDir = plugins.path.join(
   plugins.smartpath.get.dirnameFromImportMetaUrl(import.meta.url),
   '../',
 );
+
+/** Select only an explicitly requested binary or this package's Linux musl artifact. */
+export function getBinaryPath(
+  binaryName: string,
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+  override: string | undefined = process.env.SMARTVPN_RUST_BINARY,
+): string {
+  // Smartrust validates explicit paths, including empty/invalid overrides, without
+  // repairing their permissions or falling through to an unrelated executable.
+  if (override !== undefined) {
+    return override;
+  }
+  if (platform !== 'linux' || (arch !== 'x64' && arch !== 'arm64')) {
+    throw new Error(`SmartVPN does not bundle a daemon for ${platform}/${arch}; set SMARTVPN_RUST_BINARY to an explicitly built executable or use socket transport.`);
+  }
+  const suffix = arch === 'x64' ? 'linux_amd64_musl' : 'linux_arm64_musl';
+  return plugins.path.join(packageDir, 'dist_rust', `${binaryName}_${suffix}`);
+}

package/readme.hints.md

@@ -1,8 +0,0 @@
-# smartvpn hints
-
-## 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`).
-- `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".

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