opmsec 0.1.0 → 0.1.3

package/docs/contract/functions.mdx

@@ -0,0 +1,220 @@
+---
+title: 'Contract Functions'
+description: 'All OPMRegistry functions with parameters and behavior.'
+---
+
+# Contract Functions
+
+## Admin (Owner Only)
+
+### setAgent
+
+```solidity
+function setAgent(address agent, bool status) external onlyOwner
+```
+
+Authorize or deauthorize an agent. Only the contract owner can call this.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| agent | address | Agent wallet address |
+| status | bool | true = authorized, false = deauthorized |
+
+### revokeAgent
+
+```solidity
+function revokeAgent(address agent) external onlyOwner
+```
+
+Deactivate a registered agent. Sets <code>active</code> to false and removes from <code>authorizedAgents</code>.
+
+---
+
+## Package Registration (Public)
+
+### registerPackage
+
+```solidity
+function registerPackage(
+    string calldata name,
+    string calldata version,
+    bytes32 checksum,
+    bytes calldata sig,
+    string calldata ensName
+) external
+```
+
+Register a package version. Callable by anyone; the sender becomes the author.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Package name |
+| version | string | Semantic version |
+| checksum | bytes32 | SHA-256 of tarball |
+| sig | bytes | ECDSA signature of checksum |
+| ensName | string | Author ENS name (e.g. vitalik.eth) |
+
+Reverts if the version is already registered.
+
+---
+
+## Agent-Only (Authorized Agents)
+
+### submitScore
+
+```solidity
+function submitScore(
+    string calldata name,
+    string calldata version,
+    uint8 riskScore,
+    string calldata reasoning
+) external onlyAgent
+```
+
+Submit a risk score (0–100) for a package version. Each agent may score a version only once.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Package name |
+| version | string | Semantic version |
+| riskScore | uint8 | Risk score 0–100 |
+| reasoning | string | Agent reasoning |
+
+### setReportURI
+
+```solidity
+function setReportURI(
+    string calldata name,
+    string calldata version,
+    string calldata uri
+) external onlyAgent
+```
+
+Set the Fileverse/IPFS report URI for a package version.
+
+---
+
+## Permissionless Agent Registration
+
+### registerAgent
+
+```solidity
+function registerAgent(
+    string calldata name,
+    string calldata model,
+    bytes32 systemPromptHash,
+    bytes32 proofHash
+) external
+```
+
+Register a new agent with ZK-verified benchmark proof. Callable by anyone; the sender becomes the agent.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Agent identifier |
+| model | string | LLM model (e.g. anthropic/claude-sonnet-4) |
+| systemPromptHash | bytes32 | Keccak256 of system prompt |
+| proofHash | bytes32 | Keccak256 of ZK proof |
+
+Reverts if the sender is already authorized or registered, or if <code>proofHash</code> is zero.
+
+---
+
+## View Functions
+
+### getPackageInfo
+
+```solidity
+function getPackageInfo(string calldata name, string calldata version)
+    external view returns (
+        address author,
+        bytes32 checksum,
+        bytes memory sig,
+        string memory ensName,
+        string memory reportURI,
+        uint8 aggregateScore,
+        bool exists
+    )
+```
+
+Returns full package info for a version. <code>aggregateScore</code> is the mean of all agent scores.
+
+### getScores
+
+```solidity
+function getScores(string calldata name, string calldata version)
+    external view returns (AgentScore[] memory)
+```
+
+Returns all agent scores for a package version. Each <code>AgentScore</code> has <code>agent</code>, <code>riskScore</code>, <code>reasoning</code>.
+
+### getAggregateScore
+
+```solidity
+function getAggregateScore(string calldata name, string calldata version)
+    external view returns (uint8)
+```
+
+Returns the mean risk score (0 if no scores).
+
+### getSafestVersion
+
+```solidity
+function getSafestVersion(string calldata name, uint8 lookback)
+    external view returns (string memory)
+```
+
+Returns the lowest-risk version among the last <code>lookback</code> versions. Default lookback is 3.
+
+### getVersions
+
+```solidity
+function getVersions(string calldata name)
+    external view returns (string[] memory)
+```
+
+Returns all registered versions for a package.
+
+### getAuthorByAddress
+
+```solidity
+function getAuthorByAddress(address addr)
+    external view returns (AuthorProfile memory)
+```
+
+Returns author profile by wallet address. <code>AuthorProfile</code> includes <code>addr</code>, <code>ensName</code>, <code>reputationTotal</code>, <code>reputationCount</code>, <code>packagesPublished</code>.
+
+### getAuthorByENS
+
+```solidity
+function getAuthorByENS(string calldata ensName)
+    external view returns (AuthorProfile memory)
+```
+
+Returns author profile by ENS name. Reverts if ENS not found.
+
+### getAuthorReputation
+
+```solidity
+function getAuthorReputation(address addr)
+    external view returns (uint256)
+```
+
+Returns average reputation (mean of all scores received) for an author. 0 if no scores.
+
+### getRegisteredAgent
+
+```solidity
+function getRegisteredAgent(address agent)
+    external view returns (RegisteredAgent memory)
+```
+
+Returns registered agent info: <code>agentAddress</code>, <code>name</code>, <code>model</code>, <code>systemPromptHash</code>, <code>proofHash</code>, <code>registeredAt</code>, <code>active</code>.
+
+### getAgentCount
+
+```solidity
+function getAgentCount() external view returns (uint256)
+```
+
+Returns the number of registered agents.

