@itsl-solutions/npm-registry-shield 0.1.0

package/src/filter.ts

@@ -0,0 +1,186 @@
+import type { ShieldConfig } from "./config.js";
+import { recordFiltered, recordBlocked, recordWarning } from "./stats.js";
+
+export interface Packument {
+  name: string;
+  "dist-tags": Record<string, string>;
+  versions: Record<string, Record<string, unknown>>;
+  time: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface FilterResult {
+  packument: Packument;
+  filtered: boolean;
+  filteredCount: number;
+  blocked: boolean;
+  warned: boolean;
+}
+
+export function matchPassthrough(
+  packageName: string,
+  passthrough: string[]
+): { match: boolean; versionSpecific: string[] } {
+  const versionSpecific: string[] = [];
+  let fullMatch = false;
+
+  for (const entry of passthrough) {
+    const atIndex = entry.lastIndexOf("@");
+    const hasVersionPin = atIndex > 0 && !entry.startsWith("@", atIndex - 1);
+
+    if (hasVersionPin) {
+      const entryPkg = entry.substring(0, atIndex);
+      const entryVersion = entry.substring(atIndex + 1);
+      if (entryPkg === packageName) {
+        versionSpecific.push(entryVersion);
+      }
+      continue;
+    }
+
+    if (entry === packageName) {
+      fullMatch = true;
+      break;
+    }
+
+    if (entry.endsWith("/*") && packageName.startsWith(entry.slice(0, -1))) {
+      fullMatch = true;
+      break;
+    }
+  }
+
+  return { match: fullMatch, versionSpecific };
+}
+
+export function filterPackument(
+  packument: Packument,
+  config: ShieldConfig
+): FilterResult {
+  const { match, versionSpecific } = matchPassthrough(
+    packument.name,
+    config.passthrough
+  );
+
+  if (match) {
+    return {
+      packument,
+      filtered: false,
+      filteredCount: 0,
+      blocked: false,
+      warned: false,
+    };
+  }
+
+  const now = Date.now();
+  const quarantineMs = config.quarantineDays * 24 * 60 * 60 * 1000;
+  const filteredVersions: Record<string, Record<string, unknown>> = {};
+  let filteredCount = 0;
+  let warned = false;
+
+  for (const [version, meta] of Object.entries(packument.versions)) {
+    const publishedAt = packument.time[version];
+    if (!publishedAt) {
+      filteredVersions[version] = meta;
+      continue;
+    }
+
+    const age = now - new Date(publishedAt).getTime();
+    const isQuarantined = age < quarantineMs;
+
+    if (!isQuarantined) {
+      filteredVersions[version] = meta;
+      continue;
+    }
+
+    if (versionSpecific.includes(version)) {
+      filteredVersions[version] = meta;
+      warned = true;
+      console.warn(
+        `[npm-registry-shield] WARNING: Allowing quarantined version ${packument.name}@${version} (published ${formatAge(age)} ago, quarantine is ${config.quarantineDays}d)`
+      );
+      recordWarning(packument.name);
+      continue;
+    }
+
+    filteredCount++;
+  }
+
+  if (Object.keys(filteredVersions).length === 0) {
+    recordBlocked(packument.name);
+    return {
+      packument,
+      filtered: true,
+      filteredCount,
+      blocked: true,
+      warned,
+    };
+  }
+
+  const filtered: Packument = {
+    ...packument,
+    versions: filteredVersions,
+    time: { ...packument.time },
+  };
+
+  const newDistTags: Record<string, string> = {};
+  const survivingVersions = Object.keys(filteredVersions);
+
+  for (const [tag, version] of Object.entries(packument["dist-tags"])) {
+    if (version in filteredVersions) {
+      newDistTags[tag] = version;
+    } else {
+      const newest = findNewest(survivingVersions, packument.time);
+      if (newest) {
+        newDistTags[tag] = newest;
+      }
+    }
+  }
+
+  filtered["dist-tags"] = newDistTags;
+
+  if (filteredCount > 0) {
+    recordFiltered(packument.name, filteredCount);
+  }
+
+  return {
+    packument: filtered,
+    filtered: filteredCount > 0,
+    filteredCount,
+    blocked: false,
+    warned,
+  };
+}
+
+export function isVersionQuarantined(
+  publishedAt: string,
+  quarantineDays: number
+): boolean {
+  const age = Date.now() - new Date(publishedAt).getTime();
+  return age < quarantineDays * 24 * 60 * 60 * 1000;
+}
+
+function findNewest(
+  versions: string[],
+  time: Record<string, string>
+): string | null {
+  let newest: string | null = null;
+  let newestTime = 0;
+
+  for (const v of versions) {
+    const t = time[v];
+    if (!t) continue;
+    const ts = new Date(t).getTime();
+    if (ts > newestTime) {
+      newestTime = ts;
+      newest = v;
+    }
+  }
+
+  return newest;
+}
+
+function formatAge(ms: number): string {
+  const hours = Math.floor(ms / (1000 * 60 * 60));
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ${hours % 24}h`;
+}

package/src/origin.ts

@@ -0,0 +1,130 @@
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import type { Socket } from "node:net";
+
+export interface Origin {
+  pid: number;
+  command: string;
+  cwd: string | null;
+  root: string | null;
+}
+
+const SUPPORTED = platform() === "darwin";
+const PID_CACHE = new Map<number, { value: Origin | null; expiresAt: number }>();
+const PID_TTL_MS = 60_000;
+
+function run(cmd: string, args: string[], timeoutMs = 500): Promise<string> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs, encoding: "utf-8" }, (err, stdout) => {
+      resolve(err ? "" : stdout || "");
+    });
+  });
+}
+
+function parseLsofPidByPort(output: string, port: number): number | null {
+  const portTag = `:${port}`;
+  const blocks = output.split(/(?=^p)/m);
+  const selfPid = process.pid;
+  for (const block of blocks) {
+    if (!block.startsWith("p")) continue;
+    const lines = block.split("\n");
+    const pid = Number(lines[0]?.slice(1).trim());
+    if (!Number.isFinite(pid) || pid === selfPid) continue;
+    const isClient = lines.some((line) => {
+      if (!line.startsWith("n")) return false;
+      const arrow = line.indexOf("->");
+      if (arrow === -1) return false;
+      return line.slice(arrow + 2).trim().endsWith(portTag);
+    });
+    if (isClient) return pid;
+  }
+  return null;
+}
+
+async function findRootAncestor(pid: number): Promise<string | null> {
+  let current = pid;
+  let lastName: string | null = null;
+  for (let i = 0; i < 16; i++) {
+    const out = await run("/bin/ps", ["-o", "ppid=,ucomm=", "-p", String(current)]);
+    if (!out) return lastName;
+    const m = out.trim().match(/^\s*(\d+)\s+(.*)$/);
+    if (!m) return lastName;
+    const ppid = m[1]!;
+    const name = m[2]!.trim();
+    lastName = name || lastName;
+    if (ppid === "1" || ppid === "0") return lastName;
+    const next = Number(ppid);
+    if (!Number.isFinite(next) || next === current) return lastName;
+    current = next;
+  }
+  return lastName;
+}
+
+async function lookupByPid(pid: number): Promise<Origin | null> {
+  const cached = PID_CACHE.get(pid);
+  if (cached && cached.expiresAt > Date.now()) return cached.value;
+
+  const [cwdOut, cmdOut, root] = await Promise.all([
+    run("/usr/sbin/lsof", ["-a", "-p", String(pid), "-d", "cwd", "-F", "n"]),
+    run("/bin/ps", ["-p", String(pid), "-o", "command="]),
+    findRootAncestor(pid),
+  ]);
+
+  const cwdLine = cwdOut.split("\n").find((l) => l.startsWith("n"));
+  const cwd = cwdLine ? cwdLine.slice(1).trim() || null : null;
+  const command = cmdOut.trim().split("\n")[0]?.trim() || "";
+
+  const origin = !cwd && !command ? null : { pid, command, cwd, root };
+  PID_CACHE.set(pid, { value: origin, expiresAt: Date.now() + PID_TTL_MS });
+  return origin;
+}
+
+async function lookupOriginForSocket(
+  socket: Socket,
+  proxyPort: number
+): Promise<Origin | null> {
+  const remotePort = socket.remotePort;
+  if (typeof remotePort !== "number") return null;
+
+  const lsofOut = await run("/usr/sbin/lsof", [
+    "-nP",
+    `-iTCP:${remotePort}`,
+    "-sTCP:ESTABLISHED",
+    "-F",
+    "pcfn",
+  ]);
+  const pid = parseLsofPidByPort(lsofOut, proxyPort);
+  return pid ? lookupByPid(pid) : null;
+}
+
+type SocketWithOrigin = Socket & { __origin?: Origin | null };
+
+export function installOriginAttribution(server: { on: (e: "connection", h: (s: Socket) => void) => void }, proxyPort: number): void {
+  if (!SUPPORTED) return;
+  server.on("connection", (socket) => {
+    lookupOriginForSocket(socket, proxyPort)
+      .catch(() => null)
+      .then((origin) => {
+        (socket as SocketWithOrigin).__origin = origin;
+      });
+  });
+}
+
+export function readOrigin(socket: Socket): Origin | null {
+  return (socket as SocketWithOrigin).__origin ?? null;
+}
+
+export function detectToolFromUserAgent(ua: string | undefined): string {
+  if (!ua) return "unknown";
+  const lower = ua.toLowerCase();
+  if (lower.startsWith("npm/") || lower.includes(" npm/")) return "npm";
+  if (lower.includes("pnpm")) return "pnpm";
+  if (lower.includes("yarn")) return "yarn";
+  if (lower.includes("bun")) return "bun";
+  if (lower.includes("deno")) return "deno";
+  if (lower.includes("curl")) return "curl";
+  if (lower.includes("mozilla") || lower.includes("safari") || lower.includes("chrome")) {
+    return "browser";
+  }
+  return ua.split(/[\s/]/)[0]?.toLowerCase() || "unknown";
+}

package/src/pm-config.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync, copyFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const NPMRC_PATH = join(homedir(), ".npmrc");
+const NPMRC_BACKUP = join(homedir(), ".npmrc.npm-shield-backup");
+const YARNRC_PATH = join(homedir(), ".yarnrc.yml");
+const YARNRC_BACKUP = join(homedir(), ".yarnrc.yml.npm-shield-backup");
+
+export function configurePackageManagers(port: number): void {
+  configureNpmrc(port);
+  configureYarnBerry(port);
+  printDenoInstructions(port);
+}
+
+export function restorePackageManagers(): void {
+  restoreNpmrc();
+  restoreYarnBerry();
+  printDenoUnsetReminder();
+}
+
+export function hasStaleState(): boolean {
+  return existsSync(NPMRC_BACKUP) || existsSync(YARNRC_BACKUP);
+}
+
+export function forceRestore(): void {
+  if (existsSync(NPMRC_BACKUP)) {
+    restoreNpmrc();
+  }
+  if (existsSync(YARNRC_BACKUP)) {
+    restoreYarnBerry();
+  }
+}
+
+function configureNpmrc(port: number): void {
+  if (existsSync(NPMRC_PATH)) {
+    copyFileSync(NPMRC_PATH, NPMRC_BACKUP);
+  } else {
+    writeFileSync(NPMRC_BACKUP, "", { encoding: "utf-8", mode: 0o600 });
+  }
+  chmodSync(NPMRC_BACKUP, 0o600);
+
+  const registryLine = `registry=http://localhost:${port}`;
+  const replaceHostLine = `replace-registry-host=never`;
+  let content = "";
+
+  if (existsSync(NPMRC_PATH)) {
+    content = readFileSync(NPMRC_PATH, "utf-8");
+    const lines = content.split("\n").filter((line) => {
+      const trimmed = line.trim();
+      return (
+        !trimmed.startsWith("registry=") &&
+        !trimmed.startsWith("replace-registry-host=")
+      );
+    });
+    content = lines.join("\n");
+    if (content.length > 0 && !content.endsWith("\n")) {
+      content += "\n";
+    }
+  }
+
+  content += registryLine + "\n" + replaceHostLine + "\n";
+  writeFileSync(NPMRC_PATH, content, "utf-8");
+  console.log(`[npm-registry-shield] Updated ~/.npmrc (backup at ~/.npmrc.npm-shield-backup)`);
+}
+
+function restoreNpmrc(): void {
+  if (!existsSync(NPMRC_BACKUP)) {
+    console.log("[npm-registry-shield] No .npmrc backup found, skipping restore");
+    return;
+  }
+
+  const backup = readFileSync(NPMRC_BACKUP, "utf-8");
+  if (backup.length === 0) {
+    if (existsSync(NPMRC_PATH)) {
+      unlinkSync(NPMRC_PATH);
+    }
+  } else {
+    writeFileSync(NPMRC_PATH, backup, "utf-8");
+  }
+
+  unlinkSync(NPMRC_BACKUP);
+  console.log("[npm-registry-shield] Restored ~/.npmrc");
+}
+
+function configureYarnBerry(port: number): void {
+  if (!existsSync(YARNRC_PATH)) {
+    return;
+  }
+
+  copyFileSync(YARNRC_PATH, YARNRC_BACKUP);
+
+  let content = readFileSync(YARNRC_PATH, "utf-8");
+  const lines = content.split("\n").filter(
+    (line) => !line.trim().startsWith("npmRegistryServer:")
+  );
+  content = lines.join("\n");
+  if (content.length > 0 && !content.endsWith("\n")) {
+    content += "\n";
+  }
+  content += `npmRegistryServer: "http://localhost:${port}"\n`;
+
+  writeFileSync(YARNRC_PATH, content, "utf-8");
+  console.log(`[npm-registry-shield] Updated ~/.yarnrc.yml (backup at ~/.yarnrc.yml.npm-shield-backup)`);
+}
+
+function restoreYarnBerry(): void {
+  if (!existsSync(YARNRC_BACKUP)) {
+    return;
+  }
+
+  const backup = readFileSync(YARNRC_BACKUP, "utf-8");
+  writeFileSync(YARNRC_PATH, backup, "utf-8");
+  unlinkSync(YARNRC_BACKUP);
+  console.log("[npm-registry-shield] Restored ~/.yarnrc.yml");
+}
+
+function printDenoInstructions(port: number): void {
+  console.log(`[npm-registry-shield] For Deno, run: export DENO_NPM_REGISTRY=http://localhost:${port}`);
+}
+
+function printDenoUnsetReminder(): void {
+  console.log("[npm-registry-shield] If using Deno, run: unset DENO_NPM_REGISTRY");
+}

package/src/registry.ts

@@ -0,0 +1,128 @@
+import type { Packument } from "./filter.js";
+
+interface CacheEntry {
+  data: Packument;
+  timestamp: number;
+}
+
+const FETCH_TIMEOUT_MS = 10_000;
+const CACHE_MAX_ENTRIES = 1000;
+const cache = new Map<string, CacheEntry>();
+
+export function getCachedPackument(
+  packageName: string,
+  ttlMinutes: number
+): Packument | null {
+  const entry = cache.get(packageName);
+  if (!entry) return null;
+  const age = Date.now() - entry.timestamp;
+  if (age > ttlMinutes * 60 * 1000) {
+    cache.delete(packageName);
+    return null;
+  }
+  cache.delete(packageName);
+  cache.set(packageName, entry);
+  return entry.data;
+}
+
+export function setCachedPackument(
+  packageName: string,
+  data: Packument
+): void {
+  if (cache.has(packageName)) cache.delete(packageName);
+  cache.set(packageName, { data, timestamp: Date.now() });
+  while (cache.size > CACHE_MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest === undefined) break;
+    cache.delete(oldest);
+  }
+}
+
+export function clearCache(packageName?: string): void {
+  if (packageName) {
+    cache.delete(packageName);
+  } else {
+    cache.clear();
+  }
+}
+
+export async function fetchPackument(
+  packageName: string,
+  upstream: string
+): Promise<Packument | null> {
+  const url = `${upstream}/${packageName}`;
+  const res = await fetch(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+
+  if (res.status === 404) return null;
+
+  if (!res.ok) {
+    throw new Error(`Upstream returned ${res.status} for ${packageName}`);
+  }
+
+  return (await res.json()) as Packument;
+}
+
+export async function fetchVersionMetadata(
+  packageName: string,
+  version: string,
+  upstream: string
+): Promise<{ status: number; body: string; contentType: string }> {
+  const url = `${upstream}/${packageName}/${version}`;
+  const res = await fetch(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+
+  return {
+    status: res.status,
+    body: await res.text(),
+    contentType: res.headers.get("content-type") || "application/json",
+  };
+}
+
+export async function proxyRequest(
+  method: string,
+  path: string,
+  upstream: string,
+  headers: Record<string, string>,
+  requestBody?: Buffer
+): Promise<{ status: number; body: Buffer; headers: Record<string, string> }> {
+  const url = `${upstream}${path}`;
+
+  const forwardHeaders: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    const k = key.toLowerCase();
+    if (k === "host" || k === "connection" || k === "content-length") continue;
+    forwardHeaders[key] = value;
+  }
+
+  const hasBody = requestBody !== undefined && requestBody.length > 0;
+  const res = await fetch(url, {
+    method,
+    headers: forwardHeaders,
+    body: hasBody ? new Uint8Array(requestBody) : undefined,
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+
+  const arrayBuf = await res.arrayBuffer();
+  const responseBody = Buffer.from(arrayBuf);
+
+  const responseHeaders: Record<string, string> = {};
+  res.headers.forEach((value, key) => {
+    const k = key.toLowerCase();
+    if (k === "content-encoding" || k === "content-length" || k === "transfer-encoding") {
+      return;
+    }
+    responseHeaders[key] = value;
+  });
+  responseHeaders["content-length"] = String(responseBody.length);
+
+  return {
+    status: res.status,
+    body: responseBody,
+    headers: responseHeaders,
+  };
+}