opmsec 0.1.0

package/packages/core/src/prompt.ts

@@ -0,0 +1,111 @@
+import type { PackageMetadata, VersionHistoryEntry, SourceFile } from './types';
+
+export const SYSTEM_PROMPT = `You are a security auditor for npm packages. Your job is to analyze package source code and version history to identify security risks, malicious patterns, and supply chain attack indicators.
+
+You MUST respond with a valid JSON object matching this exact schema -- no markdown, no explanation outside the JSON:
+
+{
+  "risk_score": <number 0-100>,
+  "risk_level": "<LOW | MEDIUM | HIGH | CRITICAL>",
+  "reasoning": "<string: 2-4 sentence summary of your overall security assessment>",
+  "vulnerabilities": [
+    {
+      "severity": "<LOW | MEDIUM | HIGH | CRITICAL>",
+      "category": "<string>",
+      "description": "<string: what the vulnerability is>",
+      "file": "<string: file path where found>",
+      "evidence": "<string: relevant code snippet or pattern>"
+    }
+  ],
+  "supply_chain_indicators": {
+    "has_install_scripts": <boolean>,
+    "has_native_bindings": <boolean>,
+    "has_obfuscated_code": <boolean>,
+    "has_network_calls": <boolean>,
+    "has_filesystem_access": <boolean>,
+    "has_process_spawn": <boolean>,
+    "has_eval_usage": <boolean>,
+    "accesses_env_variables": <boolean>
+  },
+  "version_analysis": {
+    "version_reviewed": "<string: current version>",
+    "previous_versions_reviewed": ["<string>"],
+    "changelog_risk": "<NONE | LOW | MEDIUM | HIGH>",
+    "changelog_reasoning": "<string>"
+  },
+  "recommendation": "<SAFE | CAUTION | WARN | BLOCK>"
+}
+
+Risk score guidelines:
+- 0-20: Clean, well-structured code with no concerning patterns
+- 21-40: Minor concerns but likely benign
+- 41-70: Moderate risk, suspicious patterns that warrant manual review
+- 71-100: High/critical risk, likely malicious or extremely dangerous
+
+Focus on these attack vectors:
+1. Postinstall/preinstall scripts that execute arbitrary code
+2. Code that exfiltrates environment variables, credentials, or filesystem data
+3. Obfuscated or encoded payloads (base64, hex-encoded strings executed at runtime)
+4. Network requests to suspicious or hardcoded external endpoints
+5. Prototype pollution or injection vulnerabilities
+6. Typosquatting indicators (name similarity to popular packages)
+7. Sudden large changes between versions (new maintainer, scope change)
+8. Dependency confusion patterns (scoped vs unscoped name conflicts)`;
+
+export interface KnownCVE {
+  id: string;
+  summary: string;
+}
+
+export function buildUserPrompt(
+  meta: PackageMetadata,
+  versionHistory: VersionHistoryEntry[],
+  sourceFiles: SourceFile[],
+  knownCVEs?: KnownCVE[],
+): string {
+  const depsStr = Object.entries(meta.dependencies || {})
+    .map(([k, v]) => `${k}@${v}`)
+    .join(', ') || 'none';
+
+  const scriptsStr = ['preinstall', 'postinstall', 'prepare']
+    .map((s) => `${s}: ${meta.scripts?.[s] || 'none'}`)
+    .join(', ');
+
+  const historyStr = versionHistory
+    .map(
+      (v) =>
+        `- ${v.version} (published: ${v.published}):\n` +
+        `  Dependencies changed: ${v.depsChanged}\n` +
+        `  Files changed: ${v.filesChanged}\n` +
+        `  Size delta: ${v.sizeDelta}\n` +
+        `  New maintainer: ${v.newMaintainer}`,
+    )
+    .join('\n');
+
+  const codeStr = sourceFiles
+    .map((f) => `### File: ${f.path} (${f.size} bytes)\n\`\`\`\n${f.content}\n\`\`\``)
+    .join('\n\n');
+
+  const cveStr = knownCVEs && knownCVEs.length > 0
+    ? `## Known Vulnerabilities (from OSV/GitHub Advisory Database)\n${knownCVEs.map((c) => `- ${c.id}: ${c.summary}`).join('\n')}\n`
+    : '';
+
+  return `Analyze this npm package for security risks.
+
+## Package Metadata
+- Name: ${meta.name}
+- Version: ${meta.version}
+- Description: ${meta.description || 'none'}
+- Author: ${meta.author || 'unknown'}
+- License: ${meta.license || 'none'}
+- Dependencies: ${depsStr}
+- Install scripts: ${scriptsStr}
+
+## Version History (last 3 versions)
+${historyStr || 'No previous versions available.'}
+
+${cveStr}## Source Code
+${codeStr || 'No source files found.'}
+
+Analyze this package thoroughly and respond with the JSON schema specified in your system instructions.`;
+}

