blue-js-sdk 2.6.0 → 2.7.0

package/connection/connect.js

@@ -15,7 +15,7 @@ import {
 import {
   createClient, privKeyFromMnemonic, broadcastWithFeeGrant,
   extractId, findExistingSession, getBalance, MSG_TYPES, queryNode,
-  isMnemonicValid, filterNodes,
+  isMnemonicValid, filterNodes, checkFeeGrant,
 } from '../cosmjs-setup.js';
 import { nodeStatusV3, waitForPort } from '../v3protocol.js';
 import {
@@ -40,11 +40,51 @@ import {
 import { performHandshake, validateTunnelRequirements, killV2RayProc, verifyDependencies } from './tunnel.js';
 import { verifyConnection } from './state.js';
 import { registerCleanupHandlers } from './disconnect.js';
+import { withMnemonicRedaction } from './logger.js';
 
-let defaultLog = console.log;
+// Default logger wraps console.log with a mnemonic redactor. Anything that
+// resembles a 12–24 word BIP-39 phrase in a log argument is replaced with
+// `[REDACTED MNEMONIC]` before it reaches 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);
 
 // ─── Shared Validation ───────────────────────────────────────────────────────
 
+/**
+ * Validate a chain endpoint URL. Enforces https:// to prevent attackers from
+ * coercing the SDK into broadcasting signed TXs over cleartext HTTP — a passive
+ * network observer on http://attacker.example/rpc would see the full TX body
+ * and could correlate it to the user's wallet address. Localhost 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') {
@@ -60,8 +100,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) ─
@@ -99,13 +139,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 on state for session-end TX on disconnect (fire-and-forget cleanup)
-  state._mnemonic = opts.mnemonic;
+  // v37 (security): store the derived OfflineSigner — NOT the BIP-39 mnemonic.
+  // _endSessionOnChain only needs to sign one TX on disconnect; it doesn't need
+  // the recovery phrase. Holding the mnemonic in heap for the full session
+  // expanded the heap-dump attack surface unnecessarily.
+  state._wallet = walletResult;
 
   // 2. RPC connect + LCD lookup in parallel (independent network calls)
   // v21: parallelized — saves 1-3s (was sequential)
@@ -381,9 +425,12 @@ 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 BEFORE fast reconnect and stash on state — _endSessionOnChain()
+    // needs the signer, not the mnemonic. Same wallet object is reused by connectInternal()
+    // below if fast reconnect misses (cachedCreateWallet keys on mnemonic SHA256).
+    const fastState = opts._state || _defaultState;
+    fastState._wallet = await cachedCreateWallet(opts.mnemonic);
+    const fast = await tryFastReconnect(opts, fastState);
     if (fast) {
       clearCircuitBreaker(opts.nodeAddress);
       return fast;
@@ -405,7 +452,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).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).catch(e => {
             logFn?.(`[connect] Failed to cancel stale session ${staleId}: ${e.message}`);
           });
         },
@@ -548,7 +598,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)
@@ -701,6 +751,22 @@ export async function connectViaPlan(opts) {
     // Fee grant: the app passes the plan owner's address as feeGranter.
     const feeGranter = opts.feeGranter || null;
 
+    // Opt-in precheck: verify the grant exists and is not expired before the TX.
+    // Builders who prefer fail-fast over silent user-pay fallback set requireFeeGrant.
+    if (feeGranter && opts.requireFeeGrant === true) {
+      const status = await checkFeeGrant(lcdUrl, feeGranter, account.address);
+      if (!status.exists) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_MISSING_AT_START,
+          `Required fee grant missing from ${feeGranter} to ${account.address}`,
+          { granter: feeGranter, grantee: account.address });
+      }
+      if (status.expired) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_EXPIRED,
+          `Required fee grant expired at ${status.expiresAt?.toISOString()}`,
+          { granter: feeGranter, grantee: account.address, expiresAt: status.expiresAt });
+      }
+    }
+
     progress(null, opts.log || defaultLog, 'session', `Subscribing to plan ${opts.planId} + starting session${feeGranter ? ' (fee granted)' : ''}...`);
 
     let result;
@@ -708,8 +774,10 @@ export async function connectViaPlan(opts) {
       try {
         result = await broadcastWithFeeGrant(client, account.address, [msg], feeGranter);
       } catch (feeErr) {
-        // Fee grant TX failed — fall back to user-paid
-        progress(null, opts.log || defaultLog, 'session', 'Fee grant failed, paying gas from wallet...');
+        if (opts.requireFeeGrant === true) throw feeErr;
+        // Fee grant TX failed — fall back to user-paid (default behavior)
+        const reason = feeErr?.message ? `: ${feeErr.message}` : '';
+        progress(null, opts.log || defaultLog, 'session', `Fee grant failed${reason}, paying gas from wallet...`);
         result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
       }
     } else {
@@ -770,7 +838,7 @@ export async function connectViaSubscription(opts) {
   try {
 
   async function subPayment(ctx) {
-    const { client, account, logFn, onProgress, signal } = ctx;
+    const { client, account, lcd: lcdUrl, logFn, onProgress, signal } = ctx;
     const msg = {
       typeUrl: MSG_TYPES.SUB_START_SESSION,
       value: {
@@ -784,6 +852,22 @@ export async function connectViaSubscription(opts) {
 
     // Fee grant: operator pays gas for the agent (e.g., x402 managed plan flow)
     const feeGranter = opts.feeGranter || null;
+
+    // Opt-in precheck: verify the grant exists and is not expired before the TX.
+    if (feeGranter && opts.requireFeeGrant === true) {
+      const status = await checkFeeGrant(lcdUrl, feeGranter, account.address);
+      if (!status.exists) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_MISSING_AT_START,
+          `Required fee grant missing from ${feeGranter} to ${account.address}`,
+          { granter: feeGranter, grantee: account.address });
+      }
+      if (status.expired) {
+        throw new ChainError(ErrorCodes.FEE_GRANT_EXPIRED,
+          `Required fee grant expired at ${status.expiresAt?.toISOString()}`,
+          { granter: feeGranter, grantee: account.address, expiresAt: status.expiresAt });
+      }
+    }
+
     progress(null, opts.log || defaultLog, 'session', `Starting session via subscription ${opts.subscriptionId}${feeGranter ? ' (fee granted)' : ''}...`);
 
     let result;
@@ -791,8 +875,10 @@ export async function connectViaSubscription(opts) {
       try {
         result = await broadcastWithFeeGrant(client, account.address, [msg], feeGranter);
       } catch (feeErr) {
-        // Fee grant TX failed — fall back to user-paid
-        progress(null, opts.log || defaultLog, 'session', 'Fee grant failed, paying gas from wallet...');
+        if (opts.requireFeeGrant === true) throw feeErr;
+        // Fee grant TX failed — fall back to user-paid (default behavior)
+        const reason = feeErr?.message ? `: ${feeErr.message}` : '';
+        progress(null, opts.log || defaultLog, 'session', `Fee grant failed${reason}, paying gas from wallet...`);
         result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
       }
     } else {

package/connection/disconnect.js

@@ -26,6 +26,11 @@ import { DEFAULT_LCD, DEFAULT_TIMEOUTS } from '../defaults.js';
 import { nodeStatusV3 } from '../v3protocol.js';
 import { queryNode, privKeyFromMnemonic } from '../cosmjs-setup.js';
 import { createNodeHttpsAgent } from '../tls-trust.js';
+import { withMnemonicRedaction } from './logger.js';
+
+// Default logger wraps console.log so any 12–24 word BIP-39 phrase that ends
+// up in a log argument is replaced before reaching stdout. See connection/logger.js.
+const defaultLog = withMnemonicRedaction(console.log);
 
 // ─── Disconnect ──────────────────────────────────────────────────────────────
 //
@@ -89,8 +94,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).catch(e => {
+      if (prev?.sessionId && state._wallet) {
+        _endSessionOnChain(prev.sessionId, state._wallet).catch(e => {
           console.warn(`[sentinel-sdk] Failed to end session ${prev.sessionId} on chain: ${e.message}`);
         });
       }
@@ -102,7 +107,7 @@ async function _disconnectInternal(state, { endSession }) {
     }
   } finally {
     // ALWAYS clear connection state — even if teardown threw
-    state._mnemonic = null;
+    state._wallet = null;
     state.connection = null;
     clearState();
     clearWalletCache(); // v34: Clear cached wallet objects (private keys) from memory
@@ -204,7 +209,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/connection/logger.js

@@ -0,0 +1,66 @@
+/**
+ * Redacting logger wrapper — defense-in-depth against accidental mnemonic leaks
+ * in SDK log output.
+ *
+ * The SDK's default logger is `console.log`. Any future bug that interpolates
+ * a mnemonic into a log template string (e.g. `log(`opts: ${JSON.stringify(opts)}`)`)
+ * would leak the BIP-39 phrase to stdout/stderr — and from there to terminal
+ * scrollback, CI logs, log-aggregation tools (Datadog, Loki, Sentry breadcrumbs),
+ * and shell history.
+ *
+ * This module wraps any logger function with a regex-based redactor that matches
+ * BIP-39 word sequences and replaces them with `[REDACTED MNEMONIC]` before the
+ * underlying logger sees them. It is NOT a substitute for the rule "do not log
+ * the mnemonic" — it is a safety net so that violation does not produce a leak.
+ *
+ * Performance: the regex runs only on string arguments and short-circuits if the
+ * argument has fewer than ~60 characters (a 12-word mnemonic is ~80 characters).
+ * Negligible overhead on the SDK's hot path (a few connect-time progress logs).
+ */
+
+/**
+ * Match 12 / 15 / 18 / 21 / 24 lowercase BIP-39-shaped words separated by single
+ * spaces. We deliberately don't try to validate against the full 2048-word list
+ * here — the goal is to catch anything that *looks* like a mnemonic and redact
+ * it. False positives (e.g. a long lowercase sentence) are acceptable since the
+ * SDK's own log strings never contain 12+ consecutive lowercase-only ASCII words.
+ *
+ * BIP-39 words are 3–8 lowercase ASCII letters (a–z), no digits, no diacritics.
+ */
+const MNEMONIC_REGEX = /\b(?:[a-z]{3,8}\s+){11,23}[a-z]{3,8}\b/g;
+
+const REDACTED = '[REDACTED MNEMONIC]';
+
+/**
+ * Redact mnemonic-shaped substrings from a single value. Strings are scanned;
+ * everything else is returned unchanged. We do NOT recurse into objects — the
+ * SDK's loggers are called with scalar args, and walking arbitrary objects
+ * would risk triggering custom getters that have side effects.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function redactValue(value) {
+  if (typeof value !== 'string') return value;
+  if (value.length < 60) return value; // shortest plausible 12-word phrase ~ 60 chars
+  return value.replace(MNEMONIC_REGEX, REDACTED);
+}
+
+/**
+ * Wrap a logger function so that mnemonic-shaped strings in its arguments are
+ * replaced with `[REDACTED MNEMONIC]` before they reach the wrapped logger.
+ * Pass-through for non-function input (returns it unchanged) so callers can
+ * disable logging by passing `null`.
+ *
+ * @param {Function|null|undefined} logFn - underlying logger (typically console.log)
+ * @returns {Function|null|undefined}
+ */
+export function withMnemonicRedaction(logFn) {
+  if (typeof logFn !== 'function') return logFn;
+  return function redactedLog(...args) {
+    return logFn(...args.map(redactValue));
+  };
+}
+
+// Exported for tests.
+export const _internal = { MNEMONIC_REGEX, redactValue };

package/connection/resilience.js

@@ -30,6 +30,11 @@ import { findV2RayExe } from './tunnel.js';
 import { enableKillSwitch, isKillSwitchEnabled as _isKillSwitchEnabled } from './security.js';
 import { setSystemProxy, clearSystemProxy, checkPortFree } from './proxy.js';
 import { connectAuto, connectViaSubscription, connectViaPlan } from './connect.js';
+import { withMnemonicRedaction } from './logger.js';
+
+// Default logger wraps console.log so any 12–24 word BIP-39 phrase that ends
+// up in a log argument is replaced before reaching stdout. See connection/logger.js.
+const defaultLog = withMnemonicRedaction(console.log);
 
 // ─── Circuit Breaker ─────────────────────────────────────────────────────────
 // v22: Skip nodes that repeatedly fail. Resets after TTL expires.
@@ -108,7 +113,7 @@ export async function tryFastReconnect(opts, state = _defaultState) {
   if (!saved) return null;
 
   const onProgress = opts.onProgress || null;
-  const logFn = opts.log || console.log;
+  const logFn = opts.log || defaultLog;
   const fullTunnel = opts.fullTunnel !== false;
   const killSwitch = opts.killSwitch === true;
   const systemProxy = opts.systemProxy === true;
@@ -210,12 +215,12 @@ export async function tryFastReconnect(opts, state = _defaultState) {
           }
           try { await disconnectWireGuard(); } catch {}
           // End session on chain (fire-and-forget)
-          if (saved.sessionId && state._mnemonic) {
-            _endSessionOnChain(saved.sessionId, state._mnemonic).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).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();
         },
       };
@@ -335,11 +340,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).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+          if (sessionIdStr && state._wallet) {
+            _endSessionOnChain(sessionIdStr, state._wallet).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();
         },
       };

