blue-js-sdk 2.4.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;
@@ -1011,7 +1021,20 @@ export async function connectDirect(opts) {
     if (!forceNewSession) {
       progress(onProgress, logFn, 'session', 'Checking for existing session...');
       checkAborted(signal);
-      sessionId = await findExistingSession(lcd, account.address, opts.nodeAddress);
+      sessionId = await findExistingSession(lcd, account.address, opts.nodeAddress, {
+        // Dedup: if multiple active sessions exist for this node (stale duplicates from
+        // crashes or multi-client wallets), keep the highest-ID one. Silently cancel stale
+        // lower-ID sessions before MsgStartSession — mirrors C# SessionManager dedup pattern.
+        onStaleDuplicate: (staleId) => {
+          logFn?.(`[connect] Cancelling stale duplicate session ${staleId} on ${opts.nodeAddress}...`);
+          // 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}`);
+          });
+        },
+      });
       if (sessionId && isSessionPoisoned(String(sessionId))) {
         progress(onProgress, logFn, 'session', `Session ${sessionId} previously failed — skipping`);
         sessionId = null;
@@ -1142,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)
@@ -1433,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) {
@@ -1441,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) ─
@@ -1460,8 +1515,10 @@ async function connectInternal(opts, paymentStrategy, retryStrategy, state = _de
         { nodeAddress: state.connection?.nodeAddress });
     }
     const prev = state.connection;
-    await disconnectState(state);
-    if (opts.log || defaultLog) (opts.log || defaultLog)(`[connect] Disconnected from ${prev?.nodeAddress || 'previous node'}`);
+    // Hard disconnect: user is actively connecting to a different node,
+    // so the old session should be settled and the deposit refunded.
+    await disconnectStateAndEndSession(state);
+    if (opts.log || defaultLog) (opts.log || defaultLog)(`[connect] Ended session on ${prev?.nodeAddress || 'previous node'} — connecting to new node`);
   }
 
   const onProgress = opts.onProgress || null;
@@ -1478,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)
@@ -1872,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();
     },
   };
@@ -2136,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();
     },
   };
@@ -2171,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' });
@@ -2218,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();
@@ -2227,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;
@@ -2238,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;
@@ -2267,13 +2328,35 @@ function formatUptime(ms) {
 }
 
 // ─── Disconnect ──────────────────────────────────────────────────────────────
+//
+// TWO DISCONNECT PATHS — CHOOSE INTENT EXPLICITLY.
+//
+// Soft: disconnect() / disconnectState(state)
+//   - Tears down the local tunnel (WireGuard/V2Ray) and cleans up system state.
+//   - Leaves the on-chain session in status=1 (active).
+//   - Next connectDirect() to the SAME node reuses the session via
+//     findExistingSession — no new MsgStartSession TX, no new payment, bandwidth preserved.
+//   - Use when: user is pausing, network changed, closing the app temporarily.
+//
+// Hard: disconnectAndEndSession() / disconnectStateAndEndSession(state)
+//   - Tears down the tunnel AND broadcasts MsgCancelSession on chain.
+//   - Session moves status=1 → settling → refund after ~2h settlement window.
+//   - Use when: user is done with this node, switching nodes permanently,
+//     or wants the bandwidth deposit back.
+//
+// Internal: _disconnectInternal(state, { endSession })
+//   - Caller MUST pass endSession explicitly as true or false.
+//   - No default — forces intentional choice at every callsite.
 
 /**
- * Clean up all active tunnels and system proxy.
- * ALWAYS call this on exit — a stale WireGuard tunnel will kill your internet.
+ * Internal disconnect implementation. Caller must explicitly pass endSession.
+ * @param {object} state - ConnectionState instance
+ * @param {{ endSession: boolean }} opts
+ *   endSession: true  → broadcast MsgCancelSession (hard disconnect)
+ *   endSession: false → preserve on-chain session for reuse (soft disconnect)
+ * @private
  */