package/packages/core/src/types.ts

@@ -0,0 +1,104 @@
+export type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export type Recommendation = 'SAFE' | 'CAUTION' | 'WARN' | 'BLOCK';
+export type ChangelogRisk = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
+
+export interface Vulnerability {
+  severity: RiskLevel;
+  category: string;
+  description: string;
+  file: string;
+  evidence: string;
+  cve_id?: string;
+}
+
+export interface SupplyChainIndicators {
+  has_install_scripts: boolean;
+  has_native_bindings: boolean;
+  has_obfuscated_code: boolean;
+  has_network_calls: boolean;
+  has_filesystem_access: boolean;
+  has_process_spawn: boolean;
+  has_eval_usage: boolean;
+  accesses_env_variables: boolean;
+}
+
+export interface VersionAnalysis {
+  version_reviewed: string;
+  previous_versions_reviewed: string[];
+  changelog_risk: ChangelogRisk;
+  changelog_reasoning: string;
+}
+
+export interface AgentScanResult {
+  risk_score: number;
+  risk_level: RiskLevel;
+  reasoning: string;
+  vulnerabilities: Vulnerability[];
+  supply_chain_indicators: SupplyChainIndicators;
+  version_analysis: VersionAnalysis;
+  recommendation: Recommendation;
+}
+
+export interface AgentEntry {
+  agent_id: string;
+  model: string;
+  result: AgentScanResult;
+}
+
+export interface ScanReport {
+  package: string;
+  version: string;
+  scan_timestamp: string;
+  agents: AgentEntry[];
+  aggregate_risk_score: number;
+  consensus: RiskLevel;
+  versions_analyzed: string[];
+}
+
+export interface PackageMetadata {
+  name: string;
+  version: string;
+  description: string;
+  author: string;
+  license: string;
+  dependencies: Record<string, string>;
+  scripts: Record<string, string>;
+}
+
+export interface VersionHistoryEntry {
+  version: string;
+  published: string;
+  depsChanged: string;
+  filesChanged: string;
+  sizeDelta: string;
+  newMaintainer: boolean;
+}
+
+export interface SourceFile {
+  path: string;
+  size: number;
+  content: string;
+}
+
+export interface AuthorProfile {
+  addr: string;
+  ensName: string;
+  reputationScore: number;
+  packagesPublished: number;
+}
+
+export interface OnChainPackageInfo {
+  author: string;
+  checksum: string;
+  signature: string;
+  ensName: string;
+  reportURI: string;
+  scores: Array<{ agent: string; riskScore: number; reasoning: string }>;
+  aggregateScore: number;
+  exists: boolean;
+}
+
+export interface ChainPatrolResult {
+  status: 'UNKNOWN' | 'ALLOWED' | 'BLOCKED';
+  source: string;
+}

package/packages/core/src/utils.ts

