solana-privacy-scanner-core 0.6.0 → 0.6.2

package/README.md

@@ -1,14 +1,14 @@
 # solana-privacy-scanner-core
 
-Core scanning engine for Solana privacy analysis. Analyze on-chain privacy exposure using heuristic-based risk detection.
+Core scanning engine for Solana privacy analysis. Analyze on-chain privacy exposure using 13 heuristic-based detections plus static code analysis.
 
 ## Features
 
-- 🔍 **Privacy Risk Detection** - Identifies balance traceability, amount reuse, counterparty patterns, and timing correlations
-- 🏷️ **Known Entity Detection** - Flags interactions with exchanges, bridges, and KYC services
-- 📊 **Structured Reports** - Generates detailed JSON reports with risk scores, evidence, and mitigations
-- ⚡ **Fast & Efficient** - Built with esbuild, supports both ESM and CJS
-- 🔒 **Privacy-First** - All analysis happens locally, no data sent to external servers
+- **13 Privacy Heuristics** - Fee payer reuse, signer overlap, memo PII, ATA linkage, priority fee fingerprinting, staking patterns, identity metadata exposure, and more
+- **Static Code Analyzer** - AST-based detection of privacy anti-patterns in TypeScript/JavaScript source code
+- **Known Entity Detection** - Flags interactions with exchanges, bridges, and KYC services
+- **Structured Reports** - JSON reports with risk scores, evidence, and actionable mitigations
+- **Works Out of the Box** - Built-in RPC endpoint, no configuration required
 
 ## Installation
 
@@ -18,31 +18,72 @@ npm install solana-privacy-scanner-core
 
 ## Quick Start
 
-```typescript
-import { scan, RPCClient } from 'solana-privacy-scanner-core';
+### Scan a wallet
 
-// Create an RPC client
-const rpc = new RPCClient('https://api.mainnet-beta.solana.com');
+```typescript
+import {
+  RPCClient,
+  collectWalletData,
+  normalizeWalletData,
+  createDefaultLabelProvider,
+  generateReport,
+} from 'solana-privacy-scanner-core';
 
-// Scan a wallet
-const report = await scan({
-  target: 'YourWalletAddressHere',
-  targetType: 'wallet',
-  rpcClient: rpc,
-  maxSignatures: 100,
-});
+const rpc = new RPCClient(); // uses built-in RPC
+const raw = await collectWalletData(rpc, 'YourWalletAddress', { maxSignatures: 100 });
+const labels = createDefaultLabelProvider();
+const context = normalizeWalletData(raw, labels);
+const report = generateReport(context);
 
