blue-js-sdk 2.6.0 → 2.7.0

package/node-connect.js

@@ -62,6 +62,7 @@ import {
   SentinelError, ValidationError, NodeError, ChainError, TunnelError, ErrorCodes,
 } from './errors.js';
 import { createNodeHttpsAgent, publicEndpointAgent } from './tls-trust.js';
+import { withMnemonicRedaction } from './connection/logger.js';
 
 // CA-validated agent for LCD/RPC public endpoints (valid CA certs)
 const httpsAgent = publicEndpointAgent;
@@ -116,7 +117,9 @@ export class ConnectionState {
     this.systemProxy = false;
     this.connection = null;  // { nodeAddress, serviceType, sessionId, connectedAt, socksPort? }
     this.savedProxyState = null;
-    this._mnemonic = null;   // Stored for session-end TX on disconnect (zeroed after use)
+    // v37 (security): store the derived OfflineSigner — NOT the BIP-39 mnemonic.
+    // See connection/state.js for the rationale (heap-dump attack surface).
+    this._wallet = null;     // OfflineSigner — used by _endSessionOnChain on disconnect
     this._feeGranter = null; // Stored for fee-granted session end on disconnect (0-P2P agents)
     _activeStates.add(this);
   }
@@ -128,8 +131,13 @@ export class ConnectionState {
 const _activeStates = new Set();
 const _defaultState = new ConnectionState();
 
-// Default logger — can be overridden per-call via opts.log
-let defaultLog = console.log;
+// Default logger — can be overridden per-call via opts.log.
+// Wrapped with mnemonic redaction so any 12–24 word BIP-39 phrase that ends up
+// in a log argument is replaced with `[REDACTED MNEMONIC]` before reaching
+// stdout. Defense-in-depth — the SDK does not currently log the mnemonic, but
+// a future template-string bug or careless `JSON.stringify(opts)` won't leak
+// it through the default logger.
+let defaultLog = withMnemonicRedaction(console.log);
 
 // ─── Wallet Cache ────────────────────────────────────────────────────────────
 // v21: Cache wallet derivation (BIP39 → SLIP-10 is CPU-bound, ~300ms).
@@ -798,12 +806,12 @@ export async function tryFastReconnect(opts, state = _defaultState) {
           if (_killSwitchEnabled) disableKillSwitch();
           try { await disconnectWireGuard(); } catch {}
           // End session on chain (fire-and-forget)
-          if (saved.sessionId && state._mnemonic) {
-            _endSessionOnChain(saved.sessionId, state._mnemonic, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+          if (saved.sessionId && state._wallet) {
+            _endSessionOnChain(saved.sessionId, state._wallet, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
           }
           state.wgTunnel = null;
           state.connection = null;
-          state._mnemonic = null;
+          state._wallet = null;
           clearState();
         },
       };
@@ -923,11 +931,11 @@ export async function tryFastReconnect(opts, state = _defaultState) {
           if (state.v2rayProc) { state.v2rayProc.kill(); state.v2rayProc = null; await sleep(500); }
           if (state.systemProxy) clearSystemProxy(state);
           // End session on chain (fire-and-forget)
-          if (sessionIdStr && state._mnemonic) {
-            _endSessionOnChain(sessionIdStr, state._mnemonic, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+          if (sessionIdStr && state._wallet) {
+            _endSessionOnChain(sessionIdStr, state._wallet, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
           }
           state.connection = null;
-          state._mnemonic = null;
+          state._wallet = null;
           clearState();
         },
       };
@@ -993,9 +1001,11 @@ export async function connectDirect(opts) {
 
   // ── Fast Reconnect: check for saved credentials ──
   if (!forceNewSession) {
-    // Set mnemonic on state BEFORE fast reconnect — needed for _endSessionOnChain() on disconnect
-    (opts._state || _defaultState)._mnemonic = opts.mnemonic;
-    const fast = await tryFastReconnect(opts, opts._state || _defaultState);
+    // v37: Derive wallet up front so _endSessionOnChain() has a signer if fast reconnect succeeds.
+    // cachedCreateWallet is keyed on mnemonic SHA256 — connectInternal() below reuses the same object.
+    const fastState = opts._state || _defaultState;
+    fastState._wallet = await cachedCreateWallet(opts.mnemonic);
+    const fast = await tryFastReconnect(opts, fastState);
     if (fast) {
       _circuitBreaker.delete(opts.nodeAddress);
       return fast;
@@ -1017,7 +1027,10 @@ export async function connectDirect(opts) {
         // lower-ID sessions before MsgStartSession — mirrors C# SessionManager dedup pattern.
         onStaleDuplicate: (staleId) => {
           logFn?.(`[connect] Cancelling stale duplicate session ${staleId} on ${opts.nodeAddress}...`);
-          _endSessionOnChain(staleId, opts.mnemonic, opts.feeGranter || null).catch(e => {
+          // v37: pass the derived wallet (set on state above) instead of the mnemonic
+          const w = (opts._state || _defaultState)._wallet;
+          if (!w) { logFn?.(`[connect] No wallet on state — skipping stale session ${staleId} cleanup`); return; }
+          _endSessionOnChain(staleId, w, opts.feeGranter || null).catch(e => {
             logFn?.(`[connect] Failed to cancel stale session ${staleId}: ${e.message}`);
           });
         },
@@ -1152,7 +1165,7 @@ export async function connectAuto(opts) {
   if (opts.circuitBreaker) configureCircuitBreaker(opts.circuitBreaker);
 
   const maxAttempts = opts.maxAttempts || 3;
-  const logFn = opts.log || console.log;
+  const logFn = opts.log || defaultLog;
   const errors = [];
 
   // If nodeAddress specified, try it first (skip circuit breaker check for explicit choice)
@@ -1443,6 +1456,38 @@ export async function connectViaSubscription(opts) {
 
 // ─── Shared Validation ───────────────────────────────────────────────────────
 
+/**
+ * Validate a chain endpoint URL. Enforces https:// for non-localhost endpoints
+ * to prevent attackers from coercing the SDK into broadcasting signed TXs over
+ * cleartext HTTP. Localhost (loopback) is exempted for local-node development.
+ *
+ * @param {*} url - Value to validate (allowed: undefined/null, or string)
+ * @param {string} fieldName - 'rpcUrl' or 'lcdUrl', used in error messages
+ */
+function validateChainUrl(url, fieldName) {
+  if (url == null) return;
+  if (typeof url !== 'string') {
+    throw new ValidationError(ErrorCodes.INVALID_URL, `${fieldName} must be a string URL`, { value: url });
+  }
+  let parsed;
+  try { parsed = new URL(url); }
+  catch { throw new ValidationError(ErrorCodes.INVALID_URL, `${fieldName} is not a valid URL`, { value: url }); }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new ValidationError(ErrorCodes.INVALID_URL, `${fieldName} must use http:// or https:// (got ${parsed.protocol})`, { value: url });
+  }
+  const isLocalhost = parsed.hostname === 'localhost'
+    || parsed.hostname === '127.0.0.1'
+    || parsed.hostname === '::1'
+    || parsed.hostname === '[::1]';
+  if (parsed.protocol === 'http:' && !isLocalhost) {
+    throw new ValidationError(
+      ErrorCodes.INVALID_URL,
+      `${fieldName} must use https:// for non-localhost endpoints. Cleartext HTTP leaks signed TXs and queries to network observers (got ${url}).`,
+      { value: url },
+    );
+  }
+}
+
 function validateConnectOpts(opts, fnName) {
   if (!opts || typeof opts !== 'object') throw new ValidationError(ErrorCodes.INVALID_OPTIONS, `${fnName}() requires an options object`);
   if (typeof opts.mnemonic !== 'string' || opts.mnemonic.trim().split(/\s+/).length < 12) {
@@ -1451,8 +1496,8 @@ function validateConnectOpts(opts, fnName) {
   if (typeof opts.nodeAddress !== 'string' || !/^sentnode1[a-z0-9]{38}$/.test(opts.nodeAddress)) {
     throw new ValidationError(ErrorCodes.INVALID_NODE_ADDRESS, 'nodeAddress must be a valid sentnode1... bech32 address (47 characters)', { value: opts.nodeAddress });
   }
-  if (opts.rpcUrl != null && typeof opts.rpcUrl !== 'string') throw new ValidationError(ErrorCodes.INVALID_URL, 'rpcUrl must be a string URL', { value: opts.rpcUrl });
-  if (opts.lcdUrl != null && typeof opts.lcdUrl !== 'string') throw new ValidationError(ErrorCodes.INVALID_URL, 'lcdUrl must be a string URL', { value: opts.lcdUrl });
+  validateChainUrl(opts.rpcUrl, 'rpcUrl');
+  validateChainUrl(opts.lcdUrl, 'lcdUrl');
 }
 
 // ─── Shared Connect Flow (eliminates connectDirect/connectViaPlan duplication) ─
@@ -1490,13 +1535,17 @@ async function connectInternal(opts, paymentStrategy, retryStrategy, state = _de
   // v21: parallelized — saves ~300ms (was sequential)
   progress(onProgress, logFn, 'wallet', 'Setting up wallet...');
   checkAborted(signal);
-  const [{ wallet, account }, privKey] = await Promise.all([
+  const [walletResult, privKey] = await Promise.all([
     cachedCreateWallet(opts.mnemonic),
     privKeyFromMnemonic(opts.mnemonic),
   ]);
+  const { wallet, account } = walletResult;
 
-  // Store mnemonic + feeGranter on state for session-end TX on disconnect (fire-and-forget cleanup)
-  state._mnemonic = opts.mnemonic;
+  // v37 (security): store the derived OfflineSigner — NOT the raw BIP-39 phrase.
+  // _endSessionOnChain only signs one TX on disconnect; it doesn't need the recovery
+  // phrase, and keeping the phrase in heap for the full session expanded the
+  // heap-dump attack surface unnecessarily.
+  state._wallet = walletResult;
   state._feeGranter = opts.feeGranter || null;
 
   // 2. RPC connect + LCD lookup in parallel (independent network calls)
@@ -1884,12 +1933,12 @@ async function setupWireGuard({ remoteUrl, sessionId, privKey, fullTunnel, split
       if (_killSwitchEnabled) disableKillSwitch();
       try { await disconnectWireGuard(); } catch {} // tunnel may already be down
       // End session on chain (fire-and-forget)
-      if (sessionIdStr && state._mnemonic) {
-        _endSessionOnChain(sessionIdStr, state._mnemonic, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+      if (sessionIdStr && state._wallet) {
+        _endSessionOnChain(sessionIdStr, state._wallet, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
       }
       state.wgTunnel = null;
       state.connection = null;
-      state._mnemonic = null;
+      state._wallet = null;
       clearState();
     },
   };
@@ -2148,11 +2197,11 @@ async function setupV2Ray({ remoteUrl, serverHost, sessionId, privKey, v2rayExeP
       if (state.v2rayProc) { state.v2rayProc.kill(); state.v2rayProc = null; await sleep(500); }
       if (state.systemProxy) clearSystemProxy();
       // End session on chain (fire-and-forget)
-      if (sessionIdStr && state._mnemonic) {
-        _endSessionOnChain(sessionIdStr, state._mnemonic, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+      if (sessionIdStr && state._wallet) {
+        _endSessionOnChain(sessionIdStr, state._wallet, state._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
       }
       state.connection = null;
-      state._mnemonic = null;
+      state._wallet = null;
       clearState();
     },
   };
@@ -2183,8 +2232,8 @@ export function getStatus() {
     const stale = _defaultState.connection;
     _defaultState.connection = null;
     // End session on chain (fire-and-forget) to prevent stale session leaks
-    if (stale?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(stale.sessionId, _defaultState._mnemonic, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (stale?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(stale.sessionId, _defaultState._wallet, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     clearState();
     events.emit('disconnected', { nodeAddress: stale.nodeAddress, serviceType: stale.serviceType, reason: 'phantom_state' });
@@ -2230,8 +2279,8 @@ export function getStatus() {
   // clean up stale state. Prevents ghost "connected" status after tunnel dies.
   if (!healthChecks.tunnelActive && !_defaultState.v2rayProc && !_defaultState.wgTunnel) {
     // Both tunnel handles are null — connection state is stale
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (conn?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(conn.sessionId, _defaultState._wallet, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.connection = null;
     clearState();
@@ -2239,8 +2288,8 @@ export function getStatus() {
   }
   if (_defaultState.wgTunnel && !healthChecks.tunnelActive) {
     // WireGuard state says connected but tunnel is dead — auto-cleanup
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (conn?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(conn.sessionId, _defaultState._wallet, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.wgTunnel = null;
     _defaultState.connection = null;
@@ -2250,8 +2299,8 @@ export function getStatus() {
   }
   if (_defaultState.v2rayProc && !healthChecks.tunnelActive) {
     // V2Ray process died — auto-cleanup
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+    if (conn?.sessionId && _defaultState._wallet) {
+      _endSessionOnChain(conn.sessionId, _defaultState._wallet, _defaultState._feeGranter).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.v2rayProc = null;
     _defaultState.connection = null;
@@ -2335,8 +2384,8 @@ async function _disconnectInternal(state, { endSession }) {
 
     if (endSession) {
       // Hard disconnect: broadcast MsgCancelSession — session settles and refunds deposit.
-      if (prev?.sessionId && state._mnemonic) {
-        _endSessionOnChain(prev.sessionId, state._mnemonic, state._feeGranter).catch(e => {
+      if (prev?.sessionId && state._wallet) {
+        _endSessionOnChain(prev.sessionId, state._wallet, state._feeGranter).catch(e => {
           console.warn(`[sentinel-sdk] Failed to end session ${prev.sessionId} on chain: ${e.message}`);
         });
       }
@@ -2348,7 +2397,7 @@ async function _disconnectInternal(state, { endSession }) {
     }
   } finally {
     // ALWAYS clear connection state — even if teardown threw
-    state._mnemonic = null;
+    state._wallet = null;
     state._feeGranter = null;
     state.connection = null;
     clearState();
@@ -2415,11 +2464,14 @@ export async function disconnectAndEndSession() {
  * End a session on-chain. Best-effort, fire-and-forget.
  * Prevents stale session accumulation on nodes.
  * @param {string|bigint} sessionId - Session ID to end
- * @param {string} mnemonic - BIP39 mnemonic for signing the TX
+ * @param {object} walletObj - { wallet, account } from cachedCreateWallet (NOT the mnemonic).
+ *   v37 (security): the BIP-39 phrase is no longer kept on ConnectionState.
+ * @param {string} [feeGranter] - Optional fee grant payer for 0-P2P agents
  * @private
  */
-async function _endSessionOnChain(sessionId, mnemonic, feeGranter = null) {
-  const { wallet, account } = await cachedCreateWallet(mnemonic);
+async function _endSessionOnChain(sessionId, walletObj, feeGranter = null) {
+  if (!walletObj) throw new SentinelError(ErrorCodes.INVALID_OPTIONS, '_endSessionOnChain requires a wallet object');
+  const { wallet, account } = walletObj;
   const client = await tryWithFallback(
     RPC_ENDPOINTS,
     async (url) => createClient(url, wallet),
@@ -2465,7 +2517,7 @@ export async function recoverSession(opts) {
   if (!opts?.nodeAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'recoverSession requires opts.nodeAddress');
   if (!opts?.mnemonic) throw new ValidationError(ErrorCodes.INVALID_MNEMONIC, 'recoverSession requires opts.mnemonic');
 
-  const logFn = opts.log || console.log;
+  const logFn = opts.log || defaultLog;
   const onProgress = opts.onProgress || null;
   const sessionId = BigInt(opts.sessionId);
   const timeouts = { ...DEFAULT_TIMEOUTS, ...opts.timeouts };

package/operator.js

@@ -81,6 +81,16 @@ export {
   computeFeeGrantGasCosts,
 } from './cosmjs-setup.js';
 
+export {
+  batchRevokeFeeGrants,
+} from './operator/batch-revoke.js';
+
+export {
+  queryFeeGrantHistory,
+  decodeFeeGrantEvent,
+  attr,
+} from './operator/feegrant-history.js';
+
 // ─── Authz ──────────────────────────────────────────────────────────────────
 
 export {
@@ -134,3 +144,17 @@ export {
   encodeMsgUpdateSubscription,
   encodeMsgUpdateSession,
 } from './v3protocol.js';
+
+// ─── Lease Batch Utilities ───────────────────────────────────────────────────
+
+export {
+  autoLeaseNode,
+  batchLeaseNodes,
+} from './operator/auto-lease.js';
+// ─── Plan Ownership Pre-Flight ──────────────────────────────────────────────
+
+export {
+  assertPlanOwnership,
+  PlanOwnershipError,
+  walletToProviderAddr,
+} from './operator/plan-ownership.js';

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "blue-js-sdk",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Decentralized VPN SDK for the Sentinel P2P bandwidth network. WireGuard + V2Ray tunnels, Cosmos blockchain, 900+ nodes. Tested on Windows. macOS/Linux support included but untested.",
   "type": "module",
   "main": "index.js",
   "types": "types/index.d.ts",
   "bin": {
-    "sentinel": "./cli/index.js"
+    "sentinel": "cli/index.js"
   },
   "exports": {
     ".": {
@@ -63,6 +63,9 @@
     "proto:generate": "npx protoc --ts_proto_out=generated --ts_proto_opt=esModuleInterop=true --ts_proto_opt=env=node --ts_proto_opt=outputTypeRegistry=true --proto_path=proto proto/sentinel/types/v1/*.proto proto/sentinel/node/v3/*.proto proto/sentinel/session/v3/*.proto proto/sentinel/plan/v3/*.proto proto/sentinel/subscription/v3/*.proto proto/sentinel/lease/v1/*.proto proto/sentinel/provider/v2/*.proto",
     "test": "node test/smoke.js",
     "test:exports": "node -e \"import('./index.js').then(m => console.log(Object.keys(m).length + ' exports OK'))\"",
+    "test:privy": "node test/privy-cosmos-signer.test.mjs && node test/privy-client-integration.test.mjs",
+    "test:privy:live": "node test/privy-live-chain.test.mjs",
+    "test:privy:server": "node test/privy-real-server.test.mjs",
     "postinstall": "node bin/setup.js || true"
   },
   "keywords": [
@@ -86,18 +89,18 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Sentinel-Autonomybuilder/sentinel-dvpn-sdk.git"
+    "url": "git+https://github.com/Sentinel-Autonomybuilder/sentinel-dvpn-sdk.git"
   },
   "bugs": {
     "url": "https://github.com/Sentinel-Autonomybuilder/sentinel-dvpn-sdk/issues"
   },
   "homepage": "https://github.com/Sentinel-Autonomybuilder/sentinel-dvpn-sdk#readme",
   "dependencies": {
-    "@cosmjs/amino": "0.32.2",
-    "@cosmjs/crypto": "0.32.2",
-    "@cosmjs/encoding": "0.32.2",
-    "@cosmjs/proto-signing": "0.32.2",
-    "@cosmjs/stargate": "0.32.2",
+    "@cosmjs/amino": "0.32.4",
+    "@cosmjs/crypto": "0.32.4",
+    "@cosmjs/encoding": "0.32.4",
+    "@cosmjs/proto-signing": "0.32.4",
+    "@cosmjs/stargate": "0.32.4",
     "@noble/curves": "^1.4.0",
     "axios": "^1.7.0",
     "dotenv": "^16.4.0",

package/session-manager.js

@@ -329,3 +329,71 @@ export class SessionManager {
     if (this._logger) this._logger(msg);
   }
 }
+
+// ─── Multi-message tx session extraction ─────────────────────────────────────
+
+/**
+ * Extract session IDs keyed by node_address from a multi-message transaction.
+ *
+ * Background: a single tx can carry up to N MsgStartSession messages. The chain
+ * emits a `session_id` per session, but on most chain heights the events do NOT
+ * include `node_address` alongside the `session_id`. Confirmed empirically
+ * 2026-03-23. Naively pairing events to messages by index causes address
+ * mismatch, so any session_id without a colocated node_address is reported as
+ * an "orphan" — the caller MUST resolve it to a node by querying the chain.
+ *
+ * Returns a Map with two non-enumerable hint fields attached:
+ *   - `_orphanIds`        Array<bigint>  session IDs needing chain lookup
+ *   - `_needsChainLookup` boolean        true if any expected node is unmapped
+ *
+ * @param {{ events?: Array }} txResult - Tx broadcast result (RPC or LCD shape)
+ * @param {string[]} [nodeAddrs] - Expected node addresses (used to compute
+ *   `_needsChainLookup`). If omitted, the flag is true whenever orphans exist.
+ * @returns {Map<string, bigint> & { _orphanIds: bigint[], _needsChainLookup: boolean }}
+ *
+ * @example
+ *   const map = extractSessionMap(txResult, batch.map(b => b.node.address));
+ *   if (map._needsChainLookup) {
+ *     for (const sid of map._orphanIds) {
+ *       const session = await querySessionById(client, sid);
+ *       map.set(session.nodeAddress, sid);
+ *     }
+ *   }
+ */
+export function extractSessionMap(txResult, nodeAddrs) {
+  const map = new Map();
+  const orphanIds = [];
+
+  for (const event of (txResult?.events || [])) {
+    if (!/session/i.test(event.type)) continue;
+    let sessionId = null;
+    let nodeAddr = null;
+    for (const attr of (event.attributes || [])) {
+      const k = typeof attr.key === 'string'
+        ? attr.key
+        : Buffer.from(attr.key, 'base64').toString('utf8');
+      const rawV = typeof attr.value === 'string'
+        ? attr.value
+        : Buffer.from(attr.value, 'base64').toString('utf8');
+      const clean = rawV.replace(/"/g, '');
+      if (k === 'session_id' || k === 'id') {
+        try {
+          const id = BigInt(clean);
+          if (id > 0n) sessionId = id;
+        } catch { /* not a numeric id; skip */ }
+      }
+      if (k === 'node_address') nodeAddr = clean;
+    }
+    if (sessionId && nodeAddr) {
+      map.set(nodeAddr, sessionId);
+    } else if (sessionId) {
+      orphanIds.push(sessionId);
+    }
+  }
+
+  // Chain events NEVER include node_address on most heights. Caller resolves.
+  map._orphanIds = orphanIds;
+  map._needsChainLookup = orphanIds.length > 0
+    && map.size < (nodeAddrs?.length || Number.POSITIVE_INFINITY);
+  return map;
+}

package/speedtest.js

@@ -565,3 +565,142 @@ export function compareSpeedTests(before, after) {
   };
 }
 
+// ─── Post-Tunnel Google Accessibility Checks ────────────────────────────────
+//
+// Some nodes route Cloudflare fine but block Google (region-specific egress
+// filtering). Speedtest passing != general internet works. These helpers do
+// a cheap, latency-only HTTPS hit against `google.com` after the tunnel is
+// up — useful as a fast pre-flight before a full speedtest, or as a separate
+// "general internet works" signal in audit results.
+//
+// Two flavors:
+//   - checkGoogleDirect:    for tunnels where all traffic is tunneled (WireGuard)
+//   - checkGoogleViaSocks5: for tunnels where traffic goes via local SOCKS5 (V2Ray)
+//
+// Direct check uses an external resolver (8.8.8.8 / 1.1.1.1) to resolve
+// `www.google.com` BEFORE the tunnel may have working DNS, then issues HTTPS
+// to the IP with `Host: www.google.com` + SNI. Works on tunnels that don't
+// route DNS or that point to dead resolvers.
+
+const GOOGLE_HOST = 'www.google.com';
+const GOOGLE_DNS_CACHE_TTL = 5 * 60_000;
+let cachedGoogleIp = null;
+let cachedGoogleTime = 0;
+
+/**
+ * Resolve `www.google.com` to an A record using public resolvers, with
+ * fallback to the system resolver and finally `dns.lookup`. Result is cached
+ * for {@link GOOGLE_DNS_CACHE_TTL} ms across calls in the same process.
+ *
+ * @returns {Promise<string|null>} IPv4 address or null if every resolver failed
+ */
+export async function resolveGoogleIp() {
+  if (cachedGoogleIp && Date.now() - cachedGoogleTime < GOOGLE_DNS_CACHE_TTL) return cachedGoogleIp;
+  try {
+    const resolver = new dns.Resolver();
+    resolver.setServers(['8.8.8.8', '1.1.1.1']);
+    const addrs = await new Promise((resolve, reject) => {
+      resolver.resolve4(GOOGLE_HOST, (err, addresses) => err ? reject(err) : resolve(addresses));
+    });
+    if (addrs.length > 0) { cachedGoogleIp = addrs[0]; cachedGoogleTime = Date.now(); return cachedGoogleIp; }
+  } catch { }
+  try {
+    const addrs = await dns.promises.resolve4(GOOGLE_HOST);
+    if (addrs.length > 0) { cachedGoogleIp = addrs[0]; cachedGoogleTime = Date.now(); return cachedGoogleIp; }
+  } catch { }
+  try {
+    const { address } = await dns.promises.lookup(GOOGLE_HOST);
+    cachedGoogleIp = address;
+    cachedGoogleTime = Date.now();
+    return cachedGoogleIp;
+  } catch { }
+  return null;
+}
+
+/**
+ * Check if `google.com` is reachable through the ambient network path
+ * (typically a WireGuard tunnel where all traffic is tunneled). Tries the
+ * resolved IP first (with `Host` header + SNI), then falls back to the
+ * hostname directly. Any successful TLS handshake counts as reachable.
+ *
+ * @param {number} [timeoutMs=10000]
+ * @returns {Promise<{ googleAccessible: boolean, googleLatencyMs: number|null, googleError: string|null }>}
+ */
+export async function checkGoogleDirect(timeoutMs = 10_000) {
+  const start = Date.now();
+  const targetIp = await resolveGoogleIp();
+  const targets = [];
+  if (targetIp) targets.push(`https://${targetIp}/`);
+  targets.push(`https://${GOOGLE_HOST}/`);
+
+  for (const url of targets) {
+    try {
+      await new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const options = {
+          hostname: parsed.hostname,
+          path: '/',
+          method: 'GET',
+          rejectUnauthorized: false,
+          agent: false,
+          headers: { Host: GOOGLE_HOST },
+          servername: GOOGLE_HOST,
+        };
+        const req = https.get(options, (res) => {
+          res.destroy();
+          resolve();
+        });
+        req.on('error', reject);
+        req.setTimeout(timeoutMs, () => { req.destroy(); reject(new Error('timeout')); });
+      });
+      return {
+        googleAccessible: true,
+        googleLatencyMs: Date.now() - start,
+        googleError: null,
+      };
+    } catch { }
+  }
+
+  return {
+    googleAccessible: false,
+    googleLatencyMs: null,
+    googleError: 'Google unreachable through tunnel',
+  };
+}
+
+/**
+ * Check if `google.com` is reachable through a V2Ray SOCKS5 proxy on
+ * localhost. Required because native Node `fetch` silently ignores SOCKS
+ * proxy agents — must use axios + SocksProxyAgent.
+ *
+ * @param {number} proxyPort - Local V2Ray SOCKS5 port (e.g. 1080)
+ * @param {number} [timeoutMs=10000]
+ * @returns {Promise<{ googleAccessible: boolean, googleLatencyMs: number|null, googleError: string|null }>}
+ */
+export async function checkGoogleViaSocks5(proxyPort, timeoutMs = 10_000) {
+  const start = Date.now();
+  const agent = new SocksProxyAgent(`socks5://127.0.0.1:${proxyPort}`);
+  try {
+    await axios.get(`https://${GOOGLE_HOST}/`, {
+      timeout: timeoutMs,
+      httpAgent: agent,
+      httpsAgent: agent,
+      maxRedirects: 2,
+      validateStatus: () => true,
+    });
+    return {
+      googleAccessible: true,
+      googleLatencyMs: Date.now() - start,
+      googleError: null,
+    };
+  } catch (err) {
+    return {
+      googleAccessible: false,
+      googleLatencyMs: null,
+      googleError: err.message || 'Google unreachable through SOCKS5',
+    };
+  } finally {
+    agent.destroy();
+  }
+}
+

package/test-all-logic.js

@@ -29,12 +29,14 @@ t('formatUptime 0', sdk.formatUptime(0) === '0s');
 
 // ═══ ADDRESS CONVERSION (6) ═══
 console.log('═══ ADDRESS CONVERSION ═══');
-t('shortAddress truncates', sdk.shortAddress('sent1example9pqrse8q4m6lz8alxqv5hkx3fkxe0q').includes('...'));
+// Valid sent1 address derived from BIP39 test mnemonic ("abandon abandon...about")
+const ADDR = 'sent19rl4cm2hmr8afy4kldpxz3fka4jguq0a8mmym6';
+t('shortAddress truncates', sdk.shortAddress(ADDR).includes('...'));
 t('shortAddress short passthrough', sdk.shortAddress('sent1abc') === 'sent1abc');
-t('sentToSentprov', sdk.sentToSentprov('sent1example9pqrse8q4m6lz8alxqv5hkx3fkxe0q').startsWith('sentprov'));
-t('sentToSentnode', sdk.sentToSentnode('sent1example9pqrse8q4m6lz8alxqv5hkx3fkxe0q').startsWith('sentnode'));
-t('sentprovToSent', sdk.sentprovToSent(sdk.sentToSentprov('sent1example9pqrse8q4m6lz8alxqv5hkx3fkxe0q')).startsWith('sent1'));
-t('isSameKey cross-prefix', sdk.isSameKey('sent1example9pqrse8q4m6lz8alxqv5hkx3fkxe0q', sdk.sentToSentprov('sent1example9pqrse8q4m6lz8alxqv5hkx3fkxe0q')));
+t('sentToSentprov', sdk.sentToSentprov(ADDR).startsWith('sentprov'));
+t('sentToSentnode', sdk.sentToSentnode(ADDR).startsWith('sentnode'));
+t('sentprovToSent', sdk.sentprovToSent(sdk.sentToSentprov(ADDR)).startsWith('sent1'));
+t('isSameKey cross-prefix', sdk.isSameKey(ADDR, sdk.sentToSentprov(ADDR)));
 
 // ═══ VALIDATION (7) ═══
 console.log('═══ VALIDATION ═══');
@@ -78,7 +80,7 @@ t('no duplicate DNS', new Set(sdk.resolveDnsServers().split(', ')).size === sdk.
 
 // ═══ ERROR SYSTEM (20) ═══
 console.log('═══ ERROR SYSTEM ═══');
-t('33 error codes', Object.values(sdk.ErrorCodes).length === 33);
+t('42 error codes', Object.values(sdk.ErrorCodes).length === 42);
 t('all have messages', Object.values(sdk.ErrorCodes).every(c => sdk.userMessage(c) !== 'An unexpected error occurred.'));
 t('unknown default', sdk.userMessage('FAKE') === 'An unexpected error occurred.');
 t('INSUFFICIENT fatal', sdk.ERROR_SEVERITY[sdk.ErrorCodes.INSUFFICIENT_BALANCE] === 'fatal');