@@ -0,0 +1,50 @@
+import { HIGH_RISK_THRESHOLD, MEDIUM_RISK_THRESHOLD } from './constants';
+import type { RiskLevel, AgentScanResult } from './types';
+
+export function classifyRisk(score: number): RiskLevel {
+  if (score >= HIGH_RISK_THRESHOLD) return 'HIGH';
+  if (score >= MEDIUM_RISK_THRESHOLD) return 'MEDIUM';
+  return 'LOW';
+}
+
+export function averageScores(scores: number[]): number {
+  if (scores.length === 0) return 0;
+  return Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+}
+
+export function truncateAddress(addr: string): string {
+  if (addr.length <= 10) return addr;
+  return `${addr.slice(0, 6)}...${addr.slice(-4)}`;
+}
+
+export function getEnvOrThrow(key: string): string {
+  const val = process.env[key];
+  if (!val) throw new Error(`Missing required env var: ${key}`);
+  return val;
+}
+
+export function getEnvOrDefault(key: string, fallback: string): string {
+  return process.env[key] || fallback;
+}
+
+export function validateScanResult(obj: unknown): obj is AgentScanResult {
+  if (!obj || typeof obj !== 'object') return false;
+  const o = obj as Record<string, unknown>;
+  return (
+    typeof o.risk_score === 'number' &&
+    typeof o.risk_level === 'string' &&
+    typeof o.reasoning === 'string' &&
+    Array.isArray(o.vulnerabilities) &&
+    typeof o.supply_chain_indicators === 'object' &&
+    typeof o.version_analysis === 'object' &&
+    typeof o.recommendation === 'string'
+  );
+}
+
+export function safeJsonParse<T>(raw: string): T | null {
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}

package/packages/scanner/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@opm/scanner",
+  "version": "0.1.0",
+  "private": true,
+  "main": "src/index.ts"
+}

package/packages/scanner/src/agents/agent-configs.ts

@@ -0,0 +1,24 @@
+import { OPENROUTER_MODELS, OPENAI_MODELS } from '@opm/core';
+import { getEnvOrDefault } from '@opm/core';
+import { getLLMProvider } from '../services/openrouter';
+import type { AgentConfig } from './base-agent';
+
+export function getAgentConfigs(): AgentConfig[] {
+  const provider = getLLMProvider();
+  const defaults = provider === 'openai' ? OPENAI_MODELS : OPENROUTER_MODELS;
+
+  return [
+    {
+      agentId: `agent-1`,
+      model: getEnvOrDefault('AGENT1_MODEL', defaults.agent1),
+    },
+    {
+      agentId: `agent-2`,
+      model: getEnvOrDefault('AGENT2_MODEL', defaults.agent2),
+    },
+    {
+      agentId: `agent-3`,
+      model: getEnvOrDefault('AGENT3_MODEL', defaults.agent3),
+    },
+  ];
+}

package/packages/scanner/src/agents/base-agent.ts