package/docs/contract/overview.mdx

@@ -0,0 +1,58 @@
+---
+title: 'Contract Overview'
+description: 'OPMRegistry smart contract deployed on Base Sepolia.'
+---
+
+# Contract Overview
+
+The **OPMRegistry** is the core on-chain component of OPM. It stores package metadata, agent scores, author profiles, and registered agents on Base Sepolia.
+
+## Deployment
+
+| Property | Value |
+|----------|-------|
+| Contract | OPMRegistry.sol |
+| Network | Base Sepolia (chain ID 84532) |
+| Address | <code>0x16684391fc9bf48246B08Afe16d1a57BFa181d48</code> |
+| Solidity | 0.8.20 |
+
+<Note>
+View the contract on [BaseScan](https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48).
+</Note>
+
+## Design
+
+### Owner Pattern
+
+The contract uses an owner pattern for initial agent authorization. The deployer is the owner and can:
+
+- Authorize or deauthorize agents via <code>setAgent(address, bool)</code>
+- Revoke permissionless agents via <code>revokeAgent(address)</code>
+
+### Permissionless Agent Registration
+
+New agents can register without owner approval by passing the benchmark verification:
+
+1. Run 10 labeled benchmark cases
+2. Achieve 100% accuracy
+3. Generate a ZK proof of accuracy
+4. Call <code>registerAgent(name, model, systemPromptHash, proofHash)</code>
+
+On success, the agent is automatically authorized to submit scores.
+
+### Data Stored
+
+| Data | Description |
+|------|-------------|
+| **Packages** | Name → versions mapping |
+| **Version data** | Per (name, version): author, checksum, signature, report URI, agent scores |
+| **Authors** | Address → profile (ENS name, reputation, packages published) |
+| **Agents** | Authorized agents (owner-set or ZK-verified) |
+| **Registered agents** | Permissionless agents with name, model, proof hash |
+
+## Risk Thresholds
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| <code>HIGH_RISK_THRESHOLD</code> | 70 | Blocks install; high-risk packages |
+| <code>MEDIUM_RISK_THRESHOLD</code> | 40 | Warning threshold |

package/docs/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#0a0a0a"/>
+  <path d="M8 10L12 22L16 13L20 22L24 10" stroke="#ededed" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="16" cy="24" r="1.5" fill="#4ade80"/>
+</svg>

package/docs/introduction.mdx

