penthera 1.4.0 → 1.6.0

package/lib/hook/index.js

@@ -0,0 +1,345 @@
+/**
+ * `penthera hook`: a git pre-commit hook that runs the checks that matter most
+ * before code leaves the laptop, on staged content only.
+ *
+ *   - secrets in staged files (lib/whitebox/secrets.js, AI provider keys included)
+ *   - `penthera agents` rules on staged agent config (.mcp.json, CLAUDE.md, skills/, ...)
+ *   - a staged package-lock.json: the capability diff against HEAD's lockfile,
+ *     plus the license policy when penthera.policy.json has one
+ *
+ * Everything is read from the git index (what will be committed), never the
+ * working tree, so a half-staged file is judged by its staged half. That
+ * includes penthera.policy.json and penthera.suppress.json: an unstaged edit
+ * to either cannot loosen the check. Staged symlinks are never followed.
+ * Offline, no telemetry. Findings use the standard shape, so ids match a full
+ * scan and penthera.suppress.json works here too.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, posix, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findSecretsInText, isSecretScanTarget, maskMatch } from "../whitebox/secrets.js";
+import { loadPolicy, normalizePolicy, POLICY_FILE } from "../install/policy.js";
+import { parseRepoSuppressions, REPO_SUPPRESS_FILE } from "../memory/repo-suppress.js";
+import { findingId } from "../memory/views.js";
+import { fingerprintFinding } from "../audit-loop.js";
+import { globToRegExp, isAtLeast, SEVERITIES } from "./policy.js";
+
+export const HOOK_MARKER = "# penthera-hook";
+export const BACKUP_NAME = "pre-commit.pre-penthera";
+const MAX_BLOB_BYTES = 2 * 1024 * 1024;
+
+// ── git plumbing ──────────────────────────────────────────────────────────
+
+function git(cwd, args, opts = {}) {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024, ...opts });
+}
+
+export function repoRoot(cwd) {
+  try {
+    return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    throw new Error(`Not inside a git repository: ${cwd}`);
+  }
+}
+
+/** Paths added, copied, modified or renamed in the index (what this commit adds). */
+export function stagedFiles(root) {
+  return git(root, ["diff", "--cached", "--name-only", "-z", "--diff-filter=ACMR", "--no-renames"]).split("\0").filter(Boolean);
+}
+
+/** Read index blobs in one `git cat-file --batch` call. Returns Map(path → Buffer); large files are skipped. */
+export function readStaged(root, paths) {
+  const out = new Map();
+  const wanted = paths.filter((p) => !p.includes("\n"));
+  if (!wanted.length) return out;
+  const r = spawnSync("git", ["cat-file", "--batch"], { cwd: root, input: wanted.map((p) => `:${p}\n`).join(""), maxBuffer: 1024 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git cat-file failed: ${String(r.stderr).trim()}`);
+  const buf = r.stdout;
+  let pos = 0;
+  for (const p of wanted) {
+    const nl = buf.indexOf(10, pos);
+    if (nl === -1) break;
+    const header = buf.subarray(pos, nl).toString();
+    pos = nl + 1;
+    const m = /^\S+ (\w+) (\d+)$/.exec(header);
+    if (!m) continue; // "<name> missing"
+    const size = Number(m[2]);
+    if (m[1] === "blob" && size <= MAX_BLOB_BYTES) out.set(p, buf.subarray(pos, pos + size));
+    pos += size + 1;
+  }
+  return out;
+}
+
+// ── Checks ────────────────────────────────────────────────────────────────
+
+function lineOf(text, index) {
+  let n = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+function checkSecrets(files, blobs) {
+  const findings = [];
+  for (const path of files) {
+    if (!isSecretScanTarget(path)) continue;
+    const buf = blobs.get(path);
+    if (!buf || buf.subarray(0, 8192).includes(0)) continue;
+    const text = buf.toString("utf-8");
+    for (const hit of findSecretsInText(text)) {
+      // Same title/url/category/source as the repo scan, so finding ids match.
+      findings.push({
+        severity: hit.severity,
+        title: `${hit.name} in source`,
+        description: `Possible secret in \`${path}\`: \`${maskMatch(hit.match)}\``,
+        url: path,
+        line: lineOf(text, text.indexOf(hit.match)),
+        evidence: maskMatch(hit.match),
+        category: "secrets",
+        source: "secret-scan",
+      });
+    }
+  }
+  return findings;
+}
+
+const AGENT_FILES = new Set(["AGENTS.md", "CLAUDE.md", "CLAUDE.local.md", "GEMINI.md", ".cursorrules", ".windsurfrules", ".mcp.json", ".github/copilot-instructions.md", ".vscode/mcp.json"]);
+const AGENT_DIRS = [".claude/", ".cursor/", ".agents/", ".codex/", ".clinerules/", ".claude-plugin/", ".github/instructions/", "skills/", "plugins/"];
+
+/** Is this repo path agent configuration that `penthera agents` reads? */
+export function isAgentConfig(path) {
+  return AGENT_FILES.has(path) || AGENT_DIRS.some((d) => path.startsWith(d));
+}
+
+/**
+ * Agent rules on the staged view of the agent config. The whole agent config
+ * in the index is checked out to a temp folder (a skill is judged as a folder,
+ * not file by file); only findings that touch a staged path are kept.
+ */
+async function checkAgents(root, staged) {
+  const touched = staged.filter(isAgentConfig);
+  if (!touched.length) return { findings: [], files: 0 };
+  // Regular files only (mode 100644/100755): a staged symlink would be checked
+  // out as a symlink and the scan would read whatever it points at.
+  const all = git(root, ["ls-files", "-z", "--cached", "--stage"]).split("\0")
+    .map((l) => /^(\d{6}) [0-9a-f]+ \d\t(.*)$/s.exec(l))
+    .filter((m) => m && (m[1] === "100644" || m[1] === "100755") && isAgentConfig(m[2]))
+    .map((m) => m[2]);
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), "penthera-hook-")));
+  try {
+    const r = spawnSync("git", ["checkout-index", "-z", "--stdin", `--prefix=${tmp}/`], { cwd: root, input: all.join("\0") });
+    if (r.status !== 0) throw new Error(`git checkout-index failed: ${String(r.stderr).trim()}`);
+    const { scanAgents } = await import("../agents/index.js");
+    const result = await scanAgents(tmp, { lockPath: join(tmp, ".penthera-hook-no-lock") });
+    const relates = (url) => touched.some((s) => url === s || s.startsWith(`${url}/`) || url.startsWith(`${s}/`));
+    const findings = result.findings
+      .filter((f) => !String(f.templateId).startsWith("agents/lock-") && relates(f.url))
+      .map((f) => {
+        const m = /\(line (\d+)\)/.exec(f.description || "");
+        return m ? { ...f, line: Number(m[1]) } : f;
+      });
+    return { findings, files: touched.length };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const EMPTY_LOCK = { lockfileVersion: 3, packages: {} };
+
+/** Capability diff (and license policy) for each staged lockfile, against HEAD. */
+async function checkLockfiles(root, staged, blobs, { licensePolicy }) {
+  const locks = staged.filter((p) => ["package-lock.json", "npm-shrinkwrap.json"].includes(posix.basename(p)));
+  if (!locks.length) return { findings: [], files: 0 };
+  const { scanDeps } = await import("../deps/index.js");
+  const findings = [];
+  for (const path of locks) {
+    const buf = blobs.get(path);
+    if (!buf) continue;
+    let lock;
+    try { lock = JSON.parse(buf.toString("utf-8")); } catch (e) {
+      findings.push({ severity: "high", title: `${path} is not valid JSON`, description: e.message, url: path, category: "dependency-risk", source: "deps-scan" });
+      continue;
+    }
+    let baseLock = EMPTY_LOCK;
+    try { baseLock = JSON.parse(git(root, ["show", `HEAD:${path}`])); } catch { /* new lockfile or first commit */ }
+    const dir = posix.dirname(path);
+    const result = await scanDeps(join(root, dir), { lock, baseLock, baseLabel: "HEAD", changedOnly: true, licensePolicy });
+    const prefix = dir === "." ? "" : `${dir}/`;
+    for (const f of result.findings) findings.push({ ...f, url: f.url ? `${prefix}${f.url}` : path });
+  }
+  return { findings, files: locks.length };
+}
+
+// ── Run ───────────────────────────────────────────────────────────────────
+
+function suppressedBy(entries, f) {
+  if (!entries.length) return null;
+  const id = findingId(f);
+  const fp = fingerprintFinding(f);
+  return entries.find((e) => e.id === id || e.fingerprint === fp) || null;
+}
+
+const bySeverity = (a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity) || String(a.url).localeCompare(String(b.url)) || (a.line || 0) - (b.line || 0);
+
+/**
+ * Check what is staged. Never writes to the repo.
+ * @param {string} cwd anywhere inside the repo
+ * @param {{ policyPath?: string, now?: string }} opts
+ * @returns {Promise<{ root, staged, checked, blocking, below, suppressed, blockOn, policyPath, warnings, duration }>}
+ */
+/** One file as staged, or null when it is not in the index. */
+function stagedBlob(root, path) {
+  return readStaged(root, [path]).get(path) || null;
+}
+
+/** The policy: an explicit --policy file, else penthera.policy.json as staged, else defaults. */
+function stagedPolicy(root, explicitPath) {
+  if (explicitPath) return loadPolicy(root, explicitPath);
+  const buf = stagedBlob(root, POLICY_FILE);
+  if (!buf) return { policy: normalizePolicy({}), path: null };
+  let raw;
+  try {
+    raw = JSON.parse(buf.toString("utf-8"));
+  } catch (e) {
+    throw new Error(`${POLICY_FILE} (staged): ${e.message}`);
+  }
+  return { policy: normalizePolicy(raw, `${POLICY_FILE} (staged)`), path: join(root, POLICY_FILE) };
+}
+
+export async function runHook(cwd, opts = {}) {
+  const started = Date.now();
+  const root = repoRoot(cwd);
+  const { policy, path: policyPath } = stagedPolicy(root, opts.policyPath || null);
+  const { blockOn, checks, ignore } = policy.hook;
+  const ignored = ignore.map(globToRegExp);
+  const staged = stagedFiles(root).filter((p) => !ignored.some((re) => re.test(p)));
+
+  const wantBlobs = staged.filter((p) => (checks.secrets && isSecretScanTarget(p)) || /(^|\/)(package-lock|npm-shrinkwrap)\.json$/.test(p));
+  const blobs = readStaged(root, wantBlobs);
+
+  const secrets = checks.secrets ? checkSecrets(staged, blobs) : [];
+  const agents = checks.agents ? await checkAgents(root, staged) : { findings: [], files: 0 };
+  const deps = checks.deps ? await checkLockfiles(root, staged, blobs, { licensePolicy: checks.licenses ? policy.licenses : null }) : { findings: [], files: 0 };
+
+  const supBuf = stagedBlob(root, REPO_SUPPRESS_FILE);
+  const sup = supBuf ? parseRepoSuppressions(supBuf, { now: opts.now }) : { entries: [], warnings: [] };
+  for (const f of [POLICY_FILE, REPO_SUPPRESS_FILE]) {
+    if (f === POLICY_FILE && opts.policyPath) continue;
+    const disk = join(root, f);
+    const staged = f === POLICY_FILE ? policyPath : supBuf;
+    if (existsSync(disk) && !staged) sup.warnings.push(`${f} is not staged, so this check ignores it (git add it to apply it)`);
+  }
+  const all = [...secrets, ...agents.findings, ...deps.findings].map((f) => ({ ...f, id: findingId(f) }));
+  const suppressed = [];
+  const kept = [];
+  for (const f of all) {
+    const s = suppressedBy(sup.entries, f);
+    if (s) suppressed.push({ ...f, suppression: { reason: s.reason } });
+    else kept.push(f);
+  }
+  kept.sort(bySeverity);
+  return {
+    root,
+    staged: staged.length,
+    checked: { secrets: checks.secrets ? staged.filter(isSecretScanTarget).length : 0, agents: agents.files, lockfiles: deps.files },
+    blockOn,
+    policyPath,
+    blocking: kept.filter((f) => isAtLeast(f.severity, blockOn)),
+    below: kept.filter((f) => !isAtLeast(f.severity, blockOn)),
+    suppressed,
+    warnings: sup.warnings,
+    duration: Date.now() - started,
+  };
+}
+
+/** One short "how to fix" line per finding. */
+export function fixHint(f) {
+  if (f.category === "secrets") return "Load it from an env var or secret store and unstage the file; rotate it if it was ever pushed or shared.";
+  if (f.category === "license") return `Replace ${f.package}, or add it to "allowPackages" in the licenses section of penthera.policy.json.`;
+  if (f.category === "dependency-risk") return `Review it before committing the lockfile: \`penthera deps --base HEAD -v\` shows the evidence.`;
+  const first = String(f.description || "").replace(/\s*\[[^\]]*\]$/, "").replace(/\s*\(line \d+\)/, "").split(/(?<=\.)\s/)[0];
+  return first || "See `penthera agents` for details.";
+}
+
+// ── Install / uninstall ───────────────────────────────────────────────────
+
+const BIN = fileURLToPath(new URL("../../bin/penthera.js", import.meta.url));
+const sq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+
+export function hookScript({ node = process.execPath, bin = BIN } = {}) {
+  return `#!/bin/sh
+${HOOK_MARKER}: pre-commit hook installed by \`penthera hook install\`.
+# Remove it with \`penthera hook uninstall\`, which restores any hook it replaced.
+# Skip it for one commit with \`git commit --no-verify\`.
+hook_dir=$(dirname "$0")
+if [ -x "$hook_dir/${BACKUP_NAME}" ]; then
+  "$hook_dir/${BACKUP_NAME}" "$@" || exit $?
+fi
+if [ -f ${sq(bin)} ] && [ -x ${sq(node)} ]; then
+  exec ${sq(node)} ${sq(bin)} hook run
+elif command -v penthera >/dev/null 2>&1; then
+  exec penthera hook run
+fi
+echo "penthera: not found, pre-commit check skipped (npm install -g penthera, then penthera hook install)" >&2
+exit 0
+`;
+}
+
+/** Where git looks for hooks (honours core.hooksPath and worktrees). */
+export function hooksDir(root) {
+  return resolve(root, git(root, ["rev-parse", "--git-path", "hooks"]).trim());
+}
+
+function hooksPathSetting(root) {
+  try { return git(root, ["config", "--get", "core.hooksPath"]).trim() || null; } catch { return null; }
+}
+
+const isOurs = (path) => existsSync(path) && readFileSync(path, "utf-8").includes(HOOK_MARKER);
+
+/**
+ * Write .git/hooks/pre-commit. An existing hook that is not ours is kept as
+ * pre-commit.pre-penthera and runs first.
+ * @returns {{ path, chained: string|null, updated: boolean }}
+ */
+export function installHook(cwd, { force = false, script = hookScript() } = {}) {
+  const root = repoRoot(cwd);
+  const custom = hooksPathSetting(root);
+  if (custom && !force) {
+    const err = new Error(`core.hooksPath is set to "${custom}" (husky, lefthook or similar manage hooks here). Add \`penthera hook run\` to that tool's pre-commit config instead, or rerun with --force to write ${join(custom, "pre-commit")}.`);
+    err.code = "HOOKS_PATH";
+    throw err;
+  }
+  const dir = hooksDir(root);
+  const path = join(dir, "pre-commit");
+  const backup = join(dir, BACKUP_NAME);
+  let updated = false;
+  if (existsSync(path)) {
+    if (isOurs(path)) updated = true;
+    else if (existsSync(backup)) throw new Error(`Both ${path} and ${backup} exist. Merge them by hand, then run \`penthera hook install\` again.`);
+    else renameSync(path, backup);
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, script);
+  chmodSync(path, 0o755);
+  return { path, chained: existsSync(backup) ? backup : null, updated };
+}
+
+/**
+ * Remove our hook and put back the one it replaced.
+ * @returns {{ path, removed: boolean, restored: string|null }}
+ */
+export function uninstallHook(cwd) {
+  const root = repoRoot(cwd);
+  const dir = hooksDir(root);
+  const path = join(dir, "pre-commit");
+  const backup = join(dir, BACKUP_NAME);
+  if (!existsSync(path)) return { path, removed: false, restored: null };
+  if (!isOurs(path)) throw new Error(`${path} was not installed by penthera; left untouched.`);
+  unlinkSync(path);
+  if (existsSync(backup)) {
+    renameSync(backup, path);
+    return { path, removed: true, restored: path };
+  }
+  return { path, removed: true, restored: null };
+}

