@cyberhub/shieldpm 0.1.0

package/src/diff/dependency.ts

@@ -0,0 +1,297 @@
+/**
+ * ShieldPM — Dependency Diff
+ * Compare two states of package-lock.json to detect meaningful changes
+ * in the dependency tree — new packages, version bumps, and red flags.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface LockPackageInfo {
+  version: string;
+  resolved?: string;
+  integrity?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  hasInstallScript?: boolean;
+  hasBin?: boolean;
+}
+
+export interface PackageDelta {
+  name: string;
+  type: 'added' | 'removed' | 'changed';
+  oldVersion?: string;
+  newVersion?: string;
+  /** Significant changes detected */
+  flags: DeltaFlag[];
+}
+
+export interface DeltaFlag {
+  type: 'new-install-script' | 'new-native-module' | 'new-network-dep' | 'major-bump' |
+        'new-dependency' | 'removed-dependency' | 'version-downgrade' | 'new-bin';
+  message: string;
+}
+
+export interface DependencyDiffReport {
+  /** Total packages in the old lock */
+  oldPackageCount: number;
+  /** Total packages in the new lock */
+  newPackageCount: number;
+  /** Added packages */
+  added: PackageDelta[];
+  /** Removed packages */
+  removed: PackageDelta[];
+  /** Changed packages */
+  changed: PackageDelta[];
+  /** High-level summary */
+  summary: string;
+  /** Red flags found */
+  flags: DeltaFlag[];
+}
+
+// ── Lock file parsing ────────────────────────────────────────────────────
+
+interface LockfileV2 {
+  lockfileVersion?: number;
+  packages?: Record<string, LockPackageInfo>;
+  dependencies?: Record<string, LockPackageInfo>;
+}
+
+function parseLockPackages(lockContent: string): Map<string, LockPackageInfo> {
+  const lock: LockfileV2 = JSON.parse(lockContent);
+  const packages = new Map<string, LockPackageInfo>();
+
+  if (lock.packages) {
+    // v2/v3 format: keys are "node_modules/<name>"
+    for (const [key, info] of Object.entries(lock.packages)) {
+      if (key === '') continue; // Root package
+      const name = key.replace(/^node_modules\//, '');
+      // Skip nested node_modules
+      if (name.includes('node_modules/')) continue;
+      packages.set(name, info);
+    }
+  } else if (lock.dependencies) {
+    // v1 format
+    for (const [name, info] of Object.entries(lock.dependencies)) {
+      packages.set(name, info);
+    }
+  }
+
+  return packages;
+}
+
+// ── Known network-capable packages ───────────────────────────────────────
+
+const NETWORK_PACKAGES = new Set([
+  'node-fetch', 'axios', 'got', 'request', 'superagent', 'undici',
+  'http-proxy', 'http-proxy-agent', 'https-proxy-agent', 'socks-proxy-agent',
+  'socket.io', 'ws', 'websocket', 'net', 'dgram',
+]);
+
+const NATIVE_PACKAGES = new Set([
+  'node-gyp', 'node-pre-gyp', 'prebuild-install', 'nan', 'napi',
+  'sharp', 'bcrypt', 'better-sqlite3', 'canvas', 'grpc',
+  'sqlite3', 'pg-native', 'libxmljs',
+]);
+
+// ── Version comparison ───────────────────────────────────────────────────
+
+function parseSemver(version: string): { major: number; minor: number; patch: number } | null {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10),
+  };
+}
+
+function isMajorBump(oldVer: string, newVer: string): boolean {
+  const o = parseSemver(oldVer);
+  const n = parseSemver(newVer);
+  if (!o || !n) return false;
+  return n.major > o.major;
+}
+
+function isDowngrade(oldVer: string, newVer: string): boolean {
+  const o = parseSemver(oldVer);
+  const n = parseSemver(newVer);
+  if (!o || !n) return false;
+  if (n.major < o.major) return true;
+  if (n.major === o.major && n.minor < o.minor) return true;
+  if (n.major === o.major && n.minor === o.minor && n.patch < o.patch) return true;
+  return false;
+}
+
+// ── Diff computation ─────────────────────────────────────────────────────
+
+function computeFlags(
+  name: string,
+  oldInfo: LockPackageInfo | undefined,
+  newInfo: LockPackageInfo | undefined
+): DeltaFlag[] {
+  const flags: DeltaFlag[] = [];
+
+  if (newInfo && !oldInfo) {
+    // Newly added package
+    if (newInfo.hasInstallScript) {
+      flags.push({
+        type: 'new-install-script',
+        message: `New package "${name}" has install scripts`,
+      });
+    }
+    if (NATIVE_PACKAGES.has(name)) {
+      flags.push({
+        type: 'new-native-module',
+        message: `New package "${name}" is a native module`,
+      });
+    }
+    if (NETWORK_PACKAGES.has(name)) {
+      flags.push({
+        type: 'new-network-dep',
+        message: `New package "${name}" has network capabilities`,
+      });
+    }
+    if (newInfo.hasBin) {
+      flags.push({
+        type: 'new-bin',
+        message: `New package "${name}" installs binaries`,
+      });
+    }
+  }
+
+  if (oldInfo && newInfo) {
+    // Version change checks
+    if (oldInfo.version && newInfo.version) {
+      if (isMajorBump(oldInfo.version, newInfo.version)) {
+        flags.push({
+          type: 'major-bump',
+          message: `"${name}" major version bump: ${oldInfo.version} -> ${newInfo.version}`,
+        });
+      }
+      if (isDowngrade(oldInfo.version, newInfo.version)) {
+        flags.push({
+          type: 'version-downgrade',
+          message: `"${name}" version downgrade: ${oldInfo.version} -> ${newInfo.version}`,
+        });
+      }
+    }
+
+    // New install script added
+    if (!oldInfo.hasInstallScript && newInfo.hasInstallScript) {
+      flags.push({
+        type: 'new-install-script',
+        message: `"${name}" added install scripts in ${newInfo.version}`,
+      });
+    }
+
+    // New sub-dependencies
+    const oldDeps = new Set(Object.keys(oldInfo.dependencies ?? {}));
+    const newDeps = Object.keys(newInfo.dependencies ?? {});
+    for (const dep of newDeps) {
+      if (!oldDeps.has(dep)) {
+        flags.push({
+          type: 'new-dependency',
+          message: `"${name}" added new dependency "${dep}"`,
+        });
+      }
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Compare two package-lock.json contents and produce a diff report.
+ */
+export function diffLockfiles(
+  oldLockContent: string,
+  newLockContent: string
+): DependencyDiffReport {
+  const oldPackages = parseLockPackages(oldLockContent);
+  const newPackages = parseLockPackages(newLockContent);
+
+  const added: PackageDelta[] = [];
+  const removed: PackageDelta[] = [];
+  const changed: PackageDelta[] = [];
+  const allFlags: DeltaFlag[] = [];
+
+  // Find added and changed
+  for (const [name, newInfo] of newPackages) {
+    const oldInfo = oldPackages.get(name);
+
+    if (!oldInfo) {
+      const flags = computeFlags(name, undefined, newInfo);
+      added.push({
+        name,
+        type: 'added',
+        newVersion: newInfo.version,
+        flags,
+      });
+      allFlags.push(...flags);
+    } else if (oldInfo.version !== newInfo.version) {
+      const flags = computeFlags(name, oldInfo, newInfo);
+      changed.push({
+        name,
+        type: 'changed',
+        oldVersion: oldInfo.version,
+        newVersion: newInfo.version,
+        flags,
+      });
+      allFlags.push(...flags);
+    }
+  }
+
+  // Find removed
+  for (const [name, oldInfo] of oldPackages) {
+    if (!newPackages.has(name)) {
+      removed.push({
+        name,
+        type: 'removed',
+        oldVersion: oldInfo.version,
+        flags: [],
+      });
+    }
+  }
+
+  // Sort alphabetically
+  added.sort((a, b) => a.name.localeCompare(b.name));
+  removed.sort((a, b) => a.name.localeCompare(b.name));
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Summary
+  const parts: string[] = [];
+  if (added.length > 0) parts.push(`${added.length} added`);
+  if (removed.length > 0) parts.push(`${removed.length} removed`);
+  if (changed.length > 0) parts.push(`${changed.length} changed`);
+  if (allFlags.length > 0) parts.push(`${allFlags.length} flags`);
+
+  const summary = parts.length > 0
+    ? `Dependency changes: ${parts.join(', ')}`
+    : 'No dependency changes';
+
+  return {
+    oldPackageCount: oldPackages.size,
+    newPackageCount: newPackages.size,
+    added,
+    removed,
+    changed,
+    summary,
+    flags: allFlags,
+  };
+}
+
+/**
+ * Load and diff two package-lock.json files from disk.
+ */
+export async function diffLockfilesByPath(
+  oldPath: string,
+  newPath: string
+): Promise<DependencyDiffReport> {
+  const [oldContent, newContent] = await Promise.all([
+    readFile(oldPath, 'utf-8'),
+    readFile(newPath, 'utf-8'),
+  ]);
+  return diffLockfiles(oldContent, newContent);
+}

package/src/fingerprint/profile.ts

@@ -0,0 +1,333 @@
+/**
+ * ShieldPM — Behavioral Fingerprinting
+ * Creates and compares behavioral profiles for packages to detect
+ * unexpected changes between versions.
+ */
+
+import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
+import { join, extname, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface BehaviorProfile {
+  /** Package name */
+  name: string;
+  /** Package version */
+  version: string;
+  /** ISO timestamp of when the profile was generated */
+  generatedAt: string;
+  /** SHA-256 hash of all .js file contents concatenated */
+  contentHash: string;
+  /** Individual file hashes */
+  fileHashes: Record<string, string>;
+  /** All require() and import statements found */
+  imports: string[];
+  /** Native module bindings (e.g., .node files, node-gyp) */
+  nativeBindings: string[];
+  /** Network endpoints parsed from source */
+  networkEndpoints: string[];
+  /** Filesystem paths parsed from source */
+  fsPaths: string[];
+  /** Total file count */
+  fileCount: number;
+  /** Total size in bytes */
+  totalSize: number;
+}
+
+export interface ProfileDiff {
+  /** Newly added imports */
+  addedImports: string[];
+  /** Removed imports */
+  removedImports: string[];
+  /** Newly added network endpoints */
+  addedNetworkEndpoints: string[];
+  /** Removed network endpoints */
+  removedNetworkEndpoints: string[];
+  /** New filesystem paths */
+  addedFsPaths: string[];
+  /** Removed filesystem paths */
+  removedFsPaths: string[];
+  /** New native bindings */
+  addedNativeBindings: string[];
+  /** Removed native bindings */
+  removedNativeBindings: string[];
+  /** Files added */
+  addedFiles: string[];
+  /** Files removed */
+  removedFiles: string[];
+  /** Files with changed content */
+  changedFiles: string[];
+  /** Whether the overall content hash changed */
+  contentHashChanged: boolean;
+  /** Human-readable summary */
+  summary: string;
+}
+
+// ── Profile storage ──────────────────────────────────────────────────────
+
+const PROFILE_DIR = '.shieldpm/profiles';
+
+function profilePath(baseDir: string, name: string, version: string): string {
+  return join(baseDir, PROFILE_DIR, `${name.replace('/', '__')}@${version}.json`);
+}
+
+export async function saveProfile(baseDir: string, profile: BehaviorProfile): Promise<string> {
+  const dir = join(baseDir, PROFILE_DIR);
+  await mkdir(dir, { recursive: true });
+
+  const path = profilePath(baseDir, profile.name, profile.version);
+  await writeFile(path, JSON.stringify(profile, null, 2) + '\n', 'utf-8');
+  return path;
+}
+
+export async function loadProfile(
+  baseDir: string,
+  name: string,
+  version: string
+): Promise<BehaviorProfile | null> {
+  const path = profilePath(baseDir, name, version);
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw) as BehaviorProfile;
+  } catch {
+    return null;
+  }
+}
+
+// ── Source parsing helpers ────────────────────────────────────────────────
+
+const JS_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'test', 'tests', '__tests__']);
+
+async function collectSourceFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function walk(d: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) await walk(full);
+      } else if (entry.isFile() && JS_EXTENSIONS.has(extname(entry.name))) {
+        files.push(full);
+      }
+    }
+  }
+
+  await walk(dir);
+  return files.sort();
+}
+
+function extractImports(source: string): string[] {
+  const imports = new Set<string>();
+
+  // CommonJS require
+  const requireRe = /require\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = requireRe.exec(source)) !== null) {
+    imports.add(m[1]);
+  }
+
+  // ESM import
+  const importRe = /(?:import|export)\s+.*?from\s+['"`]([^'"`]+)['"`]/g;
+  while ((m = importRe.exec(source)) !== null) {
+    imports.add(m[1]);
+  }
+
+  // Dynamic import
+  const dynImportRe = /import\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+  while ((m = dynImportRe.exec(source)) !== null) {
+    imports.add(m[1]);
+  }
+
+  return [...imports].sort();
+}
+
+function extractNetworkEndpoints(source: string): string[] {
+  const endpoints = new Set<string>();
+
+  // URL literals
+  const urlRe = /['"`](https?:\/\/[^'"`\s]+)['"`]/g;
+  let m: RegExpExecArray | null;
+  while ((m = urlRe.exec(source)) !== null) {
+    endpoints.add(m[1]);
+  }
+
+  // fetch/http.request with template literals are harder — capture hostname patterns
+  const hostRe = /(?:hostname|host)\s*[:=]\s*['"`]([^'"`]+)['"`]/g;
+  while ((m = hostRe.exec(source)) !== null) {
+    endpoints.add(m[1]);
+  }
+
+  return [...endpoints].sort();
+}
+
+function extractFsPaths(source: string): string[] {
+  const paths = new Set<string>();
+
+  // readFile, writeFile, etc. with string literals
+  const fsRe = /(?:readFile|writeFile|readdir|unlink|stat|access|mkdir|rmdir|rename|copyFile|appendFile)\w*\s*\(\s*['"`]([^'"`]+)['"`]/g;
+  let m: RegExpExecArray | null;
+  while ((m = fsRe.exec(source)) !== null) {
+    paths.add(m[1]);
+  }
+
+  return [...paths].sort();
+}
+
+function extractNativeBindings(files: string[], source: string): string[] {
+  const bindings = new Set<string>();
+
+  // .node files
+  for (const f of files) {
+    if (f.endsWith('.node')) {
+      bindings.add(f);
+    }
+  }
+
+  // require with .node extension
+  const nodeReqRe = /require\s*\(\s*['"`]([^'"`]*\.node)['"`]\s*\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = nodeReqRe.exec(source)) !== null) {
+    bindings.add(m[1]);
+  }
+
+  // node-gyp / node-pre-gyp / prebuild patterns
+  if (/binding\.gyp|node-gyp|node-pre-gyp|prebuild-install|napi_/.test(source)) {
+    bindings.add('<native-addon>');
+  }
+
+  return [...bindings].sort();
+}
+
+// ── Profile generation ───────────────────────────────────────────────────
+
+/**
+ * Generate a behavioral profile for a package directory.
+ */
+export async function generateProfile(
+  packageDir: string,
+  name: string,
+  version: string
+): Promise<BehaviorProfile> {
+  const files = await collectSourceFiles(packageDir);
+
+  const allImports = new Set<string>();
+  const allEndpoints = new Set<string>();
+  const allFsPaths = new Set<string>();
+  const fileHashes: Record<string, string> = {};
+  const contentParts: string[] = [];
+  let totalSize = 0;
+  let allSourceConcat = '';
+
+  for (const file of files) {
+    let content: string;
+    try {
+      content = await readFile(file, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const relPath = relative(packageDir, file);
+    const hash = createHash('sha256').update(content).digest('hex');
+    fileHashes[relPath] = hash;
+    contentParts.push(content);
+    totalSize += Buffer.byteLength(content);
+    allSourceConcat += content + '\n';
+
+    for (const imp of extractImports(content)) allImports.add(imp);
+    for (const ep of extractNetworkEndpoints(content)) allEndpoints.add(ep);
+    for (const fp of extractFsPaths(content)) allFsPaths.add(fp);
+  }
+
+  const contentHash = createHash('sha256')
+    .update(contentParts.join('\n'))
+    .digest('hex');
+
+  const nativeBindings = extractNativeBindings(
+    files.map((f) => relative(packageDir, f)),
+    allSourceConcat
+  );
+
+  return {
+    name,
+    version,
+    generatedAt: new Date().toISOString(),
+    contentHash,
+    fileHashes,
+    imports: [...allImports].sort(),
+    nativeBindings,
+    networkEndpoints: [...allEndpoints].sort(),
+    fsPaths: [...allFsPaths].sort(),
+    fileCount: files.length,
+    totalSize,
+  };
+}
+
+// ── Profile comparison ───────────────────────────────────────────────────
+
+function arrayDiff<T>(oldArr: T[], newArr: T[]): { added: T[]; removed: T[] } {
+  const oldSet = new Set(oldArr);
+  const newSet = new Set(newArr);
+  return {
+    added: newArr.filter((x) => !oldSet.has(x)),
+    removed: oldArr.filter((x) => !newSet.has(x)),
+  };
+}
+
+/**
+ * Compare two behavioral profiles and report differences.
+ */
+export function diffProfiles(oldProfile: BehaviorProfile, newProfile: BehaviorProfile): ProfileDiff {
+  const importDiff = arrayDiff(oldProfile.imports, newProfile.imports);
+  const netDiff = arrayDiff(oldProfile.networkEndpoints, newProfile.networkEndpoints);
+  const fsDiff = arrayDiff(oldProfile.fsPaths, newProfile.fsPaths);
+  const nativeDiff = arrayDiff(oldProfile.nativeBindings, newProfile.nativeBindings);
+
+  const oldFiles = Object.keys(oldProfile.fileHashes);
+  const newFiles = Object.keys(newProfile.fileHashes);
+  const fileDiff = arrayDiff(oldFiles, newFiles);
+
+  const commonFiles = oldFiles.filter((f) => newFiles.includes(f));
+  const changedFiles = commonFiles.filter(
+    (f) => oldProfile.fileHashes[f] !== newProfile.fileHashes[f]
+  );
+
+  const contentHashChanged = oldProfile.contentHash !== newProfile.contentHash;
+
+  // Build summary
+  const parts: string[] = [];
+  if (fileDiff.added.length > 0) parts.push(`${fileDiff.added.length} files added`);
+  if (fileDiff.removed.length > 0) parts.push(`${fileDiff.removed.length} files removed`);
+  if (changedFiles.length > 0) parts.push(`${changedFiles.length} files changed`);
+  if (importDiff.added.length > 0) parts.push(`${importDiff.added.length} new imports`);
+  if (importDiff.removed.length > 0) parts.push(`${importDiff.removed.length} removed imports`);
+  if (netDiff.added.length > 0) parts.push(`${netDiff.added.length} new network endpoints`);
+  if (nativeDiff.added.length > 0) parts.push(`${nativeDiff.added.length} new native bindings`);
+
+  const summary = parts.length > 0
+    ? `Changes: ${parts.join(', ')}`
+    : 'No behavioral changes detected';
+
+  return {
+    addedImports: importDiff.added,
+    removedImports: importDiff.removed,
+    addedNetworkEndpoints: netDiff.added,
+    removedNetworkEndpoints: netDiff.removed,
+    addedFsPaths: fsDiff.added,
+    removedFsPaths: fsDiff.removed,
+    addedNativeBindings: nativeDiff.added,
+    removedNativeBindings: nativeDiff.removed,
+    addedFiles: fileDiff.added,
+    removedFiles: fileDiff.removed,
+    changedFiles,
+    contentHashChanged,
+    summary,
+  };
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * ShieldPM — Public API
+ * Runtime-aware package firewall for Node.js
+ *
+ * @module shieldpm
+ */
+
+// Static analysis
+export { analyzePackage, analyzeSource } from './analyzer/static.js';
+export type { Finding, RiskReport, Severity } from './analyzer/static.js';
+
+// Typosquatting detection
+export { checkTyposquatting, checkMultiple, levenshtein, POPULAR_PACKAGES } from './analyzer/typosquat.js';
+export type { TyposquatResult, DetectionMethod } from './analyzer/typosquat.js';
+
+// Sandbox execution
+export { runSandboxed, runPostInstall } from './sandbox/runner.js';
+export type { SandboxOptions, SandboxResult } from './sandbox/runner.js';
+
+// Permission manifest
+export { loadManifest, saveManifest, validateAccess, generateManifest } from './monitor/permissions.js';
+export type { PermissionManifest, PackagePermissions, AccessCheck, ResourceType } from './monitor/permissions.js';
+
+// Behavioral fingerprinting
+export { generateProfile, diffProfiles, saveProfile, loadProfile } from './fingerprint/profile.js';
+export type { BehaviorProfile, ProfileDiff } from './fingerprint/profile.js';
+
+// Dependency diff
+export { diffLockfiles, diffLockfilesByPath } from './diff/dependency.js';
+export type { DependencyDiffReport, PackageDelta, DeltaFlag } from './diff/dependency.js';
+
+// Utilities
+export { log } from './utils/logger.js';
+export * as colors from './utils/colors.js';