@@ -0,0 +1,75 @@
+import { SYSTEM_PROMPT, buildUserPrompt } from '@opm/core';
+import type { AgentEntry, KnownCVE } from '@opm/core';
+import {
+  fetchPackageData, buildLocalPackageData, extractMetadata,
+  buildVersionHistory, fetchSourceFiles, extractLocalSourceFiles,
+  type NpmPackageData,
+} from '../services/npm-registry';
+import { callLLM } from '../services/openrouter';
+import { submitScoreOnChain } from '../services/contract-writer';
+import { queryOSV } from '../services/osv';
+
+export interface AgentConfig {
+  agentId: string;
+  model: string;
+}
+
+export interface LocalScanContext {
+  tarballPath: string;
+  pkgJsonPath: string;
+}
+
+export async function runAgent(
+  config: AgentConfig,
+  packageName: string,
+  version: string,
+  onStatus?: (msg: string) => void,
+  local?: LocalScanContext,
+): Promise<AgentEntry> {
+  const log = onStatus || console.log;
+
+  log(`[${config.agentId}] Fetching package data...`);
+  let data: NpmPackageData;
+  let sourceFiles;
+
+  try {
+    data = await fetchPackageData(packageName);
+    const tarballUrl = data.versions[version]?.dist?.tarball;
+    if (!tarballUrl) throw new Error(`Version ${version} not on npm`);
+    log(`[${config.agentId}] Downloading source from npm...`);
+    sourceFiles = await fetchSourceFiles(packageName, version, tarballUrl);
+  } catch {
+    if (!local) throw new Error(`${packageName}@${version} not found on npm and no local tarball provided`);
+    log(`[${config.agentId}] Using local tarball...`);
+    data = buildLocalPackageData(local.pkgJsonPath);
+    sourceFiles = await extractLocalSourceFiles(local.tarballPath);
+  }
+
+  const meta = extractMetadata(data, version);
+  const history = buildVersionHistory(data, version);
+
+  log(`[${config.agentId}] Querying CVE database (OSV)...`);
+  const osvVulns = await queryOSV(packageName, version);
+  const knownCVEs: KnownCVE[] = osvVulns.map((v) => ({ id: v.id, summary: v.summary }));
+  if (knownCVEs.length > 0) {
+    log(`[${config.agentId}] Found ${knownCVEs.length} known CVE(s)`);
+  }
+
+  log(`[${config.agentId}] Analyzing with ${config.model} (${sourceFiles.length} files)...`);
+  const userPrompt = buildUserPrompt(meta, history, sourceFiles, knownCVEs);
+  const result = await callLLM(config.model, SYSTEM_PROMPT, userPrompt);
+
+  log(`[${config.agentId}] Submitting score (${result.risk_score}) to contract...`);
+  try {
+    await submitScoreOnChain(packageName, version, result.risk_score, result.reasoning);
+    log(`[${config.agentId}] Score submitted on-chain`);
+  } catch (err: any) {
+    log(`[${config.agentId}] On-chain: ${err?.shortMessage || err?.message || 'failed'}`);
+  }
+
+  return {
+    agent_id: config.agentId,
+    model: config.model,
+    result,
+  };
+}

package/packages/scanner/src/index.ts

@@ -0,0 +1,25 @@
+import { enqueueScan } from './queue/memory-queue';
+
+export { enqueueScan } from './queue/memory-queue';
+export type { LocalScanContext } from './agents/base-agent';
+export { runAgent } from './agents/base-agent';
+export { getAgentConfigs } from './agents/agent-configs';
+export { callLLM, getLLMProvider } from './services/openrouter';
+export { fetchPackageData, extractMetadata, buildVersionHistory, fetchSourceFiles, extractLocalSourceFiles, buildLocalPackageData } from './services/npm-registry';
+export { submitScoreOnChain, setReportURIOnChain } from './services/contract-writer';
+export { uploadReportToFileverse, fetchReportFromFileverse } from './services/fileverse';
+
+if (import.meta.main) {
+  const [pkg, ver] = process.argv.slice(2);
+  if (!pkg || !ver) {
+    console.error('Usage: bun run packages/scanner/src/index.ts <package> <version>');
+    process.exit(1);
+  }
+  enqueueScan(pkg, ver).then((r) => {
+    console.log(`Scan complete. Risk: ${r.report.aggregate_risk_score} (${r.report.consensus})`);
+    console.log(`Report: ${r.reportURI}`);
+  }).catch((err) => {
+    console.error('Scan failed:', err);
+    process.exit(1);
+  });
+}

package/packages/scanner/src/queue/memory-queue.ts

