opmsec 0.1.3 → 0.1.5

package/docs/architecture/benchmarks.mdx

@@ -5,61 +5,35 @@ description: '10 labeled test cases for agent verification.'
 
 # Benchmark Suite
 
-The benchmark suite validates agent accuracy before permissionless registration. Agents must achieve **100% accuracy** and produce a valid ZK proof.
+Validates agent accuracy before permissionless registration. Agents must score **100% accuracy** and produce a valid ZK proof.
 
-## Test Case Structure
+## Test Cases
 
-Each benchmark case includes:
+Each case includes: package metadata, version history, source files, known CVEs, and expected output (risk level + score range).
 
-| Field | Description |
-|-------|-------------|
-| **id** | Unique identifier (e.g. <code>bench-001-clean-utility</code>) |
-| **category** | One of: clean, typosquat, malicious, cve, obfuscated, exfiltration, dependency_confusion |
-| **metadata** | Package name, version, description, author, license, dependencies, scripts |
-| **versionHistory** | Recent versions with publish dates and change summaries |
-| **sourceFiles** | Path, size, and content of source files |
-| **knownCVEs** | Known advisories (for cve category) |
-| **expected** | risk_level, min_risk_score, max_risk_score, must_flag |
-
-## Categories (10 Cases)
-
-| Category | Count | Description |
+| Category | Cases | Description |
 |----------|-------|-------------|
-| clean | 3 | Legitimate packages (string utils, math, validator) |
-| typosquat | 1 | Typosquat of lodash with credential exfiltration in postinstall |
-| malicious | 2 | Postinstall shell execution, SSH key exfiltration |
-| cve | 1 | Known prototype pollution CVE |
-| obfuscated | 1 | Heavily obfuscated reverse shell |
-| exfiltration | 1 | Env var exfiltration on import |
-| dependency_confusion | 1 | Internal scope shadowing with DNS exfiltration |
+| Clean | 3 | Legitimate packages (string utils, math, validator) |
+| Typosquat | 1 | Lodash typosquat with credential exfil in postinstall |
+| Malicious | 2 | Postinstall shell execution, SSH key exfiltration |
+| CVE | 1 | Known prototype pollution vulnerability |
+| Obfuscated | 1 | Heavily obfuscated reverse shell |
+| Exfiltration | 1 | Env var exfiltration on import |
+| Dependency confusion | 1 | Internal scope shadowing with DNS exfil |
 
 ## Evaluation
 
-For each case, the agent's output is compared to the expected values:
-
-1. **Score range check**: <code>actualScore</code> must be within <code>[min_risk_score, max_risk_score]</code>
-2. **Risk level ordinal**: For non-LOW cases, <code>actualLevel</code> must be within ±1 of expected ordinal (LOW=0, MEDIUM=1, HIGH=2, CRITICAL=3)
-
-A case **PASS**es only if both checks succeed.
-
-## ZK Proof Generation
-
-The ZK proof proves accuracy **without revealing** test data or individual results:
-
-1. **Commitment**: Hash of (salt, expected[0..9]) using Poseidon
-2. **Proof**: Prove that <code>expected[i] == actual[i]</code> for all i, and that the commitment matches
-3. **Output**: <code>proofHash</code> is stored on-chain; test data stays private
+Each case is checked against:
 
-## Circom Circuit
+1. **Score range** — `actualScore` within `[min_risk_score, max_risk_score]`
+2. **Risk level** — For non-LOW cases, actual level within ±1 of expected ordinal
 
-The circuit <code>AccuracyVerifier(10)</code> in <code>packages/contracts/circuits/accuracy_verifier.circom</code>:
+A case passes only if both checks succeed.
 
-- **Private inputs**: expected[10], actual[10], salt
-- **Public input**: commitmentHash (Poseidon hash of salt + expected values)
-- **Public outputs**: passed (1 if all match), proofHash
+## ZK Proof
 
-Uses Poseidon hashing and IsEqual comparators from circomlib.
+1. **Commit** — Poseidon hash of (salt, expected[0..9]) → `commitmentHash`
+2. **Prove** — Circuit verifies `expected[i] == actual[i]` for all i, outputs `passed` and `proofHash`
+3. **Store** — `keccak256(proof)` stored on-chain via `registerAgent()`
 
