@itsl-solutions/npm-registry-shield 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ITSL Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# npm-registry-shield
+
+Registry proxy that quarantines recently published npm package versions. Protects against supply chain attacks by ensuring you only install versions that have been on the registry for a configurable number of days.
+
+## How it works
+
+npm-registry-shield sits between your package manager and the npm registry. When you run `npm install`, it intercepts the package metadata and strips out versions published within the quarantine window (default: 3 days). Your package manager never sees the risky versions - it resolves to the newest safe version automatically.
+
+```
+npm install express
+    |
+    v
+localhost:4873 (npm-registry-shield)
+    |
+    |- fetch metadata from registry.npmjs.org
+    |- strip versions published < 3 days ago
+    |- return filtered metadata
+    |
+    v
+npm resolves to newest safe version
+```
+
+All transitive dependencies are also protected - every package at every depth resolves through the proxy.
+
+### What gets filtered, what passes through
+
+| Request type | Behavior |
+|--------------|----------|
+| `GET /<pkg>` (full packument) | Versions inside the quarantine window are stripped. `dist-tags` are rewritten to point at the newest surviving version. If every version is quarantined, returns 404. |
+| `GET /<pkg>/<version>` (single version metadata) | Passed through unchanged. If the version is quarantined, a warning is logged and counted in stats but the response is not blocked. |
+| Tarball downloads (`/<pkg>/-/<file>.tgz`) | Forwarded upstream as-is. |
+| Search, login, publish, anything else | Forwarded upstream as-is. |
+
+Packuments are cached in memory for 10 minutes (configurable via `cacheTtlMinutes`). The cache is cleared automatically when you run `allow` or `remove`.
+
+## Requirements
+
+- [bun](https://bun.sh) >= 1.0
+
+`bun` is the only runtime. The proxy itself runs under bun, and the published package ships TypeScript sources executed directly by bun.
+
+## Install
+
+```bash
+bun add -g npm-registry-shield
+```
+
+## Quick start
+
+```bash
+npm-registry-shield start
+```
+
+That's it. On macOS this installs a launchd service and starts it. On Linux it installs a systemd user service. The proxy runs in the background, survives reboots, and rewrites your `~/.npmrc` (and `~/.yarnrc.yml` if present) to point at it.
+
+Your `npm`, `pnpm`, `yarn`, and `bun install` commands are now protected.
+
+To stop:
+
+```bash
+npm-registry-shield stop
+```
+
+This unloads the service and restores your original `~/.npmrc`.
+
+To run in the foreground (for debugging or one-off use):
+
+```bash
+npm-registry-shield start --foreground
+```
+
+Logs are written to `~/.npm-shield/daemon.log`. Configuration is at `~/.npm-shield/config.json`.
+
+## Manual daemon install
+
+If you want to write the service file yourself (custom flags, custom path, etc.):
+
+```bash
+# macOS
+npm-registry-shield daemon-template launchd > ~/Library/LaunchAgents/com.npm-registry-shield.plist
+launchctl load ~/Library/LaunchAgents/com.npm-registry-shield.plist
+
+# Linux
+mkdir -p ~/.config/systemd/user
+npm-registry-shield daemon-template systemd > ~/.config/systemd/user/npm-registry-shield.service
+systemctl --user daemon-reload && systemctl --user enable --now npm-registry-shield
+```
+
+## Commands
+
+```
+npm-registry-shield start [options]      Install + start the background daemon (survives reboots)
+npm-registry-shield stop                 Stop the daemon and restore package manager configs
+npm-registry-shield status               Show running state and config
+npm-registry-shield allow <pkg>          Skip quarantine for a package
+npm-registry-shield allow <pkg>@<ver>    Allow specific version (with warning)
+npm-registry-shield remove <pattern>     Remove from passthrough list
+npm-registry-shield list                 Show passthrough entries
+npm-registry-shield config get <key>     Show config value
+npm-registry-shield config set <k> <v>   Update config value
+npm-registry-shield stats                Show statistics summary
+npm-registry-shield daemon-template <launchd|systemd>
+                                         Print a service unit you can install for persistence
+```
+
+### Start options
+
+```
+--foreground          Run in this terminal instead of installing the daemon
+--quarantine=<days>   Override quarantine period (default: 3)
+--port=<port>         Override proxy port (default: 4873)
+--upstream=<url>      Override upstream registry URL
+--no-dashboard        Disable the web dashboard
+```
+
+## Package manager support
+
+| Manager | Supported | How |
+|---------|-----------|-----|
+| npm | Yes | `.npmrc` registry setting |
+| pnpm | Yes | `.npmrc` registry setting |
+| yarn v1 | Yes | `.npmrc` registry setting |
+| yarn v2+ | Yes | `.yarnrc.yml` npmRegistryServer |
+| bun | Yes | `.npmrc` registry setting |
+| deno | Manual | `export DENO_NPM_REGISTRY=http://localhost:4873` |
+
+## Dashboard
+
+When the proxy is running, open `http://localhost:4873/` for a live stats dashboard showing total requests, hidden (quarantined) versions, blocked installs, and a per-package breakdown.
+
+Each package row also shows:
+
+- **Tool** that fetched it (`npm`, `pnpm`, `yarn`, `bun`, `deno`, `browser`, ...) detected from the request `User-Agent`.
+- **Origin path** of the process that made the request (working directory) plus the **launcher app** that started the chain (e.g. `iTerm2`, `Claude`, `Code Helper`), so you can tell apart an explicit `npm install` from a tool that quietly spawned `npm` in the background.
+
+By default only packages with more than 10 requests are shown; the "Show all" button in the Packages header reveals the long tail.
+
+Origin attribution uses `lsof` + `ps` and works on macOS today. On Linux and other platforms the proxy still serves stats - the origin/tool columns are simply empty.
+
+## Stats CLI
+
+For a terminal-friendly snapshot:
+
+```bash
+npm-registry-shield stats
+```
+
+Prints the totals, the top 20 packages by request count with aligned columns, and the legend explaining what each column means. Reads from `~/.npm-shield/stats.json`, which the daemon flushes every 30 seconds.
+
+## Security & networking
+
+The proxy listens on `127.0.0.1` only, so nothing on your LAN can reach it. Upstream traffic still goes out over HTTPS to whatever registry you configured (`https://registry.npmjs.org` by default).
+
+## Configuration
+
+Config is stored at `~/.npm-shield/config.json`:
+
+```json
+{
+  "port": 4873,
+  "upstream": "https://registry.npmjs.org",
+  "quarantineDays": 3,
+  "cacheTtlMinutes": 10,
+  "dashboard": true,
+  "passthrough": []
+}
+```
+
+### Passthrough list
+
+Skip quarantine for trusted packages:
+
+```bash
+# Entire package
+npm-registry-shield allow lodash
+
+# Scoped packages
+npm-registry-shield allow "@my-org/*"
+
+# Specific version (allowed with a warning)
+npm-registry-shield allow express@5.0.0
+```
+
+## What happens when...
+
+**`npm install express`** - Resolves to the newest version that is at least 3 days old.
+
+**`npm install express@5.0.0` where 5.0.0 is too new** - npm fetches the full packument first to resolve, sees 5.0.0 missing, and fails. Run `npm-registry-shield allow express@5.0.0` to permit it.
+
+**A brand-new package (all versions < 3 days old)** - The packument response is a 404 with an explanatory error. Add the package to the passthrough list to allow it.
+
+**`npm ci` with a lockfile pointing at a quarantined version** - The packument resolution step strips the version, so npm errors. Catches dependencies your teammates added that haven't aged past the quarantine window yet. Add the offending versions to passthrough or wait them out.
+
+**`npm view express@5.0.0`** - Hits the single-version endpoint, which passes through with a warning logged in `~/.npm-shield/daemon.log` and counted under "warnings" in stats. Useful for inspecting fresh versions without committing to install them.
+
+**The proxy is down** - `.npmrc` points at a dead server, npm commands fail. Run `npm-registry-shield stop` to restore your config. If the CLI is unreachable, manually remove the `registry=` line from `~/.npmrc`.
+
+## Recovery
+
+If something goes wrong and npm commands fail:
+
+```bash
+# Restore configs from backup
+npm-registry-shield stop
+
+# If the CLI is unavailable, remove this line manually:
+#   registry=http://localhost:4873
+nano ~/.npmrc
+```
+
+## Development
+
+```bash
+git clone https://github.com/maleta/npm-registry-shield.git
+cd npm-registry-shield
+bun install
+bun link
+exec $SHELL              # reload shell so the new global bin is on PATH
+npm-registry-shield start
+```
+
+`bun link` symlinks the package into bun's global bin dir pointing at your clone. Edit `src/*.ts` and the change is live on the next run - no rebuild step.
+
+Note: after `bun link`, the `npm-registry-shield` command is not available in the same shell session that ran the link - shells cache PATH lookups. Open a new terminal or run `exec $SHELL` (or `hash -r` in bash/zsh) to refresh.
+
+Run tests with `bun test`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@itsl-solutions/npm-registry-shield",
+  "version": "0.1.0",
+  "description": "Registry proxy that quarantines recently published npm package versions",
+  "type": "module",
+  "bin": {
+    "npm-registry-shield": "src/cli.ts"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "npm",
+    "security",
+    "supply-chain",
+    "registry",
+    "proxy",
+    "quarantine"
+  ],
+  "license": "MIT",
+  "author": "Aleksandar Maletic",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun test && bunx tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.14"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,346 @@
+#!/usr/bin/env bun
+import { loadConfig, saveConfig, getConfigValue, setConfigValue } from "./config.js";
+import { startServer, stopServer } from "./server.js";
+import { configurePackageManagers, restorePackageManagers, hasStaleState, forceRestore } from "./pm-config.js";
+import { formatStatsForConsole, loadStats } from "./stats.js";
+import { installDaemon, uninstallDaemon, isDaemonRunning, getDaemonType, printDaemonInstructions } from "./daemon.js";
+
+interface ParsedArgs {
+  command: string | undefined;
+  positional: string[];
+  flags: Record<string, string | boolean>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  for (const arg of argv) {
+    if (arg.startsWith("--no-")) {
+      flags[arg.slice(5)] = false;
+    } else if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      } else {
+        flags[arg.slice(2)] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return {
+    command: positional[0],
+    positional,
+    flags,
+  };
+}
+
+const parsed = parseArgs(process.argv.slice(2));
+const { command, positional, flags } = parsed;
+const subcommand = positional[1];
+
+function printUsage(): void {
+  console.log(`npm-registry-shield - Registry proxy that quarantines recent package versions
+
+Usage:
+  npm-registry-shield start [options]      Install + start the background daemon (survives reboots)
+  npm-registry-shield stop                 Stop the daemon and restore package manager configs
+  npm-registry-shield status               Show running state and config
+  npm-registry-shield allow <pkg>          Skip quarantine for a package
+  npm-registry-shield allow <pkg>@<ver>    Allow specific version (with warning)
+  npm-registry-shield remove <pattern>     Remove from passthrough list
+  npm-registry-shield list                 Show passthrough entries
+  npm-registry-shield config get <key>     Show config value
+  npm-registry-shield config set <k> <v>   Update config value
+  npm-registry-shield stats                Show statistics summary
+  npm-registry-shield daemon-template <launchd|systemd>
+                                           Print a service unit (manual install path)
+
+Start options:
+  --foreground          Run in this terminal instead of installing the daemon
+  --quarantine=<days>   Override quarantine period (default: 3)
+  --port=<port>         Override proxy port (default: 4873)
+  --upstream=<url>      Override upstream registry URL
+  --no-dashboard        Disable the web dashboard
+  --dashboard           Enable the web dashboard (default)`);
+}
+
+function applyStartFlags(config: ReturnType<typeof loadConfig>): void {
+  if (flags.quarantine !== undefined) {
+    const days = Number(flags.quarantine);
+    if (isNaN(days) || days <= 0) {
+      console.error("--quarantine must be a positive number");
+      process.exit(1);
+    }
+    config.quarantineDays = days;
+  }
+
+  if (flags.port !== undefined) {
+    const port = Number(flags.port);
+    if (isNaN(port) || port <= 0 || port > 65535) {
+      console.error("--port must be a valid port number (1-65535)");
+      process.exit(1);
+    }
+    config.port = port;
+  }
+
+  if (flags.dashboard === false) {
+    config.dashboard = false;
+  } else if (flags.dashboard === true) {
+    config.dashboard = true;
+  }
+
+  if (flags.upstream !== undefined) {
+    config.upstream = String(flags.upstream);
+  }
+}
+
+function handleStartForeground(): void {
+  const config = loadConfig();
+  applyStartFlags(config);
+
+  if (hasStaleState()) {
+    console.log("[npm-registry-shield] Detected stale backup files from a previous crash. Cleaning up...");
+    forceRestore();
+  }
+  configurePackageManagers(config.port);
+
+  const server = startServer(config);
+
+  const cleanup = (): void => {
+    console.log("\n[npm-registry-shield] Shutting down...");
+    restorePackageManagers();
+    stopServer(server).then(() => {
+      console.log("[npm-registry-shield] Stopped.");
+      process.exit(0);
+    }).catch(() => {
+      process.exit(1);
+    });
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("SIGHUP", cleanup);
+}
+
+function handleStartDaemon(): void {
+  const config = loadConfig();
+  applyStartFlags(config);
+  saveConfig(config);
+
+  if (isDaemonRunning()) {
+    console.log("[npm-registry-shield] Daemon is already running. Use 'npm-registry-shield stop' first.");
+    process.exit(1);
+  }
+
+  try {
+    installDaemon();
+  } catch (err) {
+    if ((err as Error).message === "DAEMON_UNSUPPORTED") {
+      console.log("[npm-registry-shield] Auto-daemon is only supported on macOS and Linux.");
+      console.log("[npm-registry-shield] Falling back to foreground (Ctrl+C to stop).");
+      handleStartForeground();
+      return;
+    }
+    throw err;
+  }
+
+  console.log(`[npm-registry-shield] Quarantine: ${config.quarantineDays} days`);
+  console.log(`[npm-registry-shield] Port: ${config.port}`);
+  if (config.dashboard) {
+    console.log(`[npm-registry-shield] Dashboard: http://localhost:${config.port}/`);
+  }
+}
+
+function handleStart(): void {
+  if (flags.foreground) {
+    handleStartForeground();
+  } else {
+    handleStartDaemon();
+  }
+}
+
+function handleStop(): void {
+  const wasRunning = isDaemonRunning();
+  uninstallDaemon();
+
+  if (hasStaleState()) {
+    forceRestore();
+  }
+
+  if (wasRunning) {
+    console.log("[npm-registry-shield] Daemon stopped and package manager configs restored.");
+  } else if (hasStaleState()) {
+    console.log("[npm-registry-shield] Restored package manager configs (daemon was not running).");
+  } else {
+    console.log("[npm-registry-shield] Nothing to stop.");
+  }
+}
+
+function handleStatus(): void {
+  const config = loadConfig();
+  const running = isDaemonRunning();
+  const stale = hasStaleState();
+  const daemonType = getDaemonType();
+
+  console.log(`npm-registry-shield status:`);
+  console.log(`  Running:        ${running ? `yes (${daemonType})` : "no"}`);
+  console.log(`  Port:           ${config.port}`);
+  console.log(`  Upstream:       ${config.upstream}`);
+  console.log(`  Quarantine:     ${config.quarantineDays} days`);
+  console.log(`  Cache TTL:      ${config.cacheTtlMinutes} minutes`);
+  console.log(`  Dashboard:      ${config.dashboard ? "on" : "off"}`);
+  console.log(`  Passthrough:    ${config.passthrough.length === 0 ? "(none)" : config.passthrough.join(", ")}`);
+
+  if (stale && !running) {
+    console.log(`  WARNING:        Stale config detected - run 'npm-registry-shield stop' to clean up`);
+  }
+}
+
+function handleAllow(): void {
+  const pattern = positional[1];
+  if (!pattern) {
+    console.error("Usage: npm-registry-shield allow <pkg> or npm-registry-shield allow <pkg>@<version>");
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+  if (config.passthrough.includes(pattern)) {
+    console.log(`[npm-registry-shield] "${pattern}" is already in the passthrough list`);
+    return;
+  }
+
+  config.passthrough.push(pattern);
+  saveConfig(config);
+  console.log(`[npm-registry-shield] Added "${pattern}" to passthrough list`);
+}
+
+function handleRemove(): void {
+  const pattern = positional[1];
+  if (!pattern) {
+    console.error("Usage: npm-registry-shield remove <pattern>");
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+  const idx = config.passthrough.indexOf(pattern);
+  if (idx === -1) {
+    console.error(`[npm-registry-shield] "${pattern}" not found in passthrough list`);
+    process.exit(1);
+  }
+
+  config.passthrough.splice(idx, 1);
+  saveConfig(config);
+  console.log(`[npm-registry-shield] Removed "${pattern}" from passthrough list`);
+}
+
+function handleList(): void {
+  const config = loadConfig();
+  if (config.passthrough.length === 0) {
+    console.log("Passthrough list is empty");
+  } else {
+    console.log("Passthrough list:");
+    for (const entry of config.passthrough) {
+      console.log(`  ${entry}`);
+    }
+  }
+}
+
+function handleConfig(): void {
+  const action = subcommand;
+  const key = positional[2];
+
+  if (action === "get") {
+    if (!key) {
+      console.error("Usage: npm-registry-shield config get <key>");
+      process.exit(1);
+    }
+    try {
+      const value = getConfigValue(key);
+      console.log(Array.isArray(value) ? value.join(", ") : String(value));
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (action === "set") {
+    const value = positional[3];
+    if (!key || value === undefined) {
+      console.error("Usage: npm-registry-shield config set <key> <value>");
+      process.exit(1);
+    }
+    try {
+      setConfigValue(key, value);
+      console.log(`[npm-registry-shield] Set ${key} = ${value}`);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  console.error("Usage: npm-registry-shield config <get|set> <key> [value]");
+  process.exit(1);
+}
+
+function handleStats(): void {
+  loadStats();
+  console.log(formatStatsForConsole());
+}
+
+function handleDaemonTemplate(): void {
+  const target = subcommand;
+  if (target !== "launchd" && target !== "systemd") {
+    console.error("Usage: npm-registry-shield daemon-template <launchd|systemd>");
+    process.exit(1);
+  }
+  try {
+    printDaemonInstructions(target);
+  } catch (err) {
+    console.error((err as Error).message);
+    process.exit(1);
+  }
+}
+
+switch (command) {
+  case "start":
+    handleStart();
+    break;
+  case "stop":
+    handleStop();
+    break;
+  case "status":
+    handleStatus();
+    break;
+  case "allow":
+    handleAllow();
+    break;
+  case "remove":
+    handleRemove();
+    break;
+  case "list":
+    handleList();
+    break;
+  case "config":
+    handleConfig();
+    break;
+  case "stats":
+    handleStats();
+    break;
+  case "daemon-template":
+    handleDaemonTemplate();
+    break;
+  case "--help":
+  case "-h":
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}