-console.log('Risk Level:', report.overallRisk);
+console.log('Risk:', report.overallRisk);
 console.log('Signals:', report.signals.length);
 ```
 
+### Analyze source code
+
+```typescript
+import { analyze } from 'solana-privacy-scanner-core';
+
+const result = await analyze(['src/**/*.ts']);
+console.log(`Found ${result.summary.total} privacy issues`);
+result.issues.forEach(i => console.log(`  ${i.severity} ${i.type}: ${i.message}`));
+```
+
+### Use individual heuristics
+
+```typescript
+import { detectFeePayerReuse, detectMemoExposure } from 'solana-privacy-scanner-core';
+import type { ScanContext } from 'solana-privacy-scanner-core';
+
+const signals = detectFeePayerReuse(context);
+const memoSignals = detectMemoExposure(context);
+```
+
+## The 13 Heuristics
+
+| # | Heuristic | What it checks |
+|---|-----------|---------------|
+| 1 | Fee Payer Reuse | One wallet paying fees for multiple accounts |
+| 2 | Signer Overlap | Same signers appearing across transactions |
+| 3 | Memo Exposure | Personal information in memo fields |
+| 4 | Known Entity Interaction | Transfers to/from exchanges, bridges, KYC services |
+| 5 | Identity Metadata Exposure | .sol domain and NFT metadata linkage |
+| 6 | ATA Linkage | One wallet funding token accounts for multiple owners |
+| 7 | Address Reuse | Using one address across many different protocols |
+| 8 | Counterparty Reuse | Repeated transfers to the same address |
+| 9 | Instruction Fingerprinting | Repeated program call patterns |
+| 10 | Token Account Lifecycle | Frequent create/close cycles |
+| 11 | Priority Fee Fingerprinting | Consistent priority fee amounts |
+| 12 | Staking Delegation | Concentrated validator delegation |
+| 13 | Timing Patterns | Burst activity and regular intervals |
+
 ## Documentation
 
-Full documentation available at: https://taylorferran.github.io/solana-privacy-scanner
+Full documentation: https://taylorferran.github.io/solana-privacy-scanner
 
 - [Getting Started](https://taylorferran.github.io/solana-privacy-scanner/guide/getting-started)
 - [Library Usage](https://taylorferran.github.io/solana-privacy-scanner/library/usage)
-- [API Reference](https://taylorferran.github.io/solana-privacy-scanner/library/examples)
+- [Heuristics Reference](https://taylorferran.github.io/solana-privacy-scanner/reports/heuristics)
 
 ## License
 

package/dist/index.cjs

@@ -47,6 +47,8 @@ __export(index_exports, {
   detectATALinkage: () => detectATALinkage,
   detectAddressReuse: () => detectAddressReuse,
   detectCounterpartyReuse: () => detectCounterpartyReuse,
+  detectFeePayerReuse: () => detectFeePayerReuse,
+  detectFeePayerReuseInCode: () => detectFeePayerReuseInCode,
   detectIdentityMetadataExposure: () => detectIdentityMetadataExposure,
   detectInstructionFingerprinting: () => detectInstructionFingerprinting,
   detectKnownEntityInteraction: () => detectKnownEntityInteraction,
@@ -80,7 +82,7 @@ var import_web3 = require("@solana/web3.js");
 // src/constants.ts
 var _RPC_ENCODED = "aHR0cHM6Ly9zZXJlbmUtcm91Z2gtcG9vbC5zb2xhbmEtbWFpbm5ldC5xdWlrbm9kZS5wcm8vYTliM2RkNGRkMzc0MzYwYzQzNzY4YzQyMTI2NmE2ZGNlZDU4MTI3Ny8=";
 var DEFAULT_RPC_URL = /* @__PURE__ */ Buffer.from(_RPC_ENCODED, "base64").toString("utf-8");
-var VERSION = "0.6.0";
+var VERSION = "0.6.2";
 
 // src/rpc/client.ts
 var RateLimiter = class {
@@ -2695,6 +2697,7 @@ function createDefaultLabelProvider() {
 var fs = __toESM(require("fs/promises"), 1);
 var path = __toESM(require("path"), 1);
 var import_glob = require("glob");
+var CODE_EXTENSIONS = ["ts", "tsx", "js", "jsx"];
 async function readFile2(filePath) {
   try {
     return await fs.readFile(filePath, "utf-8");
@@ -2702,15 +2705,29 @@ async function readFile2(filePath) {
     throw new Error(`Failed to read file ${filePath}: ${error}`);
   }
 }
+async function expandPattern(pattern) {
+  try {
+    const cleaned = pattern.replace(/\/+$/, "");
+    const stat2 = await fs.stat(cleaned);
+    if (stat2.isDirectory()) {
+      return CODE_EXTENSIONS.map((ext) => path.join(cleaned, "**", `*.${ext}`));
+    }
+  } catch {
+  }
+  return [pattern];
+}
 async function findFiles(patterns, options) {
   const files = [];
   for (const pattern of patterns) {
-    const matches = await (0, import_glob.glob)(pattern, {
-      ignore: options?.exclude || [],
-      nodir: true,
-      absolute: true
-    });
-    files.push(...matches);
+    const expanded = await expandPattern(pattern);
+    for (const p of expanded) {
+      const matches = await (0, import_glob.glob)(p, {
+        ignore: options?.exclude || [],
+        nodir: true,
+        absolute: true
+      });
+      files.push(...matches);
+    }
   }
   return [...new Set(files)];
 }
@@ -2781,7 +2798,7 @@ function isNodeInsideNode(searchNode, parentNode) {
 }
 
 // src/analyzer/detectors/fee-payer-reuse.ts
-function detectFeePayerReuse2(content, filePath) {
+function detectFeePayerReuseInCode(content, filePath) {
   const issues = [];
   try {
     const ast = (0, import_typescript_estree.parse)(content, {
@@ -2800,7 +2817,7 @@ function detectFeePayerReuse2(content, filePath) {
     traverse(ast, (node) => {
       if (node.type === "VariableDeclarator" && node.id.type === "Identifier" && node.init && isKeypairGenerate(node.init)) {
         const varName = node.id.name;
-        if (varName.toLowerCase().includes("fee") || varName.toLowerCase().includes("payer")) {
+        if (isFeePayerName(varName)) {
           const isInsideLoop = loops.some((loop) => {
             return isNodeInsideNode(node, loop.body);
           });
@@ -2817,6 +2834,22 @@ function detectFeePayerReuse2(content, filePath) {
           }
         }
       }
+      if ((node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") && node.params) {
+        for (const param of node.params) {
+          const paramName = param.type === "Identifier" ? param.name : param.type === "AssignmentPattern" && param.left.type === "Identifier" ? param.left.name : null;
+          if (paramName && isFeePayerName(paramName)) {
+            feePayerVars.set(paramName, {
+              name: paramName,
+              declaration: {
+                line: param.loc.start.line,
+                column: param.loc.start.column,
+                file: filePath
+              },
+              usages: []
+            });
+          }
+        }
+      }
     });
     for (const [varName, varInfo] of feePayerVars) {
       for (const loop of loops) {
@@ -2831,6 +2864,34 @@ function detectFeePayerReuse2(content, filePath) {
               });
             }
           }
+          if (node.type === "CallExpression" && !isTransactionCall(node)) {
+            for (const arg of node.arguments) {
+              if (arg.type === "Identifier" && arg.name === varName) {
+                const alreadyTracked = varInfo.usages.some(
+                  (u) => u.line === node.loc.start.line && u.column === node.loc.start.column
+                );
+                if (!alreadyTracked) {
+                  varInfo.usages.push({
+                    line: node.loc.start.line,
+                    column: node.loc.start.column,
+                    file: filePath
+                  });
+                }
+                break;
+              }
+            }
+          }
+          if (node.type === "AssignmentExpression" && node.left.type === "MemberExpression" && node.left.property.type === "Identifier" && node.left.property.name === "feePayer") {
+            const right = node.right;
+            const assignedName = right.type === "MemberExpression" && right.object.type === "Identifier" ? right.object.name : right.type === "Identifier" ? right.name : null;
+            if (assignedName === varName) {
+              varInfo.usages.push({
+                line: node.loc.start.line,
+                column: node.loc.start.column,
+                file: filePath
+              });
+            }
+          }
         });
       }
       if (varInfo.usages.length > 0) {
@@ -2902,6 +2963,10 @@ function traverse(node, visitor) {
     }
   }
 }
+function isFeePayerName(name) {
+  const lower = name.toLowerCase();
+  return lower.includes("fee") || lower.includes("payer");
+}
 function isKeypairGenerate(node) {
   if (node.type === "CallExpression") {
     const callee = node.callee;
@@ -2933,10 +2998,15 @@ function findFeePayerArgument(node) {
   for (const arg of node.arguments) {
     if (arg.type === "ArrayExpression") {
       const elements = arg.elements.filter((e) => e !== null);
+      for (const el of elements) {
+        if (el && el.type === "Identifier" && isFeePayerName(el.name)) {
+          return el;
+        }
+      }
       if (elements.length > 0) {
-        const lastElement = elements[elements.length - 1];
-        if (lastElement && lastElement.type !== "SpreadElement") {
-          return lastElement;
+        const first = elements[0];
+        if (first && first.type !== "SpreadElement") {
+          return first;
         }
       }
     }
@@ -2993,6 +3063,7 @@ var PII_PATTERNS = [
 function detectMemoPII(content, filePath) {
   const issues = [];
   const lines = content.split("\n");
+  const hasMemoProgram = /MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr/.test(content);
   lines.forEach((line, index) => {
     let memoValue = null;
     let columnOffset = 0;
@@ -3002,6 +3073,9 @@ function detectMemoPII(content, filePath) {
     } else if (line.includes("createMemoInstruction") || line.includes("MemoInstruction")) {
       memoValue = extractMemoFromFunction(line);
       columnOffset = line.indexOf("Instruction") + 1;
+    } else if (hasMemoProgram && line.includes("Buffer.from(")) {
+      memoValue = extractBufferFromValue(line);
+      columnOffset = line.indexOf("Buffer.from") + 1;
     }
     if (memoValue) {
       for (const pattern of PII_PATTERNS) {
@@ -3021,6 +3095,20 @@ function detectMemoPII(content, filePath) {
           });
         }
       }
+      const piiVarMatches = memoValue.matchAll(/\$\{(\w*(?:email|name|user|phone|ssn|address|identity|account)\w*)\}/gi);
+      for (const match of piiVarMatches) {
+        issues.push({
+          type: "memo-pii",
+          severity: "HIGH",
+          file: filePath,
+          line: index + 1,
+          column: columnOffset,
+          message: `Variable '${match[1]}' interpolated into memo likely contains PII`,
+          suggestion: "Do not interpolate user-identifying variables into memo fields. Memos are permanently public on-chain.",
+          codeSnippet: extractSnippet(content, index + 1),
+          identifier: `pii-variable: ${match[1]}`
+        });
+      }
       if (isDescriptiveContent(memoValue)) {
         issues.push({
           type: "memo-pii",
@@ -3071,6 +3159,19 @@ function extractMemoFromFunction(line) {
   }
   return null;
 }
+function extractBufferFromValue(line) {
+  const patterns = [
+    /Buffer\.from\(\s*["']([^"']+)["']/,
+    /Buffer\.from\(\s*`([^`]+)`/
+  ];
+  for (const pattern of patterns) {
+    const match = line.match(pattern);
+    if (match) {
+      return match[1];
+    }
+  }
+  return null;
+}
 function isDescriptiveContent(memo) {
   if (memo.length > 20 && /\s/.test(memo)) {
     return true;
@@ -3154,7 +3255,7 @@ var SolanaPrivacyAnalyzer = class {
   async analyzeFile(filePath) {
     const content = await readFile2(filePath);
     const issues = [];
-    issues.push(...detectFeePayerReuse2(content, filePath));
+    issues.push(...detectFeePayerReuseInCode(content, filePath));
     issues.push(...detectMemoPII(content, filePath));
     return issues;
   }
@@ -3581,6 +3682,8 @@ function getTestWallet(config) {
   detectATALinkage,
   detectAddressReuse,
   detectCounterpartyReuse,
+  detectFeePayerReuse,
+  detectFeePayerReuseInCode,
   detectIdentityMetadataExposure,
   detectInstructionFingerprinting,
   detectKnownEntityInteraction,