package/lib/hook/policy.js

@@ -0,0 +1,62 @@
+/**
+ * The `hook` section of penthera.policy.json: what `penthera hook run` checks
+ * and what blocks a commit.
+ *
+ *   "hook": {
+ *     "blockOn": "high",                 // lowest severity that blocks: critical | high | medium | low
+ *     "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true },
+ *     "ignore": ["tests/fixtures/**"]    // staged paths the hook skips (globs)
+ *   }
+ */
+export const SEVERITIES = ["critical", "high", "medium", "low", "info"];
+const CHECKS = ["secrets", "agents", "deps", "licenses"];
+
+export const DEFAULT_HOOK_POLICY = Object.freeze({
+  blockOn: "high",
+  checks: Object.freeze(Object.fromEntries(CHECKS.map((c) => [c, true]))),
+  ignore: Object.freeze([]),
+});
+
+export function normalizeHookPolicy(raw, label = "hook") {
+  if (raw == null) return { ...DEFAULT_HOOK_POLICY, checks: { ...DEFAULT_HOOK_POLICY.checks }, ignore: [] };
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${label}: expected an object`);
+  const extra = Object.keys(raw).filter((k) => !["blockOn", "checks", "ignore"].includes(k));
+  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected blockOn, checks, ignore)`);
+  const blockOn = raw.blockOn ?? "high";
+  if (!SEVERITIES.slice(0, 4).includes(blockOn)) throw new Error(`${label}: "blockOn" must be one of critical, high, medium, low`);
+  const checks = { ...DEFAULT_HOOK_POLICY.checks };
+  if (raw.checks != null) {
+    if (typeof raw.checks !== "object" || Array.isArray(raw.checks)) throw new Error(`${label}: "checks" must be an object`);
+    for (const [k, v] of Object.entries(raw.checks)) {
+      if (!CHECKS.includes(k)) throw new Error(`${label}: unknown check "${k}" (known: ${CHECKS.join(", ")})`);
+      if (typeof v !== "boolean") throw new Error(`${label}: checks.${k} must be true or false`);
+      checks[k] = v;
+    }
+  }
+  const ignore = raw.ignore ?? [];
+  if (!Array.isArray(ignore) || ignore.some((x) => typeof x !== "string" || !x.trim())) throw new Error(`${label}: "ignore" must be an array of path globs`);
+  return { blockOn, checks, ignore: ignore.map((x) => x.trim()) };
+}
+
+/** Git-style path glob: `**` crosses folders, `*` and `?` stay inside one; a bare name matches at any depth. */
+export function globToRegExp(glob) {
+  let g = glob.replace(/^\.\//, "");
+  if (!g.includes("/")) g = `**/${g}`;
+  if (g.endsWith("/")) g += "**";
+  let re = "";
+  for (let i = 0; i < g.length; i++) {
+    const ch = g[i];
+    if (ch === "*" && g[i + 1] === "*") {
+      i++;
+      if (g[i + 1] === "/") { i++; re += "(?:.*/)?"; } else re += ".*";
+    } else if (ch === "*") re += "[^/]*";
+    else if (ch === "?") re += "[^/]";
+    else re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+export function isAtLeast(severity, threshold) {
+  const s = SEVERITIES.indexOf(severity);
+  return s !== -1 && s <= SEVERITIES.indexOf(threshold);
+}

package/lib/install/index.js

@@ -5,16 +5,19 @@
  *      in a temporary copy of package.json / package-lock.json / .npmrc. Not in
  *      place: npm rewrites node_modules/.package-lock.json even in lock-only
  *      mode, and an abort must leave the project byte for byte as it was.
- *   2. Fetch. `npm cache add` puts each new tarball in npm's cache; nothing is
- *      unpacked into node_modules and no package code runs. The deps engine
+ *   2. Fetch. `npm cache add --ignore-scripts` puts each new tarball in npm's
+ *      cache; nothing is unpacked into node_modules and no package code runs
+ *      (git dependencies would run `prepare` here without --ignore-scripts, so
+ *      they are refused unless --allow-non-registry is passed). The deps engine
  *      reads tarballs back from the cache only after verifying them against
  *      the proposed lockfile's integrity (lib/deps/source.js).
  *   3. Diff. lib/deps scans the proposed tree against the current lockfile:
  *      new packages, capabilities gained, install scripts, typosquats.
  *   4. Decide. lib/install/policy.js turns that into deny / needs-approval.
  *   5. Apply (only when allowed). The vetted package.json and lockfile are
- *      written into the project and `npm install` installs exactly that tree,
- *      with `--ignore-scripts` unless the new install scripts were approved.
+ *      written into the project and `npm ci` installs exactly that tree (it
+ *      fails rather than re-resolve), with `--ignore-scripts` unless the new
+ *      install scripts were approved.
  *
  * Penthera makes no network calls here. npm talks to its configured registry
  * (resolve and fetch); that is the one expected egress.
@@ -35,6 +38,8 @@ const LOCKFILES = ["package-lock.json", "npm-shrinkwrap.json"];
 const COPY = ["package.json", ...LOCKFILES, ".npmrc"];
 const QUIET = ["--no-audit", "--no-fund", "--no-update-notifier"];
 const LOCAL_SPEC = /^(file:|link:|portal:|\.{1,2}\/|\/)/;
+// Specs npm resolves outside the registry: git, tarball URLs, hosted-git shorthands.
+const REMOTE_SPEC = /^(?:git\+|git:|github:|gitlab:|bitbucket:|gist:|https?:|ssh:)|^[^@][^/@:]*\/[^/]+$|^[^@]+@(?:git\+|git:|github:|gitlab:|bitbucket:|gist:|https?:|ssh:|file:)|\.(?:tgz|tar\.gz|tar)$/i;
 
 async function npm(args, opts) {
   try {
@@ -45,26 +50,50 @@ async function npm(args, opts) {
   }
 }
 
-/** npm's version and registry, as npm sees them from the project. */
+/** npm's version and registries (default and @scope:registry), as npm sees them from the project. */
 export async function npmInfo(root, env = process.env) {
-  const [version, registry] = await Promise.all([
+  const [version, config] = await Promise.all([
     npm(["--version"], { cwd: root, env }).then((r) => r.stdout.trim()),
-    npm(["config", "get", "registry"], { cwd: root, env }).then((r) => r.stdout.trim(), () => "the configured npm registry"),
+    npm(["config", "list", "--json"], { cwd: root, env }).then((r) => JSON.parse(r.stdout), () => ({})),
   ]);
+  const registry = typeof config.registry === "string" ? config.registry : "the configured npm registry";
+  const registries = Object.entries(config)
+    .filter(([k, v]) => (k === "registry" || /^@[^:]+:registry$/.test(k)) && typeof v === "string")
+    .map(([, v]) => v);
   const major = parseInt(version, 10) || 0;
   // npm 12 blocks dependency install scripts unless package.json allowScripts lists them.
-  return { version, major, registry, allowScriptsPolicy: major >= 12 };
+  return { version, major, registry, registries, allowScriptsPolicy: major >= 12 };
+}
+
+const origin = (u) => {
+  try {
+    const x = new URL(u);
+    return /^https?:$/.test(x.protocol) ? x.origin : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Lockfile entries that would come from somewhere other than a configured
+ * registry: git repositories, tarball URLs on other hosts. Their contents are
+ * not what a registry name and version promise, and git ones run `prepare`.
+ */
+export function nonRegistryPackages(pkgs, registries) {
+  const allowed = new Set((registries || []).map(origin).filter(Boolean));
+  return pkgs.filter((p) => p.resolved && !p.link && !allowed.has(origin(p.resolved)));
 }
 
 const key = (p) => `${p.path}@${p.version}#${p.integrity || ""}`;
 const scriptsOf = (s) => (s && Object.keys(s).length ? s : null);
 
 /** The rule ids a change raises (see lib/install/policy.js). */
-function flagsFor(caps, { newScripts, typosquat, unscanned }) {
+function flagsFor(caps, { newScripts, typosquat, unscanned, scriptMismatch }) {
   const flags = [...(caps || [])].filter((id) => id !== "install-scripts");
   if (newScripts) flags.unshift("install-scripts");
   if (typosquat) flags.push("typosquat");
   if (unscanned) flags.push("unscanned");
+  if (scriptMismatch) flags.push("script-mismatch");
   return flags;
 }
 
@@ -89,7 +118,8 @@ export function changesFromDiff(diff, typosquats = [], packages = []) {
       capabilities: a.capabilities || [],
       installScripts: scripts,
       typosquatOf: typo.get(a.name)?.target || null,
-      flags: flagsFor(a.capabilities, { newScripts: !!scripts, typosquat: typo.has(a.name), unscanned: a.capabilities === null }),
+      unscanned: a.unscanned || null,
+      flags: flagsFor(a.capabilities, { newScripts: !!scripts, typosquat: typo.has(a.name), unscanned: a.capabilities === null, scriptMismatch: !!a.scriptMismatch }),
     });
   }
   for (const u of diff.upgraded) {
@@ -109,7 +139,8 @@ export function changesFromDiff(diff, typosquats = [], packages = []) {
       previousInstallScripts: before,
       compared: u.unavailable == null,
       typosquatOf: null,
-      flags: flagsFor(gained, { newScripts, typosquat: false, unscanned: u.unavailable === "new" }),
+      unscanned: u.unscanned || null,
+      flags: flagsFor(gained, { newScripts, typosquat: false, unscanned: u.unavailable === "new" || !!u.unscanned, scriptMismatch: !!u.scriptMismatch }),
     });
   }
   return out;
@@ -143,6 +174,10 @@ export async function planInstall(root, specs, opts = {}) {
   checkProject(root, JSON.parse(readFileSync(pkgPath, "utf-8")));
   const bad = specs.filter((s) => s.startsWith("-") || LOCAL_SPEC.test(s));
   if (bad.length) throw new Error(`Unsupported package spec(s): ${bad.join(", ")}. Pass registry names (name, name@version, name@range).`);
+  const remote = specs.filter((s) => REMOTE_SPEC.test(s));
+  if (remote.length && !opts.allowNonRegistry) {
+    throw new Error(`Non-registry package spec(s): ${remote.join(", ")}. Git and tarball-URL installs bypass the registry's name and version, and git ones run \`prepare\` while being fetched. Pass --allow-non-registry if you mean it.`);
+  }
 
   const info = opts.info || await npmInfo(root, env);
   const original = Object.fromEntries(COPY.map((f) => [f, readIfExists(join(root, f))]));
@@ -171,6 +206,10 @@ export async function planInstall(root, specs, opts = {}) {
     }
     const oldKeys = new Set(parseLockfile(JSON.parse(readFileSync(baseLockPath, "utf-8"))).map(key));
     const fresh = parseLockfile(proposedLock).filter((p) => !p.link && p.version && !oldKeys.has(key(p)));
+    const offRegistry = nonRegistryPackages(fresh, info.registries || [info.registry]);
+    if (offRegistry.length && !opts.allowNonRegistry) {
+      throw new Error(`The resolved tree pulls ${offRegistry.length} package(s) from outside the configured registry: ${offRegistry.slice(0, 5).map((p) => `${p.name} (${p.resolved})`).join(", ")}. Nothing was fetched or installed. Pass --allow-non-registry to review them anyway.`);
+    }
 
     // New tarballs go into a private npm cache (npm cache add): nothing is
     // unpacked or run. Private because npm will not reliably say where its own
@@ -182,11 +221,11 @@ export async function planInstall(root, specs, opts = {}) {
     if (toFetch.length) {
       onPhase(`Fetching ${toFetch.length} tarball(s) with npm cache add (nothing is unpacked or run)`);
       const fetchSpecs = [...new Set(toFetch.map((p) => (p.resolved && !/^https?:/.test(p.resolved) ? p.resolved : `${p.name}@${p.version}`)))];
-      await npm(["cache", "add", "--cache", fetchCache, ...(opts.offline ? ["--offline"] : []), ...fetchSpecs], { cwd: tmp, env });
+      await npm(["cache", "add", "--ignore-scripts", ...QUIET, "--cache", fetchCache, ...(opts.offline ? ["--offline"] : []), ...fetchSpecs], { cwd: tmp, env });
     }
 
     onPhase("Comparing capabilities with the current tree (offline, integrity-verified)");
-    const result = await scanDeps(work, { diff: baseLockPath, treeRoot: root, cacheDir: [fetchCache, userCache] });
+    const result = await scanDeps(work, { diff: baseLockPath, treeRoot: root, cacheDir: [fetchCache, userCache], ecosystem: "npm" });
     const changes = changesFromDiff(result.deps.diff, result.deps.typosquats, result.deps.packages);
     const verdict = evaluatePolicy(changes, opts.policy || normalizePolicy({}));
 
@@ -242,8 +281,10 @@ function restore(root, original) {
 
 /**
  * Install the vetted tree. Writes the proposed package.json and lockfile,
- * then runs `npm install` with no package arguments, so npm installs exactly
- * the lockfile that was reviewed. Restores both files if npm fails.
+ * then runs `npm ci`, which installs exactly that lockfile and fails instead
+ * of re-resolving, so what runs is what was reviewed (`npm install` could
+ * resolve something new and only be caught afterwards, once its scripts ran).
+ * Restores both files if npm fails.
  * @param {{ runScripts: boolean, env?: object, stdio?: string, offline?: boolean }} opts
  */
 export async function applyInstall(plan, opts) {
@@ -255,15 +296,15 @@ export async function applyInstall(plan, opts) {
 
   writeFileSync(join(root, "package.json"), pkgJson);
   writeFileSync(join(root, plan.lockName), plan.proposed[plan.lockName]);
-  const args = ["install", ...QUIET, ...(opts.runScripts ? [] : ["--ignore-scripts"]), ...(opts.offline ? ["--offline"] : [])];
+  const args = ["ci", ...QUIET, ...(opts.runScripts ? [] : ["--ignore-scripts"]), ...(opts.offline ? ["--offline"] : [])];
   try {
     await npm(args, { cwd: root, env });
   } catch (e) {
     restore(root, original);
-    throw new Error(`${e.message}\npackage.json and ${plan.lockName} were restored; node_modules may be partly updated (run \`npm ci\` to reset it).`);
+    throw new Error(`${e.message}\npackage.json and ${plan.lockName} were restored; node_modules may be partly updated (run \`npm ci --ignore-scripts\` to reset it).`);
   }
 
-  // npm should have installed the reviewed lockfile as is.
+  // npm ci never rewrites the lockfile; check anyway.
   const want = new Set(parseLockfile(JSON.parse(plan.proposed[plan.lockName])).map(key));
   const got = parseLockfile(JSON.parse(readFileSync(join(root, plan.lockName), "utf-8"))).map(key);
   const drift = got.filter((k) => !want.has(k));

package/lib/install/policy.js

@@ -8,25 +8,42 @@
  *   }
  *
  * `deny` and `requireApproval` list capability ids from lib/deps/capabilities.js,
- * plus two of the firewall's own: `typosquat` (a new name close to a popular
- * package) and `unscanned` (a new package whose files could not be read).
+ * plus three of the firewall's own: `typosquat` (a new name close to a popular
+ * package), `unscanned` (a new package whose files could not be read safely)
+ * and `script-mismatch` (the lockfile says the package has an install script
+ * but the scan found none: the scanner and npm disagree about its files).
+ *
+ * Two floors no policy lowers, not even an allow entry: `script-mismatch` is
+ * always denied, and `unscanned` always needs at least an approval. Both mean
+ * Penthera could not see what would run, so "clean" would be a guess.
  * `allow` lists package names or globs (`*` matches any run of characters),
  * optionally pinned to one version with `@x.y.z`; an allowed package passes
  * both lists. A field left out keeps its default; a field given replaces it.
  * Everything here is pure: no files are read except the policy itself.
+ *
+ * The same file has two optional sections for other commands: `licenses`
+ * (penthera deps, lib/deps/license.js) and `hook` (penthera hook run,
+ * lib/hook/policy.js). Both come back as null / defaults when absent.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CAPABILITY_ORDER, CAPABILITIES } from "../deps/capabilities.js";
+import { normalizeLicensePolicy } from "../deps/license.js";
+import { normalizeHookPolicy } from "../hook/policy.js";
 
 export const POLICY_FILE = "penthera.policy.json";
 
-export const RULE_IDS = [...CAPABILITY_ORDER, "typosquat", "unscanned"];
+export const RULE_IDS = [...CAPABILITY_ORDER, "typosquat", "unscanned", "script-mismatch"];
+
+/** Floors the policy cannot lower (see the header). */
+export const ALWAYS_DENY = Object.freeze(["script-mismatch"]);
+export const ALWAYS_APPROVE = Object.freeze(["unscanned"]);
 
 export const RULE_LABELS = {
   ...Object.fromEntries(CAPABILITY_ORDER.map((id) => [id, CAPABILITIES[id].label])),
   typosquat: "looks like a popular package",
   unscanned: "could not be scanned",
+  "script-mismatch": "lockfile lists an install script the scan did not find",
 };
 
 export const DEFAULT_POLICY = Object.freeze({
@@ -41,9 +58,9 @@ export const DEFAULT_POLICY = Object.freeze({
  */
 export function normalizePolicy(raw, label = POLICY_FILE) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${label}: expected a JSON object`);
-  const known = ["allow", "deny", "requireApproval", "$schema", "description"];
+  const known = ["allow", "deny", "requireApproval", "licenses", "hook", "$schema", "description"];
   const extra = Object.keys(raw).filter((k) => !known.includes(k));
-  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected allow, deny, requireApproval)`);
+  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected allow, deny, requireApproval, licenses, hook)`);
   const out = {};
   for (const field of ["allow", "deny", "requireApproval"]) {
     const v = raw[field] ?? DEFAULT_POLICY[field];
@@ -56,6 +73,8 @@ export function normalizePolicy(raw, label = POLICY_FILE) {
     const bad = out[field].filter((id) => !RULE_IDS.includes(id));
     if (bad.length) throw new Error(`${label}: unknown capability in "${field}": ${bad.join(", ")}. Known: ${RULE_IDS.join(", ")}`);
   }
+  out.licenses = raw.licenses == null ? null : normalizeLicensePolicy(raw.licenses, `${label}: licenses`);
+  out.hook = normalizeHookPolicy(raw.hook, `${label}: hook`);
   return out;
 }
 
@@ -107,8 +126,9 @@ export function matchAllow(allow, name, version) {
 export function evaluatePolicy(changes, policy) {
   const items = changes.map((c) => {
     const allowedBy = matchAllow(policy.allow, c.name, c.version);
-    const deny = allowedBy ? [] : c.flags.filter((id) => policy.deny.includes(id));
-    const approval = allowedBy ? [] : c.flags.filter((id) => policy.requireApproval.includes(id) && !deny.includes(id));
+    const deny = c.flags.filter((id) => ALWAYS_DENY.includes(id) || (!allowedBy && policy.deny.includes(id)));
+    const approval = c.flags.filter((id) => !deny.includes(id)
+      && (ALWAYS_APPROVE.includes(id) || (!allowedBy && policy.requireApproval.includes(id))));
     return { ...c, allowedBy, deny, approval };
   });
   const denied = items.filter((i) => i.deny.length);