package/connection/state.js

@@ -82,7 +82,13 @@ 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 wallet, NOT the raw BIP-39 mnemonic.
+    // Previously _mnemonic held the recovery phrase for the full session lifetime so
+    // that disconnect could sign MsgEndSession. The mnemonic is the highest-value
+    // secret in the SDK — keeping it on a long-lived object enlarged the heap-dump
+    // attack surface unnecessarily. The wallet object holds only the derived signing
+    // key, which is no more sensitive than the privKey buffer we were already keeping.
+    this._wallet = null;     // OfflineSigner — used by _endSessionOnChain on disconnect
     _activeStates.add(this);
   }
   get isConnected() { return !!(this.v2rayProc || this.wgTunnel); }
@@ -216,11 +222,14 @@ export function formatUptime(ms) {
  * 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).
+ *   Accepting the derived signer instead of the raw phrase keeps the BIP-39 mnemonic
+ *   off the long-lived ConnectionState — see ConnectionState._wallet.
  * @private
  */
-export async function _endSessionOnChain(sessionId, mnemonic) {
-  const { wallet, account } = await cachedCreateWallet(mnemonic);
+export async function _endSessionOnChain(sessionId, walletObj) {
+  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),
@@ -261,8 +270,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).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).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' });
@@ -308,8 +317,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).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).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.connection = null;
     clearState();
