npmguard-cli 1.1.3 → 1.1.5

package/README.md

@@ -7,7 +7,7 @@ engine before it touches your `node_modules`.
 npx npmguard-cli install express
 ```
 
-- **SAFE** → installs immediately
+- **SAFE** → installs immediately from the configured source
 - **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
@@ -50,7 +50,7 @@ lockfiles and runs the correct add command (`npm install`, `pnpm add`,
 
 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
+3. **Found + SAFE** → installs from the configured source
 4. **Found + DANGEROUS** → shows findings + capabilities, prompts `y/N`
    (bypass with `--force`)
 5. **Not found** → asks how you want to pay for the audit:
@@ -63,6 +63,30 @@ lockfiles and runs the correct add command (`npm install`, `pnpm add`,
    report when the browser-wallet page owns the live view
 7. Runs the install if the verdict is SAFE, or prompts otherwise
 
+The install source defaults to `auto`: after a SAFE verdict the CLI waits
+briefly for NpmGuard publication, then tries ENS, then the NpmGuard Pinata
+storage API, and only falls back to npm if no publication is available.
+
+The source is configurable:
+
+```bash
+# default: audited verdict, then ENS/Pinata when available
+npmguard install express --install-source auto
+
+# default: audited verdict, then normal registry install
+npmguard install express --install-source npm
+
+# audited verdict, then install the tarball published by NpmGuard on Pinata
+npmguard install express --install-source pinata
+
+# audited verdict, then resolve ENS text records to find the Pinata tarball
+npmguard install express --install-source ens
+```
+
+The source choice never replaces server-side verification. NpmGuard always
+checks the report store first; `pinata` and `ens` only decide where the SAFE
+package bytes come from.
+
 ### `npmguard audit <package>[@version]`
 
 Run a standalone audit without installing. Returns the verdict and exits.
@@ -151,6 +175,28 @@ export NPMGUARD_WEB_URL=http://localhost:3000
 npmguard install lodash
 ```
 
+Install source:
+
+```bash
+# via flag
+npmguard install lodash --install-source ens
+
+# via env
+export NPMGUARD_INSTALL_SOURCE=ens
+export NPMGUARD_ENS_ROOT_DOMAIN=npmguard-demo.eth
+export NPMGUARD_ENS_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
+npmguard install lodash
+```
+
+Available values:
+
+| Source | Behavior |
+|---|---|
+| `auto` | Tries ENS, then NpmGuard's Pinata storage API, then npm fallback |
+| `npm` | Installs `<package>@<version>` from the normal npm registry |
+| `pinata` | Reads `/package/<name>/storage?version=<version>` from NpmGuard and installs the pinned tarball URL |
+| `ens` | Resolves Sepolia ENS `npmguard.*` text records and installs the announced Pinata tarball |
+
 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,

package/dist/api.js

@@ -78,3 +78,16 @@ export async function getPackageReport(apiUrl, packageName, version) {
         throw err;
     }
 }
+export async function getPackageStorage(apiUrl, packageName, version) {
+    const query = `?version=${encodeURIComponent(version)}`;
+    const url = `${apiUrl}/package/${encodeURIComponent(packageName)}/storage${query}`;
+    try {
+        return await request(url);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("HTTP 404")) {
+            return null;
+        }
+        throw err;
+    }
+}

package/dist/commands/install.js