@@ -0,0 +1,91 @@
+import type { ScanReport, AgentEntry } from '@opm/core';
+import { averageScores, classifyRisk } from '@opm/core';
+import { runAgent, type LocalScanContext } from '../agents/base-agent';
+import { getAgentConfigs } from '../agents/agent-configs';
+import { setReportURIOnChain } from '../services/contract-writer';
+import { uploadReportToFileverse } from '../services/fileverse';
+
+export interface ScanJobResult {
+  report: ScanReport;
+  reportURI: string;
+}
+
+const activeJobs = new Map<string, Promise<ScanJobResult>>();
+
+export async function enqueueScan(
+  packageName: string,
+  version: string,
+  onStatus?: (msg: string) => void,
+  local?: LocalScanContext,
+): Promise<ScanJobResult> {
+  const key = `${packageName}@${version}`;
+  const existing = activeJobs.get(key);
+  if (existing) return existing;
+
+  const promise = executeScan(packageName, version, onStatus, local);
+  activeJobs.set(key, promise);
+
+  try {
+    return await promise;
+  } finally {
+    activeJobs.delete(key);
+  }
+}
+
+async function executeScan(
+  packageName: string,
+  version: string,
+  onStatus?: (msg: string) => void,
+  local?: LocalScanContext,
+): Promise<ScanJobResult> {
+  const log = onStatus || console.log;
+  const configs = getAgentConfigs();
+
+  log('Starting parallel agent scans...');
+  const results = await Promise.allSettled(
+    configs.map((cfg) => runAgent(cfg, packageName, version, onStatus, local)),
+  );
+
+  const agents: AgentEntry[] = [];
+  for (const r of results) {
+    if (r.status === 'fulfilled') {
+      agents.push(r.value);
+    } else {
+      log(`Agent failed: ${r.reason}`);
+    }
+  }
+
+  if (agents.length === 0) throw new Error('All agents failed');
+
+  const scores = agents.map((a) => a.result.risk_score);
+  const aggScore = averageScores(scores);
+
+  const report: ScanReport = {
+    package: packageName,
+    version,
+    scan_timestamp: new Date().toISOString(),
+    agents,
+    aggregate_risk_score: aggScore,
+    consensus: classifyRisk(aggScore),
+    versions_analyzed: [version],
+  };
+
+  log('Uploading report to Fileverse...');
+  let reportURI: string;
+  try {
+    reportURI = await uploadReportToFileverse(report);
+    log(`Report uploaded: ${reportURI}`);
+  } catch (err) {
+    log(`Fileverse upload failed: ${err}`);
+    reportURI = `local://report-${packageName}-${version}`;
+  }
+
+  try {
+    await setReportURIOnChain(packageName, version, reportURI);
+    log('Report URI stored on-chain');
+  } catch (err: any) {
+    log(`On-chain report URI: ${err?.shortMessage || err?.message || 'failed'}`);
+  }
+
+  return { report, reportURI };
+}

package/packages/scanner/src/services/contract-writer.ts

@@ -0,0 +1,34 @@
+import { ethers } from 'ethers';
+import { OPM_REGISTRY_ABI, getEnvOrThrow, getEnvOrDefault, BASE_SEPOLIA_RPC } from '@opm/core';
+
+function getContract() {
+  const rpc = getEnvOrDefault('BASE_SEPOLIA_RPC_URL', BASE_SEPOLIA_RPC);
+  const provider = new ethers.JsonRpcProvider(rpc);
+  const wallet = new ethers.Wallet(getEnvOrThrow('AGENT_PRIVATE_KEY'), provider);
+  const address = getEnvOrThrow('CONTRACT_ADDRESS');
+  return new ethers.Contract(address, OPM_REGISTRY_ABI, wallet);
+}
+
+export async function submitScoreOnChain(
+  packageName: string,
+  version: string,
+  riskScore: number,
+  reasoning: string,
+): Promise<string> {
+  const contract = getContract();
+  const truncated = reasoning.slice(0, 256);
+  const tx = await contract.submitScore(packageName, version, riskScore, truncated);
+  const receipt = await tx.wait();
+  return receipt.hash;
+}
+
+export async function setReportURIOnChain(
+  packageName: string,
+  version: string,
+  uri: string,
+): Promise<string> {
+  const contract = getContract();
+  const tx = await contract.setReportURI(packageName, version, uri);
+  const receipt = await tx.wait();
+  return receipt.hash;
+}