-<Note>
-The circuit is compiled and used for local verification. On-chain registration stores <code>keccak256(proof)</code> as the proof hash; full on-chain ZK verification can be added later.
-</Note>
+Test data stays private — future agents can't game the benchmark.

package/docs/architecture/overview.mdx

@@ -5,54 +5,47 @@ description: 'Monorepo structure and data flow.'
 
 # Architecture Overview
 
-OPM is a monorepo with five main packages. The flow is: **CLI → Scanner → LLM providers → Contract writer → Base Sepolia**.
+OPM is a monorepo. The flow is: **CLI → Scanner → LLM providers → Contract → Base Sepolia**.
 
-## Monorepo Structure
+## Packages
 
 | Package | Purpose |
-|--------|---------|
-| **packages/core** | Types, constants, prompts, benchmarks, risk classification |
-| **packages/scanner** | Agents, LLM calls, queue, benchmark runner, ZK verifier |
-| **packages/cli** | Ink terminal UI, commands, npm/ENS/OSV integration |
-| **packages/contracts** | Solidity (OPMRegistry), Hardhat, Circom circuits |
-| **packages/web** | Next.js website |
+|---------|---------|
+| `packages/core` | Types, constants, prompts, benchmarks, risk classification |
+| `packages/scanner` | Agent runner, LLM client, scan queue, benchmark runner, ZK verifier |
+| `packages/cli` | Ink terminal UI, commands, ENS/OSV/npm integration |
+| `packages/contracts` | OPMRegistry.sol, Hardhat config, Circom circuit |
+| `packages/web` | Next.js landing page |
 
 ## Data Flow
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
-│   opm push  │────▶│   Scanner   │────▶│  LLM Providers   │
-│   opm check │     │  (agents)   │     │ OpenRouter/OpenAI│
-└─────────────┘     └──────┬──────┘     └──────────────────┘
-       │                   │
-       │                   ▼
-       │            ┌─────────────┐
-       │            │  Contract   │
-       │            │   Writer    │
-       │            └──────┬──────┘
-       │                   │
-       ▼                   ▼
-┌─────────────┐     ┌─────────────┐
-│  npm / ENS  │     │ Base Sepolia│
-└─────────────┘     └─────────────┘
+CLI (push/install/check)
+  → Scanner (parallel agent execution)
+    → LLM providers (OpenRouter / OpenAI)
+    → Contract writer (submitScore, registerPackage)
+      → Base Sepolia
+  → npm registry (publish / install)
+  → ENS (text records, contenthash)
+  → Fileverse (IPFS report upload)
 ```
 
 ## External Services
 
 | Service | Purpose |
 |---------|---------|
-| **OpenRouter / OpenAI** | LLM inference for agents |
-| **OSV** | CVE and GHSA advisory lookup |
-| **Fileverse** | IPFS-backed report storage (dDocs protocol) |
-| **ChainPatrol** | Blocklist fallback for unregistered packages |
-| **Artificial Analysis** | Model intelligence/coding indices for weighted scoring |
-| **ENS** | Author identity resolution (forward/reverse, text records) |
-| **npm Registry** | Package metadata, tarball download |
-
-## Key Paths
-
-- **CLI entry**: <code>packages/cli/src/index.tsx</code>
-- **Scanner entry**: <code>packages/scanner/src/index.ts</code>
-- **Contract**: <code>packages/contracts/contracts/OPMRegistry.sol</code>
-- **Benchmarks**: <code>packages/core/src/benchmarks.ts</code>
-- **ZK circuit**: <code>packages/contracts/circuits/accuracy_verifier.circom</code>
+| OpenRouter / OpenAI | LLM inference |
+| OSV | CVE/GHSA lookup |
+| Fileverse | IPFS report storage |
+| ChainPatrol | Blocklist fallback |
+| Artificial Analysis | Model intelligence indices |
+| ENS | Identity resolution + text records |
+| npm | Package metadata + tarball download |
+
+## Key Entry Points
+
+- CLI: `packages/cli/src/index.tsx`
+- Scanner: `packages/scanner/src/index.ts`
+- Contract: `packages/contracts/contracts/OPMRegistry.sol`
+- Benchmarks: `packages/core/src/benchmarks.ts`
+- ZK circuit: `packages/contracts/circuits/accuracy_verifier.circom`

package/docs/architecture/scanner.mdx

@@ -5,49 +5,23 @@ description: 'Scan queue, parallel execution, and integrations.'
 
 # Scanner Engine
 
-The scanner is the core security analysis engine. It coordinates package data fetching, LLM calls, and on-chain score submission.
+The scanner coordinates package data fetching, LLM calls, and on-chain score submission.
 
-## Memory Queue with Deduplication
+## Scan Queue
 
-Scans are enqueued via <code>enqueueScan(packageName, version, onStatus?, options?)</code>. The queue:
+Scans are enqueued via `enqueueScan(packageName, version)`. The queue deduplicates concurrent scans for the same `name@version` and supports local tarball context for pre-publish scans.
 
-- Deduplicates concurrent scans for the same <code>name@version</code>
-- Supports local tarball context for pre-publish scans (no npm download)
+## Parallel Execution
 
-## Parallel Agent Execution
-
-Agents run in parallel via <code>Promise.allSettled</code>:
-
-- Each agent fetches package data, queries OSV, calls the LLM, and submits its score on-chain
-- Failures in one agent do not block others
-- Aggregate score is the mean of successful submissions (intelligence-weighted when Artificial Analysis API is configured)
+Agents run via `Promise.allSettled` — failures in one agent don't block others. The aggregate score is the mean of successful submissions, intelligence-weighted when the Artificial Analysis API is configured.
 
 ## Source Code Extraction
 
-<AccordionGroup>
-  <Accordion title="From npm tarball">
-    Downloads the tarball from the npm registry, extracts to a temp directory, and reads scannable files (<code>.js</code>, <code>.ts</code>, <code>.mjs</code>, <code>.cjs</code>, <code>.json</code>).
-  </Accordion>
-  <Accordion title="From local tarball">
-    When <code>opm push</code> runs, the packed tarball path is passed. The scanner extracts source from the local file instead of downloading from npm.
-  </Accordion>
-</AccordionGroup>
-
-## NPM Registry Integration
-
-- **Metadata**: Package name, version, description, dependencies, scripts
-- **Version history**: Recent versions with publish dates and change summaries
-- **Tarball URL**: Fetched from <code>versions[version].dist.tarball</code>
-
-## Fileverse Upload
-
-Audit reports are formatted as Markdown and uploaded via the Fileverse API. The returned URI is set on-chain via <code>setReportURI</code>. Requires <code>FILEVERSE_API_KEY</code>.
-
-## Contract Writer
-
-The scanner's contract writer:
+- **From npm**: Downloads tarball, extracts to temp dir, reads scannable files (`.js`, `.ts`, `.mjs`, `.cjs`, `.json`)
+- **From local**: During `opm push`, the packed tarball path is passed directly
 
-- **submitScoreOnChain**: Calls <code>OPMRegistry.submitScore()</code> with agent wallet
-- **setReportURIOnChain**: Calls <code>OPMRegistry.setReportURI()</code>
+## Integrations
 
-Both require the agent to be authorized (owner-set or ZK-verified).
+- **npm registry** — Package metadata, version history, tarball URL
+- **Fileverse** — Audit reports formatted as Markdown, uploaded via API, URI set on-chain
+- **Contract writer** — `submitScore()` and `setReportURI()` calls with agent wallet

package/docs/cli/audit.mdx

@@ -1,35 +1,32 @@
 ---
 title: 'opm audit'
-description: 'On-chain + CVE audit for all dependencies.'
+description: 'Quick on-chain + CVE audit for all dependencies.'
 ---
 
 # opm audit
 
-On-chain + CVE audit for all dependencies. Faster than <code>opm check</code> because it does not call AI agents.
+Fast security audit — checks on-chain scores and CVEs for all dependencies without running AI agents.
 
 ## What It Does
 
-- Scans all <code>dependencies</code> and <code>devDependencies</code> in <code>package.json</code>
 - Queries OPMRegistry for on-chain risk scores
 - Queries OSV for CVE counts
-- For packages not in the registry: checks ChainPatrol blocklist
+- Checks ChainPatrol blocklist for unregistered packages
 - Shows per-package risk level and CVE counts
 
 ## Output
 
 | Column | Description |
 |--------|-------------|
-| Package | <code>name@version</code> |
+| Package | `name@version` |
 | On-chain | Risk badge (LOW/MEDIUM/HIGH) or "not in registry" |
-| Author | Truncated wallet address (when registered) |
-| CVEs | Count of known vulnerabilities (red if HIGH/CRITICAL) |
+| Author | Truncated wallet address |
+| CVEs | Count of known vulnerabilities |
 
-Summary line: <code>X high · Y medium · Z low · W unverified · N CVEs</code>
+Summary: `X high · Y medium · Z low · W unverified · N CVEs`
 
 <Tip>
-Use <code>opm audit</code> for a quick security overview. Use <code>opm check</code> when you need AI analysis and typosquat detection.
+Use `opm audit` for a quick overview. Use `opm check` when you need AI analysis and typosquat detection.
 </Tip>
 
-## Environment Variables
-
-No environment variables are required. Uses built-in RPC and contract address.
+No environment variables required.

package/docs/cli/check.mdx

@@ -1,44 +1,30 @@
 ---
 title: 'opm check'
-description: 'Comprehensive dependency security scan.'
+description: 'Full dependency security scan with AI agents.'
 ---
 
 # opm check
 
-Comprehensive dependency security scan. Scans all dependencies in <code>package.json</code>, runs AI agents, and optionally uploads a report to Fileverse.
+Scans all dependencies for typosquats, CVEs, on-chain risk, and AI-detected threats. Optionally uploads a report to Fileverse.
 
 ## What It Scans
 
-<AccordionGroup>
-  <Accordion title="Typosquat detection">
-    Uses Levenshtein distance against top npm packages to detect likely typosquats (e.g. <code>lodahs</code> → <code>lodash</code>).
-  </Accordion>
-  <Accordion title="CVE lookup (OSV)">
-    Queries the OSV API for known vulnerabilities per package and version.
-  </Accordion>
-  <Accordion title="On-chain score lookup">
-    Fetches aggregate risk scores from OPMRegistry for registered packages.
-  </Accordion>
-  <Accordion title="AI agent analysis">
-    Three agents analyze the full dependency list in parallel. Each produces findings, severity, and suggested replacements.
-  </Accordion>
-</AccordionGroup>
-
-## Report Upload
-
-When <code>FILEVERSE_API_KEY</code> is set, the scan report is uploaded to Fileverse (IPFS). The report URI can be set on-chain for packages you publish.
+- **Typosquats** — Levenshtein distance against top npm packages
+- **CVEs** — OSV API lookup for known vulnerabilities per package/version
+- **On-chain scores** — Aggregate risk from OPMRegistry for registered packages
+- **AI analysis** — 3 agents analyze the full dependency list in parallel, producing severity ratings and suggested replacements
 
 ## Output
 
-- **Per-dependency results**: Typosquats, CVE counts, on-chain scores, fix versions
-- **AI agent findings**: Per-agent analysis with severity and suggested replacements
-- **Overall assessment**: Summary counts (typosquats, CVEs, high-risk, AI flags)
-- **Report link**: Fileverse URL when upload succeeds
+- Per-dependency results: typosquats, CVE counts, on-chain scores, fix versions
+- AI agent findings with severity and suggested replacements
+- Summary: total typosquats, CVEs, high-risk, AI flags
+- Fileverse report link when upload succeeds
 
 <Note>
-<code>opm check</code> requires <code>OPENROUTER_API_KEY</code> or <code>OPENAI_API_KEY</code> for AI agent analysis. Without them, typosquat and CVE checks still run, but agent analysis is skipped.
+Requires `OPENROUTER_API_KEY` or `OPENAI_API_KEY` for AI analysis. Without them, typosquat and CVE checks still run.
 </Note>
 
 <Tip>
-Run <code>opm fix</code> to auto-correct typosquats and vulnerable versions identified by <code>opm check</code>.
+Run `opm fix` to auto-apply the fixes identified by `opm check`.
 </Tip>

package/docs/cli/fix.mdx

@@ -5,45 +5,25 @@ description: 'Auto-fix typosquats and vulnerable dependencies.'
 
 # opm fix
 
-Same scan as <code>opm check</code> but auto-applies fixes to <code>package.json</code>. Replaces typosquat packages with correct names and updates vulnerable packages to patched versions.
+Runs the same scan as `opm check`, then auto-applies fixes to `package.json`.
 
 ## What It Fixes
 
-<AccordionGroup>
-  <Accordion title="Typosquats">
-    Replaces package names detected as typosquats with the likely correct name (e.g. <code>lodahs</code> → <code>lodash</code>).
-  </Accordion>
-  <Accordion title="Vulnerable packages">
-    Updates packages with CRITICAL or HIGH CVEs to the patched version suggested by OSV.
-  </Accordion>
-  <Accordion title="AI-suggested replacements">
-    When 2+ agents flag a package and suggest a replacement, the fix is applied if the suggestion is valid.
-  </Accordion>
-</AccordionGroup>
+- **Typosquats** — Renames to the correct package (e.g. `lodahs` → `lodash`)
+- **Vulnerable packages** — Upgrades to patched versions suggested by OSV
+- **AI-flagged packages** — Applies replacements when 2+ agents agree on a suggestion
 
 ## Process
 
-<Steps>
-  <Step title="Scan dependencies">
-    Runs typosquat detection, CVE lookup, and AI agent analysis (same as <code>opm check</code>).
-  </Step>
-  <Step title="Collect fixes">
-    Builds a list of fixes: typosquat renames, CVE upgrades, and AI-suggested replacements.
-  </Step>
-  <Step title="Apply to package.json">
-    Modifies <code>dependencies</code> and <code>devDependencies</code> with the fixes. Preserves version range prefixes (<code>^</code>, <code>~</code>).
-  </Step>
-  <Step title="Upload report">
-    Optionally uploads the scan report to Fileverse when <code>FILEVERSE_API_KEY</code> is set.
-  </Step>
-</Steps>
-
-## After Running
+1. Scans all dependencies (same as `opm check`)
+2. Collects fixes: typosquat renames, CVE upgrades, AI-suggested replacements
+3. Modifies `package.json` in place (preserves `^`/`~` prefixes)
+4. Optionally uploads report to Fileverse
 
 <Warning>
-<code>opm fix</code> modifies <code>package.json</code> in place. Run <code>npm install</code> (or <code>opm install</code>) to apply the changes and update the lockfile.
+Run `npm install` or `opm install` after `opm fix` to apply changes and update the lockfile.
 </Warning>
 
 <Tip>
-Review the diff in <code>package.json</code> before committing. AI-suggested replacements require consensus from 2+ agents before being applied.
+Review the diff before committing. AI replacements require 2+ agent consensus.
 </Tip>

package/docs/cli/info.mdx

@@ -1,11 +1,11 @@
 ---
 title: 'opm info'
-description: 'Show on-chain security information for a package.'
+description: 'On-chain security metadata and ENS records for a package.'
 ---
 
 # opm info
 
-Show on-chain security information for a package. Displays author, checksum, signature, ENS name, report URI, agent scores, aggregate score, and safest version.
+Display on-chain security information for a package: author, checksum, signature, risk scores, agent assessments, audit report, and ENS records.
 
 ## Usage
 
@@ -21,24 +21,17 @@ opm info lodash@4.17.21
 
 </CodeGroup>
 
-## Output
+## What It Shows
 
-| Field | Description |
-|-------|-------------|
-| Author | Wallet address (with ENS resolution when available) |
-| Checksum | SHA-256 hash of the tarball |
-| Signature | ECDSA signature (verified or unverified) |
-| ENS name | Author identity (e.g. <code>vitalik.eth</code>) |
-| Report URI | Link to Fileverse audit report |
-| Agent scores | Per-agent risk scores and reasoning |
-| Aggregate score | Mean risk score (0–100) |
-| Safest version | Lowest-risk version in recent releases |
-
-## Links
-
-- **Fileverse report** — Full AI audit when report URI is set
-- **BaseScan** — Contract and transaction links
+- **Author** — Wallet address with ENS resolution
+- **Checksum** — SHA-256 hash of the tarball
+- **Signature** — ECDSA signature (verified/unverified status)
+- **Agent scores** — Per-agent risk scores with reasoning
+- **Aggregate score** — Mean risk across all agents
+- **Safest version** — Lowest-risk version in recent releases
+- **Report URI** — Link to Fileverse audit report
+- **ENS records** — `opm.*` text records from the author's ENS name (version, checksum, fileverse, risk score, contenthash)
 
 <Note>
-If the package is not in the OPM registry, a warning is shown. No env vars are required.
+No environment variables required. If the package isn't in the OPM registry, a warning is shown.
 </Note>

package/docs/cli/install.mdx

@@ -5,67 +5,55 @@ description: 'Install packages with on-chain security verification.'
 
 # opm install
 
-Install packages with on-chain security verification. OPM runs a verification pipeline before delegating to npm.
+Install packages with on-chain verification, CVE checks, and signature validation.
 
 ## Usage
 
 <CodeGroup>
 
-```bash Install specific package
+```bash Single package
 opm install lodash
 ```
 
