opmsec 0.1.0 → 0.1.3

package/docs/architecture/agents.mdx

@@ -0,0 +1,77 @@
+---
+title: 'Agent Architecture'
+description: 'Agent config, base agent, prompts, and model ranking.'
+---
+
+# Agent Architecture
+
+Security agents are LLM-powered analyzers that score packages and submit results on-chain.
+
+## AgentConfig
+
+```typescript
+interface AgentConfig {
+  agentId: string;  // e.g. "agent1", "agent2", "agent3"
+  model: string;    // e.g. "anthropic/claude-sonnet-4-20250514"
+}
+```
+
+Configs are defined in <code>packages/scanner/src/agents/agent-configs.ts</code> and can be overridden via <code>AGENT1_MODEL</code>, <code>AGENT2_MODEL</code>, <code>AGENT3_MODEL</code>.
+
+## Base Agent Flow
+
+<Steps>
+  <Step title="Fetch data">
+    Fetches package metadata and version history from npm (or uses local tarball for pre-publish scans).
+  </Step>
+  <Step title="Query OSV">
+    Looks up known CVEs for the package and version.
+  </Step>
+  <Step title="Call LLM">
+    Sends system prompt + user prompt to the configured model. Expects JSON with <code>risk_score</code>, <code>risk_level</code>, <code>reasoning</code>, <code>vulnerabilities</code>.
+  </Step>
+  <Step title="Submit score on-chain">
+    Calls <code>OPMRegistry.submitScore()</code> with the agent wallet.
+  </Step>
+</Steps>
+
+## System Prompt
+
+The system prompt defines a **security auditor persona** and enforces a structured JSON output schema:
+
+- Risk score (0–100)
+- Risk level (LOW, MEDIUM, HIGH, CRITICAL)
+- Reasoning
+- List of vulnerabilities with severity
+
+## User Prompt
+
+The user prompt includes:
+
+- Package metadata (name, version, description, author, license, dependencies, scripts)
+- Version history (recent versions, publish dates, changes)
+- Source code (extracted from tarball, truncated to size limits)
+- Known CVEs from OSV
+
+## Model Ranking
+
+When <code>ARTIFICIAL_ANALYSIS_API_KEY</code> is set, the scanner fetches model rankings:
+
+- **Intelligence index**: General reasoning capability
+- **Coding index**: Code-related task performance
+
+These indices are used to compute a **weight** for each agent. The aggregate score is intelligence-weighted across agents.
+
+<Tip>
+Without the Artificial Analysis API, agents are weighted equally.
+</Tip>
+
+## Extensibility
+
+New agents can register **permissionlessly** via <code>opm register-agent</code>:
+
+1. Pass 10 benchmark cases with 100% accuracy
+2. Generate a ZK proof
+3. Call <code>OPMRegistry.registerAgent()</code>
+
+Once registered, the agent participates in package scans alongside existing agents.

package/docs/architecture/benchmarks.mdx

@@ -0,0 +1,65 @@
+---
+title: 'Benchmark Suite'
+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.
+
+## Test Case Structure
+
+Each benchmark case includes:
+
+| 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 |
+|----------|-------|-------------|
+| 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 |
+
+## 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
+
+## Circom Circuit
+
+The circuit <code>AccuracyVerifier(10)</code> in <code>packages/contracts/circuits/accuracy_verifier.circom</code>:
+
+- **Private inputs**: expected[10], actual[10], salt
+- **Public input**: commitmentHash (Poseidon hash of salt + expected values)
+- **Public outputs**: passed (1 if all match), proofHash
+
+Uses Poseidon hashing and IsEqual comparators from circomlib.
+
+<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>

package/docs/architecture/overview.mdx

