solguard-cli 0.1.0

package/lib/solguard/aiSummary.js

@@ -0,0 +1,127 @@
+import OpenAI from "openai";
+import { isInvalidAiVerdict, ensureCompleteSentence } from "./verdictValidation.js";
+
+export { isInvalidAiVerdict, ensureCompleteSentence } from "./verdictValidation.js";
+
+export const OPENROUTER_MODEL = process.env.OPENROUTER_MODEL || "openrouter/free";
+
+let _client = null;
+function getOpenRouterClient() {
+  if (!_client) {
+    _client = new OpenAI({
+      apiKey: process.env.OPENROUTER_API_KEY,
+      baseURL: "https://openrouter.ai/api/v1",
+      defaultHeaders: {
+        "HTTP-Referer": "https://www.solguard.space",
+        "X-Title": "SolGuard AI",
+      },
+    });
+  }
+  return _client;
+}
+
+const SYSTEM_PROMPT = `You are a Solana security auditor. Respond with ONLY one plain-English sentence (max 35 words) that states the bottom-line risk for this token.
+
+Output rules:
+- Exactly one sentence ending with a period
+- Reference at least one specific number from the scan data
+- No preamble, no bullet points, no markdown, no labels like "Risk Score:" or "Verdict:"
+- Do not repeat the instructions or restate the raw data fields
+- Do not start with "Based on", "Here is", or "This token"`;
+
+function logOpenRouterError(context, e, extra = {}) {
+  const status = e?.status ?? e?.code ?? extra.status ?? "unknown";
+  console.error(`[OpenRouter] ${context} failed:`, {
+    status,
+    message: e?.message || extra.message || "unknown error",
+    model: OPENROUTER_MODEL,
+    ...extra,
+  });
+}
+
+async function requestCompletion(messages, maxTokens, temperature) {
+  return getOpenRouterClient().chat.completions.create({
+    model: OPENROUTER_MODEL,
+    max_tokens: maxTokens,
+    temperature,
+    messages,
+  });
+}
+
+function buildRiskSummaryMessages(scan) {
+  const user = `Scan data:
+Risk ${scan.riskScore}/100 (${scan.riskLevel})
+Mint authority ${scan.authorityCheck.mintAuthority}, freeze authority ${scan.authorityCheck.freezeAuthority}
+Bundle clustering ${scan.bundleDetection.detected ? `yes (${scan.bundleDetection.walletCount} wallets)` : "not detected"}
+Top holder ${scan.bundleDetection.holderDataAvailable ? scan.bundleDetection.topHolderPercent.toFixed(1) + "%" : "unverified"}
+Top 10 holders ${scan.bundleDetection.holderDataAvailable ? scan.bundleDetection.top10Percent.toFixed(1) + "%" : "unverified"}
+DEX liquidity ${scan.liquidityLock.poolFound ? `$${Math.round(scan.liquidityLock.liquidityUsd || 0).toLocaleString("en-US")}` : "none found"}
+Flags: ${scan.riskFactors.slice(0, 3).join("; ") || "none"}`;
+
+  return [
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: user },
+  ];
+}
+
+async function completeRiskSummary(messages, { llmClient, maxTokens, temperature } = {}) {
+  if (llmClient?.complete) {
+    const raw = await llmClient.complete(messages, { maxTokens, temperature });
+    return { raw: raw?.trim() || "", finishReason: null };
+  }
+  const completion = await requestCompletion(messages, maxTokens, temperature);
+  return {
+    raw: completion.choices?.[0]?.message?.content?.trim() || "",
+    finishReason: completion.choices?.[0]?.finish_reason,
+  };
+}
+
+/**
+ * @param {object} scan
+ * @param {{ llmClient?: { complete: Function, model?: string } }} [opts] — inject BYOK client for CLI local runs
+ * @returns {{ text: string|null, verdict: string|null, aiAvailable: boolean, reason: string|null }}
+ */
+export async function generateRiskSummary(scan, { llmClient } = {}) {
+  const messages = buildRiskSummaryMessages(scan);
+  const logTag = llmClient?.model ? `[LLM:${llmClient.model}]` : "[OpenRouter]";
+
+  let lastError = null;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      const maxTokens = attempt === 1 ? 120 : 200;
+      const { raw, finishReason } = await completeRiskSummary(messages, { llmClient, maxTokens, temperature: 0.3 });
+      if (raw) {
+        const text = ensureCompleteSentence(raw);
+        if (isInvalidAiVerdict(text)) {
+          console.warn(`${logTag} generateRiskSummary rejected invalid verdict shape, attempt`, attempt);
+          lastError = { message: "invalid_verdict_shape", status: 200 };
+          if (attempt < 2) continue;
+          break;
+        }
+        if (finishReason === "length" && attempt < 2) {
+          console.warn(`${logTag} generateRiskSummary hit token limit, retrying with higher max_tokens`);
+          continue;
+        }
+        if (attempt > 1) console.log(`${logTag} generateRiskSummary succeeded on retry`);
+        return { text, verdict: text, aiAvailable: true, reason: null };
+      }
+      lastError = { message: "Empty response", status: 200 };
+    } catch (e) {
+      lastError = e;
+      if (llmClient) {
+        console.error(`${logTag} generateRiskSummary failed:`, { message: e?.message, attempt });
+      } else {
+        logOpenRouterError("generateRiskSummary", e, { attempt });
+      }
+      if (attempt < 2) await new Promise((r) => setTimeout(r, 800));
+    }
+  }
+
+  if (llmClient) {
+    console.error(`${logTag} generateRiskSummary failed:`, { message: lastError?.message, final: true });
+  } else {
+    logOpenRouterError("generateRiskSummary", lastError, { final: true });
+  }
+  const reason = lastError?.message?.slice(0, 120) || "request_failed";
+  return { text: null, verdict: null, aiAvailable: false, reason };
+}

