pkg-gate 0.1.0

package/src/index.js

@@ -0,0 +1,54 @@
+import { resolveManifest } from './resolver.js';
+import { evaluatePackage } from './gate.js';
+
+/**
+ * Pre-install security gate for npm lifecycle scripts using TypeSafe System One.
+ *
+ * @param {string | object} input - Package name ('esbuild'), path ('./package.json'), or manifest object
+ * @param {object} [options] - Evaluation options
+ * @param {string} [options.apiKey] - TypeSafe API key (falls back to process.env.TYPESAFE_API_KEY)
+ * @param {boolean} [options.mock] - Force local offline simulation
+ * @param {boolean} [options.script] - Treat string input as a raw script command
+ * @returns {Promise<import('./gate.js').GateReport>}
+ */
+function looksLikeShellCommand(input) {
+  if (typeof input !== 'string') return false;
+  const trimmed = input.trim();
+  if (trimmed.startsWith('.') || trimmed.startsWith('/') || trimmed.endsWith('.json')) {
+    return false;
+  }
+  return (
+    /(\||\&\&|;|\|\||`|\$\(|\b(curl|wget|bash|sh|node -e|eval|exec|sudo|chmod|rm -rf)\b)/.test(trimmed) ||
+    (trimmed.includes(' ') && !trimmed.startsWith('@'))
+  );
+}
+
+export default async function pkgGate(input, options = {}) {
+  const isScript = Boolean(options.script || looksLikeShellCommand(input));
+
+  if (isScript && typeof input === 'string') {
+    return evaluatePackage(
+      {
+        name: 'inline-script',
+        version: '0.0.0',
+        description: 'Single inline lifecycle script',
+        scripts: { postinstall: input },
+      },
+      options
+    );
+  }
+
+  const manifest = await resolveManifest(input);
+  return evaluatePackage(manifest, options);
+}
+
+// Backward compatibility alias
+export const pkgGuard = pkgGate;
+
+export { evaluatePackage } from './gate.js';
+export { resolveManifest } from './resolver.js';
+export { THRESHOLDS, createLifecycleQuestions } from './questions.js';
+export { simulateLifecycleEvaluation } from './simulator.js';
+export { formatReport } from './utils.js';
+export { renderTUI, drawBox, getTerminalWidth } from './tui.js';
+

package/src/questions.js

@@ -0,0 +1,66 @@
+import { choice, noul, score } from '@typesafe-ai/sdk';
+
+/**
+ * Deterministic decision thresholds.
+ * Centralized here for easy review and calibration.
+ */
+export const THRESHOLDS = {
+  // Score >= 2.0 triggers automatic block
+  BLOCK_SCORE: 2.0,
+  // Score >= 1.2 triggers warning / confirmation
+  WARN_SCORE: 1.2,
+  // Secret harvesting probability >= 0.6 triggers block
+  BLOCK_SECRET_NOUL: 0.6,
+  // Secret harvesting probability >= 0.3 triggers warning
+  WARN_SECRET_NOUL: 0.3,
+  // Arbitrary remote code download/exec >= 0.6 triggers block
+  BLOCK_REMOTE_EXEC_NOUL: 0.6,
+  // Arbitrary remote code download/exec >= 0.3 triggers warning
+  WARN_REMOTE_EXEC_NOUL: 0.3,
+  // Confidence floor: decisions with lower confidence route to human review
+  CONFIDENCE_FLOOR: 0.5,
+};
+
+/**
+ * The battery of TypeSafe System One questions asked for each lifecycle script.
+ * Evaluated in parallel within a single System One call.
+ */
+export function createLifecycleQuestions() {
+  return {
+    script_intent: choice(
+      'What is the primary intent and runtime behavior of `script_content` executed in lifecycle hook `lifecycle_hook`?',
+      {
+        build_tool: 'Standard compilation or native build (e.g. node-gyp, esbuild, tsc, cargo)',
+        binary_download: 'Downloads official pre-compiled native binaries or assets from a known repository or CDN',
+        benign_notice: 'Informational message, donation banner, or benign no-op command',
+        system_recon: 'Gathers host system details, environment variables, network interfaces, or user directories',
+        credential_access: 'Reads or extracts secrets, authentication tokens (NPM_TOKEN, AWS, SSH keys), or credential files',
+        obfuscated_exec: 'Executes obfuscated code, base64 payloads, or pipes curl/wget to bash/sh/node',
+        other: 'General package maintenance or utility task',
+      }
+    ),
+    threat_severity: score(
+      'How severe is the security risk of executing `script_content` during npm install of `package.name`?',
+      [
+        'Safe: standard build or benign command with no external network or secret access',
+        'Low risk: fetches known binary from release domain or routine package setup',
+        'Suspicious: makes non-standard outbound connections, inspects system environment, or runs encoded commands',
+        'Critical threat: credential harvesting, token exfiltration, backdoor dropper, or destructive action',
+      ]
+    ),
+    accesses_secrets: noul(
+      'Does `script_content` attempt to access, extract, or transmit environment variables, private credentials, or authentication tokens?',
+      {
+        true: 'It accesses or exfiltrates environment secrets, auth tokens, or private credentials',
+        false: 'It does not attempt to access credentials or environment secrets',
+      }
+    ),
+    remote_execution: noul(
+      'Does `script_content` download and execute arbitrary unverified external code or pipe remote scripts directly into a shell?',
+      {
+        true: 'It downloads and executes unverified remote code or uses curl/wget piping to a shell',
+        false: 'It only runs local tools or verified fixed installers',
+      }
+    ),
+  };
+}

package/src/resolver.js

@@ -0,0 +1,133 @@
+import { readFile, stat } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+
+/**
+ * Resolves an input (package name, file path, directory, or object) into a normalized manifest.
+ *
+ * @param {string | object} input
+ * @returns {Promise<{ name: string, version: string, scripts: Record<string, string>, raw: object }>}
+ */
+export async function resolveManifest(input) {
+  if (!input) {
+    throw new Error('No package or manifest provided to pkg-gate');
+  }
+
+  // Case 1: Plain manifest object
+  if (typeof input === 'object' && input !== null) {
+    return normalizeManifest(input);
+  }
+
+  if (typeof input !== 'string') {
+    throw new TypeError(`Expected package name or path string, got ${typeof input}`);
+  }
+
+  const trimmed = input.trim();
+
+  // Case 2: Local file path or directory
+  if (trimmed.startsWith('.') || trimmed.startsWith('/') || trimmed.endsWith('.json')) {
+    return loadLocalManifest(trimmed);
+  }
+
+  // Case 3: Check if local directory/file exists with that name before querying registry
+  try {
+    const localPath = resolve(process.cwd(), trimmed);
+    const stats = await stat(localPath);
+    if (stats.isDirectory() || stats.isFile()) {
+      return loadLocalManifest(localPath);
+    }
+  } catch {
+    // Not a local path, continue to npm registry
+  }
+
+  // Case 4: Fetch from npm registry
+  return fetchRegistryManifest(trimmed);
+}
+
+async function loadLocalManifest(filePath) {
+  let target = resolve(process.cwd(), filePath);
+  let stats;
+  try {
+    stats = await stat(target);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`File or directory not found: "${filePath}". Please pass a valid package.json path or npm package name.`);
+    }
+    throw err;
+  }
+
+  if (stats.isDirectory()) {
+    target = join(target, 'package.json');
+    try {
+      await stat(target);
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        throw new Error(`Directory "${filePath}" does not contain a package.json file.`);
+      }
+      throw err;
+    }
+  }
+
+  try {
+    const content = await readFile(target, 'utf8');
+    const json = JSON.parse(content);
+    return normalizeManifest(json);
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Invalid JSON syntax in "${target}": ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+
+async function fetchRegistryManifest(packageName) {
+  // Support scoped packages like @foo/bar or specific versions like foo@1.2.3
+  let name = packageName;
+  let tagOrVersion = 'latest';
+
+  if (packageName.startsWith('@')) {
+    const parts = packageName.split('@');
+    if (parts.length === 3) {
+      name = `@${parts[1]}`;
+      tagOrVersion = parts[2];
+    }
+  } else if (packageName.includes('@')) {
+    const parts = packageName.split('@');
+    name = parts[0];
+    tagOrVersion = parts[1];
+  }
+
+  const encodedName = name.startsWith('@')
+    ? `@${encodeURIComponent(name.slice(1))}`
+    : encodeURIComponent(name);
+
+  const url = `https://registry.npmjs.org/${encodedName}/${tagOrVersion}`;
+  const res = await fetch(url, {
+    headers: {
+      Accept: 'application/json',
+      'User-Agent': 'pkg-gate/0.1.0',
+    },
+  });
+
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error(`Package "${packageName}" not found on npm registry`);
+    }
+    throw new Error(`Failed to fetch "${packageName}" from npm: ${res.status} ${res.statusText}`);
+  }
+
+  const json = await res.json();
+  return normalizeManifest(json);
+}
+
+function normalizeManifest(manifest) {
+  return {
+    name: manifest.name || 'unnamed-package',
+    version: manifest.version || '0.0.0',
+    description: manifest.description || '',
+    scripts: manifest.scripts || {},
+    dependencies: manifest.dependencies || {},
+    devDependencies: manifest.devDependencies || {},
+    raw: manifest,
+  };
+}