@@ -7,18 +7,85 @@ import { parsePackageArg, prompt, resolveLatestVersion, detectPackageManager, op
 import { auditCommand } from "./audit.js";
 import { payViaWalletConnect, readAuditFee } from "../wallet/walletconnect.js";
 import { streamAuditEvents } from "../stream.js";
+import { defaultEnsRootDomain, defaultEnsRpcUrl, normalizeInstallSource, resolveEnsInstallSpec, resolvePinataInstallSpec, resolvePublishedInstallSpec, } from "../install-source.js";
+const POST_AUDIT_STORAGE_WAIT_MS = Number(process.env.NPMGUARD_STORAGE_WAIT_MS ?? 90_000);
 /**
  * Run the correct "add this package" command for the detected package manager.
  * `npm install <pkg>` adds the package. `pnpm add <pkg>` / `yarn add <pkg>` do
  * the same. Crucially, `yarn install <pkg>` would ignore <pkg> in yarn classic.
  */
-function runInstall(packageSpec) {
+function runInstall(packageSpec, label) {
     const pm = detectPackageManager();
     const verb = pm === "npm" ? "install" : "add";
-    console.log(chalk.gray(`\n  Running: ${pm} ${verb} ${packageSpec}\n`));
+    console.log(chalk.gray(`\n  Running: ${pm} ${verb} ${packageSpec}${label ? `\n  Source: ${label}` : ""}\n`));
     const res = spawnSync(pm, [verb, packageSpec], { stdio: "inherit" });
     return res.status ?? 1;
 }
+async function resolveInstallTarget(fullSpec, packageName, version, opts, waitForPublishedMs = 0) {
+    const source = normalizeInstallSource(opts.installSource);
+    const rootDomain = opts.ensRoot ?? defaultEnsRootDomain();
+    const rpcUrl = opts.ensRpc ?? defaultEnsRpcUrl();
+    if (source === "auto") {
+        const deadline = Date.now() + waitForPublishedMs;
+        do {
+            const published = await resolvePublishedInstallSpec({
+                apiUrl: opts.api,
+                packageName,
+                version,
+                rootDomain,
+                rpcUrl,
+            });
+            if (published)
+                return published;
+            if (Date.now() < deadline)
+                await delay(3000);
+        } while (Date.now() < deadline);
+        return { spec: fullSpec, detail: "npm registry (ENS/Pinata publication not available yet)" };
+    }
+    if (source === "npm") {
+        return { spec: fullSpec, detail: "npm registry" };
+    }
+    if (source === "pinata") {
+        return retryInstallSource(() => resolvePinataInstallSpec(opts.api, packageName, version), waitForPublishedMs);
+    }
+    return retryInstallSource(() => resolveEnsInstallSpec({
+        packageName,
+        version,
+        rootDomain,
+        rpcUrl,
+    }), waitForPublishedMs);
+}
+async function installSafePackage(fullSpec, packageName, version, opts, waitForPublishedMs = 0) {
+    let target;
+    try {
+        target = await resolveInstallTarget(fullSpec, packageName, version, opts, waitForPublishedMs);
+    }
+    catch (err) {
+        console.error(chalk.red("Could not resolve install source: " +
+            (err instanceof Error ? err.message : String(err))));
+        console.log(chalk.gray("  Retry with --install-source npm to install from the npm registry."));
+        process.exit(1);
+    }
+    process.exit(runInstall(target.spec, target.detail));
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryInstallSource(resolve, waitMs) {
+    const deadline = Date.now() + waitMs;
+    let lastError;
+    do {
+        try {
+            return await resolve();
+        }
+        catch (err) {
+            lastError = err;
+            if (Date.now() < deadline)
+                await delay(3000);
+        }
+    } while (Date.now() < deadline);
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
 function extractVerdict(report) {
     const nested = report.report?.verdict;
     return (nested ?? report.verdict ?? "UNKNOWN").toUpperCase();
@@ -66,7 +133,7 @@ export async function installCommand(packageSpec, opts) {
     }
     spinner.stop();
     if (report) {
-        handleExistingReport(report, name, fullSpec, apiUrl, opts);
+        await handleExistingReport(report, name, version, fullSpec, apiUrl, opts);
         return;
     }
     // No audit found — ask how to pay
@@ -81,25 +148,25 @@ export async function installCommand(packageSpec, opts) {
     console.log();
     const choice = await prompt("  Choice [1/2/3/4/5]: ");
     if (choice === "1") {
-        await runStripeAuditAndInstall(fullSpec, name, version, apiUrl);
+        await runStripeAuditAndInstall(fullSpec, name, version, apiUrl, opts);
         return;
     }
     if (choice === "2") {
-        await runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl, webUrl);
+        await runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl, webUrl, opts);
         return;
     }
     if (choice === "3") {
-        await runCryptoAuditAndInstall(fullSpec, name, version, apiUrl);
+        await runCryptoAuditAndInstall(fullSpec, name, version, apiUrl, opts);
         return;
     }
     if (choice === "4") {
         console.log(chalk.yellow("  Installing without audit. Proceed at your own risk."));
-        process.exit(runInstall(fullSpec));
+        process.exit(runInstall(fullSpec, "npm registry (audit skipped)"));
     }
     console.log(chalk.gray("  Cancelled."));
     process.exit(0);
 }
-function handleExistingReport(report, name, fullSpec, apiUrl, opts) {
+async function handleExistingReport(report, name, version, fullSpec, apiUrl, opts) {
     const verdict = extractVerdict(report);
     const capabilities = extractCapabilities(report);
     if (verdict === "SAFE") {
@@ -107,7 +174,8 @@ function handleExistingReport(report, name, fullSpec, apiUrl, opts) {
         if (capabilities.length > 0) {
             console.log(chalk.gray(`  Capabilities: ${capabilities.join(", ")}`));
         }
-        process.exit(runInstall(fullSpec));
+        await installSafePackage(fullSpec, name, version, opts);
+        return;
     }
     if (verdict === "DANGEROUS" || verdict === "CRITICAL" || verdict === "WARNING") {
         console.log(chalk.bgRed.white.bold(`  ${verdict}  `));
@@ -119,23 +187,24 @@ function handleExistingReport(report, name, fullSpec, apiUrl, opts) {
         console.log();
         if (opts.force) {
             console.log(chalk.yellow("  --force passed, installing anyway..."));
-            process.exit(runInstall(fullSpec));
+            await installSafePackage(fullSpec, name, version, opts);
+            return;
         }
-        promptAndInstallIfAccepted(fullSpec, "  Install anyway? This package is flagged. (y/N) ");
+        await promptAndInstallIfAccepted(fullSpec, name, version, opts, "  Install anyway? This package is flagged. (y/N) ");
         return;
     }
     console.log(chalk.yellow(`  Verdict: ${verdict}`));
-    promptAndInstallIfAccepted(fullSpec, "  Proceed with install? (y/N) ");
+    await promptAndInstallIfAccepted(fullSpec, name, version, opts, "  Proceed with install? (y/N) ");
 }
-async function promptAndInstallIfAccepted(fullSpec, question) {
+async function promptAndInstallIfAccepted(fullSpec, name, version, opts, question) {
     const answer = await prompt(chalk.red.bold(question));
     if (answer === "y" || answer === "yes") {
-        process.exit(runInstall(fullSpec));
+        await installSafePackage(fullSpec, name, version, opts);
     }
     console.log(chalk.gray("  Aborted."));
     process.exit(1);
 }
-async function runStripeAuditAndInstall(fullSpec, name, version, apiUrl) {
+async function runStripeAuditAndInstall(fullSpec, name, version, apiUrl, opts) {
     try {
         await auditCommand(fullSpec, { api: apiUrl, exit: false });
     }
@@ -143,7 +212,7 @@ async function runStripeAuditAndInstall(fullSpec, name, version, apiUrl) {
         console.error(chalk.red("Audit failed: " + (err instanceof Error ? err.message : String(err))));
         process.exit(1);
     }
-    await finalizeAfterAudit(fullSpec, name, version, apiUrl);
+    await finalizeAfterAudit(fullSpec, name, version, apiUrl, opts);
 }
 function buildBrowserWalletUrl(webUrl, packageName, version) {
     const url = new URL("/pay", webUrl.replace(/\/+$/, ""));
@@ -153,7 +222,7 @@ function buildBrowserWalletUrl(webUrl, packageName, version) {
     return url.toString();
 }
 function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return delay(ms);
 }
 async function waitForPackageReport(apiUrl, packageName, version, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
@@ -165,7 +234,7 @@ async function waitForPackageReport(apiUrl, packageName, version, timeoutMs) {
     }
     return null;
 }
-async function runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl, webUrl) {
+async function runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl, webUrl, opts) {
     const paymentUrl = buildBrowserWalletUrl(webUrl, name, version);
     console.log();
     console.log(chalk.bold("  Open this URL in Brave or Chrome with MetaMask/Rabby:"));
@@ -197,9 +266,9 @@ async function runBrowserWalletAuditAndInstall(fullSpec, name, version, apiUrl,
         process.exit(1);
     }
     spinner.succeed("Audit report received");
-    await finalizeWithReport(fullSpec, report);
+    await finalizeWithReport(fullSpec, name, version, report, opts, POST_AUDIT_STORAGE_WAIT_MS);
 }
-async function runCryptoAuditAndInstall(fullSpec, name, version, apiUrl) {
+async function runCryptoAuditAndInstall(fullSpec, name, version, apiUrl, opts) {
     // 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;
@@ -257,26 +326,26 @@ async function runCryptoAuditAndInstall(fullSpec, name, version, apiUrl) {
     //    would trigger a second, unpaid audit via /checkout).
     await streamAuditEvents(apiUrl, auditId);
     // 5. Fetch the persisted report and decide whether to install
-    await finalizeAfterAudit(fullSpec, name, version, apiUrl);
+    await finalizeAfterAudit(fullSpec, name, version, apiUrl, opts);
 }
-async function finalizeAfterAudit(fullSpec, name, version, apiUrl) {
+async function finalizeAfterAudit(fullSpec, name, version, apiUrl, opts) {
     const freshReport = await api.getPackageReport(apiUrl, name, version);
     if (!freshReport) {
         console.log(chalk.red("  Audit finished but report not found."));
         process.exit(1);
     }
-    await finalizeWithReport(fullSpec, freshReport);
+    await finalizeWithReport(fullSpec, name, version, freshReport, opts, POST_AUDIT_STORAGE_WAIT_MS);
 }
-async function finalizeWithReport(fullSpec, report) {
+async function finalizeWithReport(fullSpec, name, version, report, opts, waitForPublishedMs = 0) {
     const verdict = extractVerdict(report);
     if (verdict === "SAFE") {
         console.log(chalk.green("\n  ✓ SAFE — proceeding with install"));
-        process.exit(runInstall(fullSpec));
+        await installSafePackage(fullSpec, name, version, opts, waitForPublishedMs);
     }
     console.log(chalk.red(`\n  Audit verdict: ${verdict}`));
     const confirm = await prompt(chalk.red.bold("  Install anyway? (y/N) "));
     if (confirm === "y" || confirm === "yes") {
-        process.exit(runInstall(fullSpec));
+        await installSafePackage(fullSpec, name, version, opts);
     }
     process.exit(1);
 }

package/dist/index.js

@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
 import { auditCommand } from "./commands/audit.js";
 import { checkCommand } from "./commands/check.js";
 import { installCommand } from "./commands/install.js";
+import { defaultEnsRootDomain, defaultEnsRpcUrl, normalizeInstallSource } from "./install-source.js";
 function readPackageVersion() {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
@@ -33,9 +34,19 @@ program
     .description("Install an npm package with NpmGuard security check")
     .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")
+    .option("--install-source <source>", "Install SAFE packages from auto, npm, pinata, or ens", process.env.NPMGUARD_INSTALL_SOURCE ?? "auto")
+    .option("--ens-root <name>", "ENS root domain for auto/ens install resolution", defaultEnsRootDomain())
+    .option("--ens-rpc <url>", "Sepolia RPC URL for auto/ens install resolution", defaultEnsRpcUrl())
     .action(async (pkg, cmdOpts) => {
     const opts = program.opts();
-    await installCommand(pkg, { api: opts.api, web: opts.web, force: cmdOpts.force });
+    await installCommand(pkg, {
+        api: opts.api,
+        web: opts.web,
+        force: cmdOpts.force,
+        installSource: normalizeInstallSource(cmdOpts.installSource),
+        ensRoot: cmdOpts.ensRoot,
+        ensRpc: cmdOpts.ensRpc,
+    });
 });
 program
     .command("check")

package/dist/install-source.js

@@ -0,0 +1,150 @@
+import { createPublicClient, http, parseAbi, toHex, zeroAddress } from "viem";
+import { sepolia } from "viem/chains";
+import { namehash, packetToBytes } from "viem/ens";
+import * as api from "./api.js";
+const DEFAULT_ENS_RPC_URL = "https://ethereum-sepolia-rpc.publicnode.com";
+const DEFAULT_ENS_ROOT_DOMAIN = "npmguard-demo.eth";
+const UNIVERSAL_RESOLVER = "0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe";
+const universalResolverAbi = parseAbi([
+    "function findResolver(bytes name) view returns (address resolver, bytes32 node, uint256 offset)",
+]);
+const resolverAbi = parseAbi([
+    "function text(bytes32 node, string key) view returns (string)",
+]);
+export function normalizeInstallSource(value) {
+    const source = (value ?? "auto").toLowerCase();
+    if (source === "auto" || source === "npm" || source === "pinata" || source === "ens")
+        return source;
+    throw new Error(`Invalid install source "${value}". Expected auto, npm, pinata, or ens.`);
+}
+export function defaultEnsRootDomain() {
+    return process.env.NPMGUARD_ENS_ROOT_DOMAIN ?? DEFAULT_ENS_ROOT_DOMAIN;
+}
+export function defaultEnsRpcUrl() {
+    return process.env.NPMGUARD_ENS_RPC_URL ?? process.env.SEPOLIA_RPC_URL ?? DEFAULT_ENS_RPC_URL;
+}
+function ensSafeLabel(value) {
+    const label = value
+        .replace(/^@/, "")
+        .replace(/[^a-z0-9-]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+    if (!label)
+        throw new Error(`Cannot derive an ENS label from "${value}"`);
+    return label.slice(0, 63);
+}
+function tarballFromStorage(storage) {
+    return (storage.storage.tarball?.gatewayUrl ??
+        storage.storage.manifest?.value?.tarball?.gatewayUrl ??
+        null);
+}
+export async function resolvePinataInstallSpec(apiUrl, packageName, version) {
+    const publication = await api.getPackageStorage(apiUrl, packageName, version);
+    if (!publication) {
+        throw new Error(`No Pinata publication found for ${packageName}@${version}`);
+    }
+    const tarballUrl = tarballFromStorage(publication);
+    if (!tarballUrl) {
+        throw new Error(`Pinata publication for ${packageName}@${version} has no installable tarball URL`);
+    }
+    return {
+        spec: tarballUrl,
+        detail: publication.storage.ens?.recordName
+            ? `Pinata tarball announced by ${publication.storage.ens.recordName}`
+            : "Pinata tarball from NpmGuard storage API",
+    };
+}
+async function readTextRecords(name, keys, rpcUrl) {
+    const client = createPublicClient({ chain: sepolia, transport: http(rpcUrl) });
+    const found = await client.readContract({
+        address: UNIVERSAL_RESOLVER,
+        abi: universalResolverAbi,
+        functionName: "findResolver",
+        args: [toHex(packetToBytes(name))],
+    });
+    const resolver = found.resolver ?? found[0] ?? zeroAddress;
+    if (!resolver || resolver === zeroAddress)
+        return {};
+    const node = namehash(name);
+    const records = {};
+    for (const key of keys) {
+        try {
+            const value = await client.readContract({
+                address: resolver,
+                abi: resolverAbi,
+                functionName: "text",
+                args: [node, key],
+            });
+            if (value)
+                records[key] = value;
+        }
+        catch {
+            // Some resolvers throw for missing keys; treat that as an empty record.
+        }
+    }
+    return records;
+}
+async function tarballFromManifest(manifestUrl) {
+    const res = await fetch(manifestUrl);
+    if (!res.ok)
+        return null;
+    const manifest = await res.json();
+    return manifest.tarball?.gatewayUrl ?? null;
+}
+export async function resolveEnsInstallSpec(options) {
+    const packageLabel = ensSafeLabel(options.packageName);
+    const versionLabel = ensSafeLabel(options.version || "latest");
+    const root = options.rootDomain.replace(/\.+$/, "");
+    const candidates = [
+        `${versionLabel}.${packageLabel}.${root}`,
+        `${packageLabel}.${root}`,
+        root,
+    ];
+    const keys = [
+        "npmguard.tarball_uri",
+        "npmguard.latest_tarball_uri",
+        "npmguard.manifest_uri",
+        "npmguard.latest_manifest_uri",
+        "npmguard.package",
+        "npmguard.version",
+        "npmguard.latest_version",
+    ];
+    for (const name of candidates) {
+        const records = await readTextRecords(name, keys, options.rpcUrl);
+        const recordPackage = records["npmguard.package"];
+        const recordVersion = records["npmguard.version"] ?? records["npmguard.latest_version"];
+        const packageMatches = !recordPackage || recordPackage === options.packageName;
+        const versionMatches = !recordVersion || recordVersion === options.version;
+        if (!packageMatches || !versionMatches)
+            continue;
+        const directTarball = records["npmguard.tarball_uri"] ?? records["npmguard.latest_tarball_uri"];
+        if (directTarball)
+            return { spec: directTarball, detail: `ENS ${name} -> Pinata tarball` };
+        const manifestUrl = records["npmguard.manifest_uri"] ?? records["npmguard.latest_manifest_uri"];
+        if (manifestUrl) {
+            const tarballUrl = await tarballFromManifest(manifestUrl);
+            if (tarballUrl)
+                return { spec: tarballUrl, detail: `ENS ${name} -> manifest -> Pinata tarball` };
+        }
+    }
+    throw new Error(`No installable ENS tarball record found for ${options.packageName}@${options.version}`);
+}
+export async function resolvePublishedInstallSpec(options) {
+    try {
+        return await resolveEnsInstallSpec({
+            packageName: options.packageName,
+            version: options.version,
+            rootDomain: options.rootDomain,
+            rpcUrl: options.rpcUrl,
+        });
+    }
+    catch {
+        // Fall through to the API-backed Pinata publication.
+    }
+    try {
+        return await resolvePinataInstallSpec(options.apiUrl, options.packageName, options.version);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npmguard-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "type": "module",
   "description": "NpmGuard CLI — check npm packages against NpmGuard security audits",
   "main": "dist/index.js",