package/lib/solguard/exploits.js

@@ -0,0 +1,13 @@
+// Hardcoded recent Solana/web3 exploit feed for the Exploit Watch page.
+export const EXPLOITS = [
+  { id: "e1", project: "Loopscale", date: "2025-04-26", lossUsd: 5800000, chain: "Solana", vector: "Oracle Manipulation", relevantAgent: "contract-security", summary: "Attacker exploited a price oracle dependency to drain $5.8M from the lending protocol." },
+  { id: "e2", project: "Mango Markets v2", date: "2025-03-12", lossUsd: 2100000, chain: "Solana", vector: "Liquidation Logic", relevantAgent: "contract-security", summary: "Edge case in cross-margin liquidation allowed extraction of liquidity from insurance fund." },
+  { id: "e3", project: "Pump.fun rug — $BOOM", date: "2025-06-18", lossUsd: 740000, chain: "Solana", vector: "Freeze Authority Abuse", relevantAgent: "contract-security", summary: "Deployer froze all holder wallets and dumped reserves. Mint had active freeze authority at launch." },
+  { id: "e4", project: "Slope wallet leak", date: "2025-01-09", lossUsd: 8000000, chain: "Solana", vector: "Seed Phrase Exposure", relevantAgent: "wallet-verification", summary: "Mobile wallet logged seed phrases server-side; multiple users drained.", relatedWallets: ["7VSwHQuy1CZrxQZPqJySmWmetm9jWUSMWSR3LRFrrgCv"] },
+  { id: "e9", project: "Phishing campaign", date: "2025-06-20", lossUsd: 95000, chain: "Solana", vector: "Drainer dApp", relevantAgent: "website-security", summary: "Fake airdrop site impersonated a major launchpad and harvested approvals.", relatedWallets: ["DrainerX1111111111111111111111111111111111"] },
+  { id: "e5", project: "Cetus AMM", date: "2025-05-22", lossUsd: 230000000, chain: "Sui/Solana", vector: "Integer Overflow", relevantAgent: "contract-security", summary: "AMM math overflow allowed minting of liquidity tokens against negligible deposit." },
+  { id: "e6", project: "Anonymous SPL Bundle", date: "2025-06-04", lossUsd: 1200000, chain: "Solana", vector: "Coordinated Bundle Snipe", relevantAgent: "solana-token-verification", summary: "12-wallet bundle accumulated 41% of supply in first slot then dumped over 90 seconds." },
+  { id: "e7", project: "Wormhole bridge ", date: "2025-02-14", lossUsd: 320000000, chain: "Solana/ETH", vector: "Signature Verification Bypass", relevantAgent: "contract-security", summary: "Signature check accepted forged guardian signatures." },
+  { id: "e8", project: "Raydium rug — $MOONK", date: "2025-06-12", lossUsd: 380000, chain: "Solana", vector: "LP Pull", relevantAgent: "solana-token-verification", summary: "Deployer removed unlocked LP tokens 47 minutes after launch." },
+  { id: "e10", project: "Volume wash farm", date: "2025-06-08", lossUsd: 0, chain: "Solana", vector: "Wash Trading", relevantAgent: "volume-authenticity", summary: "Several tokens exhibited 100x+ daily turnover from a single MEV bot." },
+];

