blue-js-sdk 2.0.0

package/protocol/wireguard.js

@@ -0,0 +1,125 @@
+/**
+ * Sentinel WireGuard Config Builder
+ *
+ * Generates WireGuard key pairs and writes .conf files from v3 handshake results.
+ * Handles platform-specific security (Windows NTFS ACLs, Unix file permissions).
+ */
+
+import { randomBytes } from 'crypto';
+import { x25519 } from '@noble/curves/ed25519.js';
+import path from 'path';
+import os from 'os';
+import { mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { SecurityError, ErrorCodes } from '../errors.js';
+
+// ─── WireGuard Key Generation ─────────────────────────────────────────────────
+
+/**
+ * Generate a WireGuard-compatible Curve25519 key pair.
+ * Returns { privateKey: Buffer(32), publicKey: Buffer(32) }
+ */
+export function generateWgKeyPair() {
+  // Generate private key with WireGuard bit clamping
+  const priv = Buffer.from(randomBytes(32));
+  priv[0] &= 248;  // clear bottom 3 bits
+  priv[31] &= 127;  // clear top bit
+  priv[31] |= 64;   // set second-highest bit
+
+  // Derive public key via X25519 (Curve25519 scalar base mult)
+  const pub = Buffer.from(x25519.getPublicKey(priv));
+
+  return { privateKey: priv, publicKey: pub };
+}
+
+// ─── Build & Write WireGuard Config ──────────────────────────────────────────
+
+/**
+ * Write a WireGuard .conf file from v3 handshake result.
+ * @param {Buffer}   wgPrivKey      - Our WireGuard private key (32 bytes)
+ * @param {string[]} assignedAddrs  - Our assigned IPs from node (e.g. ["10.8.0.2/24"])
+ * @param {string}   serverPubKey   - Server WireGuard public key (base64)
+ * @param {string}   serverEndpoint - "IP:PORT" for the WireGuard server
+ * @param {string[]} [splitIPs]     - If provided, only route these IPs through tunnel (split tunneling).
+ *                                    Prevents internet death if tunnel cleanup fails.
+ *                                    Pass null/empty for full tunnel (0.0.0.0/0) — NOT recommended for testing.
+ * @param {object}   [opts]         - Optional config overrides { mtu, dns, keepalive }
+ * @returns {string} Path to the written .conf file
+ */
+export function writeWgConfig(wgPrivKey, assignedAddrs, serverPubKey, serverEndpoint, splitIPs = null, opts = {}) {
+  // Use a SYSTEM-readable path on Windows. The WireGuard service runs as SYSTEM
+  // and often can't read configs from user temp dirs (C:\Users\X\AppData\Local\Temp).
+  // C:\ProgramData is readable by all accounts including SYSTEM.
+  const tmpDir = process.platform === 'win32'
+    ? path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'sentinel-wg')
+    : path.join(os.tmpdir(), 'sentinel-wg');
+  mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+
+  // SECURITY: Restrict directory ACL BEFORE writing the config file.
+  // The file inherits the directory ACL on creation, closing the race window
+  // where the private key would be world-readable between write and ACL set.
+  if (process.platform === 'win32') {
+    const user = process.env.USERNAME || 'BUILTIN\\Users';
+    try {
+      execFileSync('icacls', [tmpDir, '/inheritance:r', '/grant:r', `${user}:F`, '/grant:r', 'SYSTEM:F'], { stdio: 'pipe', timeout: 5000 });
+    } catch (dirAclErr) {
+      throw new SecurityError(ErrorCodes.TLS_CERT_CHANGED, `Failed to secure WireGuard config directory (private key exposure risk): ${dirAclErr.message}`, { tmpDir });
+    }
+  }
+
+  const confPath = path.join(tmpDir, 'wgsent0.conf');
+  const privKeyBase64 = wgPrivKey.toString('base64');
+  const address = assignedAddrs.join(', ');
+
+  // Split tunneling: only route speedtest target IPs through tunnel.
+  // Full tunnel (0.0.0.0/0) captures ALL traffic — if tunnel dies, internet dies.
+  const useSplit = splitIPs && splitIPs.length > 0;
+  const allowedIPsStr = useSplit
+    ? splitIPs.map(ip => ip.includes('/') ? ip : `${ip}/32`).join(', ')
+    : '0.0.0.0/0, ::/0';
+
+  // WireGuard config values — configurable via opts parameter or defaults
+  // MTU 1280 = Sentinel nodes configured for 1280. Using 1420 causes TLS failures. (FAILURES.md T2)
+  // DNS 10.8.0.1 = node's internal resolver (always reachable inside tunnel). (FAILURES.md T3)
+  //   External DNS (Cloudflare, Google) may be unreachable through some nodes.
+  //   Caller can override via opts.dns for specific DNS presets.
+  // PersistentKeepalive 15 = safe for all NAT routers (20-30s timeout windows). (FAILURES.md CF6)
+  const wgMtu = opts?.mtu || 1280;
+  const wgDns = opts?.dns || '10.8.0.1, 1.1.1.1';
+  const wgKeepalive = opts?.keepalive || 15;
+
+  const lines = [
+    '[Interface]',
+    `PrivateKey = ${privKeyBase64}`,
+    `Address = ${address}`,
+    `MTU = ${wgMtu}`,
+  ];
+  // Only set DNS for full tunnel; split tunnel uses system DNS (safer)
+  if (!useSplit) lines.push(`DNS = ${wgDns}`);
+  lines.push(
+    '',
+    '[Peer]',
+    `PublicKey = ${serverPubKey}`,
+    `Endpoint = ${serverEndpoint}`,
+    `AllowedIPs = ${allowedIPsStr}`,
+    `PersistentKeepalive = ${wgKeepalive}`,
+    '',
+  );
+
+  const conf = lines.join('\n');
+
+  writeFileSync(confPath, conf, { encoding: 'utf8', mode: 0o600 }); // restrict: owner-only read/write
+  // On Windows, POSIX mode bits are ignored — file inherits directory ACL set above.
+  // Belt-and-suspenders: also set file-level ACL explicitly.
+  if (process.platform === 'win32') {
+    const user = process.env.USERNAME || 'BUILTIN\\Users';
+    try {
+      execFileSync('icacls', [confPath, '/inheritance:r', '/grant:r', `${user}:F`, '/grant:r', 'SYSTEM:F'], { stdio: 'pipe', timeout: 5000 });
+    } catch (aclErr) {
+      // Don't leave an unprotected private key on disk
+      try { unlinkSync(confPath); } catch { /* cleanup best-effort */ }
+      throw new SecurityError(ErrorCodes.TLS_CERT_CHANGED, `Failed to secure WireGuard config (private key exposure risk): ${aclErr.message}`, { confPath });
+    }
+  }
+  return confPath;
+}