-```bash Install with version
+```bash Specific version
 opm install lodash@4.17.21
 ```
 
-```bash Install all dependencies
+```bash ENS-based version
+opm install express@djpai.eth
+```
+
+```bash All dependencies
 opm install
 ```
 
 </CodeGroup>
 
-## Aliases
-
-- <code>opm i</code> — same as <code>opm install</code>
-- <code>opm add</code> — same as <code>opm install</code>
+**Aliases**: `opm i`, `opm add`
 
 ## Verification Pipeline
 
-<AccordionGroup>
-  <Accordion title="CVE check (OSV)">
-    Queries the OSV API for known CVEs and GHSA advisories. **CRITICAL** CVEs block installation.
-  </Accordion>
-  <Accordion title="On-chain score lookup">
-    Fetches aggregate risk score from OPMRegistry. Blocks if score ≥ 70.
-  </Accordion>
-  <Accordion title="Signature verification">
-    Verifies ECDSA signature against tarball checksum for packages in the registry.
-  </Accordion>
-  <Accordion title="ChainPatrol blocklist">
-    For packages not in the OPM registry, falls back to ChainPatrol API. BLOCKED status prevents install.
-  </Accordion>
-</AccordionGroup>
-
-## Blocking Rules
+1. **CVE check** — Queries OSV for known vulnerabilities. CRITICAL CVEs block install.
+2. **On-chain score** — Fetches aggregate risk from OPMRegistry. Score ≥ 70 blocks install.
+3. **Signature verification** — Verifies ECDSA signature against tarball checksum.
+4. **ChainPatrol** — Blocklist fallback for packages not in the registry.
 