package/lib/solguard/llm/client.js

@@ -0,0 +1,83 @@
+import OpenAI from "openai";
+import { getProvider } from "./providers.js";
+
+/**
+ * Create an injectable LLM client for server (OpenRouter) or CLI BYOK.
+ * @param {{ provider: string, apiKey: string, model?: string }} opts
+ * @returns {{ provider: string, model: string, complete: Function }}
+ */
+export function createLlmClient({ provider: providerId, apiKey, model }) {
+  if (!apiKey) throw new Error("API key is required");
+  const provider = getProvider(providerId);
+  if (!provider) throw new Error(`Unknown provider: ${providerId}`);
+
+  const resolvedModel = model || provider.defaultModel;
+
+  if (provider.type === "anthropic") {
+    return {
+      provider: providerId,
+      model: resolvedModel,
+      complete: (messages, { maxTokens = 600, temperature = 0.6 } = {}) =>
+        anthropicComplete({ apiKey, model: resolvedModel, messages, maxTokens, temperature }),
+    };
+  }
+
+  const client = new OpenAI({
+    apiKey,
+    baseURL: provider.baseURL,
+    defaultHeaders: provider.defaultHeaders,
+  });
+
+  return {
+    provider: providerId,
+    model: resolvedModel,
+    complete: async (messages, { maxTokens = 600, temperature = 0.6 } = {}) => {
+      const completion = await client.chat.completions.create({
+        model: resolvedModel,
+        max_tokens: maxTokens,
+        temperature,
+        messages,
+      });
+      return completion.choices?.[0]?.message?.content?.trim() || "";
+    },
+  };
+}
+
+/** Server-side OpenRouter client using env key. */
+export function createServerOpenRouterClient() {
+  return createLlmClient({
+    provider: "openrouter",
+    apiKey: process.env.OPENROUTER_API_KEY,
+    model: process.env.OPENROUTER_MODEL || undefined,
+  });
+}
+
+async function anthropicComplete({ apiKey, model, messages, maxTokens, temperature }) {
+  const system = messages.find((m) => m.role === "system")?.content || "";
+  const userMessages = messages.filter((m) => m.role !== "system");
+
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      temperature,
+      system: system || undefined,
+      messages: userMessages.map((m) => ({ role: m.role, content: m.content })),
+    }),
+  });
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const err = new Error(data?.error?.message || `Anthropic API error (${res.status})`);
+    err.status = res.status;
+    throw err;
+  }
+  const block = data.content?.find((c) => c.type === "text");
+  return block?.text?.trim() || "";
+}

package/lib/solguard/llm/prompts/consultant.js

@@ -0,0 +1,45 @@
+export const CONSULTANT_SYSTEM_PROMPT =
+  "You are SolGuard's expert crypto security consultant. Answer concisely (under 250 words) about Solana token security, wallet safety, rug pulls, smart contract risks, and DeFi best practices. Be direct, technical, and reference specific attack vectors when relevant. End with a clear, actionable recommendation.";
+
+export function buildConsultantMessages(query) {
+  return [
+    { role: "system", content: CONSULTANT_SYSTEM_PROMPT },
+    { role: "user", content: query },
+  ];
+}
+
+/** Parse model output into verdict + recommendations (same logic as legacy execAiConsultant). */
+export function parseConsultantResponse(text, query) {
+  const sentences = text.split(/(?<=[.!?])\s+/);
+  const verdict = sentences[0] || text.slice(0, 200);
+  const recMatch = text.match(/(?:recommend|should|avoid|ensure)[^.!?]*[.!?]/i);
+  const recommendations = recMatch
+    ? [recMatch[0].trim(), "Cross-check advice against on-chain data using SolGuard's token and wallet agents."]
+    : [
+        "Apply this guidance alongside an on-chain scan before making financial decisions.",
+        "Verify any token or wallet mentioned using SolGuard's automated agents.",
+      ];
+  return {
+    verdict,
+    recommendations: recommendations.slice(0, 4),
+    keyFindings: [
+      {
+        label: "Consultation Topic",
+        value: query.slice(0, 120) + (query.length > 120 ? "…" : ""),
+        impact: "neutral",
+        explanation: "Question submitted for AI security analysis.",
+      },
+      {
+        label: "Full Response Length",
+        value: `${text.split(/\s+/).length} words`,
+        impact: "neutral",
+        explanation: "Detailed guidance is available in the raw response below.",
+      },
+    ],
+    rawEvidence: {
+      question: query,
+      fullResponse: text,
+      ai_summary_available: true,
+    },
+  };
+}