@@ -0,0 +1,58 @@
+---
+title: 'Architecture Overview'
+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**.
+
+## Monorepo Structure
+
+| 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 |
+
+## Data Flow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
+│   opm push  │────▶│   Scanner   │────▶│  LLM Providers   │
+│   opm check │     │  (agents)   │     │ OpenRouter/OpenAI│
+└─────────────┘     └──────┬──────┘     └──────────────────┘
+       │                   │
+       │                   ▼
+       │            ┌─────────────┐
+       │            │  Contract   │
+       │            │   Writer    │
+       │            └──────┬──────┘
+       │                   │
+       ▼                   ▼
+┌─────────────┐     ┌─────────────┐
+│  npm / ENS  │     │ Base Sepolia│
+└─────────────┘     └─────────────┘
+```
+
+## 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>

package/docs/architecture/scanner.mdx

@@ -0,0 +1,53 @@
+---
+title: 'Scanner Engine'
+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.
+
+## Memory Queue with Deduplication
+
+Scans are enqueued via <code>enqueueScan(packageName, version, onStatus?, options?)</code>. The queue:
+
+- Deduplicates concurrent scans for the same <code>name@version</code>
+- Supports local tarball context for pre-publish scans (no npm download)
+
+## 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)
+
+## 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:
+
+- **submitScoreOnChain**: Calls <code>OPMRegistry.submitScore()</code> with agent wallet
+- **setReportURIOnChain**: Calls <code>OPMRegistry.setReportURI()</code>
+
+Both require the agent to be authorized (owner-set or ZK-verified).

package/docs/cli/audit.mdx

@@ -0,0 +1,35 @@
+---
+title: 'opm audit'
+description: '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.
+
+## 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
+- Shows per-package risk level and CVE counts
+
+## Output
+
+| Column | Description |
+|--------|-------------|
+| Package | <code>name@version</code> |
+| 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) |
+
+Summary line: <code>X high · Y medium · Z low · W unverified · N CVEs</code>
+
+<Tip>
+Use <code>opm audit</code> for a quick security overview. Use <code>opm check</code> when you need AI analysis and typosquat detection.
+</Tip>
+
+## Environment Variables
+
+No environment variables are required. Uses built-in RPC and contract address.

package/docs/cli/check.mdx

@@ -0,0 +1,44 @@
+---
+title: 'opm check'
+description: 'Comprehensive dependency security scan.'
+---
+
+# opm check
+
+Comprehensive dependency security scan. Scans all dependencies in <code>package.json</code>, runs AI agents, and 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.
+
+## 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
+
+<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.
+</Note>
+
+<Tip>
+Run <code>opm fix</code> to auto-correct typosquats and vulnerable versions identified by <code>opm check</code>.
+</Tip>

package/docs/cli/fix.mdx

@@ -0,0 +1,49 @@
+---
+title: 'opm fix'
+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.
+
+## 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>
+
+## 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
+
+<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.
+</Warning>
+
+<Tip>
+Review the diff in <code>package.json</code> before committing. AI-suggested replacements require consensus from 2+ agents before being applied.
+</Tip>

package/docs/cli/info.mdx

@@ -0,0 +1,44 @@
+---
+title: 'opm info'
+description: 'Show on-chain security information 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.
+
+## Usage
+
+<CodeGroup>
+
+```bash Latest version
+opm info lodash
+```
+
+```bash Specific version
+opm info lodash@4.17.21
+```
+
+</CodeGroup>
+
+## Output
+
+| 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
+
+<Note>
+If the package is not in the OPM registry, a warning is shown. No env vars are required.
+</Note>

package/docs/cli/install.mdx

@@ -0,0 +1,71 @@
+---
+title: 'opm install'
+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.
+
+## Usage
+
+<CodeGroup>
+
+```bash Install specific package
+opm install lodash
+```
+
+```bash Install with version
+opm install lodash@4.17.21
+```
+
+```bash Install 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>
+
+## 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
+
+<Warning>
+Installation is **blocked** if:
+- Risk score ≥ 70 (on-chain)
+- Any CRITICAL CVE is present (OSV)
+- ChainPatrol returns BLOCKED (for unregistered packages)
+</Warning>
+
+## Fallback Behavior
+
+<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>
+
+## Environment Variables
+
+No environment variables are required for basic install. Defaults for RPC, contract address, and API URLs are built-in.
+
+<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>

package/docs/cli/push.mdx

