@itsl-solutions/npm-registry-shield 0.1.0

package/src/config.ts

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ShieldConfig {
+  port: number;
+  upstream: string;
+  quarantineDays: number;
+  cacheTtlMinutes: number;
+  dashboard: boolean;
+  passthrough: string[];
+}
+
+const DEFAULT_CONFIG: ShieldConfig = {
+  port: 4873,
+  upstream: "https://registry.npmjs.org",
+  quarantineDays: 3,
+  cacheTtlMinutes: 10,
+  dashboard: true,
+  passthrough: [],
+};
+
+export const CONFIG_DIR = join(homedir(), ".npm-shield");
+export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+function ensureConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+export function loadConfig(): ShieldConfig {
+  ensureConfigDir();
+  if (!existsSync(CONFIG_PATH)) {
+    saveConfig(DEFAULT_CONFIG);
+    return { ...DEFAULT_CONFIG };
+  }
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<ShieldConfig>;
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch {
+    console.warn("[npm-registry-shield] Config file corrupted, resetting to defaults");
+    const config = { ...DEFAULT_CONFIG };
+    saveConfig(config);
+    return config;
+  }
+}
+
+export function saveConfig(config: ShieldConfig): void {
+  ensureConfigDir();
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+export function getConfigValue(key: string): unknown {
+  const config = loadConfig();
+  if (!(key in config)) {
+    throw new Error(`Unknown config key: ${key}. Valid keys: ${Object.keys(DEFAULT_CONFIG).join(", ")}`);
+  }
+  return config[key as keyof ShieldConfig];
+}
+
+export function setConfigValue(key: string, value: string): void {
+  const config = loadConfig();
+  if (!(key in config)) {
+    throw new Error(`Unknown config key: ${key}. Valid keys: ${Object.keys(DEFAULT_CONFIG).join(", ")}`);
+  }
+
+  const k = key as keyof ShieldConfig;
+  if (k === "dashboard") {
+    if (value !== "true" && value !== "false") {
+      throw new Error(`${key} must be true or false`);
+    }
+    config.dashboard = value === "true";
+  } else if (k === "port" || k === "quarantineDays" || k === "cacheTtlMinutes") {
+    const num = Number(value);
+    if (isNaN(num) || num <= 0) {
+      throw new Error(`${key} must be a positive number`);
+    }
+    config[k] = num;
+  } else if (k === "passthrough") {
+    throw new Error("Use 'npm-registry-shield allow/remove' to manage the passthrough list");
+  } else if (k === "upstream") {
+    config.upstream = value;
+  }
+
+  saveConfig(config);
+}

package/src/daemon.ts

@@ -0,0 +1,206 @@
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { CONFIG_DIR } from "./config.js";
+
+const LABEL = "com.npm-registry-shield";
+const LOG_PATH = join(CONFIG_DIR, "daemon.log");
+
+function getLaunchdPlistPath(): string {
+  const dir = join(homedir(), "Library", "LaunchAgents");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, `${LABEL}.plist`);
+}
+
+function getSystemdUnitPath(): string {
+  const dir = join(homedir(), ".config", "systemd", "user");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, "npm-registry-shield.service");
+}
+
+function findBunPath(): string {
+  try {
+    return execSync("which bun", { encoding: "utf-8" }).trim();
+  } catch {
+    throw new Error("bun not found on PATH. Install bun: https://bun.sh");
+  }
+}
+
+function findCliPath(): string {
+  try {
+    const out = execSync("which npm-registry-shield", { encoding: "utf-8" }).trim();
+    if (out) return out;
+  } catch {
+    // fall through
+  }
+  throw new Error(
+    "npm-registry-shield is not on PATH. Install it: 'bun add -g npm-registry-shield' (or 'bun link' from a clone)."
+  );
+}
+
+export function generateLaunchdPlist(): string {
+  const bunPath = findBunPath();
+  const cliPath = findCliPath();
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${bunPath}</string>
+    <string>${cliPath}</string>
+    <string>start</string>
+    <string>--foreground</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${LOG_PATH}</string>
+  <key>StandardErrorPath</key>
+  <string>${LOG_PATH}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function generateSystemdUnit(): string {
+  const bunPath = findBunPath();
+  const cliPath = findCliPath();
+  const quote = (p: string): string => (p.includes(" ") ? `"${p}"` : p);
+
+  return `[Unit]
+Description=npm-registry-shield proxy
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${quote(bunPath)} ${quote(cliPath)} start --foreground
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:${LOG_PATH}
+StandardError=append:${LOG_PATH}
+Environment=PATH=${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function installDaemon(): void {
+  const os = platform();
+  if (os === "darwin") return installLaunchd();
+  if (os === "linux") return installSystemd();
+  throw new Error("DAEMON_UNSUPPORTED");
+}
+
+export function uninstallDaemon(): void {
+  const os = platform();
+  if (os === "darwin") return uninstallLaunchd();
+  if (os === "linux") return uninstallSystemd();
+}
+
+export function isDaemonRunning(): boolean {
+  const os = platform();
+  if (os === "darwin") {
+    try {
+      const out = execSync(`launchctl list ${LABEL} 2>/dev/null`, { encoding: "utf-8" });
+      return out.includes(LABEL);
+    } catch {
+      return false;
+    }
+  }
+  if (os === "linux") {
+    try {
+      const out = execSync("systemctl --user is-active npm-registry-shield 2>/dev/null", { encoding: "utf-8" });
+      return out.trim() === "active";
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+export function getDaemonType(): string {
+  const os = platform();
+  if (os === "darwin") return "launchd";
+  if (os === "linux") return "systemd";
+  return "unsupported";
+}
+
+function installLaunchd(): void {
+  const plistPath = getLaunchdPlistPath();
+  if (existsSync(plistPath)) {
+    try {
+      execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { stdio: "ignore" });
+    } catch {
+      // ignore
+    }
+  }
+  writeFileSync(plistPath, generateLaunchdPlist(), "utf-8");
+  execSync(`launchctl load "${plistPath}"`);
+  console.log(`[npm-registry-shield] Daemon installed and started (launchd)`);
+  console.log(`[npm-registry-shield] Plist: ${plistPath}`);
+  console.log(`[npm-registry-shield] Logs:  ${LOG_PATH}`);
+}
+
+function uninstallLaunchd(): void {
+  const plistPath = getLaunchdPlistPath();
+  if (!existsSync(plistPath)) return;
+  try {
+    execSync(`launchctl unload "${plistPath}"`, { stdio: "ignore" });
+  } catch {
+    // may already be unloaded
+  }
+  unlinkSync(plistPath);
+  console.log("[npm-registry-shield] Daemon stopped and removed (launchd)");
+}
+
+function installSystemd(): void {
+  const unitPath = getSystemdUnitPath();
+  writeFileSync(unitPath, generateSystemdUnit(), "utf-8");
+  execSync("systemctl --user daemon-reload");
+  execSync("systemctl --user enable npm-registry-shield");
+  execSync("systemctl --user start npm-registry-shield");
+  console.log("[npm-registry-shield] Daemon installed and started (systemd)");
+  console.log(`[npm-registry-shield] Unit: ${unitPath}`);
+  console.log("[npm-registry-shield] Logs: journalctl --user -u npm-registry-shield");
+}
+
+function uninstallSystemd(): void {
+  const unitPath = getSystemdUnitPath();
+  if (!existsSync(unitPath)) return;
+  try {
+    execSync("systemctl --user stop npm-registry-shield", { stdio: "ignore" });
+    execSync("systemctl --user disable npm-registry-shield", { stdio: "ignore" });
+  } catch {
+    // may already be stopped
+  }
+  unlinkSync(unitPath);
+  execSync("systemctl --user daemon-reload");
+  console.log("[npm-registry-shield] Daemon stopped and removed (systemd)");
+}
+
+export function printDaemonInstructions(target: "launchd" | "systemd"): void {
+  if (target === "launchd") {
+    console.error("# Save this output to ~/Library/LaunchAgents/com.npm-registry-shield.plist");
+    console.error("# Then run: launchctl load ~/Library/LaunchAgents/com.npm-registry-shield.plist");
+    console.error("");
+    process.stdout.write(generateLaunchdPlist());
+    return;
+  }
+  console.error("# Save this output to ~/.config/systemd/user/npm-registry-shield.service");
+  console.error("# Then run: systemctl --user daemon-reload && systemctl --user enable --now npm-registry-shield");
+  console.error("");
+  process.stdout.write(generateSystemdUnit());
+}

package/src/dashboard.ts

@@ -0,0 +1,230 @@
+export function getDashboardHtml(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>npm-registry-shield dashboard</title>
+  <script src="https://cdn.jsdelivr.net/npm/@maleta/blokjs/dist/blokjs.min.js"><\/script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace; background: #0d1117; color: #c9d1d9; }
+    #app { max-width: 960px; margin: 0 auto; padding: 24px; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    blok.mount('#app', {
+      state: {
+        stats: null,
+        config: null,
+        lastUpdate: '',
+        fetchError: '',
+        showAll: false
+      },
+
+      computed: {
+        packages() {
+          if (!this.stats || !this.stats.packages) return [];
+          return Object.entries(this.stats.packages)
+            .map(function(entry) {
+              var origins = entry[1].origins || {};
+              var tools = entry[1].tools || {};
+              var originsList = Object.keys(origins)
+                .map(function(p) { return { dir: p, count: origins[p] }; })
+                .sort(function(a, b) { return b.count - a.count; })
+                .slice(0, 5);
+              var toolsList = Object.keys(tools)
+                .map(function(t) { return { name: t, count: tools[t] }; })
+                .sort(function(a, b) { return b.count - a.count; });
+              return {
+                name: entry[0],
+                requests: entry[1].requests,
+                versionsFiltered: entry[1].versionsFiltered,
+                blocked: entry[1].blocked,
+                warnings: entry[1].warnings,
+                lastChecked: entry[1].lastChecked,
+                origins: originsList,
+                tools: toolsList,
+                hasOrigins: originsList.length > 0 || toolsList.length > 0
+              };
+            })
+            .sort(function(a, b) { return b.requests - a.requests; });
+        },
+        visiblePackages() {
+          if (this.showAll) return this.packages;
+          return this.packages.filter(function(p) { return p.requests > 10; });
+        },
+        hiddenCount() {
+          return this.packages.length - this.visiblePackages.length;
+        },
+        hasPackages() {
+          return this.packages.length > 0;
+        },
+        toggleLabel() {
+          if (this.showAll) return 'Collapse';
+          return 'Show all (' + this.hiddenCount + ' hidden ≤ 10 req)';
+        }
+      },
+
+      methods: {
+        async fetchData() {
+          try {
+            var statsRes = await fetch('/_/stats.json');
+            this.stats = await statsRes.json();
+            var configRes = await fetch('/_/config.json');
+            this.config = await configRes.json();
+            this.lastUpdate = new Date().toLocaleTimeString();
+            this.fetchError = '';
+          } catch (e) {
+            this.fetchError = 'Failed to fetch data';
+          }
+        }
+      },
+
+      mount() {
+        this.fetchData();
+        setInterval(this.fetchData.bind(this), 10000);
+      },
+
+      view: function($) {
+        return {
+          div: { children: [
+            { div: { style: 'display:flex; align-items:center; justify-content:space-between; margin-bottom:32px; border-bottom:1px solid #21262d; padding-bottom:16px', children: [
+              { h1: { style: 'font-size:24px; font-weight:600; color:#58a6ff', text: 'npm-registry-shield' } },
+              { span: { style: 'font-size:13px; color:#8b949e', text: $.lastUpdate } }
+            ]}},
+
+            { when: $.fetchError, children: [
+              { div: { style: 'background:#3d1f1f; border:1px solid #f85149; border-radius:6px; padding:12px; margin-bottom:24px; color:#f85149', text: $.fetchError } }
+            ]},
+
+            { when: $.stats, children: [
+              { div: { style: 'display:grid; grid-template-columns:repeat(4, 1fr); gap:16px; margin-bottom:32px', children: [
+                { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; padding:16px', children: [
+                  { div: { style: 'font-size:12px; color:#8b949e; text-transform:uppercase; letter-spacing:0.5px; margin-bottom:4px', text: 'Requests' } },
+                  { div: { style: 'font-size:28px; font-weight:700; color:#c9d1d9', text: $.stats.totalRequests } }
+                ]}},
+                { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; padding:16px', children: [
+                  { div: { style: 'font-size:12px; color:#8b949e; text-transform:uppercase; letter-spacing:0.5px; margin-bottom:4px', text: 'Hidden versions', title: 'Total quarantined versions stripped from served packuments (summed across all responses)' } },
+                  { div: { style: 'font-size:28px; font-weight:700; color:#d29922', text: $.stats.totalFiltered } }
+                ]}},
+                { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; padding:16px', children: [
+                  { div: { style: 'font-size:12px; color:#8b949e; text-transform:uppercase; letter-spacing:0.5px; margin-bottom:4px', text: 'Blocked' } },
+                  { div: { style: 'font-size:28px; font-weight:700; color:#f85149', text: $.stats.totalBlocked } }
+                ]}},
+                { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; padding:16px', children: [
+                  { div: { style: 'font-size:12px; color:#8b949e; text-transform:uppercase; letter-spacing:0.5px; margin-bottom:4px', text: 'Warnings' } },
+                  { div: { style: 'font-size:28px; font-weight:700; color:#d29922', text: $.stats.totalWarnings } }
+                ]}}
+              ]}},
+
+              { when: $.config, children: [
+                { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; padding:16px; margin-bottom:24px', children: [
+                  { div: { style: 'font-size:14px; font-weight:600; margin-bottom:12px; color:#58a6ff', text: 'Configuration' } },
+                  { div: { style: 'display:flex; gap:24px; font-size:13px', children: [
+                    { span: { style: 'color:#8b949e', children: [
+                      { span: { text: 'Quarantine: ' } },
+                      { span: { style: 'color:#c9d1d9; font-weight:500', text: $.config.quarantineDays } },
+                      { span: { text: ' days' } }
+                    ]}},
+                    { span: { style: 'color:#8b949e', children: [
+                      { span: { text: 'Upstream: ' } },
+                      { span: { style: 'color:#c9d1d9; font-weight:500', text: $.config.upstream } }
+                    ]}}
+                  ]}}
+                ]}}
+              ]},
+
+              { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; padding:16px; margin-bottom:24px; font-size:13px; line-height:1.6', children: [
+                { div: { style: 'font-size:14px; font-weight:600; margin-bottom:12px; color:#58a6ff', text: 'What the columns mean' } },
+                { div: { style: 'display:grid; grid-template-columns:max-content 1fr; column-gap:16px; row-gap:6px; color:#8b949e', children: [
+                  { div: { style: 'color:#c9d1d9; font-weight:500', text: 'Requests' } },
+                  { div: { text: 'proxy hits for the package’s metadata' } },
+
+                  { div: { style: 'color:#d29922; font-weight:500', text: 'Hidden' } },
+                  { div: { text: 'quarantined versions stripped from served responses (cumulative across requests, so a high Hidden:Requests ratio means the package publishes frequently)' } },
+
+                  { div: { style: 'color:#f85149; font-weight:500', text: 'Blocked' } },
+                  { div: { text: 'times every version of the package was within the quarantine window and the install was refused with 404' } },
+
+                  { div: { style: 'color:#d29922; font-weight:500', text: 'Warnings' } },
+                  { div: { text: 'times a quarantined version was served anyway, either via a passthrough rule (allow pkg@version) or a direct single-version request' } }
+                ]}}
+              ]}},
+
+              { when: $.hasPackages, children: [
+                { div: { style: 'background:#161b22; border:1px solid #21262d; border-radius:8px; overflow:hidden', children: [
+                  { div: { style: 'padding:16px; border-bottom:1px solid #21262d; display:flex; align-items:center; justify-content:space-between', children: [
+                    { div: { style: 'font-size:14px; font-weight:600; color:#58a6ff', text: 'Packages' } },
+                    { when: $.hiddenCount, children: [
+                      { button: { style: 'background:transparent; border:1px solid #30363d; color:#58a6ff; font-size:12px; padding:4px 10px; border-radius:6px; cursor:pointer; font-family:inherit', click: 'showAll = !showAll', text: $.toggleLabel } }
+                    ]}
+                  ]}},
+                  { table: { style: 'width:100%; border-collapse:collapse; font-size:13px', children: [
+                    { thead: { children: [
+                      { tr: { style: 'border-bottom:1px solid #21262d', children: [
+                        { th: { style: 'text-align:left; padding:8px 16px; color:#8b949e; font-weight:500', text: 'Package' } },
+                        { th: { style: 'text-align:right; padding:8px 16px; color:#8b949e; font-weight:500', text: 'Requests' } },
+                        { th: { style: 'text-align:right; padding:8px 16px; color:#8b949e; font-weight:500', title: 'Quarantined versions stripped from served responses (cumulative)', text: 'Hidden' } },
+                        { th: { style: 'text-align:right; padding:8px 16px; color:#8b949e; font-weight:500', text: 'Blocked' } },
+                        { th: { style: 'text-align:right; padding:8px 16px; color:#8b949e; font-weight:500', text: 'Warnings' } }
+                      ]}}
+                    ]}},
+                    { tbody: { children: [
+                      { each: $.visiblePackages, as: 'pkg', key: 'name', children: [
+                        { tr: { style: 'border-bottom:1px solid #21262d', children: [
+                          { td: { style: 'padding:8px 16px; color:#c9d1d9; font-family:monospace; vertical-align:top', children: [
+                            { div: { text: $.pkg.name } },
+                            { when: $.pkg.hasOrigins, children: [
+                              { div: { style: 'margin-top:6px; font-family:-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, monospace; font-size:11px; color:#8b949e', children: [
+                                { when: $.pkg.tools, children: [
+                                  { each: $.pkg.tools, as: 't', key: 'name', children: [
+                                    { span: { style: 'display:inline-block; margin-right:8px; padding:1px 6px; background:#21262d; border-radius:3px; color:#8b949e', children: [
+                                      { span: { style: 'color:#58a6ff', text: $.t.name } },
+                                      { span: { text: ' x' } },
+                                      { span: { text: $.t.count } }
+                                    ]}}
+                                  ]}
+                                ]},
+                                { each: $.pkg.origins, as: 'origin', key: 'dir', children: [
+                                  { div: { style: 'margin-top:2px', children: [
+                                    { span: { style: 'color:#8b949e', text: $.origin.dir } },
+                                    { span: { style: 'color:#6e7681', children: [
+                                      { span: { text: '  (' } },
+                                      { span: { text: $.origin.count } },
+                                      { span: { text: ')' } }
+                                    ]}}
+                                  ]}}
+                                ]}
+                              ]}}
+                            ]}
+                          ]}},
+                          { td: { style: 'text-align:right; padding:8px 16px; color:#c9d1d9; vertical-align:top', text: $.pkg.requests } },
+                          { td: { style: 'text-align:right; padding:8px 16px; color:#d29922; vertical-align:top', text: $.pkg.versionsFiltered } },
+                          { td: { style: 'text-align:right; padding:8px 16px; color:#f85149; vertical-align:top', text: $.pkg.blocked } },
+                          { td: { style: 'text-align:right; padding:8px 16px; color:#d29922; vertical-align:top', text: $.pkg.warnings } }
+                        ]}}
+                      ]}
+                    ]}}
+                  ]}}
+                ]}}
+              ]},
+
+              { when: $.not.hasPackages, children: [
+                { div: { style: 'text-align:center; padding:48px; color:#8b949e; font-size:14px', text: 'No packages proxied yet. Run npm install to see data here.' } }
+              ]}
+            ]},
+
+            { when: $.not.stats, children: [
+              { div: { style: 'text-align:center; padding:48px; color:#8b949e', text: 'Loading...' } }
+            ]}
+          ]}
+        };
+      }
+    });
+  <\/script>
+</body>
+</html>`;
+}