package/lib/solguard/llm/providers.js

@@ -0,0 +1,43 @@
+/** Provider registry — official API endpoints only (BYOK calls user's machine → provider). */
+export const PROVIDERS = {
+  openai: {
+    id: "openai",
+    label: "OpenAI",
+    type: "openai",
+    baseURL: "https://api.openai.com/v1",
+    defaultModel: "gpt-4o-mini",
+  },
+  anthropic: {
+    id: "anthropic",
+    label: "Anthropic (Claude)",
+    type: "anthropic",
+    baseURL: "https://api.anthropic.com/v1",
+    defaultModel: "claude-sonnet-4-20250514",
+  },
+  gemini: {
+    id: "gemini",
+    label: "Google Gemini",
+    type: "openai",
+    baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
+    defaultModel: "gemini-2.0-flash",
+  },
+  openrouter: {
+    id: "openrouter",
+    label: "OpenRouter",
+    type: "openai",
+    baseURL: "https://openrouter.ai/api/v1",
+    defaultModel: process.env.OPENROUTER_MODEL || "openrouter/free",
+    defaultHeaders: {
+      "HTTP-Referer": "https://www.solguard.space",
+      "X-Title": "SolGuard AI",
+    },
+  },
+};
+
+export function getProvider(id) {
+  return PROVIDERS[id] || null;
+}
+
+export function listByokProviders() {
+  return [PROVIDERS.openai, PROVIDERS.anthropic, PROVIDERS.gemini];
+}

package/lib/solguard/openclawAudit.js

