@push.rocks/smartvpn 1.21.0 → 2.0.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,6 +61,30 @@ 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;
@@ -85,7 +109,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 +117,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 +222,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 +304,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 +417,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 +440,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 +489,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 +511,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 +523,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}`);
+}