package/packages/scanner/src/services/fileverse.ts

@@ -0,0 +1,89 @@
+import type { ScanReport } from '@opm/core';
+import { getEnvOrDefault } from '@opm/core';
+import { formatReportAsMarkdown } from './report-formatter';
+
+const DEFAULT_API_URL = 'http://localhost:8001';
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 60_000;
+
+function getApiConfig() {
+  const apiUrl = getEnvOrDefault('FILEVERSE_API_URL', DEFAULT_API_URL);
+  const apiKey = process.env.FILEVERSE_API_KEY;
+  if (!apiKey) throw new Error('FILEVERSE_API_KEY is required (generate at ddocs.new → Settings → Developer Mode)');
+  return { apiUrl, apiKey };
+}
+
+export async function uploadReportToFileverse(report: ScanReport): Promise<string> {
+  const { apiUrl, apiKey } = getApiConfig();
+
+  const title = `OPM Security Report: ${report.package}@${report.version}`;
+  const content = formatReportAsMarkdown(report);
+
+  const res = await fetch(`${apiUrl}/api/ddocs?apiKey=${encodeURIComponent(apiKey)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title, content }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Fileverse create failed (${res.status}): ${body}`);
+  }
+
+  const { data } = await res.json() as { data: { ddocId: string; syncStatus: string; link?: string } };
+  const ddocId = data.ddocId;
+
+  if (data.syncStatus === 'synced' && data.link) return data.link;
+
+  const link = await pollForSync(apiUrl, apiKey, ddocId);
+  return link;
+}
+
+async function pollForSync(apiUrl: string, apiKey: string, ddocId: string): Promise<string> {
+  const start = Date.now();
+
+  while (Date.now() - start < POLL_TIMEOUT_MS) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+
+    const res = await fetch(`${apiUrl}/api/ddocs/${ddocId}?apiKey=${encodeURIComponent(apiKey)}`);
+    if (!res.ok) continue;
+
+    const doc = await res.json() as { syncStatus: string; link?: string };
+    if (doc.syncStatus === 'synced' && doc.link) return doc.link;
+    if (doc.syncStatus === 'failed') throw new Error('Fileverse blockchain sync failed');
+  }
+
+  return `https://ddocs.new/pending/${ddocId}`;
+}
+
+export async function fetchReportFromFileverse(reportURI: string): Promise<ScanReport | null> {
+  if (!reportURI || reportURI.startsWith('local://')) return null;
+
+  const apiKey = process.env.FILEVERSE_API_KEY;
+  const apiUrl = getEnvOrDefault('FILEVERSE_API_URL', DEFAULT_API_URL);
+
+  const ddocId = extractDdocId(reportURI);
+  if (ddocId && apiKey) {
+    try {
+      const res = await fetch(`${apiUrl}/api/ddocs/${ddocId}?apiKey=${encodeURIComponent(apiKey)}`);
+      if (res.ok) {
+        const doc = await res.json() as { content: string };
+        return JSON.parse(doc.content) as ScanReport;
+      }
+    } catch { /* fall through */ }
+  }
+
+  return null;
+}
+
+function extractDdocId(link: string): string | null {
+  try {
+    const url = new URL(link);
+    const parts = url.pathname.split('/');
+    const dIdx = parts.indexOf('d');
+    if (dIdx >= 0 && parts[dIdx + 1]) return parts[dIdx + 1];
+    const pendingIdx = parts.indexOf('pending');
+    if (pendingIdx >= 0 && parts[pendingIdx + 1]) return parts[pendingIdx + 1];
+  } catch { /* not a URL */ }
+  return null;
+}