cryptoserve 0.2.1 → 0.3.0

package/bin/cryptoserve.mjs

@@ -20,6 +20,7 @@
  *   cryptoserve vault init|set|get|list|delete|run|import|export
  *   cryptoserve login [--server URL]
  *   cryptoserve status
+ *   cryptoserve census [--format json|html] [--output file] [--no-cache] [--verbose]
  */
 
 import { readFileSync, writeFileSync } from 'node:fs';
@@ -40,7 +41,7 @@ const OPTIONS_WITH_VALUES = new Set([
 
 const KNOWN_FLAGS = new Set([
   '--insecure-storage', '--verbose', '--binary', '--fail-on-weak',
-  '--help', '--version',
+  '--help', '--version', '--no-cache',
 ]);
 
 function getFlag(args, name) {
@@ -91,6 +92,9 @@ async function cmdHelp() {
   console.log(`    ${info('cbom [path] [--format F] [--output O]')} Generate Crypto Bill of Materials`);
   console.log(`    ${info('gate [path] [--max-risk R]')}            CI/CD gate (exit 0=pass, 1=fail)`);
   console.log();
+  console.log(`  ${bold('Research')}`);
+  console.log(`    ${info('census [--format json|html]')}            Global crypto census (npm + PyPI + NVD)`);
+  console.log();
   console.log(`  ${bold('Encryption')}`);
   console.log(`    ${info('encrypt "text" [--context C]')}          Encrypt with context-aware algorithm selection`);
   console.log(`    ${info('encrypt "text" [--password P]')}         Encrypt text (interactive password if omitted)`);
@@ -988,6 +992,59 @@ function timeSince(date) {
   return `${days}d ago`;
 }
 
+// ---------------------------------------------------------------------------
+// Census — global crypto adoption survey
+// ---------------------------------------------------------------------------
+
+async function cmdCensus(args) {
+  const {
+    compactHeader, section, labelValue, tableHeader, tableRow,
+    warning, info, dim, bold, divider, progressBar,
+  } = await import('../lib/cli-style.mjs');
+
+  const format = getOption(args, '--format', 'text');
+  const output = getOption(args, '--output', null);
+  const verbose = getFlag(args, '--verbose');
+  const noCache = getFlag(args, '--no-cache');
+
+  const { runCensus } = await import('../lib/census/index.mjs');
+
+  if (format === 'text') {
+    console.log(compactHeader('census'));
+    console.log(dim('  Collecting data from npm, PyPI, NVD, and GitHub...'));
+    console.log(dim('  This may take 30-60 seconds on first run.\n'));
+  }
+
+  const data = await runCensus({ verbose, noCache });
+
+  if (format === 'json') {
+    const json = JSON.stringify(data, null, 2);
+    if (output) {
+      writeFileSync(resolve(output), json);
+      console.log(`Census data written to ${output}`);
+    } else {
+      console.log(json);
+    }
+    return;
+  }
+
+  if (format === 'html') {
+    const { generateHtml } = await import('../lib/census/report-html.mjs');
+    const html = generateHtml(data);
+    const outFile = output || 'crypto-census.html';
+    writeFileSync(resolve(outFile), html);
+    console.log(`HTML report written to ${outFile}`);
+    return;
+  }
+
+  // Default: terminal report
+  const { renderTerminal } = await import('../lib/census/report-terminal.mjs');
+  renderTerminal(data, {
+    compactHeader, section, labelValue, tableHeader, tableRow,
+    warning, info, dim, bold, divider, progressBar,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Main router
 // ---------------------------------------------------------------------------
@@ -1050,6 +1107,9 @@ try {
     case 'status':
       await cmdStatus();
       break;
+    case 'census':
+      await cmdCensus(commandArgs);
+      break;
     default:
       console.error(`Unknown command: ${command}\nRun "cryptoserve help" for usage.`);
       process.exit(1);

package/lib/census/aggregator.mjs

@@ -0,0 +1,158 @@
+/**
+ * Aggregate raw census data into headline metrics.
+ */
+
+import { TIERS } from './package-catalog.mjs';
+
+// NIST Post-Quantum Cryptography deadlines
+const NIST_2030 = new Date('2030-01-01T00:00:00Z');
+const NIST_2035 = new Date('2035-01-01T00:00:00Z');
+
+/**
+ * Sum downloads for a given tier from a packages array.
+ */
+function sumByTier(packages, tier) {
+  return packages
+    .filter(p => p.tier === tier)
+    .reduce((sum, p) => sum + p.downloads, 0);
+}
+
+/**
+ * Get top N packages sorted by downloads descending.
+ */
+function topPackages(packages, n = 10) {
+  return [...packages]
+    .sort((a, b) => b.downloads - a.downloads)
+    .slice(0, n);
+}
+
+/**
+ * Calculate days remaining until a target date.
+ */
+function daysUntil(target) {
+  const now = new Date();
+  const diff = target.getTime() - now.getTime();
+  return Math.max(0, Math.ceil(diff / (1000 * 60 * 60 * 24)));
+}
+
+/**
+ * Format days as "X yrs, Y days".
+ */
+function formatDaysRemaining(totalDays) {
+  const years = Math.floor(totalDays / 365);
+  const days = totalDays % 365;
+  if (years === 0) return `${days} days`;
+  return `${years} yr${years !== 1 ? 's' : ''}, ${days} days`;
+}
+
+/**
+ * Format a large number with suffix (M, K).
+ */
+export function formatNumber(n) {
+  if (n >= 1_000_000_000) return (n / 1_000_000_000).toFixed(1) + 'B';
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + 'K';
+  return String(n);
+}
+
+/**
+ * Aggregate all census data into headline metrics.
+ *
+ * @param {Object} data
+ * @param {Object} data.npm - Result from collectNpmDownloads
+ * @param {Object} data.pypi - Result from collectPypiDownloads
+ * @param {Object} [data.nvd] - Result from collectNvdCves
+ * @param {Object} [data.github] - Result from collectGithubAdvisories
+ * @returns {Object} Aggregated metrics
+ */
+export function aggregate(data) {
+  const npmPkgs = data.npm?.packages || [];
+  const pypiPkgs = data.pypi?.packages || [];
+  const allPkgs = [...npmPkgs, ...pypiPkgs];
+
+  // Download totals by tier
+  const totalWeakDownloads = sumByTier(allPkgs, TIERS.WEAK);
+  const totalModernDownloads = sumByTier(allPkgs, TIERS.MODERN);
+  const totalPqcDownloads = sumByTier(allPkgs, TIERS.PQC);
+  const totalDownloads = totalWeakDownloads + totalModernDownloads + totalPqcDownloads;
+
+  // Percentages
+  const weakPercentage = totalDownloads > 0 ? (totalWeakDownloads / totalDownloads * 100) : 0;
+  const modernPercentage = totalDownloads > 0 ? (totalModernDownloads / totalDownloads * 100) : 0;
+  const pqcPercentage = totalDownloads > 0 ? (totalPqcDownloads / totalDownloads * 100) : 0;
+
+  // The headline ratio
+  const weakToPqcRatio = totalPqcDownloads > 0
+    ? Math.round(totalWeakDownloads / totalPqcDownloads)
+    : null;
+
+  // Per-ecosystem breakdowns
+  const npmWeak = sumByTier(npmPkgs, TIERS.WEAK);
+  const npmModern = sumByTier(npmPkgs, TIERS.MODERN);
+  const npmPqc = sumByTier(npmPkgs, TIERS.PQC);
+  const pypiWeak = sumByTier(pypiPkgs, TIERS.WEAK);
+  const pypiModern = sumByTier(pypiPkgs, TIERS.MODERN);
+  const pypiPqc = sumByTier(pypiPkgs, TIERS.PQC);
+
+  // CVE totals
+  const nvdCves = data.nvd?.cves || [];
+  const totalCryptoCves = nvdCves.reduce((sum, c) => sum + c.totalCount, 0);
+
+  // GitHub advisories
+  const ghAdvisories = data.github?.advisories || [];
+  const totalAdvisories = ghAdvisories.reduce((sum, a) => sum + a.count, 0);
+
+  // Merge severity counts across CWEs
+  const advisorySeverity = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+  for (const adv of ghAdvisories) {
+    for (const [sev, count] of Object.entries(adv.bySeverity || {})) {
+      advisorySeverity[sev] = (advisorySeverity[sev] || 0) + count;
+    }
+  }
+
+  // NIST deadlines
+  const nistDeadline2030Days = daysUntil(NIST_2030);
+  const nistDeadline2035Days = daysUntil(NIST_2035);
+
+  return {
+    // Headline numbers
+    totalDownloads,
+    totalWeakDownloads,
+    totalModernDownloads,
+    totalPqcDownloads,
+    weakPercentage,
+    modernPercentage,
+    pqcPercentage,
+    weakToPqcRatio,
+
+    // Per-ecosystem
+    npm: {
+      weak: npmWeak, modern: npmModern, pqc: npmPqc,
+      total: npmWeak + npmModern + npmPqc,
+      topPackages: topPackages(npmPkgs, 15),
+      period: data.npm?.period,
+    },
+    pypi: {
+      weak: pypiWeak, modern: pypiModern, pqc: pypiPqc,
+      total: pypiWeak + pypiModern + pypiPqc,
+      topPackages: topPackages(pypiPkgs, 15),
+      period: data.pypi?.period,
+    },
+
+    // Vulnerabilities
+    totalCryptoCves,
+    cveBreakdown: nvdCves,
+    totalAdvisories,
+    advisorySeverity,
+    advisoryBreakdown: ghAdvisories,
+
+    // Deadlines
+    nistDeadline2030: formatDaysRemaining(nistDeadline2030Days),
+    nistDeadline2030Days,
+    nistDeadline2035: formatDaysRemaining(nistDeadline2035Days),
+    nistDeadline2035Days,
+
+    // Metadata
+    collectedAt: data.npm?.collectedAt || data.pypi?.collectedAt || new Date().toISOString(),
+  };
+}

package/lib/census/collectors/github-advisories.mjs

@@ -0,0 +1,132 @@
+/**
+ * Collect crypto-related security advisories from the GitHub Advisory Database.
+ *
+ * Endpoint: GET https://api.github.com/advisories?per_page=100
+ * - The REST API does NOT support CWE filtering -- we fetch and filter client-side
+ * - Free, no authentication required (60 req/hr unauthenticated)
+ * - We fetch up to MAX_PAGES pages and filter for crypto-related CWEs
+ */
+
+const GITHUB_API = 'https://api.github.com/advisories';
+const REQUEST_DELAY_MS = 2000;
+const MAX_PAGES = 5; // 500 advisories max to stay under rate limits
+
+const CRYPTO_CWE_IDS = new Set(['CWE-327', 'CWE-326', 'CWE-328']);
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if an advisory is crypto-related based on its CWEs.
+ */
+function isCryptoRelated(advisory) {
+  const cwes = advisory.cwes || [];
+  return cwes.some(c => CRYPTO_CWE_IDS.has(c.cwe_id));
+}
+
+/**
+ * Get the crypto CWE IDs from an advisory.
+ */
+function getCryptoCweIds(advisory) {
+  return (advisory.cwes || [])
+    .filter(c => CRYPTO_CWE_IDS.has(c.cwe_id))
+    .map(c => c.cwe_id);
+}
+
+/**
+ * Fetch crypto-related advisory counts from GitHub Advisory Database.
+ *
+ * @param {Object} [options]
+ * @param {Function} [options.fetchFn] - Fetch implementation (defaults to globalThis.fetch)
+ * @param {boolean} [options.verbose] - Log progress
+ * @returns {Promise<{advisories: Array<{cweId: string, count: number, bySeverity: Object, byEcosystem: Object}>, collectedAt: string}>}
+ */
+export async function collectGithubAdvisories(options = {}) {
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const verbose = options.verbose || false;
+
+  // Accumulate crypto advisories across all pages
+  const byCwe = {};
+  for (const cweId of CRYPTO_CWE_IDS) {
+    byCwe[cweId] = {
+      count: 0,
+      bySeverity: { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 },
+      byEcosystem: {},
+    };
+  }
+
+  let url = `${GITHUB_API}?per_page=100&type=reviewed`;
+  let page = 0;
+  let totalScanned = 0;
+
+  while (url && page < MAX_PAGES) {
+    page++;
+    if (verbose) process.stderr.write(`  github page ${page}/${MAX_PAGES}\n`);
+
+    try {
+      const res = await fetchFn(url, {
+        headers: { 'Accept': 'application/vnd.github+json' },
+      });
+
+      if (!res.ok) {
+        if (verbose) process.stderr.write(`  github page ${page}: HTTP ${res.status}\n`);
+        break;
+      }
+
+      const data = await res.json();
+      if (!Array.isArray(data) || data.length === 0) break;
+
+      totalScanned += data.length;
+
+      for (const adv of data) {
+        if (!isCryptoRelated(adv)) continue;
+
+        const cweIds = getCryptoCweIds(adv);
+        const sev = (adv.severity || 'unknown').toLowerCase();
+
+        for (const cweId of cweIds) {
+          const entry = byCwe[cweId];
+          entry.count++;
+          if (sev in entry.bySeverity) {
+            entry.bySeverity[sev]++;
+          } else {
+            entry.bySeverity.unknown++;
+          }
+
+          const vulnerabilities = adv.vulnerabilities || [];
+          for (const vuln of vulnerabilities) {
+            const eco = vuln?.package?.ecosystem || 'other';
+            entry.byEcosystem[eco] = (entry.byEcosystem[eco] || 0) + 1;
+          }
+        }
+      }
+
+      // Check for next page
+      const linkHeader = res.headers?.get?.('link') || '';
+      const nextMatch = linkHeader.match(/<([^>]+)>;\s*rel="next"/);
+      url = nextMatch ? nextMatch[1] : null;
+
+      if (url) await sleep(REQUEST_DELAY_MS);
+    } catch (err) {
+      if (verbose) process.stderr.write(`  github page ${page} error: ${err.message}\n`);
+      break;
+    }
+  }
+
+  if (verbose) {
+    process.stderr.write(`  github scanned ${totalScanned} advisories across ${page} pages\n`);
+  }
+
+  const results = [...CRYPTO_CWE_IDS].map(cweId => ({
+    cweId,
+    count: byCwe[cweId].count,
+    bySeverity: byCwe[cweId].bySeverity,
+    byEcosystem: byCwe[cweId].byEcosystem,
+  }));
+
+  return {
+    advisories: results,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/lib/census/collectors/npm-downloads.mjs

@@ -0,0 +1,132 @@
+/**
+ * Collect download counts from the npm registry API.
+ *
+ * Endpoint: GET https://api.npmjs.org/downloads/point/last-month/pkg1,pkg2,...
+ * - Bulk endpoint does NOT support scoped packages (@org/pkg)
+ * - Scoped packages must be fetched individually
+ * - No authentication required
+ */
+
+const NPM_API = 'https://api.npmjs.org/downloads/point/last-month';
+const BATCH_SIZE = 50;
+const BATCH_DELAY_MS = 1000;
+const INDIVIDUAL_DELAY_MS = 200;
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Fetch a single package's download count.
+ */
+async function fetchSingle(pkg, fetchFn, period, verbose) {
+  try {
+    const res = await fetchFn(`${NPM_API}/${pkg.name}`);
+    if (res.ok) {
+      const data = await res.json();
+      if (!period.start && data.start) {
+        period.start = data.start;
+        period.end = data.end;
+      }
+      return { name: pkg.name, downloads: data.downloads || 0, tier: pkg.tier };
+    }
+    if (verbose) process.stderr.write(`  npm ${pkg.name}: HTTP ${res.status}\n`);
+  } catch (err) {
+    if (verbose) process.stderr.write(`  npm ${pkg.name} error: ${err.message}\n`);
+  }
+  return { name: pkg.name, downloads: 0, tier: pkg.tier };
+}
+
+/**
+ * Fetch npm download counts for a list of packages.
+ *
+ * @param {import('../package-catalog.mjs').CatalogEntry[]} packages
+ * @param {Object} [options]
+ * @param {Function} [options.fetchFn] - Fetch implementation (defaults to globalThis.fetch)
+ * @param {boolean} [options.verbose] - Log progress
+ * @returns {Promise<{packages: Array<{name: string, downloads: number, tier: string}>, period: {start: string, end: string}, collectedAt: string}>}
+ */
+export async function collectNpmDownloads(packages, options = {}) {
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const verbose = options.verbose || false;
+
+  const results = [];
+  const period = { start: '', end: '' };
+
+  // Separate scoped (@org/pkg) from unscoped packages
+  const scoped = packages.filter(p => p.name.startsWith('@'));
+  const unscoped = packages.filter(p => !p.name.startsWith('@'));
+
+  // Batch unscoped packages
+  const batches = [];
+  for (let i = 0; i < unscoped.length; i += BATCH_SIZE) {
+    batches.push(unscoped.slice(i, i + BATCH_SIZE));
+  }
+
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i];
+    const names = batch.map(p => p.name).join(',');
+    const url = `${NPM_API}/${names}`;
+
+    if (verbose) {
+      process.stderr.write(`  npm batch ${i + 1}/${batches.length} (${batch.length} unscoped packages)\n`);
+    }
+
+    try {
+      const res = await fetchFn(url);
+      if (!res.ok) {
+        if (verbose) process.stderr.write(`  npm batch ${i + 1} failed: ${res.status}, falling back to individual\n`);
+        for (const pkg of batch) {
+          results.push(await fetchSingle(pkg, fetchFn, period, verbose));
+          await sleep(INDIVIDUAL_DELAY_MS);
+        }
+        continue;
+      }
+
+      const data = await res.json();
+
+      if (batch.length === 1) {
+        if (!period.start && data.start) {
+          period.start = data.start;
+          period.end = data.end;
+        }
+        results.push({ name: batch[0].name, downloads: data.downloads || 0, tier: batch[0].tier });
+      } else {
+        for (const pkg of batch) {
+          const entry = data[pkg.name];
+          if (entry) {
+            if (!period.start && entry.start) {
+              period.start = entry.start;
+              period.end = entry.end;
+            }
+            results.push({ name: pkg.name, downloads: entry.downloads || 0, tier: pkg.tier });
+          } else {
+            results.push({ name: pkg.name, downloads: 0, tier: pkg.tier });
+          }
+        }
+      }
+    } catch (err) {
+      if (verbose) process.stderr.write(`  npm batch ${i + 1} error: ${err.message}\n`);
+      for (const pkg of batch) {
+        results.push({ name: pkg.name, downloads: 0, tier: pkg.tier });
+      }
+    }
+
+    if (i < batches.length - 1) await sleep(BATCH_DELAY_MS);
+  }
+
+  // Fetch scoped packages individually (bulk API doesn't support them)
+  if (scoped.length > 0 && verbose) {
+    process.stderr.write(`  npm fetching ${scoped.length} scoped packages individually\n`);
+  }
+  for (let i = 0; i < scoped.length; i++) {
+    results.push(await fetchSingle(scoped[i], fetchFn, period, verbose));
+    if (i < scoped.length - 1) await sleep(INDIVIDUAL_DELAY_MS);
+  }
+
+  return {
+    packages: results.sort((a, b) => b.downloads - a.downloads),
+    period,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/lib/census/collectors/nvd-cves.mjs

@@ -0,0 +1,71 @@
+/**
+ * Collect crypto-related CVE counts from NVD (National Vulnerability Database).
+ *
+ * Endpoint: GET https://services.nvd.nist.gov/rest/json/cves/2.0?cweId=CWE-XXX&resultsPerPage=1
+ * - Free, no authentication required (API key optional for higher rate limits)
+ * - Rate limit: 5 requests per 30 seconds without API key
+ * - We use 7s delay between requests to stay well under limits
+ * - resultsPerPage=1 to minimize payload (we only need totalResults)
+ */
+
+const NVD_API = 'https://services.nvd.nist.gov/rest/json/cves/2.0';
+const REQUEST_DELAY_MS = 7000;
+
+const CRYPTO_CWES = [
+  { id: 'CWE-327', name: 'Use of a Broken or Risky Cryptographic Algorithm' },
+  { id: 'CWE-326', name: 'Inadequate Encryption Strength' },
+  { id: 'CWE-328', name: 'Use of Weak Hash' },
+];
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Fetch crypto-related CVE counts from NVD.
+ *
+ * @param {Object} [options]
+ * @param {Function} [options.fetchFn] - Fetch implementation (defaults to globalThis.fetch)
+ * @param {boolean} [options.verbose] - Log progress
+ * @returns {Promise<{cves: Array<{cweId: string, cweName: string, totalCount: number}>, collectedAt: string}>}
+ */
+export async function collectNvdCves(options = {}) {
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const verbose = options.verbose || false;
+
+  const results = [];
+
+  for (let i = 0; i < CRYPTO_CWES.length; i++) {
+    const cwe = CRYPTO_CWES[i];
+    const url = `${NVD_API}?cweId=${cwe.id}&resultsPerPage=1`;
+
+    if (verbose) {
+      process.stderr.write(`  nvd ${i + 1}/${CRYPTO_CWES.length}: ${cwe.id} (${cwe.name})\n`);
+    }
+
+    try {
+      const res = await fetchFn(url);
+      if (!res.ok) {
+        if (verbose) process.stderr.write(`  nvd ${cwe.id}: HTTP ${res.status}\n`);
+        results.push({ cweId: cwe.id, cweName: cwe.name, totalCount: 0 });
+      } else {
+        const data = await res.json();
+        const totalCount = data?.totalResults || 0;
+        results.push({ cweId: cwe.id, cweName: cwe.name, totalCount });
+      }
+    } catch (err) {
+      if (verbose) process.stderr.write(`  nvd ${cwe.id} error: ${err.message}\n`);
+      results.push({ cweId: cwe.id, cweName: cwe.name, totalCount: 0 });
+    }
+
+    // Delay between requests (NVD rate limit)
+    if (i < CRYPTO_CWES.length - 1) {
+      await sleep(REQUEST_DELAY_MS);
+    }
+  }
+
+  return {
+    cves: results,
+    collectedAt: new Date().toISOString(),
+  };
+}

package/lib/census/collectors/pypi-downloads.mjs

@@ -0,0 +1,67 @@
+/**
+ * Collect download counts from PyPI Stats API.
+ *
+ * Endpoint: GET https://pypistats.org/api/packages/{pkg}/recent
+ * - Individual requests only (no batch endpoint)
+ * - No authentication required
+ * - 500ms delay between requests to be polite
+ */
+
+const PYPI_API = 'https://pypistats.org/api/packages';
+const REQUEST_DELAY_MS = 500;
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Fetch PyPI download counts for a list of packages.
+ *
+ * @param {import('../package-catalog.mjs').CatalogEntry[]} packages
+ * @param {Object} [options]
+ * @param {Function} [options.fetchFn] - Fetch implementation (defaults to globalThis.fetch)
+ * @param {boolean} [options.verbose] - Log progress
+ * @returns {Promise<{packages: Array<{name: string, downloads: number, tier: string}>, period: string, collectedAt: string}>}
+ */
+export async function collectPypiDownloads(packages, options = {}) {
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const verbose = options.verbose || false;
+
+  const results = [];
+
+  for (let i = 0; i < packages.length; i++) {
+    const pkg = packages[i];
+    const url = `${PYPI_API}/${pkg.name}/recent`;
+
+    if (verbose) {
+      process.stderr.write(`  pypi ${i + 1}/${packages.length}: ${pkg.name}\n`);
+    }
+
+    try {
+      const res = await fetchFn(url);
+      if (!res.ok) {
+        if (verbose) process.stderr.write(`  pypi ${pkg.name}: ${res.status}\n`);
+        results.push({ name: pkg.name, downloads: 0, tier: pkg.tier });
+      } else {
+        const data = await res.json();
+        // Response: { data: { last_month: N, last_week: N, last_day: N }, ... }
+        const downloads = data?.data?.last_month || 0;
+        results.push({ name: pkg.name, downloads, tier: pkg.tier });
+      }
+    } catch (err) {
+      if (verbose) process.stderr.write(`  pypi ${pkg.name} error: ${err.message}\n`);
+      results.push({ name: pkg.name, downloads: 0, tier: pkg.tier });
+    }
+
+    // Delay between requests
+    if (i < packages.length - 1) {
+      await sleep(REQUEST_DELAY_MS);
+    }
+  }
+
+  return {
+    packages: results.sort((a, b) => b.downloads - a.downloads),
+    period: 'last_month',
+    collectedAt: new Date().toISOString(),
+  };
+}