@@ -0,0 +1,187 @@
+/** Rule-based static analysis of OpenClaw-style AI agent JSON configs. */
+
+function parseAgentConfig(raw) {
+  if (raw == null) throw new Error("Config is required");
+  if (typeof raw === "object") return raw;
+  const trimmed = String(raw).trim();
+  if (!trimmed) throw new Error("Config is required");
+  let outer = JSON.parse(trimmed);
+  if (typeof outer.config === "string") {
+    try {
+      outer = JSON.parse(outer.config);
+    } catch {
+      throw new Error("Nested config string is not valid JSON");
+    }
+  }
+  return outer;
+}
+
+const RISKY_TOOLS = new Set([
+  "http", "fetch", "axios", "curl", "shell", "exec", "bash", "cmd",
+  "filesystem", "fs", "read", "write", "file", "spawn", "subprocess",
+  "network", "socket", "wget",
+]);
+
+const WEAK_AUTH = new Set(["none", "null", "disabled", "open", "public", ""]);
+
+function walkStrings(obj, out = []) {
+  if (obj == null) return out;
+  if (typeof obj === "string") {
+    out.push(obj);
+    return out;
+  }
+  if (Array.isArray(obj)) {
+    for (const v of obj) walkStrings(v, out);
+    return out;
+  }
+  if (typeof obj === "object") {
+    for (const v of Object.values(obj)) walkStrings(v, out);
+  }
+  return out;
+}
+
+export function analyzeOpenClawConfig(rawConfig) {
+  let config;
+  try {
+    config = parseAgentConfig(rawConfig);
+  } catch (e) {
+    return { error: e.message || "Invalid JSON config" };
+  }
+
+  const findings = [];
+  const recommendations = [];
+  let score = 0;
+
+  const gateway = config.gateway || config.auth || {};
+  const authVal = (
+    gateway.auth ??
+    gateway.authentication ??
+    config.auth ??
+    config.authentication ??
+    null
+  );
+  const authStr = authVal == null ? "" : String(authVal).toLowerCase();
+
+  if (authStr === "" || WEAK_AUTH.has(authStr)) {
+    score += 45;
+    findings.push({
+      label: "Authentication",
+      value: authStr === "" ? "Missing" : `"${authVal}"`,
+      impact: "+45 risk",
+      explanation: "Gateway accepts connections without meaningful authentication, allowing unauthorized agent control.",
+    });
+    recommendations.push("Require API keys, OAuth, or mTLS on the agent gateway before production use.");
+  } else if (["basic", "password", "token"].includes(authStr)) {
+    score += 15;
+    findings.push({
+      label: "Authentication",
+      value: String(authVal),
+      impact: "+15 risk",
+      explanation: "Authentication mode may be weak without rate limits, rotation, and TLS enforcement.",
+    });
+    recommendations.push("Use short-lived tokens with rotation and enforce HTTPS-only gateway access.");
+  } else {
+    findings.push({
+      label: "Authentication",
+      value: String(authVal),
+      impact: "neutral",
+      explanation: "An explicit authentication mode is configured on the gateway.",
+    });
+  }
+
+  const toolList = [
+    ...(Array.isArray(config.tools) ? config.tools : []),
+    ...(Array.isArray(config.skills) ? config.skills : []),
+  ].map((t) => (typeof t === "string" ? t : t?.name || t?.id || JSON.stringify(t)).toLowerCase());
+
+  const risky = toolList.filter((t) => [...RISKY_TOOLS].some((r) => t.includes(r)));
+  if (risky.length) {
+    score += Math.min(40, risky.length * 12);
+    findings.push({
+      label: "Tool Permissions",
+      value: risky.slice(0, 6).join(", ") + (risky.length > 6 ? "…" : ""),
+      impact: "+40 risk",
+      explanation: "Tools with network, shell, or filesystem access can exfiltrate data or execute arbitrary commands.",
+    });
+    recommendations.push("Remove or sandbox high-privilege tools; allowlist only required HTTP endpoints.");
+  } else {
+    findings.push({
+      label: "Tool Permissions",
+      value: toolList.length ? `${toolList.length} tool(s) listed` : "None declared",
+      impact: "neutral",
+      explanation: "No obvious unrestricted shell/filesystem tools were declared in the config.",
+    });
+  }
+
+  const strings = walkStrings(config);
+  const injectionPatterns = strings.filter((s) =>
+    /\{\{\s*user\s*\}\}|\$\{.*user|\{\{\s*input\s*\}\}|raw\s*:\s*true|unsanitized/i.test(s)
+  );
+  if (injectionPatterns.length) {
+    score += 25;
+    findings.push({
+      label: "Injection Surface",
+      value: `${injectionPatterns.length} pattern(s) detected`,
+      impact: "+25 risk",
+      explanation: "Raw user placeholders or unsanitized message-passing can enable prompt injection or template abuse.",
+    });
+    recommendations.push("Sanitize and validate all user input before passing it to tools or system prompts.");
+  } else {
+    findings.push({
+      label: "Injection Surface",
+      value: "No raw user placeholders found",
+      impact: "neutral",
+      explanation: "No obvious unsanitized user-input templates were detected in the config strings.",
+    });
+  }
+
+  const session = config.sessionId ?? config.session ?? config.sessions;
+  const sessionIssues = [];
+  if (session != null && typeof session === "string" && session.length < 16) {
+    sessionIssues.push("predictable session id");
+  }
+  if (config.persistSession === true || config.sessionPersist === true) {
+    sessionIssues.push("persistent sessions without expiry");
+  }
+  if (sessionIssues.length) {
+    score += 20;
+    findings.push({
+      label: "Session Handling",
+      value: sessionIssues.join("; "),
+      impact: "+20 risk",
+      explanation: "Weak session identifiers or indefinite persistence increase hijacking and replay risk.",
+    });
+    recommendations.push("Use cryptographically random session IDs with explicit TTL and rotation.");
+  } else {
+    findings.push({
+      label: "Session Handling",
+      value: session ? "Configured" : "Not specified",
+      impact: "neutral",
+      explanation: "No obvious session fixation or persistence issues were detected in the config structure.",
+    });
+  }
+
+  score = Math.min(100, score);
+  const riskLevel = score >= 60 ? "HIGH" : score >= 30 ? "MEDIUM" : "LOW";
+  const agentName = config.name || "unnamed agent";
+  const verdict =
+    score >= 60
+      ? `The "${agentName}" configuration has critical gaps — ${findings.filter((f) => f.impact.includes("+")).length} high-risk checks failed in this automated audit.`
+      : score >= 30
+        ? `The "${agentName}" configuration passes basic checks but has moderate security gaps that should be fixed before production.`
+        : `The "${agentName}" configuration passed this automated audit with no critical rule violations detected.`;
+
+  if (!recommendations.length) {
+    recommendations.push("Re-run this audit after any gateway, tool, or session configuration change.");
+  }
+
+  return {
+    config,
+    riskScore: score,
+    riskLevel,
+    verdict,
+    keyFindings: findings,
+    recommendations: recommendations.slice(0, 4),
+    confidence: "High — deterministic rule-based analysis of submitted JSON structure (not LLM inference)",
+  };
+}

package/lib/solguard/reportBuilder.js

@@ -0,0 +1,105 @@
+/** Never surface 0 in UI/API — floor at 2 so "zero risk" reads as a small positive score. */
+export const MIN_RISK_SCORE = 2;
+
+export function normalizeRiskScore(score) {
+  const n = Math.round(Number(score));
+  if (!Number.isFinite(n) || n <= 0) return MIN_RISK_SCORE;
+  return Math.min(100, n);
+}
+
+/** Standard agent report envelope — keeps legacy `summary` / `evidence` aliases. */
+export function buildReport({
+  agentId,
+  input,
+  riskScore,
+  riskLevel,
+  verdict,
+  keyFindings = [],
+  recommendations = [],
+  confidence,
+  dataSource = [],
+  rawEvidence = {},
+  scannedAt = new Date().toISOString(),
+  ai_summary_available,
+  ai_summary_reason,
+}) {
+  const report = {
+    agentId,
+    input,
+    riskScore: normalizeRiskScore(riskScore),
+    riskLevel,
+    scannedAt,
+    dataSource,
+    verdict,
+    summary: verdict,
+    keyFindings,
+    recommendations,
+    confidence,
+    rawEvidence,
+    evidence: rawEvidence,
+  };
+  if (ai_summary_available !== undefined) {
+    report.ai_summary_available = ai_summary_available;
+    report.ai_summary_reason = ai_summary_reason ?? null;
+  }
+  return report;
+}
+
+export function finding(label, value, impact, explanation) {
+  return { label, value, impact, explanation };
+}
+
+export function impactFromScore(delta) {
+  if (delta === 0) return "neutral";
+  return delta > 0 ? `+${delta} risk` : `${delta} risk`;
+}
+
+export function formatSol(lamports) {
+  const n = Number(lamports) / 1e9;
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M SOL`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(2)}K SOL`;
+  if (n >= 1) return `${n.toFixed(4)} SOL`;
+  return `${n.toFixed(6)} SOL`;
+}
+
+/** Build a holder-concentration finding; never reports 0% when data was unavailable. */
+export function holderConcentrationFinding(label, bundle, { highThreshold = 20, top10Threshold = 50, isTop10 = false } = {}) {
+  const available = bundle.holderDataAvailable === true;
+  const pct = isTop10 ? bundle.top10Percent : bundle.topHolderPercent;
+  if (!available) {
+    return finding(
+      label,
+      "Unable to verify",
+      "unknown",
+      bundle.holderDataError
+        ? `Holder data could not be fetched (${bundle.holderDataError}) — zero concentration must not be assumed.`
+        : "Holder concentration could not be verified on-chain — do not assume zero concentration."
+    );
+  }
+  const threshold = isTop10 ? top10Threshold : highThreshold;
+  const impact = pct > threshold ? `+${isTop10 ? 25 : 10} risk` : "neutral";
+  const explanation = isTop10
+    ? (pct > threshold
+      ? "A small group could coordinate a mass sell-off."
+      : "Supply is spread across many holders rather than a tight cluster.")
+    : (pct > threshold
+      ? "A single wallet controls a large share, increasing dump risk."
+      : "No single wallet dominates supply, which supports healthier distribution.");
+  return finding(label, `${pct.toFixed(1)}%`, impact, explanation);
+}
+
+export function holderShareLabel(bundle, isTop10 = false) {
+  if (bundle.holderDataAvailable !== true) return "Unable to verify";
+  const pct = isTop10 ? bundle.top10Percent : bundle.topHolderPercent;
+  return `${pct.toFixed(1)}%`;
+}
+
+/** Deterministic one-sentence verdict when AI output is missing or invalid. */
+export function buildOnChainVerdict(scan) {
+  const flag = scan.riskFactors?.length
+    ? scan.riskFactors[0].replace(/\.\s*$/, "")
+    : "no major red flags detected";
+  const top10 = holderShareLabel(scan.bundleDetection, true);
+  const score = normalizeRiskScore(scan.riskScore);
+  return `This token scores ${score}/100 (${scan.riskLevel}) with mint authority ${scan.authorityCheck.mintAuthority.toLowerCase()}, freeze authority ${scan.authorityCheck.freezeAuthority.toLowerCase()}, and top 10 holders at ${top10} — ${flag}.`;
+}