-/** Disconnect a specific state instance (internal). */
-export async function disconnectState(state) {
+async function _disconnectInternal(state, { endSession }) {
   // v30: Signal any running connectAuto() retry loop to abort, and release the
   // connection lock so the user can reconnect after disconnect completes.
   _abortConnect = true;
@@ -2299,15 +2382,22 @@ export async function disconnectState(state) {
       state.wgTunnel = null;
     }
 
-    // End session on chain (best-effort, fire-and-forget — never blocks disconnect)
-    if (prev?.sessionId && state._mnemonic) {
-      _endSessionOnChain(prev.sessionId, state._mnemonic, state._feeGranter).catch(e => {
-        console.warn(`[sentinel-sdk] Failed to end session ${prev.sessionId} on chain: ${e.message}`);
-      });
+    if (endSession) {
+      // Hard disconnect: broadcast MsgCancelSession — session settles and refunds deposit.
+      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}`);
+        });
+      }
+    } else {
+      // Soft disconnect: leave session on chain in status=1 for reuse.
+      if (prev?.sessionId) {
+        console.log(`[sentinel-sdk] Session ${prev.sessionId} preserved on chain (status=1) for future reuse — no MsgCancelSession broadcast.`);
+      }
     }
   } finally {
     // ALWAYS clear connection state — even if teardown threw
-    state._mnemonic = null;
+    state._wallet = null;
     state._feeGranter = null;
     state.connection = null;
     clearState();
@@ -2317,8 +2407,55 @@ export async function disconnectState(state) {
   }
 }
 
+/**
+ * Soft disconnect — tear down the local tunnel, leave the on-chain session active.
+ *
+ * A subsequent connectDirect() to the SAME node will reuse the session via
+ * findExistingSession — no new MsgStartSession TX, no new payment, remaining
+ * bandwidth is preserved.
+ *
+ * Use when: user is pausing, network changed, or closing the app temporarily.
+ * To settle the session on-chain and reclaim the unused deposit, use
+ * disconnectAndEndSession() instead.
+ *
+ * @param {object} state - ConnectionState instance
+ */
+export async function disconnectState(state) {
+  return _disconnectInternal(state, { endSession: false });
+}
+
+/**
+ * Soft disconnect (default state) — tear down the tunnel, leave on-chain session active.
+ *
+ * @see disconnectState
+ */
 export async function disconnect() {
-  return disconnectState(_defaultState);
+  return _disconnectInternal(_defaultState, { endSession: false });
+}
+
+/**
+ * Hard disconnect — tear down the tunnel AND broadcast MsgCancelSession on chain.
+ *
+ * The session settles after the ~2h inactive_pending window. The node refunds
+ * the unused portion of the bandwidth deposit (for peer-to-peer sessions).
+ * For plan-based sessions, this stops metering against the plan allocation.
+ *
+ * Use when: user is done with this node (switching nodes permanently, ending
+ * their session, or wants the deposit back).
+ *
+ * @param {object} state - ConnectionState instance
+ */
+export async function disconnectStateAndEndSession(state) {
+  return _disconnectInternal(state, { endSession: true });
+}
+
+/**
+ * Hard disconnect (default state) — tear down the tunnel AND broadcast MsgCancelSession.
+ *
+ * @see disconnectStateAndEndSession
+ */
+export async function disconnectAndEndSession() {
+  return _disconnectInternal(_defaultState, { endSession: true });
 }
 
 // ─── Session End (on-chain cleanup) ──────────────────────────────────────────
@@ -2327,11 +2464,14 @@ export async function disconnect() {
  * 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),
@@ -2377,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

@@ -77,8 +77,20 @@ export {
   grantPlanSubscribers,
   renewExpiringGrants,
   monitorFeeGrants,
+  streamGrantPlanSubscribers,
+  computeFeeGrantGasCosts,
 } from './cosmjs-setup.js';
 
+export {
+  batchRevokeFeeGrants,
+} from './operator/batch-revoke.js';
+
+export {
+  queryFeeGrantHistory,
+  decodeFeeGrantEvent,
+  attr,
+} from './operator/feegrant-history.js';
+
 // ─── Authz ──────────────────────────────────────────────────────────────────
 
 export {
@@ -132,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,13 +1,12 @@
 {
   "name": "blue-js-sdk",
-  "version": "2.4.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-ai": "./ai-path/cli.js"
+    "sentinel": "cli/index.js"
   },
   "exports": {
     ".": {
@@ -16,7 +15,6 @@
     },
     "./consumer": "./consumer.js",
     "./operator": "./operator.js",
-    "./ai-path": "./ai-path/index.js",
     "./blue": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -49,7 +47,6 @@
     "errors/",
     "examples/",
     "docs/",
-    "ai-path/",
     "bin/setup.js",
     "dist/",
     "src/",
@@ -66,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": [
@@ -89,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;
+}