nansen-cli 1.46.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +108 -0
- package/README.md +129 -14
- package/docs/browser-login.md +117 -0
- package/package.json +11 -2
- package/scripts/postinstall.js +35 -30
- package/skills/nansen-agent-guide/SKILL.md +13 -2
- package/skills/nansen-alerts-webhook-listener/SKILL.md +5 -2
- package/skills/nansen-dca-tracker/SKILL.md +10 -2
- package/skills/nansen-defi-positions/SKILL.md +5 -2
- package/skills/nansen-exit-signals/SKILL.md +10 -2
- package/skills/nansen-fund-tracker/SKILL.md +10 -2
- package/skills/nansen-general-search/SKILL.md +10 -2
- package/skills/nansen-holder-analysis/SKILL.md +10 -2
- package/skills/nansen-limit-orders/SKILL.md +6 -3
- package/skills/nansen-perp-screener/SKILL.md +10 -2
- package/skills/nansen-perp-trader-profile/SKILL.md +10 -2
- package/skills/nansen-polymarket-deep-dive/SKILL.md +10 -2
- package/skills/nansen-polymarket-insider-scan/SKILL.md +10 -2
- package/skills/nansen-polymarket-trader-profile/SKILL.md +10 -2
- package/skills/nansen-portfolio-tracker/SKILL.md +10 -2
- package/skills/nansen-prediction-markets/SKILL.md +10 -2
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +10 -2
- package/skills/nansen-smart-alerts/SKILL.md +9 -4
- package/skills/nansen-smart-money-alpha/SKILL.md +10 -2
- package/skills/nansen-smart-money-tracker/SKILL.md +10 -2
- package/skills/nansen-smart-money-trend/SKILL.md +10 -2
- package/skills/nansen-token-research/SKILL.md +10 -2
- package/skills/nansen-token-screener/SKILL.md +14 -4
- package/skills/nansen-token-transfer-analysis/SKILL.md +10 -2
- package/skills/nansen-trading/SKILL.md +8 -2
- package/skills/nansen-wallet-batch/SKILL.md +10 -2
- package/skills/nansen-wallet-clustering/SKILL.md +10 -2
- package/skills/nansen-wallet-deep-dive/SKILL.md +10 -2
- package/skills/nansen-wallet-keychain-migration/SKILL.md +5 -2
- package/skills/nansen-wallet-manager/SKILL.md +11 -9
- package/skills/nansen-wallet-profiler/SKILL.md +10 -2
- package/skills/nansen-web-fetcher/SKILL.md +5 -2
- package/skills/nansen-web-searcher/SKILL.md +5 -2
- package/src/api.js +202 -104
- package/src/auth-browser.js +16 -0
- package/src/auth-credentials.js +73 -0
- package/src/auth-device.js +242 -0
- package/src/auth-key-input.js +46 -0
- package/src/auth-login.js +90 -0
- package/src/auth-state.js +487 -0
- package/src/auth-store-native.js +20 -0
- package/src/auth-store-worker.js +64 -0
- package/src/auth-store.js +140 -0
- package/src/auto-paginate.js +272 -0
- package/src/bridge.js +126 -21
- package/src/cache-inspect.js +345 -0
- package/src/cli.js +470 -197
- package/src/commands/agent.js +15 -7
- package/src/commands/completion.js +2 -15
- package/src/commands/mcp.js +20 -18
- package/src/cost-cache.js +16 -2
- package/src/debug.js +348 -0
- package/src/doctor.js +22 -45
- package/src/hl-action.js +41 -13
- package/src/mcp-client-config.js +169 -0
- package/src/mcp-client-config.json +17 -0
- package/src/mcp-verify.js +6 -5
- package/src/perp.js +41 -0
- package/src/privy.js +12 -12
- package/src/response-meta.js +56 -1
- package/src/rpc-urls.js +9 -11
- package/src/schema.json +185 -8
- package/src/semver.js +23 -4
- package/src/swap-simulation.js +35 -30
- package/src/telemetry.js +20 -0
- package/src/trading.js +266 -29
- package/src/transfer.js +53 -6
- package/src/update-check.js +9 -1
- package/src/wallet.js +107 -17
- package/src/walletconnect-trading.js +24 -5
- package/src/x402-svm.js +123 -64
- package/src/x402.js +46 -14
package/src/commands/agent.js
CHANGED
|
@@ -4,20 +4,20 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import crypto from 'crypto';
|
|
7
|
-
import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
|
|
7
|
+
import { NansenError, ErrorCode, statusToErrorCode, browserSessionError, browserSessionResponseMeta, telemetryHeaders, packageVersion } from '../api.js';
|
|
8
8
|
import { getCostForEndpoint } from '../cost-cache.js';
|
|
9
9
|
import { readResponseMeta } from '../response-meta.js';
|
|
10
10
|
|
|
11
11
|
/**
|
|
12
12
|
* Build standard request headers, matching apiInstance.request() conventions.
|
|
13
13
|
*/
|
|
14
|
-
function buildHeaders(apiInstance) {
|
|
14
|
+
async function buildHeaders(apiInstance) {
|
|
15
15
|
return {
|
|
16
16
|
'Content-Type': 'application/json',
|
|
17
17
|
'X-Client-Type': 'nansen-cli',
|
|
18
18
|
'X-Client-Version': packageVersion,
|
|
19
19
|
...telemetryHeaders(),
|
|
20
|
-
...
|
|
20
|
+
...await apiInstance.requestCredentials(),
|
|
21
21
|
...(apiInstance.defaultHeaders || {}),
|
|
22
22
|
};
|
|
23
23
|
}
|
|
@@ -242,7 +242,7 @@ EXAMPLES:
|
|
|
242
242
|
}
|
|
243
243
|
|
|
244
244
|
// ── Auth guard ──
|
|
245
|
-
if (
|
|
245
|
+
if (apiInstance.selection?.kind === 'anonymous') {
|
|
246
246
|
throw new NansenError(
|
|
247
247
|
'Not logged in. Run: nansen login',
|
|
248
248
|
ErrorCode.UNAUTHORIZED,
|
|
@@ -252,12 +252,15 @@ EXAMPLES:
|
|
|
252
252
|
}
|
|
253
253
|
|
|
254
254
|
// ── Request (no retry — SSE streams are not idempotent) ──
|
|
255
|
+
const sessionAuth = apiInstance.selection?.kind === 'session';
|
|
255
256
|
const url = `${apiInstance.baseUrl}${endpoint}`;
|
|
256
257
|
const body = {
|
|
257
258
|
text: question,
|
|
258
259
|
conversation_id: conversationId,
|
|
259
260
|
};
|
|
260
261
|
|
|
262
|
+
const requestHeaders = await buildHeaders(apiInstance);
|
|
263
|
+
|
|
261
264
|
// ── Timeout ──
|
|
262
265
|
const timeoutMs = expert ? 300_000 : 120_000; // 5min expert, 2min fast
|
|
263
266
|
const controller = new AbortController();
|
|
@@ -271,7 +274,7 @@ EXAMPLES:
|
|
|
271
274
|
// forwards custom credential headers (apikey) across a cross-origin
|
|
272
275
|
// redirect, handing the key to whatever host the response points at.
|
|
273
276
|
redirect: 'error',
|
|
274
|
-
headers:
|
|
277
|
+
headers: requestHeaders,
|
|
275
278
|
body: JSON.stringify(body),
|
|
276
279
|
signal: controller.signal,
|
|
277
280
|
});
|
|
@@ -286,10 +289,10 @@ EXAMPLES:
|
|
|
286
289
|
);
|
|
287
290
|
}
|
|
288
291
|
throw new NansenError(
|
|
289
|
-
`Network error: ${err.message}`,
|
|
292
|
+
sessionAuth ? 'Agent network request failed. Retry after checking connectivity.' : `Network error: ${err.message}`,
|
|
290
293
|
ErrorCode.NETWORK_ERROR,
|
|
291
294
|
null,
|
|
292
|
-
{ originalError: err.message },
|
|
295
|
+
sessionAuth ? {} : { originalError: err.message },
|
|
293
296
|
);
|
|
294
297
|
}
|
|
295
298
|
|
|
@@ -303,6 +306,10 @@ EXAMPLES:
|
|
|
303
306
|
serverDetail = errData.detail || errData.message;
|
|
304
307
|
} catch { /* ignore parse failure */ }
|
|
305
308
|
}
|
|
309
|
+
if (sessionAuth) {
|
|
310
|
+
const safe = browserSessionError(response.status, errData);
|
|
311
|
+
throw new NansenError(safe.message, safe.code, response.status, browserSessionResponseMeta(response));
|
|
312
|
+
}
|
|
306
313
|
const meta = readResponseMeta(response);
|
|
307
314
|
throwApiError(
|
|
308
315
|
serverDetail || `Agent returned ${response.status}`,
|
|
@@ -324,6 +331,7 @@ EXAMPLES:
|
|
|
324
331
|
{ detail: `${modeName} mode timeout (${timeoutMs / 1000}s)` },
|
|
325
332
|
);
|
|
326
333
|
}
|
|
334
|
+
if (sessionAuth) throw new NansenError('Agent stream failed. The selected browser session was not replaced.', err.code || ErrorCode.NETWORK_ERROR, err.status || null);
|
|
327
335
|
throw err;
|
|
328
336
|
};
|
|
329
337
|
|
|
@@ -19,28 +19,15 @@ const { version: VERSION } = require('../../package.json');
|
|
|
19
19
|
export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'];
|
|
20
20
|
|
|
21
21
|
/**
|
|
22
|
-
* Commands the CLI dispatches that schema.json does not describe.
|
|
23
|
-
*
|
|
24
|
-
* path runs before the hand-written text), so they are declared here.
|
|
22
|
+
* Commands the CLI dispatches that schema.json does not describe. They retain
|
|
23
|
+
* their hand-written help; the schema help path otherwise takes precedence.
|
|
25
24
|
* completion.test.js fails if a new top-level command appears in neither place.
|
|
26
25
|
*/
|
|
27
26
|
export const UNSCHEMA_COMMANDS = {
|
|
28
|
-
login: {
|
|
29
|
-
description: 'Save your Nansen API key',
|
|
30
|
-
options: {
|
|
31
|
-
'api-key': { type: 'string', description: 'API key (recorded in shell history — prefer --human)' },
|
|
32
|
-
human: { type: 'boolean', description: 'Prompt for the key interactively' },
|
|
33
|
-
},
|
|
34
|
-
},
|
|
35
|
-
logout: { description: 'Remove the saved API key' },
|
|
36
27
|
schema: {
|
|
37
28
|
description: 'Print the JSON schema for every command',
|
|
38
29
|
options: { full: { type: 'boolean', description: 'Verbose schema instead of the compact listing' } },
|
|
39
30
|
},
|
|
40
|
-
cache: {
|
|
41
|
-
description: 'API response cache maintenance',
|
|
42
|
-
subcommands: { clear: { description: 'Clear all cached responses' } },
|
|
43
|
-
},
|
|
44
31
|
changelog: {
|
|
45
32
|
description: 'Show release history',
|
|
46
33
|
options: { since: { type: 'string', description: 'Only show versions at or above this one' } },
|
package/src/commands/mcp.js
CHANGED
|
@@ -8,22 +8,27 @@
|
|
|
8
8
|
|
|
9
9
|
import { CommandError } from '../api.js';
|
|
10
10
|
import { DEFAULT_MCP_URL, formatMcpVerifyReport, runMcpVerifyChecks } from '../mcp-verify.js';
|
|
11
|
+
import { MCP_CLIENT_CONFIG, buildHttpEntry, buildStdioEntry, mcpRemoteSpec } from '../mcp-client-config.js';
|
|
11
12
|
import fs from 'fs';
|
|
12
13
|
import os from 'os';
|
|
13
14
|
import path from 'path';
|
|
14
15
|
|
|
16
|
+
// All values below come from src/mcp-client-config.json (API-322), the one
|
|
17
|
+
// maintained source that the README, the GitBook page and the .dxt manifest
|
|
18
|
+
// are generated from. Edit that file, not these constants.
|
|
19
|
+
|
|
15
20
|
// Hosted Nansen MCP server (streamable HTTP, auth via NANSEN-API-KEY header).
|
|
16
|
-
// Deliberately
|
|
17
|
-
// API key into a config that sends it to an arbitrary host.
|
|
18
|
-
// (REST dev override) intentionally does not affect this.
|
|
19
|
-
export const NANSEN_MCP_URL =
|
|
21
|
+
// Deliberately not user-configurable: a user-supplied URL would let `install`
|
|
22
|
+
// write the API key into a config that sends it to an arbitrary host.
|
|
23
|
+
// NANSEN_BASE_URL (REST dev override) intentionally does not affect this.
|
|
24
|
+
export const NANSEN_MCP_URL = MCP_CLIENT_CONFIG.endpoint;
|
|
20
25
|
|
|
21
26
|
// Claude Desktop's config only supports stdio servers, so it bridges through
|
|
22
27
|
// mcp-remote. Pinned exact so `npx -y` never auto-pulls a compromised future
|
|
23
|
-
// release; bump deliberately.
|
|
24
|
-
export const MCP_REMOTE_PIN =
|
|
28
|
+
// release; bump deliberately (see AGENTS.md > MCP client config).
|
|
29
|
+
export const MCP_REMOTE_PIN = mcpRemoteSpec();
|
|
25
30
|
|
|
26
|
-
const SERVER_KEY =
|
|
31
|
+
const SERVER_KEY = MCP_CLIENT_CONFIG.serverKey;
|
|
27
32
|
|
|
28
33
|
// House idiom (see src/api.js CONFIG_DIR): env first so tests can point HOME
|
|
29
34
|
// at a temp dir; os.homedir() as last resort.
|
|
@@ -49,8 +54,8 @@ OPTIONS:
|
|
|
49
54
|
--send-api-key Authorize sending your saved API key to a custom --url
|
|
50
55
|
(an https:// or loopback host). Not needed for --api-key.
|
|
51
56
|
|
|
52
|
-
The API key is taken from \`nansen login\` / NANSEN_API_KEY. Re-run install after
|
|
53
|
-
rotating your key to update the entry. Other clients:
|
|
57
|
+
The API key is taken from \`nansen login --human\` / NANSEN_API_KEY. Re-run install after
|
|
58
|
+
rotating your key to update the entry. Other clients: ${MCP_CLIENT_CONFIG.docsUrl}`;
|
|
54
59
|
|
|
55
60
|
/**
|
|
56
61
|
* Resolve the client's config file path for this platform.
|
|
@@ -83,16 +88,17 @@ export function buildServerEntry(client, apiKey) {
|
|
|
83
88
|
switch (client) {
|
|
84
89
|
case 'claude-code':
|
|
85
90
|
// "type" is required — a url without type is treated as broken stdio and skipped
|
|
86
|
-
return
|
|
91
|
+
return buildHttpEntry(apiKey, { withType: true });
|
|
87
92
|
case 'cursor':
|
|
88
|
-
return
|
|
93
|
+
return buildHttpEntry(apiKey);
|
|
89
94
|
case 'claude-desktop':
|
|
90
95
|
// Header name and value must be one arg. mcp-remote parses with
|
|
91
96
|
// /^([A-Za-z0-9_-]+):\s*(.*)$/, so whitespace after the colon is trimmed;
|
|
92
97
|
// what breaks it is an empty value.
|
|
93
98
|
// The ${NANSEN_API_KEY} placeholder is NOT shell syntax: mcp-remote itself
|
|
94
99
|
// substitutes ${VAR} in header values from its process env — see
|
|
95
|
-
// mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576
|
|
100
|
+
// mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576 (re-check this
|
|
101
|
+
// behavior before a pin bump; see AGENTS.md > MCP client config)
|
|
96
102
|
// (`value.replace(/\$\{([^}]+)}/g, ...)`, logging "Replacing ${...} with
|
|
97
103
|
// environment value in header"). Claude Desktop injects the `env` block
|
|
98
104
|
// into the spawned npx process, mcp-remote expands the reference, and the
|
|
@@ -100,11 +106,7 @@ export function buildServerEntry(client, apiKey) {
|
|
|
100
106
|
// the exact written config connects to prod with the substitution logged.
|
|
101
107
|
// Do NOT "fix" this by inlining the key into args.
|
|
102
108
|
// No --allow-http: the URL is HTTPS.
|
|
103
|
-
return
|
|
104
|
-
command: 'npx',
|
|
105
|
-
args: ['-y', MCP_REMOTE_PIN, NANSEN_MCP_URL, '--header', 'NANSEN-API-KEY:${NANSEN_API_KEY}'],
|
|
106
|
-
env: { NANSEN_API_KEY: apiKey },
|
|
107
|
-
};
|
|
109
|
+
return buildStdioEntry(apiKey);
|
|
108
110
|
default:
|
|
109
111
|
throw new CommandError(`Unknown client: ${client}. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
|
|
110
112
|
}
|
|
@@ -356,7 +358,7 @@ export function buildMcpCommands(deps = {}) {
|
|
|
356
358
|
// install
|
|
357
359
|
const apiKey = apiInstance?.apiKey;
|
|
358
360
|
if (!apiKey) {
|
|
359
|
-
throw new CommandError('
|
|
361
|
+
throw new CommandError('MCP installation requires an API key. Set NANSEN_API_KEY or run nansen login --human. Browser sessions are not exported to MCP clients.', 'API_KEY_REQUIRED');
|
|
360
362
|
}
|
|
361
363
|
|
|
362
364
|
// Deliberate asymmetry with uninstall --dry-run (which previews even an
|
package/src/cost-cache.js
CHANGED
|
@@ -14,6 +14,14 @@ const CACHE_FILE = path.join(CONFIG_DIR, 'cost-map.json');
|
|
|
14
14
|
const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
|
|
15
15
|
const OPENAPI_URL = 'https://api.nansen.ai/openapi.json';
|
|
16
16
|
|
|
17
|
+
/** How long a fetched cost map stays fresh. */
|
|
18
|
+
export const COST_MAP_TTL_MS = STALE_MS;
|
|
19
|
+
|
|
20
|
+
/** Absolute path of the cost map cache file, for `nansen cache stats` and `clear`. */
|
|
21
|
+
export function getCostMapFile() {
|
|
22
|
+
return CACHE_FILE;
|
|
23
|
+
}
|
|
24
|
+
|
|
17
25
|
/**
|
|
18
26
|
* Write `data` to `file` atomically: write to a unique temp file in the same
|
|
19
27
|
* directory, then rename over the target. rename(2) is atomic on POSIX, so a
|
|
@@ -55,7 +63,13 @@ export function getCostForEndpoint(endpoint) {
|
|
|
55
63
|
export function creditsCharged(meta, endpoint) {
|
|
56
64
|
const charged = meta?.credits?.cost;
|
|
57
65
|
if (charged != null) return { cost: charged, source: 'header' };
|
|
58
|
-
|
|
66
|
+
let estimate = endpoint ? getCostForEndpoint(endpoint) : null;
|
|
67
|
+
const livePages = meta?.pagination?.livePages;
|
|
68
|
+
if (estimate != null && Number.isSafeInteger(livePages) && livePages > 1) {
|
|
69
|
+
estimate = Object.fromEntries(
|
|
70
|
+
Object.entries(estimate).map(([plan, cost]) => [plan, typeof cost === 'number' ? cost * livePages : cost])
|
|
71
|
+
);
|
|
72
|
+
}
|
|
59
73
|
if (estimate != null) return { estimate, source: 'estimate' };
|
|
60
74
|
return null;
|
|
61
75
|
}
|
|
@@ -69,7 +83,7 @@ export async function refreshCostMapIfStale() {
|
|
|
69
83
|
try {
|
|
70
84
|
if (fs.existsSync(CACHE_FILE)) {
|
|
71
85
|
const { fetchedAt } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
|
|
72
|
-
if (fetchedAt && Date.now() - fetchedAt < STALE_MS) return;
|
|
86
|
+
if (Number.isFinite(fetchedAt) && fetchedAt !== 0 && Date.now() - fetchedAt < STALE_MS) return;
|
|
73
87
|
}
|
|
74
88
|
|
|
75
89
|
const controller = new AbortController();
|
package/src/debug.js
ADDED
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Opt-in HTTP request tracing for the CLI.
|
|
3
|
+
*
|
|
4
|
+
* Turned on by the global `--debug` flag (which calls setDebugEnabled) or by
|
|
5
|
+
* `NANSEN_DEBUG=1` in the environment. The generic `DEBUG` variable is not
|
|
6
|
+
* consulted: other packages commonly use it, and enabling HTTP tracing must
|
|
7
|
+
* always be an explicit Nansen choice.
|
|
8
|
+
*
|
|
9
|
+
* Everything is written to **stderr**, never stdout. stdout carries the JSON
|
|
10
|
+
* or CSV that callers pipe into other programs, and a trace line in that
|
|
11
|
+
* stream would corrupt it.
|
|
12
|
+
*
|
|
13
|
+
* Nothing here ever prints a credential. Request and response bodies are never
|
|
14
|
+
* traced at all, header values are never traced, URLs go through redactUrl(),
|
|
15
|
+
* and every value handed to trace() goes through redact() first. Redaction is
|
|
16
|
+
* deliberately over-eager: an over-redacted value costs one support round
|
|
17
|
+
* trip, a leaked one costs a key rotation.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** Placeholder written in place of anything that might be a credential. */
|
|
21
|
+
export const REDACTED = '[redacted]';
|
|
22
|
+
|
|
23
|
+
/** Longest traced value; anything longer is cut and marked. */
|
|
24
|
+
export const MAX_VALUE_LENGTH = 200;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Field/parameter/header names whose value is never safe to print.
|
|
28
|
+
* Matches substrings, so `apikey`, `X-Api-Key`, `authorization`,
|
|
29
|
+
* `payment-signature` and `token_address` are all covered — the last one is
|
|
30
|
+
* not a secret, but fail-closed is the right side to err on here.
|
|
31
|
+
*/
|
|
32
|
+
const SECRET_NAME = /key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private/i;
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* A credential carried inline in a header-ish string, e.g. `Bearer eyJ...`.
|
|
36
|
+
* Two copies on purpose: a /g regex carries lastIndex between .test() calls,
|
|
37
|
+
* so the matcher and the replacer must not be the same object.
|
|
38
|
+
*/
|
|
39
|
+
// Only `Bearer`/`Basic` introduce an inline credential in text we trace. `Payment`
|
|
40
|
+
// and `Signature` are ordinary English words here, and header-name matching plus the
|
|
41
|
+
// value-shape rules below already cover a real payment signature — keeping them in
|
|
42
|
+
// this pattern only garbled prose like "payment was transmitted".
|
|
43
|
+
// The value must look like a credential (8+ chars) so "Bearer token" stays readable.
|
|
44
|
+
// Keep this matcher stateless (no /g): looksLikeSecretValue calls .test() on
|
|
45
|
+
// it, while INLINE_SCHEME_ALL below is the separate global replacement copy.
|
|
46
|
+
const INLINE_SCHEME = /\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/i;
|
|
47
|
+
const INLINE_SCHEME_ALL = new RegExp(INLINE_SCHEME.source, 'gi');
|
|
48
|
+
|
|
49
|
+
/** Request ids and other UUIDs are identifiers, not secrets — keep them readable. */
|
|
50
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
51
|
+
|
|
52
|
+
/** Private-key shaped: 32 bytes of hex, with or without the 0x prefix. */
|
|
53
|
+
const HEX_32_BYTES = /^(0x)?[0-9a-fA-F]{64}$/;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* BIP-39 shaped: 12–24 lowercase words. Intentionally covers non-standard
|
|
57
|
+
* counts between the valid BIP-39 sizes too; over-redacting prose is safer
|
|
58
|
+
* than letting a malformed or partially copied recovery phrase through.
|
|
59
|
+
*/
|
|
60
|
+
const MNEMONIC = /^([a-z]{3,10} ){11,23}[a-z]{3,10}$/;
|
|
61
|
+
|
|
62
|
+
/** JWT shaped: three dot-separated base64url segments starting with a JSON header. */
|
|
63
|
+
const JWT = /^ey[\w-]{8,}\.[\w-]{4,}\.[\w-]+$/;
|
|
64
|
+
|
|
65
|
+
/** Base58 secret-key shaped (Solana keypairs are ~88 chars; addresses are ≤44). */
|
|
66
|
+
const LONG_BASE58 = /^[1-9A-HJ-NP-Za-km-z]{80,}$/;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Long opaque blob — an encoded payment payload, an API key, a session token.
|
|
70
|
+
* The 64-character floor keeps public identifiers readable: EVM addresses are
|
|
71
|
+
* 42 characters and base58 mint addresses at most 44.
|
|
72
|
+
*/
|
|
73
|
+
const LONG_OPAQUE = /^[A-Za-z0-9_\-+/=.]{64,}$/;
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Credential-shaped substrings inside otherwise useful diagnostic prose.
|
|
77
|
+
*
|
|
78
|
+
* IMPORTANT: every module-level /g regex in this block, plus
|
|
79
|
+
* INLINE_SCHEME_ALL above, is replacement-only. Use these only with
|
|
80
|
+
* String.prototype.replace — never RegExp.test() or RegExp.exec(), whose
|
|
81
|
+
* stateful lastIndex would make results depend on earlier trace calls. Add a
|
|
82
|
+
* separate non-/g matcher (as INLINE_SCHEME does) if matching is ever needed.
|
|
83
|
+
*/
|
|
84
|
+
const EMBEDDED_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
|
|
85
|
+
const EMBEDDED_NAMED_SECRET = /\b([\w-]*(?:key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private)[\w-]*)\s*([=:])\s*([^\s,;]+)/gi;
|
|
86
|
+
const EMBEDDED_HEX_32_BYTES = /(?<![0-9a-fA-F])(?:0x)?[0-9a-fA-F]{64}(?![0-9a-fA-F])/g;
|
|
87
|
+
const EMBEDDED_JWT = /\bey[\w-]{8,}\.[\w-]{4,}\.[\w-]+\b/g;
|
|
88
|
+
// NOTE: This intentionally also hides public long identifiers in error prose
|
|
89
|
+
// (for example Solana transaction signatures and block hashes). See README
|
|
90
|
+
// "Debugging"; do not loosen the threshold without auditing credential leaks.
|
|
91
|
+
const EMBEDDED_LONG_OPAQUE = /(?<![A-Za-z0-9_\-+/=.])[A-Za-z0-9_\-+/=.]{64,}(?![A-Za-z0-9_\-+/=.])/g;
|
|
92
|
+
|
|
93
|
+
let forcedEnabled = null;
|
|
94
|
+
let writer = null;
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Force tracing on or off for the process, overriding the environment.
|
|
98
|
+
* Pass undefined to hand control back to NANSEN_DEBUG.
|
|
99
|
+
*/
|
|
100
|
+
export function setDebugEnabled(enabled) {
|
|
101
|
+
forcedEnabled = enabled === undefined ? null : Boolean(enabled);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Replace the stderr sink. Pass undefined to restore it. Tests only. */
|
|
105
|
+
export function setDebugWriter(fn) {
|
|
106
|
+
writer = typeof fn === 'function' ? fn : null;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function envEnabled(value) {
|
|
110
|
+
if (value === undefined || value === null) return false;
|
|
111
|
+
const normalized = String(value).trim().toLowerCase();
|
|
112
|
+
if (normalized === '') return false;
|
|
113
|
+
return !['0', 'false', 'no', 'off'].includes(normalized);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export function isDebugEnabled() {
|
|
117
|
+
if (forcedEnabled !== null) return forcedEnabled;
|
|
118
|
+
return envEnabled(process.env.NANSEN_DEBUG);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Cut a value to MAX_VALUE_LENGTH, marking that it was cut. */
|
|
122
|
+
export function truncate(value, max = MAX_VALUE_LENGTH) {
|
|
123
|
+
const text = String(value);
|
|
124
|
+
if (text.length <= max) return text;
|
|
125
|
+
return `${text.slice(0, max)}…(+${text.length - max} more)`;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Whether a field, query parameter, or header name names a credential. */
|
|
129
|
+
export function isSecretName(name) {
|
|
130
|
+
return SECRET_NAME.test(String(name ?? ''));
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Whether a value looks like a credential regardless of what it is called —
|
|
135
|
+
* a private key, a mnemonic, a JWT, an encoded payment payload.
|
|
136
|
+
*/
|
|
137
|
+
export function looksLikeSecretValue(value) {
|
|
138
|
+
if (typeof value !== 'string') return false;
|
|
139
|
+
const text = value.trim();
|
|
140
|
+
if (text === '' || UUID.test(text)) return false;
|
|
141
|
+
return (
|
|
142
|
+
HEX_32_BYTES.test(text) ||
|
|
143
|
+
MNEMONIC.test(text) ||
|
|
144
|
+
JWT.test(text) ||
|
|
145
|
+
LONG_BASE58.test(text) ||
|
|
146
|
+
LONG_OPAQUE.test(text) ||
|
|
147
|
+
INLINE_SCHEME.test(text)
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function redactString(value) {
|
|
152
|
+
// Delegate only when the whole value is a URL. URL-prefixed diagnostic
|
|
153
|
+
// prose must still pass through the embedded Bearer/JWT/secret scrubbers.
|
|
154
|
+
if (/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(value)) return redactUrl(value);
|
|
155
|
+
// Drop inline credentials first, keeping the scheme label ("Bearer …") so
|
|
156
|
+
// the trace still says what kind of credential was in play. Doing this
|
|
157
|
+
// before the shape checks keeps the surrounding prose readable.
|
|
158
|
+
const neutralized = value
|
|
159
|
+
.replace(EMBEDDED_URL, match => redactUrl(match))
|
|
160
|
+
.replace(INLINE_SCHEME_ALL, (_match, kind) => `${kind} ${REDACTED}`)
|
|
161
|
+
.replace(EMBEDDED_NAMED_SECRET, (_match, name, separator) => `${name}${separator}${REDACTED}`)
|
|
162
|
+
.replace(EMBEDDED_HEX_32_BYTES, REDACTED)
|
|
163
|
+
.replace(EMBEDDED_JWT, REDACTED)
|
|
164
|
+
.replace(EMBEDDED_LONG_OPAQUE, REDACTED);
|
|
165
|
+
if (neutralized !== value) return truncate(neutralized);
|
|
166
|
+
return looksLikeSecretValue(neutralized) ? REDACTED : truncate(neutralized);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Redact a string, array, or (possibly nested) object for tracing.
|
|
171
|
+
* Values under a secret-looking key are replaced wholesale; every other value
|
|
172
|
+
* is still checked for credential-shaped content and truncated.
|
|
173
|
+
*/
|
|
174
|
+
export function redact(value, seen = new WeakSet()) {
|
|
175
|
+
if (value === null || value === undefined) return value;
|
|
176
|
+
if (typeof value === 'string') return redactString(value);
|
|
177
|
+
if (typeof value === 'number' || typeof value === 'boolean') return value;
|
|
178
|
+
if (typeof value === 'bigint') return `${value}`;
|
|
179
|
+
if (ArrayBuffer.isView(value)) {
|
|
180
|
+
return `[${value.constructor?.name || 'TypedArray'} ${value.byteLength} bytes]`;
|
|
181
|
+
}
|
|
182
|
+
if (value instanceof ArrayBuffer) return `[ArrayBuffer ${value.byteLength} bytes]`;
|
|
183
|
+
if (Array.isArray(value)) return value.map((item) => redact(item, seen));
|
|
184
|
+
if (typeof value === 'object') {
|
|
185
|
+
if (seen.has(value)) return '[circular]';
|
|
186
|
+
seen.add(value);
|
|
187
|
+
const out = {};
|
|
188
|
+
for (const [key, item] of Object.entries(value)) {
|
|
189
|
+
out[key] = isSecretName(key) ? REDACTED : redact(item, seen);
|
|
190
|
+
}
|
|
191
|
+
return out;
|
|
192
|
+
}
|
|
193
|
+
return truncate(String(value));
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Redact a URL: drop any userinfo and fragment, sanitize path segments, blank out query values
|
|
198
|
+
* whose parameter is credential-named, and blank out any remaining value that
|
|
199
|
+
* looks like a credential. Path segments that look credential-related are
|
|
200
|
+
* withheld because reset/session/payment credentials are often put there.
|
|
201
|
+
*/
|
|
202
|
+
export function redactUrl(raw) {
|
|
203
|
+
const text = String(raw ?? '');
|
|
204
|
+
let url;
|
|
205
|
+
try {
|
|
206
|
+
url = new URL(text);
|
|
207
|
+
} catch {
|
|
208
|
+
// Not parseable (a relative path, or a malformed URL). Fall back to a
|
|
209
|
+
// textual pass over the query string so nothing leaks from the odd case.
|
|
210
|
+
const queryIndex = text.indexOf('?');
|
|
211
|
+
if (queryIndex === -1) return truncate(text);
|
|
212
|
+
const base = text.slice(0, queryIndex);
|
|
213
|
+
const query = text.slice(queryIndex + 1);
|
|
214
|
+
return truncate(`${base}?${redactQueryText(query)}`);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
const parts = [];
|
|
218
|
+
for (const [key, value] of url.searchParams.entries()) {
|
|
219
|
+
const safe = isSecretName(key) || looksLikeSecretValue(value);
|
|
220
|
+
parts.push(`${encodeURIComponent(key)}=${safe ? REDACTED : encodeURIComponent(value)}`);
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
const credentials = url.username || url.password ? `${REDACTED}@` : '';
|
|
224
|
+
const query = parts.length ? `?${parts.join('&')}` : '';
|
|
225
|
+
const path = url.pathname.split('/').map((segment) => {
|
|
226
|
+
let decoded = segment;
|
|
227
|
+
try { decoded = decodeURIComponent(segment); } catch { /* keep raw text */ }
|
|
228
|
+
// Short path names describe API resources (`token-screener`, `auth`)
|
|
229
|
+
// rather than naming a value, so SECRET_NAME alone would hide the endpoint
|
|
230
|
+
// users need to diagnose. Long secret-named or credential-shaped dynamic
|
|
231
|
+
// segments still fail closed.
|
|
232
|
+
return looksLikeSecretValue(decoded) || (decoded.length >= 32 && isSecretName(decoded))
|
|
233
|
+
? REDACTED
|
|
234
|
+
: segment;
|
|
235
|
+
}).join('/');
|
|
236
|
+
return truncate(`${url.protocol}//${credentials}${url.host}${path}${query}`);
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
function redactQueryText(query) {
|
|
240
|
+
return query
|
|
241
|
+
.split('&')
|
|
242
|
+
.map((pair) => {
|
|
243
|
+
const index = pair.indexOf('=');
|
|
244
|
+
if (index === -1) return pair;
|
|
245
|
+
const key = pair.slice(0, index);
|
|
246
|
+
const value = pair.slice(index + 1);
|
|
247
|
+
let decoded = value;
|
|
248
|
+
try { decoded = decodeURIComponent(value); } catch { /* keep malformed encoding readable */ }
|
|
249
|
+
if (isSecretName(key)) return `${key}=${REDACTED}`;
|
|
250
|
+
const safe = redactString(decoded);
|
|
251
|
+
return `${key}=${safe === decoded ? value : safe}`;
|
|
252
|
+
})
|
|
253
|
+
.join('&');
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* Redact a header bag (plain object, Map, or fetch Headers) down to names
|
|
258
|
+
* only. Header values are never traced: even the innocuous ones carry nothing
|
|
259
|
+
* worth the risk of a rule that misses one. Production traces currently omit
|
|
260
|
+
* headers entirely; this is exported as the mandatory boundary if a future
|
|
261
|
+
* trace event ever includes header names.
|
|
262
|
+
*/
|
|
263
|
+
export function redactHeaders(headers) {
|
|
264
|
+
const entries = typeof headers?.entries === 'function' ? [...headers.entries()] : Object.entries(headers ?? {});
|
|
265
|
+
const out = {};
|
|
266
|
+
for (const [name] of entries) out[name] = REDACTED;
|
|
267
|
+
return out;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
function formatValue(key, value) {
|
|
271
|
+
const safe = key === 'url' ? redactUrl(value) : redact(value);
|
|
272
|
+
const text = typeof safe === 'object' ? JSON.stringify(safe) : String(safe);
|
|
273
|
+
const bounded = truncate(text);
|
|
274
|
+
return /[\s"]/.test(bounded) ? JSON.stringify(bounded) : bounded;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
function write(line) {
|
|
278
|
+
if (writer) writer(line);
|
|
279
|
+
else process.stderr.write(line);
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* Emit one trace line. No-op unless tracing is enabled.
|
|
284
|
+
* Fields are rendered as `key=value`, in the order given, with null and
|
|
285
|
+
* undefined fields dropped.
|
|
286
|
+
*/
|
|
287
|
+
export function trace(event, fields = {}) {
|
|
288
|
+
if (!isDebugEnabled()) return;
|
|
289
|
+
const parts = [`[nansen:debug] ${event}`];
|
|
290
|
+
for (const [key, value] of Object.entries(fields)) {
|
|
291
|
+
if (value === undefined || value === null) continue;
|
|
292
|
+
parts.push(`${key}=${formatValue(key, value)}`);
|
|
293
|
+
}
|
|
294
|
+
write(`${parts.join(' ')}\n`);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/** An HTTP request is about to go out. */
|
|
298
|
+
export function traceRequest({ method, url, attempt, maxAttempts, payment }) {
|
|
299
|
+
trace('http.request', {
|
|
300
|
+
method,
|
|
301
|
+
url,
|
|
302
|
+
attempt: maxAttempts ? `${attempt}/${maxAttempts}` : attempt,
|
|
303
|
+
payment,
|
|
304
|
+
});
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Response headers arrived. `duration_ms` is time from attempt start until
|
|
309
|
+
* fetch resolves with headers (time to first byte / TTFB); it deliberately
|
|
310
|
+
* excludes downloading and parsing the response body.
|
|
311
|
+
*/
|
|
312
|
+
export function traceResponse({ method, url, status, durationMs, requestId, attempt, payment }) {
|
|
313
|
+
trace('http.response', {
|
|
314
|
+
method,
|
|
315
|
+
url,
|
|
316
|
+
status,
|
|
317
|
+
duration_ms: durationMs,
|
|
318
|
+
request_id: requestId,
|
|
319
|
+
attempt,
|
|
320
|
+
payment,
|
|
321
|
+
});
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* The request never produced response headers. `duration_ms` is elapsed time
|
|
326
|
+
* from attempt start until the transport failure.
|
|
327
|
+
*/
|
|
328
|
+
export function traceError({ method, url, durationMs, attempt, error }) {
|
|
329
|
+
trace('http.error', { method, url, duration_ms: durationMs, attempt, error });
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** A retry was decided on: which attempt failed, why, and how long we wait. */
|
|
333
|
+
export function traceRetry({ method, url, status, attempt, reason, delayMs, retryAfterMs }) {
|
|
334
|
+
trace('http.retry', {
|
|
335
|
+
method,
|
|
336
|
+
url,
|
|
337
|
+
status,
|
|
338
|
+
attempt,
|
|
339
|
+
reason,
|
|
340
|
+
delay_ms: delayMs === undefined || delayMs === null ? null : Math.round(delayMs),
|
|
341
|
+
retry_after_ms: retryAfterMs,
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/** The response came from the local cache, so no request was made at all. */
|
|
346
|
+
export function traceCacheHit({ method, url }) {
|
|
347
|
+
trace('http.cache_hit', { method, url });
|
|
348
|
+
}
|