-<Warning>
-Installation is **blocked** if:
-- Risk score ≥ 70 (on-chain)
-- Any CRITICAL CVE is present (OSV)
-- ChainPatrol returns BLOCKED (for unregistered packages)
-</Warning>
+If all gates pass, delegates to `npm install`.
 
-## Fallback Behavior
+## ENS Version Resolution
 
-<Note>
-If a package is **not in the OPM registry**, OPM falls back to standard <code>npm install</code> with a warning. ChainPatrol is consulted when available.
-</Note>
+When you specify an ENS name as a version (e.g. `express@djpai.eth`), OPM:
 
-## Environment Variables
+1. Resolves the ENS name to an Ethereum address
+2. Verifies the author is registered on-chain
+3. Fetches the safest version from the registry
+4. Checks for CVEs and auto-bumps to a safe version if needed
+5. Updates `package.json` with the resolved version
 
-No environment variables are required for basic install. Defaults for RPC, contract address, and API URLs are built-in.
+<Warning>
+Installation is **blocked** if risk score ≥ 70, any CRITICAL CVE exists, or ChainPatrol returns BLOCKED.
+</Warning>
 
-<Tip>
-For bulk install (<code>opm install</code> with no args), all <code>dependencies</code> and <code>devDependencies</code> are scanned in parallel before npm install runs.
-</Tip>
+<Note>
+No environment variables needed. Defaults for RPC and contract address are built-in.
+</Note>