npmguard-cli 1.1.1 → 1.1.3

package/README.md

@@ -1,9 +1,197 @@
-# NpmGuard CLI
+# npmguard-cli
 
-> **TODO** — CLI will talk to the NpmGuard API server (not ENS/IPFS). Not yet implemented.
+Security-gated npm install. Runs every package through NpmGuard's audit
+engine before it touches your `node_modules`.
 
-Planned features:
+```bash
+npx npmguard-cli install express
+```
 
-- `npmguard check <package>` — run a security audit via the API
-- `npmguard install <package>` — audit-then-install workflow
-- Machine-readable JSON output for CI/CD integration
+- **SAFE** → installs immediately
+- **DANGEROUS** → warns, shows findings, asks before installing
+- **No audit yet** → offers to pay for one (Stripe or crypto), then streams
+  the results in real time
+
+## Install
+
+No install required — `npx` pulls the latest from npm:
+
+```bash
+npx npmguard-cli@latest install <pkg>
+```
+
+Or install globally:
+
+```bash
+npm install -g npmguard-cli
+npmguard install <pkg>
+```
+
+## Commands
+
+### `npmguard install <package>[@version]`
+
+The main command. Runs the full gate-then-install flow.
+
+```bash
+npmguard install express
+npmguard install lodash@4.17.21
+npmguard install @types/node@22
+
+# Force install even if the package is flagged DANGEROUS
+npmguard install left-pad --force
+```
+
+The command auto-detects your package manager (`npm` / `pnpm` / `yarn`) from
+lockfiles and runs the correct add command (`npm install`, `pnpm add`,
+`yarn add`).
+
+**Flow**:
+
+1. Resolves the version (`latest` if omitted)
+2. Asks the engine if the package has an existing audit
+3. **Found + SAFE** → runs `<pm> add <pkg>` directly
+4. **Found + DANGEROUS** → shows findings + capabilities, prompts `y/N`
+   (bypass with `--force`)
+5. **Not found** → asks how you want to pay for the audit:
+   - Stripe (credit card) — browser checkout via QR
+   - Browser wallet — MetaMask/Rabby signs in Brave or Chrome
+   - WalletConnect — mobile wallet signs a tx on Base Sepolia
+   - Install without audit (yolo)
+   - Cancel
+6. Streams audit events live for Stripe/WalletConnect, or waits for the
+   report when the browser-wallet page owns the live view
+7. Runs the install if the verdict is SAFE, or prompts otherwise
+
+### `npmguard audit <package>[@version]`
+
+Run a standalone audit without installing. Returns the verdict and exits.
+
+```bash
+npmguard audit is-number
+npmguard audit express@5.2.1
+```
+
+If the package hasn't been audited yet, the standalone audit command starts
+the Stripe checkout flow. Use `install` for the interactive browser-wallet
+and WalletConnect choices.
+
+### `npmguard check [--path <dir>]`
+
+Walk `package.json` in the given directory and check every dependency
+against NpmGuard's audit database. Useful for auditing an existing project.
+
+```bash
+cd my-project
+npmguard check
+# or
+npmguard check --path /path/to/other-project
+```
+
+## Payment options
+
+When a package hasn't been audited yet, an audit run costs real compute
+(LLM calls, sandbox execution). Three ways to pay:
+
+### Stripe (fiat)
+
+Opens a Stripe checkout page in the browser. After payment, the engine
+triggers the audit automatically. Works from any machine, no wallet
+required.
+
+### Browser wallet (crypto)
+
+The CLI prints a `https://npmguard.com/pay?...` URL and can open it in your
+default browser. Open that page in Brave or Chrome with MetaMask/Rabby
+enabled, connect the wallet, and confirm the Base Sepolia transaction. The
+browser starts the server-side audit with the tx hash, while the CLI waits
+for the persisted report before deciding whether to install.
+
+This is the desktop-friendly flow for extension wallets.
+
+### WalletConnect (crypto)
+
+The CLI generates a WalletConnect v2 QR code in the terminal. Scan it with
+any mobile wallet (MetaMask, Rainbow, Coinbase Wallet, etc.) and confirm
+the transaction. It also prints the raw WalletConnect URI for desktop
+wallets that support a "connect by URI" flow.
+
+Browser extension wallets do not automatically connect to a terminal
+process. If your wallet only works as a Brave/Chrome extension, use the
+browser wallet option instead.
+
+- **Chain**: Base Sepolia (testnet — free ETH from
+  [Alchemy faucet](https://www.alchemy.com/faucets/base-sepolia))
+- **Fee**: `0.0001 ETH` per audit
+- **Contract**: [`0xBF562626e4Afb883423Ec719e0270DB232bcB9eD`](https://sepolia.basescan.org/address/0xbf562626e4afb883423ec719e0270db232bcb9ed)
+
+Flow:
+
+1. CLI asks the engine for public crypto config (contract + fee), with a direct contract-read fallback
+2. You approve the tx in your wallet
+3. Engine verifies the receipt on Base Sepolia via Alchemy
+4. Audit starts, CLI streams events
+
+The on-chain event `AuditRequested(packageName, version, requester, feePaid)`
+acts as the payment proof. The engine decodes it and matches the args
+against your request before launching the audit.
+
+## Configuration
+
+The CLI talks to `https://npmguard.com` by default. You can override the
+API URL and the web app URL for local development:
+
+```bash
+# via flag
+npmguard --api http://localhost:8000 --web http://localhost:3000 install lodash
+
+# via env
+export NPMGUARD_API_URL=http://localhost:8000
+export NPMGUARD_WEB_URL=http://localhost:3000
+npmguard install lodash
+```
+
+No private key or paid RPC config is required from the user. For the
+WalletConnect path, the CLI uses `viem` with a public Base Sepolia RPC to
+read/confirm the transaction for local UX; your wallet broadcasts the tx,
+and the engine re-verifies the receipt with its own RPC before starting the
+audit.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Audit passed, package installed |
+| 1 | Audit failed / install aborted / network error |
+
+## Dependencies
+
+Intentionally minimal:
+
+- `commander` — CLI arg parsing
+- `chalk`, `ora`, `qrcode-terminal` — terminal UI
+- `eventsource` — SSE client for audit events
+- `viem` — read contract, encode calldata, wait for receipt
+- `@walletconnect/sign-client` — WalletConnect v2 session
+
+No private key handling in the CLI. The wallet signs and broadcasts; the
+CLI only observes.
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run build
+
+# Test against local engine
+node dist/index.js --api http://localhost:8000 install is-number
+```
+
+## Release
+
+```bash
+npm version patch   # or minor / major
+npm run build
+npm publish --access public
+```

package/dist/api.js

@@ -10,6 +10,9 @@ async function request(url, options) {
     }
     return res.json();
 }
+export async function getPublicConfig(apiUrl) {
+    return request(`${apiUrl}/config/public`);
+}
 export async function checkout(apiUrl, packageName, version) {
     const body = { packageName };
     if (version)

package/dist/commands/install.js

@@ -3,7 +3,7 @@ import ora from "ora";
 import { spawnSync } from "node:child_process";
 import { formatEther } from "viem";
 import * as api from "../api.js";
-import { parsePackageArg, prompt, resolveLatestVersion, detectPackageManager, } from "../utils.js";
+import { parsePackageArg, prompt, resolveLatestVersion, detectPackageManager, openExternalUrl, } from "../utils.js";
 import { auditCommand } from "./audit.js";
 import { payViaWalletConnect, readAuditFee } from "../wallet/walletconnect.js";
 import { streamAuditEvents } from "../stream.js";
@@ -30,6 +30,7 @@ function extractCapabilities(report) {
 }
 export async function installCommand(packageSpec, opts) {
     const apiUrl = opts.api;
+    const webUrl = opts.web;
     let parsed;
     try {
         parsed = parsePackageArg(packageSpec);
@@ -73,20 +74,25 @@ export async function installCommand(packageSpec, opts) {
     console.log();
     console.log(chalk.bold("  How do you want to pay for the audit?"));
     console.log("    1) Stripe (credit card)");
-    console.log("    2) WalletConnect — ETH on Base Sepolia");
-    console.log("    3) Install without audit (at your own risk)");
-    console.log("    4) Cancel");
+    console.log("    2) Browser wallet — MetaMask/Rabby in Brave or Chrome");
+    console.log("    3) WalletConnect — QR/mobile wallet");
+    console.log("    4) Install without audit (at your own risk)");
+    console.log("    5) Cancel");
     console.log();
-    const choice = await prompt("  Choice [1/2/3/4]: ");
+    const choice = await prompt("  Choice [1/2/3/4/5]: ");
     if (choice === "1") {
         await runStripeAuditAndInstall(fullSpec, name, version, apiUrl);
         return;
     }
     if (choice === "2") {
-        await runCryptoAuditAndInstall(fullSpec, name, version, apiUrl);
+        await runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl, webUrl);
         return;
     }
     if (choice === "3") {
+        await runCryptoAuditAndInstall(fullSpec, name, version, apiUrl);
+        return;
+    }
+    if (choice === "4") {
         console.log(chalk.yellow("  Installing without audit. Proceed at your own risk."));
         process.exit(runInstall(fullSpec));
     }
@@ -139,16 +145,86 @@ async function runStripeAuditAndInstall(fullSpec, name, version, apiUrl) {
     }
     await finalizeAfterAudit(fullSpec, name, version, apiUrl);
 }
+function buildBrowserWalletUrl(webUrl, packageName, version) {
+    const url = new URL("/pay", webUrl.replace(/\/+$/, ""));
+    url.searchParams.set("packageName", packageName);
+    url.searchParams.set("version", version);
+    url.searchParams.set("source", "cli");
+    return url.toString();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForPackageReport(apiUrl, packageName, version, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const report = await api.getPackageReport(apiUrl, packageName, version);
+        if (report)
+            return report;
+        await sleep(3000);
+    }
+    return null;
+}
+async function runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl, webUrl) {
+    const paymentUrl = buildBrowserWalletUrl(webUrl, name, version);
+    console.log();
+    console.log(chalk.bold("  Open this URL in Brave or Chrome with MetaMask/Rabby:"));
+    console.log(chalk.blue.underline(`  ${paymentUrl}`));
+    console.log();
+    console.log(chalk.gray("  The browser page will connect your wallet, sign the Base Sepolia tx, and start the audit."));
+    console.log(chalk.gray("  Keep this terminal open; it will continue when the report is ready."));
+    console.log();
+    const openAnswer = await prompt("  Open it now in your default browser? (Y/n) ");
+    if (openAnswer !== "n" && openAnswer !== "no") {
+        const opened = openExternalUrl(paymentUrl);
+        if (!opened) {
+            console.log(chalk.yellow("  Could not open automatically. Copy the URL above."));
+        }
+    }
+    const spinner = ora("  Waiting for browser payment and audit report...").start();
+    let report = null;
+    try {
+        report = await waitForPackageReport(apiUrl, name, version, 30 * 60 * 1000);
+    }
+    catch (err) {
+        spinner.fail("Could not read report: " +
+            (err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+    if (!report) {
+        spinner.fail("Timed out waiting for the browser audit report.");
+        console.log(chalk.gray(`  Check ${webUrl.replace(/\/+$/, "")}/package/${encodeURIComponent(name)}`));
+        process.exit(1);
+    }
+    spinner.succeed("Audit report received");
+    await finalizeWithReport(fullSpec, report);
+}
 async function runCryptoAuditAndInstall(fullSpec, name, version, apiUrl) {
-    // 1. Read current fee from contract
+    // 1. Read current fee from the engine's public config, then fall back to
+    // direct contract read if the engine is older or config is unavailable.
     let feeWei;
+    let contractAddress;
     try {
-        feeWei = await readAuditFee();
+        const publicConfig = await api.getPublicConfig(apiUrl);
+        const contract = publicConfig.crypto?.contract;
+        const auditFeeWei = publicConfig.crypto?.auditFeeWei;
+        if (contract && /^0x[0-9a-fA-F]{40}$/.test(contract) && auditFeeWei) {
+            contractAddress = contract;
+            feeWei = BigInt(auditFeeWei);
+        }
+        else {
+            feeWei = await readAuditFee();
+        }
     }
     catch (err) {
-        console.error(chalk.red("Could not read fee from contract: " +
-            (err instanceof Error ? err.message : String(err))));
-        process.exit(1);
+        try {
+            feeWei = await readAuditFee();
+        }
+        catch {
+            console.error(chalk.red("Could not read fee from engine or contract: " +
+                (err instanceof Error ? err.message : String(err))));
+            process.exit(1);
+        }
     }
     const feeDisplay = `${formatEther(feeWei)} ETH`;
     const confirm = await prompt(chalk.yellow(`  Pay ${feeDisplay} on Base Sepolia? (y/N) `));
@@ -157,7 +233,7 @@ async function runCryptoAuditAndInstall(fullSpec, name, version, apiUrl) {
         process.exit(0);
     }
     // 2. WalletConnect → user signs → we get txHash
-    const result = await payViaWalletConnect(name, version, feeWei, feeDisplay);
+    const result = await payViaWalletConnect(name, version, feeWei, feeDisplay, contractAddress);
     if (!result.paid || !result.txHash) {
         console.log(chalk.red("  Payment failed, aborting."));
         process.exit(1);
@@ -189,7 +265,10 @@ async function finalizeAfterAudit(fullSpec, name, version, apiUrl) {
         console.log(chalk.red("  Audit finished but report not found."));
         process.exit(1);
     }
-    const verdict = extractVerdict(freshReport);
+    await finalizeWithReport(fullSpec, freshReport);
+}
+async function finalizeWithReport(fullSpec, report) {
+    const verdict = extractVerdict(report);
     if (verdict === "SAFE") {
         console.log(chalk.green("\n  ✓ SAFE — proceeding with install"));
         process.exit(runInstall(fullSpec));

package/dist/index.js

@@ -1,14 +1,25 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { readFileSync } from "node:fs";
 import { auditCommand } from "./commands/audit.js";
 import { checkCommand } from "./commands/check.js";
 import { installCommand } from "./commands/install.js";
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 const program = new Command();
 program
     .name("npmguard")
     .description("NpmGuard CLI — audit npm packages for security issues")
-    .version("1.0.0")
-    .option("--api <url>", "NpmGuard engine API URL", process.env.NPMGUARD_API_URL ?? "https://npmguard.com");
+    .version(readPackageVersion())
+    .option("--api <url>", "NpmGuard engine API URL", process.env.NPMGUARD_API_URL ?? "https://npmguard.com")
+    .option("--web <url>", "NpmGuard web app URL for browser wallet payments", process.env.NPMGUARD_WEB_URL ?? "https://npmguard.com");
 program
     .command("audit")
     .description("Pay for and run a security audit on an npm package")
@@ -23,8 +34,8 @@ program
     .argument("<package>", "Package name, optionally with version (e.g. express@4.18.0)")
     .option("-f, --force", "Install even if the package is flagged as dangerous")
     .action(async (pkg, cmdOpts) => {
-    const apiUrl = program.opts().api;
-    await installCommand(pkg, { api: apiUrl, force: cmdOpts.force });
+    const opts = program.opts();
+    await installCommand(pkg, { api: opts.api, web: opts.web, force: cmdOpts.force });
 });
 program
     .command("check")

package/dist/utils.js

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { spawn } from "node:child_process";
 export function parsePackageArg(pkg) {
     if (pkg.startsWith("@")) {
         const slashIndex = pkg.indexOf("/");
@@ -54,3 +55,27 @@ export function detectPackageManager(cwd = process.cwd()) {
         return "yarn";
     return "npm";
 }
+export function openExternalUrl(url) {
+    try {
+        const platform = process.platform;
+        const command = platform === "darwin"
+            ? "open"
+            : platform === "win32"
+                ? "cmd"
+                : "xdg-open";
+        const args = platform === "win32"
+            ? ["/c", "start", "", url]
+            : [url];
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/wallet/walletconnect.js

@@ -14,7 +14,7 @@ function generateQrCode(text) {
         });
     });
 }
-export async function payViaWalletConnect(packageName, version, feeWei, feeDisplay) {
+export async function payViaWalletConnect(packageName, version, feeWei, feeDisplay, contractAddress = AUDIT_REQUEST_ADDRESS_BASE_SEPOLIA) {
     const calldata = encodeFunctionData({
         abi: AUDIT_REQUEST_ABI,
         functionName: "requestAudit",
@@ -63,6 +63,10 @@ export async function payViaWalletConnect(packageName, version, feeWei, feeDispl
         console.log();
         await generateQrCode(uri);
         console.log();
+        console.log(chalk.cyan("  Desktop wallet? Paste this WalletConnect URI into your wallet:"));
+        console.log(chalk.gray(`  ${uri}`));
+        console.log(chalk.gray("  Keep it private; it is only for this pairing session."));
+        console.log();
         const pairSpinner = ora("  Waiting for wallet connection...").start();
         const session = await approval();
         const accounts = session.namespaces.eip155?.accounts ?? [];
@@ -84,7 +88,7 @@ export async function payViaWalletConnect(packageName, version, feeWei, feeDispl
                 params: [
                     {
                         from: sender,
-                        to: AUDIT_REQUEST_ADDRESS_BASE_SEPOLIA,
+                        to: contractAddress,
                         data: calldata,
                         value: "0x" + feeWei.toString(16),
                     },
@@ -120,13 +124,13 @@ export async function payViaWalletConnect(packageName, version, feeWei, feeDispl
         setTimeout(() => process.off("uncaughtException", wcErrorHandler), 5000);
     }
 }
-export async function readAuditFee() {
+export async function readAuditFee(contractAddress = AUDIT_REQUEST_ADDRESS_BASE_SEPOLIA) {
     const publicClient = createPublicClient({
         chain: baseSepolia,
         transport: http(),
     });
     return (await publicClient.readContract({
-        address: AUDIT_REQUEST_ADDRESS_BASE_SEPOLIA,
+        address: contractAddress,
         abi: AUDIT_REQUEST_ABI,
         functionName: "auditFee",
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npmguard-cli",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "description": "NpmGuard CLI — check npm packages against NpmGuard security audits",
   "main": "dist/index.js",
@@ -8,7 +8,7 @@
     "dist"
   ],
   "bin": {
-    "npmguard": "./dist/index.js"
+    "npmguard": "dist/index.js"
   },
   "scripts": {
     "build": "tsc"
@@ -27,7 +27,7 @@
     "eventsource": "^2.0.2",
     "ora": "^8.1.0",
     "qrcode-terminal": "^0.12.0",
-    "viem": "^2.47.17"
+    "viem": "^2.52.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",