@@ -0,0 +1,43 @@
+---
+title: 'Introduction'
+description: 'OPM is a drop-in npm replacement that adds cryptographic signing, multi-agent AI security auditing, on-chain risk scoring, and ZK-verified permissionless agent registration to the JavaScript supply chain.'
+---
+
+# Introduction
+
+**OPM (On-chain Package Manager)** is a security-hardened CLI wrapper around npm that introduces cryptographic package attestation, multi-agent AI threat analysis, on-chain audit registries, and decentralized report storage to the JavaScript dependency supply chain. It functions as a drop-in npm replacement while interposing a verification pipeline between the developer and the npm registry.
+
+## The Problem
+
+The npm ecosystem faces persistent supply chain threats:
+
+- **Supply chain injection**: Malicious postinstall scripts, obfuscated payloads, environment variable exfiltration, and runtime code generation
+- **Typosquatting**: Package names designed to mimic popular packages (e.g., `lodash` vs `lodahs`)
+- **Malicious packages**: Deliberately harmful code in dependencies, often introduced via maintainer takeover
+- **Dependency confusion**: Scoped vs unscoped name conflicts and internal package shadowing
+- **Known vulnerabilities**: Unpatched CVEs and GHSA advisories in transitive dependencies
+
+Traditional package managers lack cryptographic provenance, real-time threat intelligence, and decentralized trust signals. OPM addresses these gaps.
+
+## The Solution
+
+OPM combines four layers of defense:
+
+1. **Cryptographic attestation**: SHA-256 checksums and ECDSA signatures (secp256k1) derived from Ethereum wallets, with on-chain registration
+2. **Multi-agent AI auditing**: Three heterogeneous LLMs (Claude, Gemini, DeepSeek) analyze packages in parallel and submit intelligence-weighted risk scores on-chain
+3. **On-chain registry**: Risk scores, author profiles, and report URIs stored on **Base Sepolia** (chain ID 84532) in the `OPMRegistry` smart contract
+4. **ZK-verified agent registration**: Permissionless agents must pass a benchmark suite and prove 100% accuracy via zero-knowledge proofs before participating
+
+## Key Integrations
+
+| Integration | Purpose |
+|-------------|---------|
+| **Base Sepolia** | EVM chain for OPMRegistry deployment and score submission |
+| **ENS** | Author identity resolution (forward/reverse) and profile metadata |
+| **Fileverse** | IPFS-backed encrypted storage for AI scan reports (dDocs protocol) |
+| **OSV** | Real-time CVE/GHSA advisory data with CVSS v3 scoring |
+| **ChainPatrol** | Blocklist fallback for packages absent from the registry |
+
+## Architecture Overview
+
+OPM implements a domain-specific instantiation of the [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004) pattern: agents hold on-chain identities, submit structured reputation signals (risk scores + reasoning), and attach off-chain validation evidence as Fileverse report URIs. Consumers invoking `opm install` query the registry, verify signatures, cross-reference OSV, and enforce configurable risk thresholds before permitting installation.

package/docs/logo/dark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 32" fill="none">
+  <path d="M4 8L8 24L12 14L16 24L20 8" stroke="#ededed" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="27" r="1.5" fill="#4ade80"/>
+  <text x="28" y="22" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600" fill="#ededed" letter-spacing="-0.5">opm</text>
+</svg>

package/docs/logo/light.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 32" fill="none">
+  <path d="M4 8L8 24L12 14L16 24L20 8" stroke="#0a0a0a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="27" r="1.5" fill="#16a34a"/>
+  <text x="28" y="22" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600" fill="#0a0a0a" letter-spacing="-0.5">opm</text>
+</svg>