package/src/simulator.js

@@ -0,0 +1,119 @@
+/**
+ * Offline evaluation engine.
+ * Emits calibrated TypeSafe System One schema answers when running offline or without an API key.
+ */
+export function simulateLifecycleEvaluation(hookName, scriptContent, pkg) {
+  const content = String(scriptContent || '').toLowerCase();
+  const rawContent = String(scriptContent || '');
+
+  // High-risk indicators: exfiltration, token theft, reverse shells, obfuscated curl piping
+  const stealsSecrets =
+    /(?:npm_token|aws_access_key|id_rsa|\.ssh|\.npmrc|\.aws|process\.env|env\s*\|\s*curl)/i.test(rawContent);
+
+  const pipesRemote =
+    /(?:curl|wget)\s+.*\|\s*(?:bash|sh|node)|eval\s*\(\s*buffer\.from|eval\s*\(\s*atob/i.test(rawContent);
+
+  const isObfuscated =
+    /(?:\\x[0-9a-f]{2}){4,}|(?:[A-Za-z0-9+/]{40,}={0,2})/i.test(rawContent);
+
+  const isRecon =
+    /(?:uname\s+-a|whoami|cat\s+\/etc\/passwd|ipconfig|ifconfig|hostname)/i.test(rawContent);
+
+  const isNativeBuild =
+    /(?:node-gyp\s+rebuild|cmake-js|prebuild-install|cargo\s+build|tsc\b)/i.test(content);
+
+  const isBinaryDownload =
+    /(?:download.*binary|node\s+install\.js|release\/download|github\.com\/.*\/releases)/i.test(content);
+
+  const isNotice =
+    /(?:opencollective|fund|echo\s+["'].*thank|exit\s+0)/i.test(content);
+
+  // Derive calibrated probabilities
+  let intent = 'other';
+  let severityScore = 0.2;
+  let secretProb = 0.05;
+  let remoteExecProb = 0.05;
+  let confidence = 0.92;
+
+  if (stealsSecrets || (pipesRemote && isObfuscated)) {
+    intent = stealsSecrets ? 'credential_access' : 'obfuscated_exec';
+    severityScore = 2.85;
+    secretProb = stealsSecrets ? 0.96 : 0.75;
+    remoteExecProb = pipesRemote ? 0.94 : 0.65;
+    confidence = 0.89;
+  } else if (pipesRemote) {
+    intent = 'obfuscated_exec';
+    severityScore = 2.45;
+    secretProb = 0.40;
+    remoteExecProb = 0.92;
+    confidence = 0.85;
+  } else if (isRecon) {
+    intent = 'system_recon';
+    severityScore = 1.65;
+    secretProb = 0.55;
+    remoteExecProb = 0.25;
+    confidence = 0.78;
+  } else if (isBinaryDownload) {
+    intent = 'binary_download';
+    severityScore = 0.85;
+    secretProb = 0.08;
+    remoteExecProb = 0.15;
+    confidence = 0.91;
+  } else if (isNativeBuild) {
+    intent = 'build_tool';
+    severityScore = 0.15;
+    secretProb = 0.02;
+    remoteExecProb = 0.03;
+    confidence = 0.98;
+  } else if (isNotice) {
+    intent = 'benign_notice';
+    severityScore = 0.05;
+    secretProb = 0.01;
+    remoteExecProb = 0.01;
+    confidence = 0.99;
+  }
+
+  return {
+    model: 'jev-latest (offline simulator)',
+    answers: {
+      script_intent: {
+        type: 'choice',
+        choice: intent,
+        probabilities: {
+          [intent]: 0.85,
+          other: 0.15,
+        },
+        confidence,
+      },
+      threat_severity: {
+        type: 'score',
+        score: severityScore,
+        legend: {
+          '0': 'Safe: standard build or benign command with no external network or secret access',
+          '1': 'Low risk: fetches known binary from release domain or routine package setup',
+          '2': 'Suspicious: makes non-standard outbound connections, inspects system environment, or runs encoded commands',
+          '3': 'Critical threat: credential harvesting, token exfiltration, backdoor dropper, or destructive action',
+        },
+        probabilities: {
+          '0': severityScore < 1.0 ? 0.8 : 0.05,
+          '1': severityScore >= 0.5 && severityScore < 1.5 ? 0.7 : 0.1,
+          '2': severityScore >= 1.5 && severityScore < 2.5 ? 0.75 : 0.1,
+          '3': severityScore >= 2.0 ? 0.85 : 0.05,
+        },
+        confidence,
+      },
+      accesses_secrets: {
+        type: 'noul',
+        noul: secretProb,
+      },
+      remote_execution: {
+        type: 'noul',
+        noul: remoteExecProb,
+      },
+    },
+    usage: {
+      input_tokens: 180,
+      output_tokens: 38,
+    },
+  };
+}