@@ -317,8 +326,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).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).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.wgTunnel = null;
     _defaultState.connection = null;
@@ -328,8 +337,8 @@ export function getStatus() {
   }
   if (_defaultState.v2rayProc && !healthChecks.tunnelActive) {
     // V2Ray process died — auto-cleanup
-    if (conn?.sessionId && _defaultState._mnemonic) {
-      _endSessionOnChain(conn.sessionId, _defaultState._mnemonic).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).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
     }
     _defaultState.v2rayProc = null;
     _defaultState.connection = null;

package/connection/tunnel.js

@@ -389,12 +389,12 @@ async function setupWireGuard({ remoteUrl, sessionId, privKey, fullTunnel, split
       if (isKillSwitchEnabled()) 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).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+      if (sessionIdStr && state._wallet) {
+        _endSessionOnChain(sessionIdStr, state._wallet).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();
     },
   };
@@ -560,12 +560,28 @@ async function setupV2Ray({ remoteUrl, serverHost, sessionId, privKey, v2rayExeP
           }
         });
       }
-      // Delete config after V2Ray reads it (contains UUID credentials)
-      setTimeout(() => { try { unlinkSync(cfgPath); } catch {} }, 2000);
+      // Delete config after V2Ray reads it (contains UUID credentials).
+      // Race-safe approach: delete the moment we know V2Ray has loaded config
+      // (port is up OR process exited), and a deadline-bound unref'd safety net.
+      // The previous fixed 2s timer raced the loop iterating to the next outbound,
+      // which overwrites cfgPath — the stale timer would then delete the NEW config.
+      let cfgDeleted = false;
+      const deleteCfg = () => {
+        if (cfgDeleted) return;
+        cfgDeleted = true;
+        try { unlinkSync(cfgPath); } catch {} // best-effort: V2Ray may have file open on Windows
+      };
+      proc.once('exit', deleteCfg);
+      const cfgSafetyTimer = setTimeout(deleteCfg, 5000);
+      cfgSafetyTimer.unref();
 
       // Wait for SOCKS5 port to accept connections instead of fixed sleep.
       // V2Ray binding is async — fixed 6s sleep causes false failures on slow starts.
       const ready = await waitForPort(socksPort, timeouts.v2rayReady);