package/docs/mint.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://mintlify.com/schema.json",
+  "name": "OPM Documentation",
+  "logo": {
+    "dark": "/logo/dark.svg",
+    "light": "/logo/light.svg"
+  },
+  "favicon": "/favicon.svg",
+  "colors": {
+    "primary": "#ffffff",
+    "light": "#ededed",
+    "dark": "#0a0a0a",
+    "background": {
+      "dark": "#0a0a0a"
+    }
+  },
+  "topbarLinks": [
+    {
+      "name": "Website",
+      "url": "https://opm.dev"
+    }
+  ],
+  "topbarCtaButton": {
+    "name": "GitHub",
+    "url": "https://github.com/dhananjaypai08/opm"
+  },
+  "tabs": [
+    {
+      "name": "CLI Reference",
+      "url": "cli"
+    },
+    {
+      "name": "Smart Contract",
+      "url": "contract"
+    },
+    {
+      "name": "Architecture",
+      "url": "architecture"
+    }
+  ],
+  "anchors": [
+    {
+      "name": "BaseScan",
+      "icon": "cube",
+      "url": "https://sepolia.basescan.org/address/0x16684391fc9bf48246B08Afe16d1a57BFa181d48"
+    },
+    {
+      "name": "npm",
+      "icon": "npm",
+      "url": "https://www.npmjs.com/package/opmsec"
+    }
+  ],
+  "navigation": [
+    {
+      "group": "Getting Started",
+      "pages": [
+        "introduction",
+        "quickstart",
+        "configuration"
+      ]
+    },
+    {
+      "group": "Core Concepts",
+      "pages": [
+        "concepts/security-model",
+        "concepts/multi-agent-consensus",
+        "concepts/on-chain-registry",
+        "concepts/zk-agent-verification"
+      ]
+    },
+    {
+      "group": "CLI Reference",
+      "pages": [
+        "cli/push",
+        "cli/install",
+        "cli/check",
+        "cli/fix",
+        "cli/audit",
+        "cli/info",
+        "cli/view",
+        "cli/register-agent"
+      ]
+    },
+    {
+      "group": "Smart Contract",
+      "pages": [
+        "contract/overview",
+        "contract/functions",
+        "contract/events",
+        "contract/deployment"
+      ]
+    },
+    {
+      "group": "Architecture",
+      "pages": [
+        "architecture/overview",
+        "architecture/scanner",
+        "architecture/agents",
+        "architecture/benchmarks"
+      ]
+    }
+  ],
+  "footerSocials": {
+    "github": "https://github.com/dhananjaypai08/opm"
+  }
+}

package/docs/quickstart.mdx

@@ -0,0 +1,133 @@
+---
+title: 'Quickstart'
+description: 'Get OPM up and running in minutes. Install the CLI, configure environment variables, and run your first security-verified install.'
+---
+
+# Quickstart
+
+## 1. Install
+
+<CodeGroup>
+
+```bash npm
+npm i -g opmsec
+```
+
+```bash bun
+bun add -g opmsec
+```
+
+</CodeGroup>
+
+The `opm` binary is available globally after installation.
+
+## 2. Set Environment Variables
+
+<Note>
+**Read-only commands** (`install`, `audit`, `info`, `view`, `whois`, `check`) require **no configuration**. Defaults for RPC, contract address, and API URLs are built-in.
+</Note>
+
+For **author-side commands** (`push`, `register-agent`), configure:
+
+<CodeGroup>
+
+```bash .env
+# Required for opm push
+OPM_SIGNING_KEY=0x...        # Your Ethereum private key for package signing
+AGENT_PRIVATE_KEY=0x...      # Agent wallet key for score submission
+NPM_TOKEN=...                # npm automation token (optional; use --token flag otherwise)
+
+# At least one required for AI scanning
+OPENROUTER_API_KEY=...       # Multi-model access (Claude, Gemini, DeepSeek)
+# OR
+OPENAI_API_KEY=...           # Fallback (GPT-4.1 family)
+
+# Optional: report uploads to IPFS
+FILEVERSE_API_KEY=...
+```
+
+</CodeGroup>
+
+## 3. Basic Usage
+
+### Security-Verified Install
+
+<CodeGroup>
+
+```bash Install specific package
+opm install lodash
+```
+
+```bash Install with version
+opm install lodash@4.17.21
+```
+
+```bash Verify all dependencies
+opm install
+```
+
+</CodeGroup>
+
+`opm install` resolves versions against the on-chain registry, verifies ECDSA signatures, checks OSV for CVEs, and blocks installation if risk exceeds the threshold (80).
+
+### Sign, Scan, and Publish
+
+```bash
+opm push
+```
+
+Computes SHA-256 checksum, signs with your wallet, dispatches 3 AI agents in parallel, submits scores on-chain, uploads report to Fileverse, publishes to npm, and registers on OPMRegistry.
+
+### Scan Dependencies
+
+```bash
+opm check
+```
+
+Scans all `dependencies` and `devDependencies` for typosquats, CVEs, and AI-detected risks. Outputs categorized findings.
+
+### On-Chain Audit
+
+```bash
+opm audit
+```
+
+Audits all dependencies against on-chain risk scores and CVE data.
+
+### View Package Info
+
+```bash
+opm info lodash
+```
+
+Displays on-chain security metadata: author, checksum, aggregate score, report URI.
+
+### View Author Profile
+
+```bash
+opm view vitalik.eth
+```
+
+Resolves ENS identity, fetches avatar and text records, and displays on-chain author reputation and published packages.
+
+## What Happens Under the Hood
+
+### `opm push` Verification Pipeline
+
+1. **Checksum**: SHA-256 over packed tarball
+2. **Sign**: ECDSA signature with author's Ethereum private key
+3. **ENS**: Resolve author identity (Sepolia, Mainnet fallback)
+4. **AI agents**: 3 models run in parallel—static analysis, risk scoring (0–100), structured JSON
+5. **On-chain**: Agent wallets call `OPMRegistry.submitScore()`; aggregate computed; publish blocked if score ≥ 80
+6. **Fileverse**: Upload formatted markdown report (encrypted, IPFS-synced)
+7. **npm**: Publish tarball (automation token or OTP for 2FA)
+8. **Registry**: `registerPackage()` stores checksum, signature, ENS name, report URI
+
+### `opm install` Verification Pipeline
+
+1. Resolve version against on-chain registry
+2. Query OSV API for CVE/GHSA advisories (CRITICAL blocks install)
+3. Fetch on-chain risk score and agent consensus
+4. Verify ECDSA signature against tarball checksum
+5. ChainPatrol API fallback for packages not in registry
+6. Delegate to `npm install` if all gates pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opmsec",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "private": false,
   "bin": {
     "opm": "packages/cli/src/index.tsx"
@@ -31,9 +31,9 @@
     "bun-types": "latest"
   },
   "opm": {
-    "signature": "0x3fadce9e0ec0a721cbff5616e4cd35893ac76ab82108d48fdadd0159f4f5270602518dbdb4d10f7402432dc756f803a56cf6404c21eeb4e1e33e0875e37d38131b",
+    "signature": "0xacf623c584df3b03a13588107cb0024212b50a20078a74d3a19394ea7378f2b23c679f3e351fd27393c5212f09ead8c826af1f103f535b9a802944e27b5ffa081b",
     "author": "0x2a3942EbDd8c5ea3E66D3fC4301F56d0F15d4bE2",
     "ensName": "djpaiethg.eth",
-    "checksum": "0x4e5b5788abbb861fa5a9896b7c41cad069c29d076f5a689325bd659baa8ea57a"
+    "checksum": "0x5e73c81a9f22b1381766bbea30dee60a945ece4d320f3c4f65597beb0bc19269"
   }
 }