package/security/index.js

@@ -0,0 +1,132 @@
+/**
+ * TLS Trust-On-First-Use (TOFU) for Sentinel Nodes
+ *
+ * Sentinel nodes use self-signed certificates (no CA issues certs for ephemeral IP servers).
+ * TOFU model: save cert fingerprint on first connect, reject if it changes later.
+ * Same concept as SSH known_hosts.
+ *
+ * Usage:
+ *   import { createNodeHttpsAgent } from './tls-trust.js';
+ *   const agent = createNodeHttpsAgent('sentnode1abc...', 'tofu');
+ *   const res = await axios.post(url, body, { httpsAgent: agent });
+ */
+
+import https from 'https';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { SecurityError, ErrorCodes } from '../errors/index.js';
+
+const KNOWN_NODES_DIR = path.join(os.homedir(), '.sentinel-sdk');
+const KNOWN_NODES_PATH = path.join(KNOWN_NODES_DIR, 'known_nodes.json');
+
+// In-memory cache to avoid file I/O on every request
+let knownNodesCache = null;
+
+function loadKnownNodes() {
+  if (knownNodesCache) return knownNodesCache;
+  try {
+    knownNodesCache = JSON.parse(readFileSync(KNOWN_NODES_PATH, 'utf8'));
+  } catch {
+    knownNodesCache = {};
+  }
+  return knownNodesCache;
+}
+
+function saveKnownNodes(nodes) {
+  knownNodesCache = nodes;
+  try {
+    if (!existsSync(KNOWN_NODES_DIR)) mkdirSync(KNOWN_NODES_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(KNOWN_NODES_PATH, JSON.stringify(nodes, null, 2), { mode: 0o600 });
+  } catch (e) {
+    console.warn('[sentinel-sdk] Failed to save known_nodes.json:', e.message);
+  }
+}
+
+/**
+ * Create an HTTPS agent with TOFU certificate pinning for a specific node.
+ *
+ * Modes:
+ * - 'tofu' (default): Pin cert on first connection, reject if it changes
+ * - 'none': Accept any cert (current behavior, for testing only)
+ *
+ * @param {string} nodeAddress - sentnode1... address (used as lookup key)
+ * @param {'tofu'|'none'} mode - Trust mode
+ * @returns {https.Agent}
+ */
+export function createNodeHttpsAgent(nodeAddress, mode = 'tofu') {
+  if (mode === 'none') {
+    return new https.Agent({ rejectUnauthorized: false });
+  }
+
+  const known = loadKnownNodes();
+
+  return new https.Agent({
+    rejectUnauthorized: false,
+    checkServerIdentity: (_hostname, cert) => {
+      const fingerprint = cert.fingerprint256;
+      if (!fingerprint) return new Error('Certificate missing fingerprint — possible MITM or malformed cert');
+
+      const saved = known[nodeAddress];
+
+      if (saved && saved.fingerprint !== fingerprint) {
+        throw new SecurityError(
+          ErrorCodes.TLS_CERT_CHANGED,
+          `TLS certificate CHANGED for ${nodeAddress}. ` +
+          `Expected: ${saved.fingerprint.substring(0, 20)}... ` +
+          `Got: ${fingerprint.substring(0, 20)}... ` +
+          `This could indicate a man-in-the-middle attack. ` +
+          `If the node legitimately rotated its certificate, call clearKnownNode('${nodeAddress}') or delete ~/.sentinel-sdk/known_nodes.json`,
+          { nodeAddress, expected: saved.fingerprint, got: fingerprint, firstSeen: saved.firstSeen },
+        );
+      }
+
+      if (!saved) {
+        known[nodeAddress] = {
+          fingerprint,
+          firstSeen: new Date().toISOString(),
+          lastSeen: new Date().toISOString(),
+        };
+        saveKnownNodes(known);
+      } else {
+        saved.lastSeen = new Date().toISOString();
+        saveKnownNodes(known);
+      }
+    },
+  });
+}
+
+/**
+ * Clear a specific node's stored certificate fingerprint.
+ * Call after a node legitimately rotates its TLS cert.
+ */
+export function clearKnownNode(nodeAddress) {
+  const known = loadKnownNodes();
+  delete known[nodeAddress];
+  saveKnownNodes(known);
+}
+
+/**
+ * Clear all stored node certificate fingerprints.
+ */
+export function clearAllKnownNodes() {
+  saveKnownNodes({});
+}
+
+/**
+ * Get stored certificate info for a node (null if not known).
+ */
+export function getKnownNode(nodeAddress) {
+  const known = loadKnownNodes();
+  return known[nodeAddress] || null;
+}
+
+/**
+ * Secure agent for LCD/RPC public endpoints (CA-validated).
+ * These endpoints have valid CA-signed certificates — no reason to skip verification.
+ * TOFU is only for node-direct connections (self-signed certs).
+ */
+export const publicEndpointAgent = new https.Agent({ rejectUnauthorized: true });
+
+/** @deprecated Use publicEndpointAgent. Kept for backward compatibility. */
+export const insecureAgent = publicEndpointAgent;

package/session-manager.js

@@ -0,0 +1,329 @@
+/**
+ * Sentinel dVPN SDK — Session Manager
+ *
+ * Reusable session management class ported from the Node Tester's battle-tested
+ * implementation. Provides:
+ *   - Paginated session map (all active sessions for a wallet)
+ *   - Session reuse (find existing session for a node)
+ *   - Credential cache (disk-persistent WG keys / V2Ray UUIDs)
+ *   - Session poisoning (track failed handshakes)
+ *   - Duplicate payment guard (prevent double-paying in a run)
+ *
+ * Usage:
+ *   import { SessionManager } from './session-manager.js';
+ *   const mgr = new SessionManager('https://lcd.sentinel.co', 'sent1...');
+ *   await mgr.buildSessionMap();
+ *   const sid = await mgr.findExistingSession('sentnode1...');
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { ChainError, ErrorCodes } from './errors.js';
+import { DEFAULT_LCD } from './defaults.js';
+import { lcdPaginatedSafe } from './cosmjs-setup.js';
+import { loadPoisonedKeys, savePoisonedKeys } from './state.js';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const STATE_DIR = path.join(os.homedir(), '.sentinel-sdk');
+const CRED_FILE = path.join(STATE_DIR, 'session-credentials.json');
+
+/** Default session map TTL: 5 minutes */
+const DEFAULT_MAP_TTL = 5 * 60 * 1000;
+
+// ─── SessionManager Class ────────────────────────────────────────────────────
+
+/**
+ * Manages session state for a wallet: session map, credential cache,
+ * poisoning, and duplicate payment tracking.
+ *
+ * @example
+ * const mgr = new SessionManager('https://lcd.sentinel.co', 'sent1abc...');
+ * await mgr.buildSessionMap();
+ * const sid = await mgr.findExistingSession('sentnode1xyz...');
+ * if (sid) console.log(`Reuse session ${sid}`);
+ */
+export class SessionManager {
+  /**
+   * @param {string} lcdUrl - LCD endpoint URL (falls back to DEFAULT_LCD)
+   * @param {string} walletAddress - Wallet address (sent1...)
+   * @param {object} [options]
+   * @param {number} [options.mapTtl=300000] - Session map cache TTL in ms (default 5 min)
+   * @param {string} [options.credentialPath] - Custom path for credential cache file
+   * @param {Function} [options.logger] - Optional logger function (msg) => void
+   */
+  constructor(lcdUrl, walletAddress, options = {}) {
+    this._lcdUrl = lcdUrl || DEFAULT_LCD;
+    this._walletAddress = walletAddress;
+    this._mapTtl = options.mapTtl ?? DEFAULT_MAP_TTL;
+    this._credPath = options.credentialPath || CRED_FILE;
+    this._logger = options.logger || null;
+
+    /** @type {Map<string, {sessionId: bigint, maxBytes: number, usedBytes: number}>|null} */
+    this._sessionMap = null;
+    this._sessionMapAt = 0;
+
+    /** @type {Set<string>} Poisoned session keys: "nodeAddr:sessionId" */
+    this._poisoned = new Set(loadPoisonedKeys());
+
+    /** @type {Set<string>} Nodes paid this run */
+    this._paidNodes = new Set();
+
+    /** @type {object|null} In-memory credential cache (lazy-loaded from disk) */
+    this._credentials = null;
+  }
+
+  // ─── Session Map ─────────────────────────────────────────────────────────
+
+  /**
+   * Fetch ALL active sessions for the wallet with full pagination.
+   * Builds a Map<nodeAddr, {sessionId, maxBytes, usedBytes}> for O(1) lookups.
+   * Skips exhausted sessions (used >= max), wrong-wallet sessions, and poisoned sessions.
+   *
+   * @param {string} [walletAddress] - Override wallet address (default: constructor value)
+   * @returns {Promise<Map<string, {sessionId: bigint, maxBytes: number, usedBytes: number}>>}
+   */
+  async buildSessionMap(walletAddress) {
+    const addr = walletAddress || this._walletAddress;
+    if (!addr) {
+      throw new ChainError(
+        ErrorCodes.INVALID_OPTIONS,
+        'buildSessionMap requires a wallet address',
+      );
+    }
+
+    const map = new Map();
+    const queryPath = `/sentinel/session/v3/sessions?address=${addr}&status=1`;
+
+    let items;
+    try {
+      const result = await lcdPaginatedSafe(this._lcdUrl, queryPath, 'sessions');
+      items = result.items || [];
+    } catch (err) {
+      throw new ChainError(
+        ErrorCodes.LCD_ERROR,
+        `Failed to build session map: ${err.message}`,
+        { walletAddress: addr, original: err.message },
+      );
+    }
+
+    for (const s of items) {
+      const bs = s.base_session || s;
+      const nodeAddr = bs.node_address || bs.node;
+      if (!nodeAddr) continue;
+
+      const acct = bs.acc_address || bs.address;
+      if (acct && acct !== addr) continue;
+      if (bs.status && bs.status !== 'active') continue;
+
+      const maxBytes = parseInt(bs.max_bytes || '0');
+      const used = parseInt(bs.download_bytes || '0') + parseInt(bs.upload_bytes || '0');
+      if (maxBytes > 0 && used >= maxBytes) continue;
+
+      const sid = BigInt(bs.id);
+      if (this.isPoisoned(nodeAddr, String(sid))) continue;
+
+      // Keep the session with the most remaining bandwidth per node
+      const existing = map.get(nodeAddr);
+      if (!existing || (maxBytes - used) > (existing.maxBytes - existing.usedBytes)) {
+        map.set(nodeAddr, { sessionId: sid, maxBytes, usedBytes: used });
+      }
+    }
+
+    this._sessionMap = map;
+    this._sessionMapAt = Date.now();
+    this._log(`Session map: ${map.size} reusable sessions (${items.length} fetched)`);
+    return map;
+  }
+
+  /**
+   * Find an existing reusable session for a node.
+   * Auto-refreshes the session map if stale or missing.
+   *
+   * @param {string} nodeAddr - Node address (sentnode1...)
+   * @returns {Promise<bigint|null>} Session ID or null
+   */
+  async findExistingSession(nodeAddr) {
+    try {
+      const now = Date.now();
+      if (!this._sessionMap || now - this._sessionMapAt > this._mapTtl) {
+        await this.buildSessionMap();
+      }
+      const entry = this._sessionMap?.get(nodeAddr);
+      return entry ? entry.sessionId : null;
+    } catch (err) {
+      if (err?.name !== 'AbortError' && !/timeout|ECONNREFUSED|ENOTFOUND/i.test(err?.message || '')) {
+        this._log(`findExistingSession error: ${err.message}`);
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Invalidate the session map cache, forcing a full refetch on next access.
+   */
+  invalidateSessionMap() {
+    this._sessionMap = null;
+    this._sessionMapAt = 0;
+  }
+
+  /**
+   * Manually add a session to the map (e.g. after batch payment creates new sessions).
+   *
+   * @param {string} nodeAddr - Node address
+   * @param {bigint} sessionId - Session ID
+   * @param {number} [maxBytes=1000000000] - Max bytes (default 1 GB)
+   */
+  addToSessionMap(nodeAddr, sessionId, maxBytes = 1_000_000_000) {
+    if (!this._sessionMap) this._sessionMap = new Map();
+    this._sessionMap.set(nodeAddr, { sessionId, maxBytes, usedBytes: 0 });
+  }
+
+  /**
+   * Get the current session map (may be null if never built).
+   *
+   * @returns {Map<string, {sessionId: bigint, maxBytes: number, usedBytes: number}>|null}
+   */
+  getSessionMap() {
+    return this._sessionMap;
+  }
+
+  // ─── Credential Cache (disk-persistent) ──────────────────────────────────
+
+  /**
+   * Save handshake credentials for a node (WG keys, V2Ray UUID, etc.).
+   * Persists to disk at ~/.sentinel-sdk/session-credentials.json.
+   *
+   * @param {string} nodeAddr - Node address (sentnode1...)
+   * @param {object} data - Credential data to save
+   */
+  saveCredential(nodeAddr, data) {
+    this._loadCredentials();
+    this._credentials[nodeAddr] = { ...data, savedAt: new Date().toISOString() };
+    this._writeCredentials();
+  }
+
+  /**
+   * Get cached credentials for a node.
+   *
+   * @param {string} nodeAddr - Node address
+   * @returns {object|null} Credential data or null
+   */
+  getCredential(nodeAddr) {
+    this._loadCredentials();
+    return this._credentials[nodeAddr] || null;
+  }
+
+  /**
+   * Clear cached credentials for a node.
+   *
+   * @param {string} nodeAddr - Node address
+   */
+  clearCredential(nodeAddr) {
+    this._loadCredentials();
+    delete this._credentials[nodeAddr];
+    this._writeCredentials();
+  }
+
+  /**
+   * Clear all cached credentials.
+   */
+  clearAllCredentials() {
+    this._credentials = {};
+    this._writeCredentials();
+  }
+
+  /** @private Load credential store from disk (lazy, once). */
+  _loadCredentials() {
+    if (this._credentials !== null) return;
+    try {
+      if (existsSync(this._credPath)) {
+        this._credentials = JSON.parse(readFileSync(this._credPath, 'utf8'));
+      } else {
+        this._credentials = {};
+      }
+    } catch {
+      this._credentials = {};
+    }
+  }
+
+  /** @private Write credential store to disk with atomic rename. */
+  _writeCredentials() {
+    try {
+      mkdirSync(path.dirname(this._credPath), { recursive: true, mode: 0o700 });
+      const tmp = this._credPath + '.tmp';
+      writeFileSync(tmp, JSON.stringify(this._credentials, null, 2), { encoding: 'utf8', mode: 0o600 });
+      renameSync(tmp, this._credPath);
+    } catch (err) {
+      this._log(`Failed to write credentials: ${err.message}`);
+    }
+  }
+
+  // ─── Session Poisoning ───────────────────────────────────────────────────
+
+  /**
+   * Mark a session as poisoned (failed handshake — should not be reused).
+   *
+   * @param {string} nodeAddr - Node address
+   * @param {string|bigint} sessionId - Session ID
+   */
+  markPoisoned(nodeAddr, sessionId) {
+    this._poisoned.add(`${nodeAddr}:${sessionId}`);
+    savePoisonedKeys([...this._poisoned]);
+  }
+
+  /**
+   * Check if a session is poisoned.
+   *
+   * @param {string} nodeAddr - Node address
+   * @param {string|bigint} sessionId - Session ID
+   * @returns {boolean}
+   */
+  isPoisoned(nodeAddr, sessionId) {
+    return this._poisoned.has(`${nodeAddr}:${sessionId}`);
+  }
+
+  /**
+   * Clear all poisoned session markers.
+   */
+  clearPoisonedSessions() {
+    this._poisoned.clear();
+    savePoisonedKeys([]);
+  }
+
+  // ─── Duplicate Payment Guard ─────────────────────────────────────────────
+
+  /**
+   * Mark a node as paid in this run (prevents double-paying).
+   *
+   * @param {string} nodeAddr - Node address
+   */
+  markPaid(nodeAddr) {
+    this._paidNodes.add(nodeAddr);
+  }
+
+  /**
+   * Check if a node has been paid in this run.
+   *
+   * @param {string} nodeAddr - Node address
+   * @returns {boolean}
+   */
+  isPaid(nodeAddr) {
+    return this._paidNodes.has(nodeAddr);
+  }
+
+  /**
+   * Clear all paid node markers (e.g. at start of a new scan run).
+   */
+  clearPaidNodes() {
+    this._paidNodes.clear();
+  }
+
+  // ─── Internals ───────────────────────────────────────────────────────────
+
+  /** @private Log a message if a logger is configured. */
+  _log(msg) {
+    if (this._logger) this._logger(msg);
+  }
+}

package/session-tracker.js

@@ -0,0 +1,80 @@
+/**
+ * Sentinel SDK — Session Payment Mode Tracker
+ *
+ * The chain doesn't distinguish GB-based from hourly sessions.
+ * This persists the payment mode per session ID so apps can
+ * show the correct pricing model after restart.
+ *
+ * Usage:
+ *   import { trackSession, getSessionMode, getAllTrackedSessions } from './session-tracker.js';
+ *   trackSession('37546368', 'gb');      // after connectDirect with gigabytes
+ *   trackSession('37546652', 'hour');    // after connectDirect with hours
+ *   trackSession('37547890', 'plan');    // after connectViaPlan
+ *   getSessionMode('37546368');          // → 'gb'
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+const SESSION_DIR = path.join(os.homedir(), '.sentinel-sdk');
+const SESSION_FILE = path.join(SESSION_DIR, 'session-modes.json');
+
+let _modes = null; // lazy load
+
+function _load() {
+  if (_modes) return _modes;
+  try {
+    if (existsSync(SESSION_FILE)) {
+      _modes = JSON.parse(readFileSync(SESSION_FILE, 'utf8'));
+    }
+  } catch { /* corrupt file — start fresh */ }
+  _modes = _modes || {};
+  return _modes;
+}
+
+function _save() {
+  try {
+    if (!existsSync(SESSION_DIR)) mkdirSync(SESSION_DIR, { recursive: true });
+    writeFileSync(SESSION_FILE, JSON.stringify(_modes, null, 2));
+  } catch { /* non-fatal */ }
+}
+
+/**
+ * Track payment mode for a session.
+ * @param {string|number|bigint} sessionId
+ * @param {'gb'|'hour'|'plan'} mode
+ */
+export function trackSession(sessionId, mode) {
+  _load();
+  _modes[String(sessionId)] = mode;
+  _save();
+}
+
+/**
+ * Get payment mode for a session.
+ * @param {string|number|bigint} sessionId
+ * @returns {'gb'|'hour'|'plan'} Defaults to 'gb' for unknown sessions
+ */
+export function getSessionMode(sessionId) {
+  _load();
+  return _modes[String(sessionId)] || 'gb';
+}
+
+/**
+ * Get all tracked sessions.
+ * @returns {Record<string, 'gb'|'hour'|'plan'>}
+ */
+export function getAllTrackedSessions() {
+  return { ..._load() };
+}
+
+/**
+ * Clear tracking for a session.
+ * @param {string|number|bigint} sessionId
+ */
+export function clearSessionMode(sessionId) {
+  _load();
+  delete _modes[String(sessionId)];
+  _save();
+}