@itsl-solutions/npm-registry-shield 0.1.0

package/src/server.ts

@@ -0,0 +1,366 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { watch as fsWatch, type FSWatcher } from "node:fs";
+import { CONFIG_PATH, loadConfig, type ShieldConfig } from "./config.js";
+import { filterPackument, isVersionQuarantined } from "./filter.js";
+import {
+  clearCache,
+  fetchPackument,
+  fetchVersionMetadata,
+  getCachedPackument,
+  setCachedPackument,
+  proxyRequest,
+} from "./registry.js";
+import { getStats, recordRequest, recordWarning, startStatsFlush, stopStatsFlush } from "./stats.js";
+import { getDashboardHtml } from "./dashboard.js";
+import {
+  detectToolFromUserAgent,
+  installOriginAttribution,
+  readOrigin,
+} from "./origin.js";
+
+type HttpServer = ReturnType<typeof createServer>;
+
+const NON_PACKAGE_PATHS = new Set([
+  "favicon.ico",
+  ".well-known",
+  "robots.txt",
+  "sitemap.xml",
+]);
+
+function isTarballPath(pathname: string): boolean {
+  return /^\/(?:@[^/]+\/)?[^/]+\/-\/.+$/.test(pathname);
+}
+
+function isPackageSubresourcePath(pathname: string): boolean {
+  return (
+    /^\/(?:@[^/]+\/)?[^/]+\/dist-tags(?:\/.*)?$/.test(pathname) ||
+    /^\/(?:@[^/]+\/)?[^/]+\/-rev\/.+$/.test(pathname)
+  );
+}
+
+function parsePackagePath(
+  pathname: string
+): { packageName: string; version: string | null } | null {
+  if (pathname.startsWith("/_/") || pathname.startsWith("/-/")) {
+    return null;
+  }
+
+  if (isTarballPath(pathname) || isPackageSubresourcePath(pathname)) {
+    return null;
+  }
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    decoded = pathname;
+  }
+
+  const parts = decoded.slice(1).split("/");
+
+  if (NON_PACKAGE_PATHS.has(parts[0])) {
+    return null;
+  }
+
+  if (parts[0]?.startsWith("@") && parts[0].length > 1 && parts.length >= 2 && parts[1]) {
+    const packageName = `${parts[0]}/${parts[1]}`;
+    const version = parts[2] || null;
+    return { packageName, version };
+  }
+
+  if (parts[0] && !parts[0].startsWith("-") && !parts[0].startsWith(".")) {
+    const packageName = parts[0];
+    const version = parts[1] || null;
+    return { packageName, version };
+  }
+
+  return null;
+}
+
+function getRequestHeaders(req: IncomingMessage): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") {
+      headers[key] = value;
+    }
+  }
+  return headers;
+}
+
+async function readRequestBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+async function handlePackument(
+  packageName: string,
+  config: ShieldConfig,
+  req: IncomingMessage,
+  res: ServerResponse
+): Promise<void> {
+  const origin = readOrigin(req.socket);
+  recordRequest(
+    packageName,
+    origin,
+    detectToolFromUserAgent(req.headers["user-agent"])
+  );
+
+  let packument = getCachedPackument(packageName, config.cacheTtlMinutes);
+  const fromCache = packument !== null;
+  if (!packument) {
+    packument = await fetchPackument(packageName, config.upstream);
+    if (!packument) {
+      res.writeHead(404, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: `Package ${packageName} not found` }));
+      return;
+    }
+    setCachedPackument(packageName, packument);
+  }
+
+  const result = filterPackument(packument, config);
+
+  if (result.blocked) {
+    const msg = JSON.stringify({
+      error: `All versions of ${packageName} are within the quarantine period (${config.quarantineDays} days). Use 'npm-registry-shield allow ${packageName}' to bypass.`,
+    });
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(msg);
+    console.log(
+      `[npm-registry-shield] BLOCKED ${packageName} - all ${result.filteredCount} versions quarantined`
+    );
+    return;
+  }
+
+  if (result.filtered && !fromCache) {
+    console.log(
+      `[npm-registry-shield] ${packageName} - filtered ${result.filteredCount} recent version(s), serving ${Object.keys(result.packument.versions).length} version(s)`
+    );
+  }
+
+  const body = JSON.stringify(result.packument);
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(body);
+}
+
+async function handleSpecificVersion(
+  packageName: string,
+  version: string,
+  config: ShieldConfig,
+  req: IncomingMessage,
+  res: ServerResponse
+): Promise<void> {
+  const origin = readOrigin(req.socket);
+  recordRequest(
+    packageName,
+    origin,
+    detectToolFromUserAgent(req.headers["user-agent"])
+  );
+
+  const upstream = await fetchVersionMetadata(
+    packageName,
+    version,
+    config.upstream
+  );
+
+  if (upstream.status === 200) {
+    try {
+      const meta = JSON.parse(upstream.body);
+      let packument = getCachedPackument(packageName, config.cacheTtlMinutes);
+      if (!packument) {
+        try {
+          packument = await fetchPackument(packageName, config.upstream);
+          if (packument) setCachedPackument(packageName, packument);
+        } catch {
+          packument = null;
+        }
+      }
+      const publishedAt = packument?.time?.[version];
+
+      if (publishedAt && isVersionQuarantined(publishedAt, config.quarantineDays)) {
+        console.warn(
+          `[npm-registry-shield] WARNING: Serving quarantined version ${packageName}@${version} (specific version request)`
+        );
+        recordWarning(packageName);
+      }
+
+      res.writeHead(200, { "content-type": upstream.contentType });
+      res.end(JSON.stringify(meta));
+    } catch {
+      res.writeHead(upstream.status, { "content-type": upstream.contentType });
+      res.end(upstream.body);
+    }
+  } else {
+    res.writeHead(upstream.status, { "content-type": upstream.contentType });
+    res.end(upstream.body);
+  }
+}
+
+async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  config: ShieldConfig
+): Promise<void> {
+  const url = new URL(req.url || "/", `http://localhost:${config.port}`);
+  const pathname = url.pathname;
+  const method = req.method || "GET";
+
+  const acceptsHtml = (req.headers.accept || "").includes("text/html");
+
+  if (config.dashboard && method === "GET" && pathname === "/" && acceptsHtml) {
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(getDashboardHtml());
+    return;
+  }
+
+  if (method === "GET" && acceptsHtml && pathname !== "/") {
+    res.writeHead(302, { location: "/" });
+    res.end();
+    return;
+  }
+
+  if (config.dashboard && pathname === "/_/stats.json") {
+    const stats = getStats();
+    res.writeHead(200, {
+      "content-type": "application/json",
+      "access-control-allow-origin": "*",
+    });
+    res.end(JSON.stringify(stats));
+    return;
+  }
+
+  if (config.dashboard && pathname === "/_/config.json") {
+    res.writeHead(200, {
+      "content-type": "application/json",
+      "access-control-allow-origin": "*",
+    });
+    res.end(JSON.stringify({
+      quarantineDays: config.quarantineDays,
+      passthrough: config.passthrough,
+      upstream: config.upstream,
+    }));
+    return;
+  }
+
+  if (method !== "GET") {
+    const body = await readRequestBody(req);
+    const result = await proxyRequest(
+      method,
+      req.url || "/",
+      config.upstream,
+      getRequestHeaders(req),
+      body
+    );
+    res.writeHead(result.status, result.headers);
+    res.end(result.body);
+    return;
+  }
+
+  const parsed = parsePackagePath(pathname);
+
+  if (parsed) {
+    if (parsed.version) {
+      await handleSpecificVersion(
+        parsed.packageName,
+        parsed.version,
+        config,
+        req,
+        res
+      );
+      return;
+    }
+
+    await handlePackument(parsed.packageName, config, req, res);
+    return;
+  }
+
+  const result = await proxyRequest(
+    method,
+    req.url || "/",
+    config.upstream,
+    getRequestHeaders(req)
+  );
+  res.writeHead(result.status, result.headers);
+  res.end(result.body);
+}
+
+type ShieldServer = HttpServer & { __configWatcher?: FSWatcher };
+
+export function startServer(initialConfig: ShieldConfig): HttpServer {
+  startStatsFlush();
+
+  let config = initialConfig;
+  const port = initialConfig.port;
+
+  const server = createServer((req, res) => {
+    handleRequest(req, res, config).catch((err) => {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      console.error(`[npm-registry-shield] Error handling ${req.url}: ${message}`);
+      if (!res.headersSent) {
+        res.writeHead(502, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: `Proxy error: ${message}` }));
+      }
+    });
+  }) as ShieldServer;
+
+  installOriginAttribution(server, port);
+
+  let reloadTimer: ReturnType<typeof setTimeout> | null = null;
+  const watcher = fsWatch(CONFIG_PATH, () => {
+    if (reloadTimer) clearTimeout(reloadTimer);
+    reloadTimer = setTimeout(() => {
+      try {
+        const next = loadConfig();
+        const passthroughChanged =
+          next.passthrough.join("|") !== config.passthrough.join("|");
+        const quarantineChanged = next.quarantineDays !== config.quarantineDays;
+        config = next;
+        if (passthroughChanged || quarantineChanged) {
+          clearCache();
+          console.log("[npm-registry-shield] Config changed - cache cleared, new rules active");
+        }
+      } catch (err) {
+        console.error(`[npm-registry-shield] Failed to reload config: ${(err as Error).message}`);
+      }
+    }, 100);
+  });
+  watcher.on("error", () => {});
+  server.__configWatcher = watcher;
+
+  server.on("error", (err: NodeJS.ErrnoException) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`[npm-registry-shield] Port ${port} is already in use. Is another instance running?`);
+    } else {
+      console.error(`[npm-registry-shield] Server error: ${err.message}`);
+    }
+    process.exit(1);
+  });
+
+  server.listen(port, "127.0.0.1", () => {
+    console.log(`[npm-registry-shield] Proxy running on http://127.0.0.1:${port} (loopback only)`);
+    console.log(`[npm-registry-shield] Upstream: ${config.upstream}`);
+    console.log(`[npm-registry-shield] Quarantine: ${config.quarantineDays} days`);
+    if (config.dashboard) {
+      console.log(`[npm-registry-shield] Dashboard: http://localhost:${port}/`);
+    }
+    if (config.passthrough.length > 0) {
+      console.log(`[npm-registry-shield] Passthrough: ${config.passthrough.join(", ")}`);
+    }
+  });
+
+  return server;
+}
+
+export function stopServer(server: HttpServer): Promise<void> {
+  stopStatsFlush();
+  const watcher = (server as ShieldServer).__configWatcher;
+  if (watcher) watcher.close();
+  return new Promise((resolve, reject) => {
+    server.close((err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}

package/src/stats.ts

@@ -0,0 +1,235 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR } from "./config.js";
+
+export interface PackageStats {
+  requests: number;
+  versionsFiltered: number;
+  blocked: number;
+  warnings: number;
+  lastChecked: string;
+  origins?: Record<string, number>;
+  tools?: Record<string, number>;
+}
+
+export interface Stats {
+  totalRequests: number;
+  totalFiltered: number;
+  totalBlocked: number;
+  totalWarnings: number;
+  since: string;
+  packages: Record<string, PackageStats>;
+}
+
+const STATS_PATH = join(CONFIG_DIR, "stats.json");
+const FLUSH_INTERVAL_MS = 30_000;
+const MAX_ORIGINS_PER_PKG = 20;
+const MAX_TOOLS_PER_PKG = 10;
+
+let stats: Stats = createEmpty();
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+
+function createEmpty(): Stats {
+  return {
+    totalRequests: 0,
+    totalFiltered: 0,
+    totalBlocked: 0,
+    totalWarnings: 0,
+    since: new Date().toISOString(),
+    packages: {},
+  };
+}
+
+function ensurePkg(name: string): PackageStats {
+  if (!stats.packages[name]) {
+    stats.packages[name] = {
+      requests: 0,
+      versionsFiltered: 0,
+      blocked: 0,
+      warnings: 0,
+      lastChecked: new Date().toISOString(),
+    };
+  }
+  return stats.packages[name];
+}
+
+export function recordRequest(
+  packageName: string,
+  origin?: { cwd?: string | null; root?: string | null } | null,
+  tool?: string
+): void {
+  stats.totalRequests++;
+  const pkg = ensurePkg(packageName);
+  pkg.requests++;
+  pkg.lastChecked = new Date().toISOString();
+
+  if (origin?.cwd) {
+    const key = origin.root ? `${origin.cwd} (${origin.root})` : origin.cwd;
+    if (!pkg.origins) pkg.origins = {};
+    pkg.origins[key] = (pkg.origins[key] || 0) + 1;
+    capRecord(pkg.origins, MAX_ORIGINS_PER_PKG);
+  }
+
+  if (tool) {
+    if (!pkg.tools) pkg.tools = {};
+    pkg.tools[tool] = (pkg.tools[tool] || 0) + 1;
+    capRecord(pkg.tools, MAX_TOOLS_PER_PKG);
+  }
+}
+
+function capRecord(rec: Record<string, number>, max: number): void {
+  const keys = Object.keys(rec);
+  if (keys.length <= max) return;
+  const sorted = keys.sort((a, b) => rec[a]! - rec[b]!);
+  const drop = sorted.length - max;
+  for (let i = 0; i < drop; i++) {
+    delete rec[sorted[i]!];
+  }
+}
+
+export function recordFiltered(packageName: string, count: number): void {
+  stats.totalFiltered += count;
+  const pkg = ensurePkg(packageName);
+  pkg.versionsFiltered += count;
+}
+
+export function recordBlocked(packageName: string): void {
+  stats.totalBlocked++;
+  const pkg = ensurePkg(packageName);
+  pkg.blocked++;
+}
+
+export function recordWarning(packageName: string): void {
+  stats.totalWarnings++;
+  const pkg = ensurePkg(packageName);
+  pkg.warnings++;
+}
+
+export function getStats(): Stats {
+  return stats;
+}
+
+export function flushStats(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  const tmpPath = STATS_PATH + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(stats, null, 2) + "\n", "utf-8");
+  renameSync(tmpPath, STATS_PATH);
+}
+
+export function loadStats(): void {
+  if (existsSync(STATS_PATH)) {
+    try {
+      const raw = readFileSync(STATS_PATH, "utf-8");
+      const loaded = JSON.parse(raw) as Stats;
+      stats = { ...createEmpty(), ...loaded };
+    } catch {
+      stats = createEmpty();
+    }
+  } else {
+    stats = createEmpty();
+  }
+}
+
+export function startStatsFlush(): void {
+  loadStats();
+  flushTimer = setInterval(flushStats, FLUSH_INTERVAL_MS);
+}
+
+export function stopStatsFlush(): void {
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+  flushStats();
+}
+
+function formatSince(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleString();
+  } catch {
+    return iso;
+  }
+}
+
+export function formatStatsForConsole(): string {
+  const lines: string[] = [
+    `npm-registry-shield  -  since ${formatSince(stats.since)}`,
+    "",
+    `  Requests       ${String(stats.totalRequests).padStart(8)}`,
+    `  Hidden vers.   ${String(stats.totalFiltered).padStart(8)}`,
+    `  Blocked        ${String(stats.totalBlocked).padStart(8)}`,
+    `  Warnings       ${String(stats.totalWarnings).padStart(8)}`,
+  ];
+
+  const pkgEntries = Object.entries(stats.packages);
+  if (pkgEntries.length === 0) {
+    return lines.join("\n");
+  }
+
+  const sorted = pkgEntries.sort((a, b) => b[1].requests - a[1].requests);
+  const top = sorted.slice(0, 20);
+  const nameWidth = Math.max(7, ...top.map(([name]) => name.length));
+  const numCols: Array<{ header: string; key: keyof PackageStats }> = [
+    { header: "Requests", key: "requests" },
+    { header: "Hidden", key: "versionsFiltered" },
+    { header: "Blocked", key: "blocked" },
+    { header: "Warnings", key: "warnings" },
+  ];
+  const colWidth = 10;
+
+  const header =
+    "  " +
+    "Package".padEnd(nameWidth) +
+    numCols.map((c) => c.header.padStart(colWidth)).join("");
+  const divider = "  " + "-".repeat(nameWidth + colWidth * numCols.length);
+
+  lines.push("", header, divider);
+
+  for (const [name, pkg] of top) {
+    const row =
+      "  " +
+      name.padEnd(nameWidth) +
+      numCols
+        .map((c) => {
+          const v = pkg[c.key];
+          return String(typeof v === "number" ? v : 0).padStart(colWidth);
+        })
+        .join("");
+    lines.push(row);
+
+    if (pkg.tools && Object.keys(pkg.tools).length > 0) {
+      const tools = Object.entries(pkg.tools)
+        .sort((a, b) => b[1] - a[1])
+        .map(([t, c]) => `${t} x${c}`)
+        .join(", ");
+      lines.push(`  ${" ".repeat(nameWidth)}  via: ${tools}`);
+    }
+
+    if (pkg.origins && Object.keys(pkg.origins).length > 0) {
+      const origins = Object.entries(pkg.origins)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5);
+      for (const [path, count] of origins) {
+        lines.push(`  ${" ".repeat(nameWidth)}  ${path} (${count})`);
+      }
+    }
+  }
+
+  if (sorted.length > top.length) {
+    lines.push(`  ... and ${sorted.length - top.length} more`);
+  }
+
+  lines.push(
+    "",
+    "  Legend:",
+    "    Requests  - proxy hits for this package's metadata",
+    "    Hidden    - quarantined versions stripped from served responses (cumulative across requests)",
+    "    Blocked   - times every version was quarantined and the install was refused (404)",
+    "    Warnings  - times a quarantined version was served anyway (passthrough rule or specific-version request)"
+  );
+
+  return lines.join("\n");
+}