package/packages/cli/src/commands/author-view.tsx

@@ -5,6 +5,7 @@ import type { AuthorProfile } from '@opm/core';
 import { Header } from '../components/Header';
 import { StatusLine } from '../components/StatusLine';
 import { RiskBadge } from '../components/RiskBadge';
+import { Hyperlink } from '../components/Hyperlink';
 import { resolveAddress, getENSTextRecords, type ENSProfile } from '../services/ens';
 import {
   getAuthorProfile,
@@ -71,6 +72,10 @@ export function AuthorViewCommand({ ensName }: AuthorViewProps) {
     setEnsProfile(profile);
     update('profile', 'done');
 
+    const avatarPromise = profile.avatar
+      ? renderAvatar(profile.avatar).catch(() => null)
+      : Promise.resolve(null);
+
     update('onchain', 'running');
     let authorProfile: AuthorProfile | null = null;
     if (addr) {
@@ -100,6 +105,9 @@ export function AuthorViewCommand({ ensName }: AuthorViewProps) {
       update('packages', 'skip');
     }
 
+    const art = await avatarPromise;
+    if (art) setAvatarArt(art);
+
     setDone(true);
   }
 
@@ -218,7 +226,7 @@ export function AuthorViewCommand({ ensName }: AuthorViewProps) {
                     {pkg.reportURI && !pkg.reportURI.startsWith('local://') && (
                       <Box>
                         <Text color="gray">Report: </Text>
-                        <Text color="blue">{pkg.reportURI}</Text>
+                        <Hyperlink url={pkg.reportURI} />
                       </Box>
                     )}
                   </Box>