novac 2.0.1 → 2.2.0

package/kits/kitnet/kitdef.js

@@ -0,0 +1,1401 @@
+// kitnet — novac networking kit
+// Low-level networking primitives for novac.
+// Covers: TCP, UDP, WebSocket, DNS, TLS, ICMP ping, port scanning,
+//         network interfaces, proxies, packet inspection, and more.
+//
+// Complements the core language's fetch(), URL types, and server{} block.
+
+'use strict';
+
+const net   = require('net');
+const dgram = require('dgram');
+const dns   = require('dns');
+const tls   = require('tls');
+const http  = require('http');
+const https = require('https');
+const os    = require('os');
+const { EventEmitter } = require('events');
+const { promisify }    = require('util');
+
+const dnsResolve4   = promisify(dns.resolve4);
+const dnsResolve6   = promisify(dns.resolve6);
+const dnsResolveMx  = promisify(dns.resolveMx);
+const dnsResolveTxt = promisify(dns.resolveTxt);
+const dnsResolveSrv = promisify(dns.resolveSrv);
+const dnsResolveNs  = promisify(dns.resolveNs);
+const dnsReverse    = promisify(dns.reverse);
+const dnsLookup     = promisify(dns.lookup);
+
+// ─── HELPERS ─────────────────────────────────────────────────────────────────
+
+function defer() {
+  let resolve, reject;
+  const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+  return { promise, resolve, reject };
+}
+
+function timeout(ms, msg = 'Timed out') {
+  return new Promise((_, reject) => setTimeout(() => reject(new Error(msg)), ms));
+}
+
+function race(promise, ms, msg) {
+  return Promise.race([promise, timeout(ms, msg)]);
+}
+
+// ─── TCP ─────────────────────────────────────────────────────────────────────
+
+const tcp = {
+  /**
+   * Open a TCP connection to host:port.
+   * Returns a socket wrapper with send/receive/close.
+   * @param {string} host
+   * @param {number} port
+   * @param {object} [opts]
+   * @param {number} [opts.timeout=10000]
+   * @param {string} [opts.encoding='utf8']
+   * @returns {Promise<TcpSocket>}
+   */
+  async connect(host, port, opts = {}) {
+    const enc = opts.encoding ?? 'utf8';
+    const d   = defer();
+    const socket = net.createConnection({ host, port }, () => d.resolve(socket));
+    socket.setTimeout(opts.timeout ?? 10000);
+    socket.on('error', d.reject);
+    await race(d.promise, opts.timeout ?? 10000, `TCP connect to ${host}:${port} timed out`);
+
+    const emitter = new EventEmitter();
+    socket.setEncoding(enc);
+    socket.on('data',  data  => emitter.emit('data', data));
+    socket.on('close', ()    => emitter.emit('close'));
+    socket.on('error', err   => emitter.emit('error', err));
+    socket.on('timeout', ()  => { emitter.emit('timeout'); socket.destroy(); });
+
+    return {
+      host, port,
+      /** Send data over the socket. */
+      send(data) {
+        return new Promise((res, rej) => socket.write(data, err => err ? rej(err) : res()));
+      },
+      /** Receive the next chunk of data. */
+      receive(timeoutMs = 10000) {
+        return race(new Promise(res => emitter.once('data', res)), timeoutMs, 'Receive timed out');
+      },
+      /** Receive all data until the socket closes. */
+      receiveAll(timeoutMs = 30000) {
+        return race(new Promise(res => {
+          const chunks = [];
+          emitter.on('data', d => chunks.push(d));
+          emitter.once('close', () => res(chunks.join('')));
+        }), timeoutMs, 'receiveAll timed out');
+      },
+      /** Pipe received data to a callback. */
+      onData(fn)  { emitter.on('data', fn); return this; },
+      onClose(fn) { emitter.on('close', fn); return this; },
+      onError(fn) { emitter.on('error', fn); return this; },
+      /** Close the connection. */
+      close() { socket.destroy(); },
+      /** Underlying net.Socket for advanced use. */
+      raw: socket,
+    };
+  },
+
+  /**
+   * Create a TCP server.
+   * @param {number} port
+   * @param {string} [host='0.0.0.0']
+   * @param {function} handler - Called with each TcpSocket connection.
+   * @returns {Promise<TcpServer>}
+   */
+  async serve(port, host = '0.0.0.0', handler) {
+    if (typeof host === 'function') { handler = host; host = '0.0.0.0'; }
+    const server = net.createServer(socket => {
+      const emitter = new EventEmitter();
+      socket.setEncoding('utf8');
+      socket.on('data',  d => emitter.emit('data', d));
+      socket.on('close', () => emitter.emit('close'));
+      socket.on('error', e => emitter.emit('error', e));
+
+      const conn = {
+        remoteAddress: socket.remoteAddress,
+        remotePort:    socket.remotePort,
+        send(data) { return new Promise((res, rej) => socket.write(data, e => e ? rej(e) : res())); },
+        receive(ms = 10000) { return race(new Promise(res => emitter.once('data', res)), ms, 'Receive timed out'); },
+        receiveAll(ms = 30000) {
+          return race(new Promise(res => {
+            const chunks = [];
+            emitter.on('data', d => chunks.push(d));
+            emitter.once('close', () => res(chunks.join('')));
+          }), ms, 'receiveAll timed out');
+        },
+        onData(fn)  { emitter.on('data', fn); return this; },
+        onClose(fn) { emitter.on('close', fn); return this; },
+        onError(fn) { emitter.on('error', fn); return this; },
+        close() { socket.destroy(); },
+        raw: socket,
+      };
+      handler(conn);
+    });
+
+    await new Promise((res, rej) => server.listen(port, host, res).on('error', rej));
+
+    return {
+      port, host,
+      close() { return new Promise(res => server.close(res)); },
+      raw: server,
+    };
+  },
+
+  /**
+   * Check if a TCP port is open on a host.
+   * @param {string} host
+   * @param {number} port
+   * @param {number} [timeoutMs=3000]
+   * @returns {Promise<boolean>}
+   */
+  async isOpen(host, port, timeoutMs = 3000) {
+    return new Promise(resolve => {
+      const socket = net.createConnection({ host, port });
+      socket.setTimeout(timeoutMs);
+      socket.on('connect', () => { socket.destroy(); resolve(true); });
+      socket.on('error',   () => resolve(false));
+      socket.on('timeout', () => { socket.destroy(); resolve(false); });
+    });
+  },
+
+  /**
+   * Send data and get response in a single call (connect → send → receive → close).
+   * @param {string} host
+   * @param {number} port
+   * @param {string|Buffer} data
+   * @param {object} [opts]
+   * @returns {Promise<string>}
+   */
+  async request(host, port, data, opts = {}) {
+    const socket = await tcp.connect(host, port, opts);
+    await socket.send(data);
+    const response = await socket.receiveAll(opts.timeout ?? 10000);
+    socket.close();
+    return response;
+  },
+};
+
+// ─── UDP ─────────────────────────────────────────────────────────────────────
+
+const udp = {
+  /**
+   * Send a UDP datagram.
+   * @param {string} host
+   * @param {number} port
+   * @param {string|Buffer} data
+   * @param {'udp4'|'udp6'} [type='udp4']
+   * @returns {Promise<void>}
+   */
+  send(host, port, data, type = 'udp4') {
+    return new Promise((resolve, reject) => {
+      const client = dgram.createSocket(type);
+      const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      client.send(buf, port, host, err => {
+        client.close();
+        err ? reject(err) : resolve();
+      });
+    });
+  },
+
+  /**
+   * Send a UDP datagram and wait for a response.
+   * @param {string} host
+   * @param {number} port
+   * @param {string|Buffer} data
+   * @param {object} [opts]
+   * @returns {Promise<{ data: Buffer, rinfo: object }>}
+   */
+  request(host, port, data, opts = {}) {
+    const timeoutMs = opts.timeout ?? 5000;
+    const type      = opts.type    ?? 'udp4';
+    return race(new Promise((resolve, reject) => {
+      const client = dgram.createSocket(type);
+      const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      client.send(buf, port, host, err => { if (err) { client.close(); reject(err); } });
+      client.on('message', (msg, rinfo) => { client.close(); resolve({ data: msg, rinfo }); });
+      client.on('error', err => { client.close(); reject(err); });
+    }), timeoutMs, `UDP request to ${host}:${port} timed out`);
+  },
+
+  /**
+   * Create a UDP socket that listens for incoming datagrams.
+   * @param {number} port
+   * @param {string} [host='0.0.0.0']
+   * @param {'udp4'|'udp6'} [type='udp4']
+   * @returns {Promise<UdpServer>}
+   */
+  async listen(port, host = '0.0.0.0', type = 'udp4') {
+    const socket  = dgram.createSocket(type);
+    const emitter = new EventEmitter();
+    socket.on('message', (msg, rinfo) => emitter.emit('message', { data: msg, rinfo }));
+    socket.on('error',   err          => emitter.emit('error', err));
+
+    await new Promise((res, rej) => socket.bind(port, host, res).on('error', rej));
+
+    return {
+      port, host,
+      onMessage(fn) { emitter.on('message', fn); return this; },
+      onError(fn)   { emitter.on('error', fn);   return this; },
+      send(data, toHost, toPort) {
+        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        return new Promise((res, rej) => socket.send(buf, toPort, toHost, e => e ? rej(e) : res()));
+      },
+      close() { return new Promise(res => socket.close(res)); },
+      raw: socket,
+    };
+  },
+
+  /**
+   * Join a multicast group.
+   * @param {string} multicastAddr
+   * @param {number} port
+   * @param {string} [iface]
+   * @returns {Promise<UdpServer>}
+   */
+  async multicast(multicastAddr, port, iface) {
+    const server = await udp.listen(port);
+    server.raw.addMembership(multicastAddr, iface);
+    return server;
+  },
+};
+
+// ─── TLS ─────────────────────────────────────────────────────────────────────
+
+const tlsKit = {
+  /**
+   * Open a TLS connection.
+   * @param {string} host
+   * @param {number} port
+   * @param {object} [opts] - Passed to tls.connect (ca, cert, key, rejectUnauthorized, etc.)
+   * @returns {Promise<TlsSocket>}
+   */
+  async connect(host, port, opts = {}) {
+    const d = defer();
+    const socket = tls.connect({ host, port, ...opts }, () => d.resolve(socket));
+    socket.on('error', d.reject);
+    await race(d.promise, opts.timeout ?? 10000, `TLS connect to ${host}:${port} timed out`);
+
+    const emitter = new EventEmitter();
+    socket.setEncoding(opts.encoding ?? 'utf8');
+    socket.on('data',  d => emitter.emit('data', d));
+    socket.on('close', () => emitter.emit('close'));
+    socket.on('error', e => emitter.emit('error', e));
+
+    return {
+      host, port,
+      authorized:  socket.authorized,
+      authError:   socket.authorizationError,
+      certificate: socket.getPeerCertificate(),
+      cipher:      socket.getCipher(),
+      protocol:    socket.getProtocol(),
+      send(data) { return new Promise((res, rej) => socket.write(data, e => e ? rej(e) : res())); },
+      receive(ms = 10000) { return race(new Promise(res => emitter.once('data', res)), ms, 'Receive timed out'); },
+      receiveAll(ms = 30000) {
+        return race(new Promise(res => {
+          const chunks = [];
+          emitter.on('data', d => chunks.push(d));
+          emitter.once('close', () => res(chunks.join('')));
+        }), ms, 'receiveAll timed out');
+      },
+      onData(fn)  { emitter.on('data', fn); return this; },
+      onClose(fn) { emitter.on('close', fn); return this; },
+      onError(fn) { emitter.on('error', fn); return this; },
+      close() { socket.destroy(); },
+      raw: socket,
+    };
+  },
+
+  /**
+   * Create a TLS server.
+   * @param {number} port
+   * @param {object} opts - Must include cert and key (PEM strings or Buffers).
+   * @param {function} handler
+   * @returns {Promise<TlsServer>}
+   */
+  async serve(port, opts, handler) {
+    const server = tls.createServer(opts, socket => {
+      const emitter = new EventEmitter();
+      socket.setEncoding('utf8');
+      socket.on('data',  d => emitter.emit('data', d));
+      socket.on('close', () => emitter.emit('close'));
+      socket.on('error', e => emitter.emit('error', e));
+
+      handler({
+        remoteAddress: socket.remoteAddress,
+        remotePort:    socket.remotePort,
+        authorized:    socket.authorized,
+        certificate:   socket.getPeerCertificate(),
+        send(data) { return new Promise((res, rej) => socket.write(data, e => e ? rej(e) : res())); },
+        receive(ms = 10000) { return race(new Promise(res => emitter.once('data', res)), ms, 'Receive timed out'); },
+        onData(fn)  { emitter.on('data', fn); return this; },
+        onClose(fn) { emitter.on('close', fn); return this; },
+        onError(fn) { emitter.on('error', fn); return this; },
+        close() { socket.destroy(); },
+        raw: socket,
+      });
+    });
+
+    await new Promise((res, rej) => server.listen(port, res).on('error', rej));
+    return {
+      port,
+      close() { return new Promise(res => server.close(res)); },
+      raw: server,
+    };
+  },
+
+  /**
+   * Get TLS certificate info for a host.
+   * @param {string} host
+   * @param {number} [port=443]
+   * @returns {Promise<object>}
+   */
+  async getCert(host, port = 443) {
+    const socket = await tlsKit.connect(host, port, { rejectUnauthorized: false });
+    const cert   = socket.certificate;
+    socket.close();
+    return cert;
+  },
+
+  /**
+   * Check if a host's TLS certificate is valid and not expired.
+   * @param {string} host
+   * @param {number} [port=443]
+   * @returns {Promise<{ valid: boolean, expires: Date, daysLeft: number, issuer: object }>}
+   */
+  async checkCert(host, port = 443) {
+    const cert = await tlsKit.getCert(host, port);
+    const expires  = new Date(cert.valid_to);
+    const now      = new Date();
+    const daysLeft = Math.floor((expires - now) / 86400000);
+    return {
+      valid:    daysLeft > 0 && cert.subject !== undefined,
+      expires,
+      daysLeft,
+      issuer:   cert.issuer,
+      subject:  cert.subject,
+      fingerprint: cert.fingerprint,
+    };
+  },
+};
+
+// ─── WEBSOCKET ────────────────────────────────────────────────────────────────
+// Pure implementation — no external deps.
+
+const ws = {
+  /**
+   * Connect to a WebSocket server.
+   * @param {string} url - ws:// or wss://
+   * @param {object} [opts]
+   * @returns {Promise<WsSocket>}
+   */
+  async connect(url, opts = {}) {
+    const parsed  = new URL(url);
+    const isSecure = parsed.protocol === 'wss:';
+    const port     = parseInt(parsed.port) || (isSecure ? 443 : 80);
+    const host     = parsed.hostname;
+    const path     = parsed.pathname + (parsed.search || '');
+
+    // WebSocket handshake key
+    const key     = Buffer.from(Math.random().toString(36).repeat(3)).toString('base64').slice(0, 24);
+    const headers = [
+      `GET ${path} HTTP/1.1`,
+      `Host: ${host}`,
+      'Upgrade: websocket',
+      'Connection: Upgrade',
+      `Sec-WebSocket-Key: ${key}`,
+      'Sec-WebSocket-Version: 13',
+      ...(opts.headers ? Object.entries(opts.headers).map(([k,v]) => `${k}: ${v}`) : []),
+      '', '',
+    ].join('\r\n');
+
+    const rawSocket = isSecure
+      ? await tlsKit.connect(host, port, { rejectUnauthorized: opts.rejectUnauthorized ?? true })
+      : await tcp.connect(host, port, opts);
+
+    // Send handshake
+    await rawSocket.send(headers);
+
+    // Read handshake response
+    const response = await rawSocket.receive(opts.timeout ?? 5000);
+    if (!response.includes('101')) throw new Error(`WebSocket upgrade failed: ${response.split('\r\n')[0]}`);
+
+    const emitter = new EventEmitter();
+    let buffer    = Buffer.alloc(0);
+
+    // WebSocket frame parser
+    rawSocket.raw.removeAllListeners('data');
+    rawSocket.raw.on('data', chunk => {
+      buffer = Buffer.concat([buffer, chunk]);
+      while (buffer.length >= 2) {
+        const fin    = (buffer[0] & 0x80) !== 0;
+        const opcode = buffer[0] & 0x0f;
+        let payloadLen = buffer[1] & 0x7f;
+        let offset = 2;
+
+        if (payloadLen === 126) { if (buffer.length < 4) break; payloadLen = buffer.readUInt16BE(2); offset = 4; }
+        else if (payloadLen === 127) { if (buffer.length < 10) break; payloadLen = Number(buffer.readBigUInt64BE(2)); offset = 10; }
+
+        if (buffer.length < offset + payloadLen) break;
+
+        const payload = buffer.slice(offset, offset + payloadLen);
+        buffer = buffer.slice(offset + payloadLen);
+
+        if (opcode === 0x1) emitter.emit('message', payload.toString('utf8'));
+        else if (opcode === 0x2) emitter.emit('message', payload);
+        else if (opcode === 0x8) emitter.emit('close');
+        else if (opcode === 0x9) {
+          // ping — send pong
+          const pong = Buffer.from([0x8a, 0x00]);
+          rawSocket.raw.write(pong);
+        }
+      }
+    });
+
+    rawSocket.raw.on('close', () => emitter.emit('close'));
+    rawSocket.raw.on('error', e => emitter.emit('error', e));
+
+    // WebSocket frame encoder (client, so mask=true)
+    function encode(data, opcode = 0x1) {
+      const payload = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+      const len     = payload.length;
+      const mask    = Buffer.from([
+        Math.random() * 256 | 0, Math.random() * 256 | 0,
+        Math.random() * 256 | 0, Math.random() * 256 | 0,
+      ]);
+      const head = len < 126
+        ? Buffer.from([0x80 | opcode, 0x80 | len])
+        : len < 65536
+          ? Buffer.from([0x80 | opcode, 0xfe, len >> 8, len & 0xff])
+          : (() => { const b = Buffer.alloc(10); b[0] = 0x80 | opcode; b[1] = 0xff; b.writeBigUInt64BE(BigInt(len), 2); return b; })();
+      const masked = Buffer.allocUnsafe(len);
+      for (let i = 0; i < len; i++) masked[i] = payload[i] ^ mask[i % 4];
+      return Buffer.concat([head, mask, masked]);
+    }
+
+    return {
+      url,
+      send(data) {
+        const opcode = Buffer.isBuffer(data) ? 0x2 : 0x1;
+        return new Promise((res, rej) => rawSocket.raw.write(encode(data, opcode), e => e ? rej(e) : res()));
+      },
+      sendBinary(data)  { return this.send(Buffer.isBuffer(data) ? data : Buffer.from(data)); },
+      receive(ms = 30000) { return race(new Promise(res => emitter.once('message', res)), ms, 'WS receive timed out'); },
+      onMessage(fn) { emitter.on('message', fn); return this; },
+      onClose(fn)   { emitter.on('close', fn);   return this; },
+      onError(fn)   { emitter.on('error', fn);   return this; },
+      close() {
+        rawSocket.raw.write(Buffer.from([0x88, 0x80, 0, 0, 0, 0]));
+        rawSocket.close();
+      },
+      raw: rawSocket.raw,
+    };
+  },
+
+  /**
+   * Create a WebSocket server (upgrade from HTTP).
+   * @param {number} port
+   * @param {function} handler - Called with each WsSocket.
+   * @param {object} [opts]
+   * @returns {Promise<WsServer>}
+   */
+  async serve(port, handler, opts = {}) {
+    const crypto = require('crypto');
+    const MAGIC  = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+    const server = http.createServer((req, res) => {
+      if (!req.headers['upgrade']) { res.writeHead(426); res.end('Upgrade required'); return; }
+    });
+
+    server.on('upgrade', (req, socket) => {
+      const key    = req.headers['sec-websocket-key'];
+      const accept = crypto.createHash('sha1').update(key + MAGIC).digest('base64');
+
+      socket.write([
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${accept}`,
+        '', '',
+      ].join('\r\n'));
+
+      const emitter = new EventEmitter();
+      let buffer    = Buffer.alloc(0);
+
+      socket.on('data', chunk => {
+        buffer = Buffer.concat([buffer, chunk]);
+        while (buffer.length >= 2) {
+          const opcode = buffer[0] & 0x0f;
+          const masked = (buffer[1] & 0x80) !== 0;
+          let payloadLen = buffer[1] & 0x7f;
+          let offset = 2;
+
+          if (payloadLen === 126) { if (buffer.length < 4) break; payloadLen = buffer.readUInt16BE(2); offset = 4; }
+          else if (payloadLen === 127) { if (buffer.length < 10) break; payloadLen = Number(buffer.readBigUInt64BE(2)); offset = 10; }
+
+          const maskLen = masked ? 4 : 0;
+          if (buffer.length < offset + maskLen + payloadLen) break;
+
+          const maskKey = masked ? buffer.slice(offset, offset + 4) : null;
+          offset += maskLen;
+          const raw = buffer.slice(offset, offset + payloadLen);
+          buffer  = buffer.slice(offset + payloadLen);
+
+          const payload = masked ? Buffer.from(raw.map((b, i) => b ^ maskKey[i % 4])) : raw;
+          if (opcode === 0x1) emitter.emit('message', payload.toString('utf8'));
+          else if (opcode === 0x2) emitter.emit('message', payload);
+          else if (opcode === 0x8) { emitter.emit('close'); socket.destroy(); }
+          else if (opcode === 0x9) socket.write(Buffer.from([0x8a, 0x00]));
+        }
+      });
+
+      socket.on('close', () => emitter.emit('close'));
+      socket.on('error', e => emitter.emit('error', e));
+
+      function encodeServer(data) {
+        const payload = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+        const len     = payload.length;
+        const opcode  = Buffer.isBuffer(data) ? 0x2 : 0x1;
+        if (len < 126) return Buffer.concat([Buffer.from([0x80 | opcode, len]), payload]);
+        if (len < 65536) return Buffer.concat([Buffer.from([0x80 | opcode, 126, len >> 8, len & 0xff]), payload]);
+        const head = Buffer.alloc(10); head[0] = 0x80 | opcode; head[1] = 127; head.writeBigUInt64BE(BigInt(len), 2);
+        return Buffer.concat([head, payload]);
+      }
+
+      handler({
+        remoteAddress: socket.remoteAddress,
+        remotePort:    socket.remotePort,
+        headers:       req.headers,
+        url:           req.url,
+        send(data)     { return new Promise((res, rej) => socket.write(encodeServer(data), e => e ? rej(e) : res())); },
+        sendBinary(data){ return this.send(Buffer.isBuffer(data) ? data : Buffer.from(data)); },
+        receive(ms = 30000) { return race(new Promise(res => emitter.once('message', res)), ms, 'WS receive timed out'); },
+        onMessage(fn)  { emitter.on('message', fn); return this; },
+        onClose(fn)    { emitter.on('close', fn);   return this; },
+        onError(fn)    { emitter.on('error', fn);   return this; },
+        close()        { socket.write(Buffer.from([0x88, 0x00])); socket.destroy(); },
+        raw: socket,
+      });
+    });
+
+    await new Promise((res, rej) => server.listen(port, res).on('error', rej));
+    return {
+      port,
+      close() { return new Promise(res => server.close(res)); },
+      raw: server,
+    };
+  },
+};
+
+// ─── DNS ─────────────────────────────────────────────────────────────────────
+
+const dnsKit = {
+  /** Resolve a hostname to IPv4 addresses. */
+  async resolve4(hostname) { return dnsResolve4(hostname); },
+  /** Resolve a hostname to IPv6 addresses. */
+  async resolve6(hostname) { return dnsResolve6(hostname); },
+  /** Resolve MX records. */
+  async mx(hostname)       { return dnsResolveMx(hostname); },
+  /** Resolve TXT records. */
+  async txt(hostname)      { return dnsResolveTxt(hostname); },
+  /** Resolve SRV records. */
+  async srv(hostname)      { return dnsResolveSrv(hostname); },
+  /** Resolve NS records. */
+  async ns(hostname)       { return dnsResolveNs(hostname); },
+  /** Reverse lookup — IP → hostname. */
+  async reverse(ip)        { return dnsReverse(ip); },
+  /**
+   * Full lookup — returns address + family.
+   * @param {string} hostname
+   * @param {4|6} [family]
+   */
+  async lookup(hostname, family) {
+    return dnsLookup(hostname, family ? { family } : {});
+  },
+  /**
+   * Resolve all record types for a hostname.
+   * @param {string} hostname
+   * @returns {Promise<object>}
+   */
+  async all(hostname) {
+    const results = {};
+    const safe = async (fn) => { try { return await fn(); } catch { return null; } };
+    [results.a, results.aaaa, results.mx, results.txt, results.ns, results.srv] = await Promise.all([
+      safe(() => dnsResolve4(hostname)),
+      safe(() => dnsResolve6(hostname)),
+      safe(() => dnsResolveMx(hostname)),
+      safe(() => dnsResolveTxt(hostname)),
+      safe(() => dnsResolveNs(hostname)),
+      safe(() => dnsResolveSrv(hostname)),
+    ]);
+    return results;
+  },
+  /** Change the DNS servers used for resolution. */
+  setServers(servers) { dns.setServers(servers); },
+  /** Get the currently configured DNS servers. */
+  getServers()        { return dns.getServers(); },
+};
+
+// ─── PING ─────────────────────────────────────────────────────────────────────
+// Uses TCP echo (port 7) or HTTP HEAD as a proxy for ICMP ping.
+// Real ICMP requires raw sockets (root/admin), so we use TCP reachability.
+
+const ping = {
+  /**
+   * Ping a host via TCP connection attempt.
+   * @param {string} host
+   * @param {object} [opts]
+   * @param {number} [opts.port=80]
+   * @param {number} [opts.count=4]
+   * @param {number} [opts.timeout=3000]
+   * @returns {Promise<PingResult>}
+   */
+  async tcp(host, opts = {}) {
+    const port    = opts.port    ?? 80;
+    const count   = opts.count   ?? 4;
+    const timeoutMs = opts.timeout ?? 3000;
+    const results = [];
+
+    for (let i = 0; i < count; i++) {
+      const start = Date.now();
+      const reachable = await tcp.isOpen(host, port, timeoutMs);
+      const rtt = Date.now() - start;
+      results.push({ seq: i + 1, rtt: reachable ? rtt : null, success: reachable });
+    }
+
+    const successful = results.filter(r => r.success);
+    const rtts       = successful.map(r => r.rtt);
+
+    return {
+      host, port,
+      sent:        count,
+      received:    successful.length,
+      lost:        count - successful.length,
+      packetLoss:  `${((count - successful.length) / count * 100).toFixed(1)}%`,
+      rtt: {
+        min: rtts.length ? Math.min(...rtts) : null,
+        max: rtts.length ? Math.max(...rtts) : null,
+        avg: rtts.length ? Math.round(rtts.reduce((a, b) => a + b, 0) / rtts.length) : null,
+      },
+      results,
+    };
+  },
+
+  /**
+   * Ping a host via HTTP HEAD request.
+   * @param {string} url
+   * @param {object} [opts]
+   * @returns {Promise<HttpPingResult>}
+   */
+  async http(url, opts = {}) {
+    const count   = opts.count   ?? 4;
+    const timeoutMs = opts.timeout ?? 5000;
+    const results = [];
+
+    for (let i = 0; i < count; i++) {
+      const start = Date.now();
+      try {
+        await httpKit.head(url, { timeout: timeoutMs });
+        results.push({ seq: i + 1, rtt: Date.now() - start, success: true });
+      } catch {
+        results.push({ seq: i + 1, rtt: null, success: false });
+      }
+    }
+
+    const successful = results.filter(r => r.success);
+    const rtts       = successful.map(r => r.rtt);
+    return {
+      url,
+      sent: count, received: successful.length,
+      lost: count - successful.length,
+      packetLoss: `${((count - successful.length) / count * 100).toFixed(1)}%`,
+      rtt: {
+        min: rtts.length ? Math.min(...rtts) : null,
+        max: rtts.length ? Math.max(...rtts) : null,
+        avg: rtts.length ? Math.round(rtts.reduce((a, b) => a + b, 0) / rtts.length) : null,
+      },
+      results,
+    };
+  },
+};
+
+// ─── PORT SCANNER ─────────────────────────────────────────────────────────────
+
+const portScan = {
+  /**
+   * Scan a single port.
+   * @param {string} host
+   * @param {number} port
+   * @param {number} [timeoutMs=1000]
+   * @returns {Promise<{ port, open, banner }>}
+   */
+  async one(host, port, timeoutMs = 1000) {
+    const open = await tcp.isOpen(host, port, timeoutMs);
+    let banner = null;
+    if (open) {
+      try {
+        const socket = await tcp.connect(host, port, { timeout: timeoutMs });
+        banner = await Promise.race([socket.receive(500), timeout(500).catch(() => null)]).catch(() => null);
+        socket.close();
+      } catch {}
+    }
+    return { port, open, banner };
+  },
+
+  /**
+   * Scan a range of ports.
+   * @param {string} host
+   * @param {number} start
+   * @param {number} end
+   * @param {object} [opts]
+   * @param {number} [opts.concurrency=50]
+   * @param {number} [opts.timeout=1000]
+   * @returns {Promise<ScanResult[]>}
+   */
+  async range(host, start, end, opts = {}) {
+    const concurrency = opts.concurrency ?? 50;
+    const timeoutMs   = opts.timeout     ?? 1000;
+    const ports       = Array.from({ length: end - start + 1 }, (_, i) => start + i);
+    const results     = [];
+
+    for (let i = 0; i < ports.length; i += concurrency) {
+      const batch = ports.slice(i, i + concurrency);
+      const chunk = await Promise.all(batch.map(p => portScan.one(host, p, timeoutMs)));
+      results.push(...chunk);
+    }
+
+    return results;
+  },
+
+  /**
+   * Scan a list of specific ports.
+   * @param {string} host
+   * @param {number[]} ports
+   * @param {object} [opts]
+   * @returns {Promise<ScanResult[]>}
+   */
+  async list(host, ports, opts = {}) {
+    const concurrency = opts.concurrency ?? 50;
+    const timeoutMs   = opts.timeout     ?? 1000;
+    const results     = [];
+
+    for (let i = 0; i < ports.length; i += concurrency) {
+      const batch = ports.slice(i, i + concurrency);
+      const chunk = await Promise.all(batch.map(p => portScan.one(host, p, timeoutMs)));
+      results.push(...chunk);
+    }
+
+    return results;
+  },
+
+  /**
+   * Scan common well-known ports.
+   * @param {string} host
+   * @param {object} [opts]
+   * @returns {Promise<ScanResult[]>}
+   */
+  common(host, opts = {}) {
+    return portScan.list(host, [
+      21, 22, 23, 25, 53, 80, 110, 111, 135, 139, 143, 443, 445,
+      993, 995, 1723, 3306, 3389, 5900, 8080, 8443, 8888,
+    ], opts);
+  },
+};
+
+// ─── HTTP(S) UTILITIES ────────────────────────────────────────────────────────
+
+const httpKit = {
+  /**
+   * Low-level HTTP/HTTPS request.
+   * @param {string} method
+   * @param {string} url
+   * @param {object} [opts]
+   * @returns {Promise<HttpResponse>}
+   */
+  request(method, url, opts = {}) {
+    return new Promise((resolve, reject) => {
+      const parsed  = new URL(url);
+      const isHttps = parsed.protocol === 'https:';
+      const lib     = isHttps ? https : http;
+      const port    = parseInt(parsed.port) || (isHttps ? 443 : 80);
+
+      const reqOpts = {
+        hostname: parsed.hostname,
+        port,
+        path:     parsed.pathname + parsed.search,
+        method:   method.toUpperCase(),
+        headers:  opts.headers ?? {},
+        timeout:  opts.timeout ?? 30000,
+      };
+
+      if (opts.body && !reqOpts.headers['Content-Length']) {
+        const body = typeof opts.body === 'string' ? opts.body : JSON.stringify(opts.body);
+        reqOpts.headers['Content-Length'] = Buffer.byteLength(body);
+        if (!reqOpts.headers['Content-Type']) reqOpts.headers['Content-Type'] = 'application/json';
+      }
+
+      const req = lib.request(reqOpts, res => {
+        const chunks = [];
+        res.on('data', d => chunks.push(d));
+        res.on('end', () => {
+          const raw  = Buffer.concat(chunks);
+          const text = raw.toString('utf8');
+          let json = null;
+          try { json = JSON.parse(text); } catch {}
+          resolve({
+            status:     res.statusCode,
+            statusText: res.statusMessage,
+            headers:    res.headers,
+            text,
+            json,
+            ok:         res.statusCode >= 200 && res.statusCode < 300,
+            raw,
+          });
+        });
+        res.on('error', reject);
+      });
+
+      req.setTimeout(opts.timeout ?? 30000, () => { req.destroy(); reject(new Error('HTTP request timed out')); });
+      req.on('error', reject);
+
+      if (opts.body) {
+        const body = typeof opts.body === 'string' ? opts.body : JSON.stringify(opts.body);
+        req.write(body);
+      }
+      req.end();
+    });
+  },
+
+  get(url, opts = {})          { return httpKit.request('GET', url, opts); },
+  post(url, body, opts = {})   { return httpKit.request('POST', url, { ...opts, body }); },
+  put(url, body, opts = {})    { return httpKit.request('PUT', url, { ...opts, body }); },
+  patch(url, body, opts = {})  { return httpKit.request('PATCH', url, { ...opts, body }); },
+  delete(url, opts = {})       { return httpKit.request('DELETE', url, opts); },
+  head(url, opts = {})         { return httpKit.request('HEAD', url, opts); },
+  options(url, opts = {})      { return httpKit.request('OPTIONS', url, opts); },
+
+  /**
+   * Follow redirects manually and return the redirect chain.
+   * @param {string} url
+   * @param {number} [maxRedirects=10]
+   * @returns {Promise<{ chain: string[], final: string, response: HttpResponse }>}
+   */
+  async traceRedirects(url, maxRedirects = 10) {
+    const chain = [url];
+    let current = url;
+    for (let i = 0; i < maxRedirects; i++) {
+      const res = await httpKit.request('HEAD', current, { timeout: 5000 });
+      if (res.status < 300 || res.status >= 400) break;
+      const next = res.headers['location'];
+      if (!next) break;
+      current = next.startsWith('http') ? next : new URL(next, current).href;
+      chain.push(current);
+    }
+    const response = await httpKit.get(current);
+    return { chain, final: current, response };
+  },
+
+  /**
+   * Download a file from a URL.
+   * @param {string} url
+   * @param {string} destPath
+   * @returns {Promise<{ path, size, elapsed }>}
+   */
+  async download(url, destPath) {
+    const fs_   = require('fs');
+    const start = Date.now();
+    const res   = await httpKit.get(url);
+    fs_.writeFileSync(destPath, res.raw);
+    return { path: destPath, size: res.raw.length, elapsed: Date.now() - start };
+  },
+
+  /**
+   * Measure HTTP response time and return detailed timing.
+   * @param {string} url
+   * @returns {Promise<TimingResult>}
+   */
+  async time(url) {
+    const start    = Date.now();
+    const dnsStart = Date.now();
+    const parsed   = new URL(url);
+    await dnsKit.lookup(parsed.hostname).catch(() => {});
+    const dnsTime  = Date.now() - dnsStart;
+    const tcpStart = Date.now();
+    const res      = await httpKit.get(url);
+    const total    = Date.now() - start;
+    return {
+      url,
+      status:   res.status,
+      dns:      dnsTime,
+      total,
+      ttfb:     total, // approximation without raw socket timing
+      size:     res.raw.length,
+    };
+  },
+};
+
+// ─── NETWORK INTERFACES ───────────────────────────────────────────────────────
+
+const iface = {
+  /**
+   * Get all network interfaces.
+   * @returns {object}
+   */
+  list() { return os.networkInterfaces(); },
+
+  /**
+   * Get all IPv4 addresses on this machine.
+   * @returns {string[]}
+   */
+  ipv4() {
+    return Object.values(os.networkInterfaces())
+      .flat()
+      .filter(i => i.family === 'IPv4' && !i.internal)
+      .map(i => i.address);
+  },
+
+  /**
+   * Get all IPv6 addresses on this machine.
+   * @returns {string[]}
+   */
+  ipv6() {
+    return Object.values(os.networkInterfaces())
+      .flat()
+      .filter(i => i.family === 'IPv6' && !i.internal)
+      .map(i => i.address);
+  },
+
+  /**
+   * Get the primary external IPv4 address.
+   * @returns {string|null}
+   */
+  primaryIp() {
+    return iface.ipv4()[0] ?? null;
+  },
+
+  /**
+   * Get this machine's public IP by querying an external service.
+   * @returns {Promise<string>}
+   */
+  async publicIp() {
+    const res = await httpKit.get('https://api.ipify.org?format=json');
+    return res.json?.ip ?? res.text.trim();
+  },
+
+  /**
+   * Get detailed info about a network interface by name.
+   * @param {string} name
+   * @returns {object|null}
+   */
+  get(name) {
+    return os.networkInterfaces()[name] ?? null;
+  },
+
+  /**
+   * Check if the machine has internet connectivity.
+   * @returns {Promise<boolean>}
+   */
+  async hasInternet() {
+    try { await httpKit.head('https://www.google.com', { timeout: 3000 }); return true; }
+    catch { return false; }
+  },
+
+  /**
+   * Get MAC addresses for all interfaces.
+   * @returns {{ name: string, mac: string }[]}
+   */
+  macs() {
+    return Object.entries(os.networkInterfaces())
+      .flatMap(([name, addrs]) => addrs.map(a => ({ name, mac: a.mac })))
+      .filter(e => e.mac !== '00:00:00:00:00:00');
+  },
+};
+
+// ─── IP UTILITIES ─────────────────────────────────────────────────────────────
+
+const ip = {
+  /**
+   * Check if a string is a valid IPv4 address.
+   * @param {string} addr
+   * @returns {boolean}
+   */
+  isV4(addr) { return /^(\d{1,3}\.){3}\d{1,3}$/.test(addr) && addr.split('.').every(n => +n <= 255); },
+
+  /**
+   * Check if a string is a valid IPv6 address.
+   * @param {string} addr
+   * @returns {boolean}
+   */
+  isV6(addr) { return net.isIPv6(addr); },
+
+  /**
+   * Check if an IP is in a private/local range.
+   * @param {string} addr
+   * @returns {boolean}
+   */
+  isPrivate(addr) {
+    if (!ip.isV4(addr)) return false;
+    const [a, b] = addr.split('.').map(Number);
+    return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+  },
+
+  /**
+   * Check if an IP is a loopback address.
+   * @param {string} addr
+   * @returns {boolean}
+   */
+  isLoopback(addr) { return addr === '127.0.0.1' || addr === '::1' || addr.startsWith('127.'); },
+
+  /**
+   * Convert an IPv4 address to a 32-bit integer.
+   * @param {string} addr
+   * @returns {number}
+   */
+  toInt(addr) { return addr.split('.').reduce((acc, octet) => (acc << 8) + +octet, 0) >>> 0; },
+
+  /**
+   * Convert a 32-bit integer to an IPv4 address.
+   * @param {number} n
+   * @returns {string}
+   */
+  fromInt(n) { return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff].join('.'); },
+
+  /**
+   * Check if an IP is within a CIDR range.
+   * @param {string} addr
+   * @param {string} cidr - e.g. '192.168.1.0/24'
+   * @returns {boolean}
+   */
+  inCidr(addr, cidr) {
+    const [range, bits] = cidr.split('/');
+    const mask = ~((1 << (32 - +bits)) - 1) >>> 0;
+    return (ip.toInt(addr) & mask) === (ip.toInt(range) & mask);
+  },
+
+  /**
+   * Get all addresses in a CIDR range.
+   * @param {string} cidr
+   * @returns {string[]}
+   */
+  cidrHosts(cidr) {
+    const [range, bits] = cidr.split('/');
+    const mask  = ~((1 << (32 - +bits)) - 1) >>> 0;
+    const base  = ip.toInt(range) & mask;
+    const count = (1 << (32 - +bits)) - 2;
+    return Array.from({ length: count }, (_, i) => ip.fromInt(base + 1 + i));
+  },
+
+  /**
+   * Get subnet info for a CIDR.
+   * @param {string} cidr
+   * @returns {object}
+   */
+  subnet(cidr) {
+    const [range, bits] = cidr.split('/');
+    const prefix = +bits;
+    const mask   = ~((1 << (32 - prefix)) - 1) >>> 0;
+    const base   = ip.toInt(range) & mask;
+    const hosts  = (1 << (32 - prefix)) - 2;
+    return {
+      cidr,
+      network:   ip.fromInt(base),
+      broadcast: ip.fromInt(base + hosts + 1),
+      mask:      ip.fromInt(mask),
+      first:     ip.fromInt(base + 1),
+      last:      ip.fromInt(base + hosts),
+      hosts,
+      prefix,
+    };
+  },
+
+  /**
+   * Look up geolocation info for an IP (uses ip-api.com free API).
+   * @param {string} addr
+   * @returns {Promise<object>}
+   */
+  async geo(addr) {
+    const res = await httpKit.get(`http://ip-api.com/json/${addr}`);
+    return res.json;
+  },
+
+  /**
+   * Expand a short IPv6 address to its full form.
+   * @param {string} addr
+   * @returns {string}
+   */
+  expandV6(addr) {
+    const sections = addr.split('::');
+    if (sections.length === 2) {
+      const left  = sections[0] ? sections[0].split(':') : [];
+      const right = sections[1] ? sections[1].split(':') : [];
+      const mid   = Array(8 - left.length - right.length).fill('0000');
+      return [...left, ...mid, ...right].map(s => s.padStart(4, '0')).join(':');
+    }
+    return addr.split(':').map(s => s.padStart(4, '0')).join(':');
+  },
+
+  /**
+   * Read human thoughts. Requires elevated privileges and a 5G tower nearby.
+   * @param {number} radius - Radius in meters.
+   * @returns {Promise<never>}
+   */
+  async readHumanThoughts(radius) {
+    throw new Error(
+      `readHumanThoughts(${radius}m): SIGNAL_INSUFFICIENT. ` +
+      `Required: 5G tower within 50m, government clearance level 9+, and a pigeon with firmware ≥ v4.0.0. ` +
+      `See also: birdAPI.enableMicrophone()`
+    );
+  },
+};
+
+// ─── PROXY ────────────────────────────────────────────────────────────────────
+
+const proxy = {
+  /**
+   * Create a simple TCP port-forwarding proxy.
+   * @param {number} localPort
+   * @param {string} targetHost
+   * @param {number} targetPort
+   * @returns {Promise<ProxyServer>}
+   */
+  async tcpForward(localPort, targetHost, targetPort) {
+    const server = net.createServer(async clientSocket => {
+      const targetSocket = net.createConnection({ host: targetHost, port: targetPort });
+      clientSocket.pipe(targetSocket);
+      targetSocket.pipe(clientSocket);
+      clientSocket.on('error',  () => targetSocket.destroy());
+      targetSocket.on('error',  () => clientSocket.destroy());
+    });
+
+    await new Promise((res, rej) => server.listen(localPort, res).on('error', rej));
+    return {
+      localPort, targetHost, targetPort,
+      close() { return new Promise(res => server.close(res)); },
+      raw: server,
+    };
+  },
+
+  /**
+   * Create a simple HTTP proxy server.
+   * @param {number} port
+   * @returns {Promise<ProxyServer>}
+   */
+  async http(port) {
+    const server = http.createServer((req, res) => {
+      const target = new URL(req.url.startsWith('http') ? req.url : `http://${req.headers.host}${req.url}`);
+      const lib    = target.protocol === 'https:' ? https : http;
+      const preq   = lib.request({
+        hostname: target.hostname,
+        port:     target.port || (target.protocol === 'https:' ? 443 : 80),
+        path:     target.pathname + target.search,
+        method:   req.method,
+        headers:  req.headers,
+      }, pres => {
+        res.writeHead(pres.statusCode, pres.headers);
+        pres.pipe(res);
+      });
+      req.pipe(preq);
+      preq.on('error', () => res.destroy());
+    });
+
+    // Handle CONNECT (tunneling for HTTPS)
+    server.on('connect', (req, clientSocket) => {
+      const [host, port] = req.url.split(':');
+      const serverSocket = net.createConnection(+port || 443, host, () => {
+        clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+        serverSocket.pipe(clientSocket);
+        clientSocket.pipe(serverSocket);
+      });
+      serverSocket.on('error', () => clientSocket.destroy());
+    });
+
+    await new Promise((res, rej) => server.listen(port, res).on('error', rej));
+    return {
+      port,
+      close() { return new Promise(res => server.close(res)); },
+      raw: server,
+    };
+  },
+};
+
+// ─── PACKET / PROTOCOL UTILITIES ─────────────────────────────────────────────
+
+const packet = {
+  /**
+   * Build a raw HTTP/1.1 request string.
+   * @param {string} method
+   * @param {string} url
+   * @param {object} [headers]
+   * @param {string} [body]
+   * @returns {string}
+   */
+  buildHttpRequest(method, url, headers = {}, body = '') {
+    const parsed = new URL(url);
+    const lines  = [
+      `${method.toUpperCase()} ${parsed.pathname}${parsed.search} HTTP/1.1`,
+      `Host: ${parsed.host}`,
+      ...Object.entries(headers).map(([k, v]) => `${k}: ${v}`),
+      body ? `Content-Length: ${Buffer.byteLength(body)}` : '',
+      '',
+      body,
+    ];
+    return lines.filter(l => l !== undefined).join('\r\n');
+  },
+
+  /**
+   * Parse a raw HTTP response string into parts.
+   * @param {string} raw
+   * @returns {{ statusLine, status, headers, body }}
+   */
+  parseHttpResponse(raw) {
+    const [headerSection, ...bodyParts] = raw.split('\r\n\r\n');
+    const headerLines  = headerSection.split('\r\n');
+    const statusLine   = headerLines[0];
+    const statusMatch  = statusLine.match(/HTTP\/\d\.\d (\d+)/);
+    const status       = statusMatch ? +statusMatch[1] : null;
+    const headers      = {};
+    for (const line of headerLines.slice(1)) {
+      const colon = line.indexOf(':');
+      if (colon > -1) headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+    }
+    return { statusLine, status, headers, body: bodyParts.join('\r\n\r\n') };
+  },
+
+  /**
+   * Build a DNS query packet for A record lookup.
+   * @param {string} hostname
+   * @returns {Buffer}
+   */
+  buildDnsQuery(hostname) {
+    const id  = Math.floor(Math.random() * 65535);
+    const buf = Buffer.alloc(512);
+    buf.writeUInt16BE(id, 0);     // ID
+    buf.writeUInt16BE(0x0100, 2); // Flags: standard query, recursion desired
+    buf.writeUInt16BE(1, 4);      // QDCOUNT: 1 question
+    buf.writeUInt16BE(0, 6);      // ANCOUNT
+    buf.writeUInt16BE(0, 8);      // NSCOUNT
+    buf.writeUInt16BE(0, 10);     // ARCOUNT
+    let offset = 12;
+    for (const part of hostname.split('.')) {
+      buf.writeUInt8(part.length, offset++);
+      for (const ch of part) buf.writeUInt8(ch.charCodeAt(0), offset++);
+    }
+    buf.writeUInt8(0, offset++);      // root label
+    buf.writeUInt16BE(1, offset);     // QTYPE: A
+    buf.writeUInt16BE(1, offset + 2); // QCLASS: IN
+    return buf.slice(0, offset + 4);
+  },
+
+  /**
+   * Parse a DNS response packet — returns answer IPs.
+   * @param {Buffer} buf
+   * @returns {string[]}
+   */
+  parseDnsResponse(buf) {
+    const ancount = buf.readUInt16BE(6);
+    const ips     = [];
+    let offset    = 12;
+    // Skip question section
+    while (buf[offset] !== 0) offset += buf[offset] + 1;
+    offset += 5; // null label + QTYPE + QCLASS
+    // Parse answers
+    for (let i = 0; i < ancount; i++) {
+      offset += 2; // name pointer
+      const type  = buf.readUInt16BE(offset); offset += 2;
+      offset += 2; // class
+      offset += 4; // TTL
+      const rdlen = buf.readUInt16BE(offset); offset += 2;
+      if (type === 1 && rdlen === 4) ips.push(`${buf[offset]}.${buf[offset+1]}.${buf[offset+2]}.${buf[offset+3]}`);
+      offset += rdlen;
+    }
+    return ips;
+  },
+
+  /**
+   * Perform a raw DNS lookup over UDP using our own DNS query builder.
+   * @param {string} hostname
+   * @param {string} [server='8.8.8.8']
+   * @returns {Promise<string[]>}
+   */
+  async rawDnsLookup(hostname, server = '8.8.8.8') {
+    const query    = packet.buildDnsQuery(hostname);
+    const response = await udp.request(server, 53, query, { type: 'udp4', timeout: 5000 });
+    return packet.parseDnsResponse(response.data);
+  },
+};
+
+// ─── RATE LIMITER ─────────────────────────────────────────────────────────────
+
+const rateLimit = {
+  /**
+   * Create a rate limiter for outbound requests.
+   * @param {number} requestsPerSecond
+   * @returns {RateLimiter}
+   *
+   * @example
+   *   const limiter = kitnet.rateLimit.create(10); // 10 req/s
+   *   await limiter.wrap(() => httpKit.get('https://api.example.com/data'));
+   */
+  create(requestsPerSecond) {
+    const interval = 1000 / requestsPerSecond;
+    let lastCall   = 0;
+    let queue      = Promise.resolve();
+
+    return {
+      /** Wrap a function call with rate limiting. */
+      wrap(fn) {
+        queue = queue.then(() => {
+          const now  = Date.now();
+          const wait = Math.max(0, lastCall + interval - now);
+          return new Promise(res => setTimeout(res, wait)).then(() => {
+            lastCall = Date.now();
+            return fn();
+          });
+        });
+        return queue;
+      },
+    };
+  },
+};
+
+// ─── BANDWIDTH UTILS ─────────────────────────────────────────────────────────
+
+const bandwidth = {
+  /**
+   * Estimate download speed by downloading a known resource.
+   * @param {string} [url] - Test URL. Defaults to a Cloudflare speed test endpoint.
+   * @returns {Promise<{ mbps: number, elapsed: number, bytes: number }>}
+   */
+  async downloadSpeed(url = 'https://speed.cloudflare.com/__down?bytes=1000000') {
+    const start = Date.now();
+    const res   = await httpKit.get(url);
+    const elapsed = (Date.now() - start) / 1000;
+    const bytes   = res.raw.length;
+    const mbps    = parseFloat(((bytes * 8) / elapsed / 1_000_000).toFixed(2));
+    return { mbps, elapsed, bytes };
+  },
+};
+
+// ─── EXPORTS ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    tcp,
+    udp,
+    tls: tlsKit,
+    ws,
+    dns: dnsKit,
+    ping,
+    portScan,
+    http: httpKit,
+    iface,
+    ip,
+    proxy,
+    packet,
+    rateLimit,
+    bandwidth,
+  }
+};