@@ -0,0 +1,99 @@
+---
+title: 'opm push'
+description: 'Sign, scan, publish, and register a package on-chain.'
+---
+
+# opm push
+
+Sign, scan, publish, and register a package on-chain. The full verification pipeline runs before publishing to npm and registering on the OPMRegistry.
+
+## What It Does
+
+<Steps>
+  <Step title="Pack tarball">
+    Creates an npm tarball via <code>npm pack</code> and computes SHA-256 checksum over the packed file.
+  </Step>
+  <Step title="Sign checksum">
+    Signs the checksum with ECDSA (secp256k1) using your <code>OPM_SIGNING_KEY</code>.
+  </Step>
+  <Step title="Resolve ENS">
+    Resolves your wallet address to an ENS name (Base Sepolia, then Ethereum Mainnet fallback).
+  </Step>
+  <Step title="Security scan">
+    Runs 3 AI agents in parallel (Claude, Gemini, DeepSeek) to analyze the package. Each agent submits a risk score (0–100) and reasoning on-chain.
+  </Step>
+  <Step title="Risk check">
+    If aggregate score ≥ 80 or risk level is CRITICAL, publishing is blocked.
+  </Step>
+  <Step title="Publish to npm">
+    Publishes the tarball to the npm registry (uses <code>--token</code> or <code>NPM_TOKEN</code> for automation).
+  </Step>
+  <Step title="Register on-chain">
+    Calls <code>OPMRegistry.registerPackage()</code> with package name, version, checksum, signature, and ENS name.
+  </Step>
+</Steps>
+
+## Usage
+
+<CodeGroup>
+
+```bash Basic
+opm push
+```
+
+```bash With npm token
+opm push --token <npm-token>
+```
+
+```bash With 2FA code
+opm push --otp <code>
+```
+
+</CodeGroup>
+
+## Required Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `OPM_SIGNING_KEY` | Ethereum private key for package signing (ECDSA) |
+| `OPENROUTER_API_KEY` or `OPENAI_API_KEY` | At least one required for AI agent scanning |
+| `AGENT_PRIVATE_KEY` | Agent wallet for submitting scores on-chain (must hold Base Sepolia ETH for gas) |
+
+## Optional Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `NPM_TOKEN` | npm automation token (alternative to <code>--token</code> flag) |
+| `FILEVERSE_API_KEY` | Upload audit report to IPFS via Fileverse |
+
+## Risk Blocking
+
+<Warning>
+Packages with **risk score ≥ 80** or **CRITICAL** level are blocked from publishing. The scan step fails, npm publish is skipped, and on-chain registration does not occur.
+</Warning>
+
+When blocked, the CLI shows which agents scored the package and the aggregate risk. Fix the issues and run <code>opm push</code> again.
+
+## What Gets Stored On-Chain
+
+After a successful push, the following data is recorded on the OPMRegistry:
+
+| Data | Description |
+|------|-------------|
+| Package name | From <code>package.json</code> |
+| Version | Semantic version |
+| Checksum | SHA-256 hash of the tarball |
+| Signature | ECDSA signature of the checksum |
+| ENS name | Author identity (e.g. <code>vitalik.eth</code>) |
+| Agent scores | Per-agent risk scores and reasoning |
+| Report URI | Fileverse/IPFS link to the full audit report |
+
+## Output
+
+- **Etherscan links** for every transaction: score submissions (one per agent) and package registration
+- **Report URI** link when uploaded to Fileverse
+- **npm package URL** on successful publish
+
+<Note>
+If 2FA is enabled on your npm account, use <code>opm push --otp &lt;code&gt;</code> or an npm automation token with "bypass 2FA" enabled.
+</Note>

package/docs/cli/register-agent.mdx

@@ -0,0 +1,80 @@
+---
+title: 'opm register-agent'
+description: 'Register a new security agent with ZK-verified benchmarks.'
+---
+
+# opm register-agent
+
+Register a new security agent with ZK-verified benchmarks. Agents must pass 10 benchmark cases with 100% accuracy and produce a valid ZK proof before they can submit scores on-chain.
+
+## Usage
+
+```bash
+opm register-agent --name <name> --model <model> [--system-prompt <prompt>]
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| <code>--name</code> | Yes | Agent identifier (e.g. <code>my-security-agent</code>) |
+| <code>--model</code> | Yes | LLM model (e.g. <code>anthropic/claude-sonnet-4-20250514</code>) |
+| <code>--system-prompt</code> | No | Custom system prompt (defaults to OPM security auditor prompt) |
+
+## Required Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| <code>AGENT_PRIVATE_KEY</code> | Wallet that becomes the agent identity; must hold Base Sepolia ETH for gas |
+| <code>OPENROUTER_API_KEY</code> or <code>OPENAI_API_KEY</code> | Required to run benchmark LLM calls |
+
+## Process
+
+<Steps>
+  <Step title="Validate configuration">
+    Checks agent name, model, and required env vars.
+  </Step>
+  <Step title="Run benchmark suite">
+    Executes 10 labeled test cases across categories: clean, typosquat, malicious, cve, obfuscated, exfiltration, dependency_confusion.
+  </Step>
+  <Step title="Generate ZK proof">
+    Produces a zero-knowledge proof that the agent achieved 100% accuracy without revealing test data or expected outputs.
+  </Step>
+  <Step title="Register on-chain">
+    Calls <code>OPMRegistry.registerAgent()</code> with name, model, system prompt hash, and proof hash.
+  </Step>
+</Steps>
+
+## Benchmark Categories
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| clean | 3 | Legitimate packages (string utils, math, validator) |
+| typosquat | 1 | Typosquat with credential exfiltration |
+| malicious | 2 | Postinstall shell, SSH key exfiltration |
+| cve | 1 | Known prototype pollution CVE |
+| obfuscated | 1 | Obfuscated reverse shell |
+| exfiltration | 1 | Env var exfiltration on import |
+| dependency_confusion | 1 | Internal scope shadowing + exfiltration |
+
+## Requirements
+
+<Warning>
+**100% accuracy** is required. The agent must pass all 10 benchmark cases. Each case is evaluated by score range and risk level ordinal.
+</Warning>
+
+<Note>
+The ZK proof hides test data and individual results. Only the commitment hash and proof hash are stored on-chain.
+</Note>
+
+## Success
+
+On success:
+- Etherscan transaction link is shown
+- Agent is authorized to submit scores
+- Agent participates in the next package scan alongside existing agents
+
+## Failure
+
+On failure, the CLI shows:
+- Which benchmark cases failed and why
+- Expected vs actual risk level and score
+- Rejection reason (e.g. "Agent achieved 90% accuracy (100% required)")