+      // Once the SOCKS port accepts connections, V2Ray has fully parsed the config —
+      // safe to delete (Windows: file is still open by V2Ray, unlink will return EBUSY,
+      // try/catch swallows; falls back to exit-handler or process orphan-cleanup).
+      if (ready) deleteCfg();
       if (!ready || proc.exitCode !== null) {
         progress(onProgress, logFn, 'tunnel', `  ${ob.tag}: v2ray ${proc.exitCode !== null ? `exited (code ${proc.exitCode})` : 'SOCKS5 port not ready'}, skipping`);
         proc.kill();
@@ -653,11 +669,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).then(r => events.emit('sessionEnded', { txHash: r?.transactionHash })).catch(e => events.emit('sessionEndFailed', { error: e.message }));
+      if (sessionIdStr && state._wallet) {
+        _endSessionOnChain(sessionIdStr, state._wallet).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();
     },
   };

package/cosmjs-setup.js

@@ -74,6 +74,8 @@ import {
   getProviderByAddress as _getProviderByAddress,
   queryPlanSubscribers as _queryPlanSubscribers,
   getPlanStats as _getPlanStats,
+  queryPlanDetails as _queryPlanDetails,
+  isActiveStatus as _isActiveStatus,
   querySubscriptionAllocations as _querySubscriptionAllocations,
   queryAuthzGrants as _queryAuthzGrants,
   loadVpnSettings as _loadVpnSettings,
@@ -83,6 +85,7 @@ import {
   queryFeeGrants as _queryFeeGrants,
   queryFeeGrantsIssued as _queryFeeGrantsIssued,
   queryFeeGrant as _queryFeeGrant,
+  checkFeeGrant as _checkFeeGrant,
   grantPlanSubscribers as _grantPlanSubscribers,
   getExpiringGrants as _getExpiringGrants,
   renewExpiringGrants as _renewExpiringGrants,
@@ -812,6 +815,20 @@ export async function queryFeeGrant(lcdUrl, granter, grantee) {
   return _queryFeeGrant(lcdUrl, granter, grantee);
 }
 
+/**
+ * Builder-friendly parsed fee-grant status — exists, expired, expiresAt,
+ * spendLimit, allowedMessages. RPC-first with LCD fallback. Use before
+ * broadcasting plan/subscription session TXs that rely on a fee granter.
+ *
+ * @param {string} lcdUrl
+ * @param {string} granter
+ * @param {string} grantee
+ * @returns {Promise<{ exists: boolean, expired: boolean, expiresAt: Date|null, spendLimit: Array<{denom:string,amount:string}>, allowedMessages: string[]|null, typeUrl: string, raw: object|null }>}
+ */
+export async function checkFeeGrant(lcdUrl, granter, grantee) {
+  return _checkFeeGrant(lcdUrl, granter, grantee);
+}
+
 /**
  * Broadcast a TX with fee paid by a granter (fee grant).
  * The grantee signs; the granter pays gas via their fee allowance.
@@ -953,6 +970,29 @@ export async function getPlanStats(planId, ownerAddress, opts = {}) {
   return _getPlanStats(planId, ownerAddress, opts);
 }
 
+/**
+ * Query a plan's on-chain metadata (provider, prices, duration, status).
+ * RPC-first with LCD fallback. Returns null if the plan does not exist.
+ *
+ * @param {number|string} planId
+ * @param {object} [opts]
+ * @param {string} [opts.lcdUrl]
+ * @returns {Promise<{ planId: string, provider: string, prices: Array, bytes: string, duration: string, status: number, statusAt: string|null, private: boolean } | null>}
+ */
+export async function queryPlanDetails(planId, opts = {}) {
+  return _queryPlanDetails(planId, opts);
+}
+
+/**
+ * Normalize chain status values. Returns true only for active status
+ * (never for transient INACTIVE_PENDING / status=3).
+ * @param {number|string|undefined} v
+ * @returns {boolean}
+ */
+export function isActiveStatus(v) {
+  return _isActiveStatus(v);
+}
+
 // ─── Fee Grant Workflow Helpers (v25b) ────────────────────────────────────────
 
 /**
@@ -1148,6 +1188,8 @@ export async function hasActiveSubscription(address, planId, lcdUrl) {
   return _hasActiveSubscription(address, planId, lcdUrl);
 }
 
+
+
 // ─── v26c: Display Helpers ───────────────────────────────────────────────────
 
 /**