depsentinel 0.1.2 → 0.1.5

package/README.md

@@ -4,12 +4,28 @@
 
 ## Quick start
 
+### 1) Scan the project
+
+```bash
+npx depsentinel scan
+```
+
+### 2) Generate secure defaults
+
+```bash
+npx depsentinel init --write
+```
+
+### 3) Run full diagnosis
+
 ```bash
-npx depsentinel scan          # diagnose your project
-npx depsentinel init --write  # generate secure baseline
-npx depsentinel ci --json     # fail CI if critical policies violated
-npx depsentinel install express  # check package safety before adding it
-npx depsentinel doctor        # full 26-point security diagnosis
+npx depsentinel doctor
+```
+
+### 4) Add CI policy gate
+
+```bash
+npx depsentinel ci --json
 ```
 
 ## Commands
@@ -25,6 +41,29 @@ npx depsentinel doctor        # full 26-point security diagnosis
 | `trust add\|remove\|list` | Manage allow/ignore build-script trust per package manager |
 | `override add\|remove\|list` | Manage policy exceptions with reason and expiration |
 
+### Trust examples
+
+```bash
+depsentinel trust add sharp --mode allow-build --write
+depsentinel trust add fsevents --mode ignore-build --write
+depsentinel trust list --pm pnpm
+```
+
+### Typical flows
+
+```bash
+# First-time hardening
+depsentinel scan
+depsentinel init --write
+depsentinel doctor
+
+# Dependency preflight
+depsentinel install <package>
+
+# CI gate
+depsentinel ci --json
+```
+
 ## What it enforces
 
 - **Disable post-install scripts** — `.npmrc` `ignore-scripts=true`

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { cac } from "cac";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { runCi } from "./commands/ci.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runFix } from "./commands/fix.js";
@@ -10,6 +12,17 @@ import { runTrust } from "./commands/trust.js";
 import { overrideAdd, overrideList, overrideRemove } from "./core/overrides.js";
 export function createCli() {
     const cli = cac("depsentinel");
+    async function askYesNo(question, defaultYes) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY)
+            return defaultYes;
+        const rl = createInterface({ input, output });
+        const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+        const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+        rl.close();
+        if (answer === "")
+            return defaultYes;
+        return answer === "y" || answer === "yes" || answer === "s" || answer === "si";
+    }
     cli
         .command("scan", "Run dependency risk scan")
         .option("--json", "Emit machine-readable JSON")
@@ -36,11 +49,23 @@ export function createCli() {
         .option("--preset <preset>", "Preset to initialize (base|expo)")
         .option("--write", "Apply changes (default is dry-run)")
         .option("--json", "Emit machine-readable JSON")
-        .action((options) => {
+        .action(async (options) => {
+        const context = options.json
+            ? {
+                publishesToNpm: true,
+                publishFromCi: true,
+                usesOidcTrustedPublisher: false
+            }
+            : {
+                publishesToNpm: await askYesNo("Does this project publish packages to npm?", false),
+                publishFromCi: await askYesNo("Does this project publish from CI?", true),
+                usesOidcTrustedPublisher: await askYesNo("Does npm publish use OIDC Trusted Publisher?", false)
+            };
         const result = runInit({
             preset: options.preset,
             dryRun: !Boolean(options.write),
-            json: Boolean(options.json)
+            json: Boolean(options.json),
+            context
         });
         process.stdout.write(`${result.output}\n`);
     });

package/dist/commands/init.js

@@ -1,13 +1,14 @@
 import path from "node:path";
 import { applySafePlan, planSafeFile } from "../core/safe-write.js";
 import { detectProjectFacts } from "../core/detector.js";
-function buildDepsentinelConfig(preset) {
+function buildDepsentinelConfig(preset, context) {
     return JSON.stringify({
         schemaVersion: "1.0.0",
         preset,
         policyCatalog: "v1",
         failOn: ["critical"],
-        overrides: []
+        overrides: [],
+        context
     }, null, 2);
 }
 function buildNpmRc() {
@@ -103,8 +104,13 @@ export function runInit(options = {}) {
     const preset = options.preset ?? "base";
     const dryRun = options.dryRun ?? true;
     const facts = detectProjectFacts(cwd);
+    const context = options.context ?? {
+        publishesToNpm: true,
+        publishFromCi: true,
+        usesOidcTrustedPublisher: false
+    };
     const planned = [
-        planSafeFile(path.join(cwd, "depsentinel.json"), `${buildDepsentinelConfig(preset)}\n`),
+        planSafeFile(path.join(cwd, "depsentinel.json"), `${buildDepsentinelConfig(preset, context)}\n`),
         planSafeFile(path.join(cwd, ".npmrc"), buildNpmRc()),
         planSafeFile(path.join(cwd, ".npmignore"), buildNpmIgnore()),
         planSafeFile(path.join(cwd, ".github", "workflows", "depsentinel-ci.yml"), `${buildCiWorkflow()}\n`)

package/dist/core/doctor-checks.js

@@ -27,24 +27,64 @@ function skip(id, category, title, detail, remediation) {
     return { id, category, severity: "low", status: "skipped", title, detail, remediation, automated: false };
 }
 export function collectDiagnoses(rootDir, facts) {
+    const context = readProjectContext(rootDir);
     return [
+        checkMixedLockfiles(rootDir, facts),
+        checkPackageManagerField(rootDir, facts),
         checkNpmRc(rootDir),
-        checkNpmIgnore(rootDir),
-        checkPackageJsonFiles(rootDir),
+        checkNpmIgnore(rootDir, context),
+        checkPackageJsonFiles(rootDir, context),
         checkPnpmWorkspace(rootDir, facts),
         checkBunfig(rootDir, facts),
         checkYarnRc(rootDir, facts),
         checkLockfileCommitted(rootDir),
-        checkCiProvenance(rootDir),
+        checkCiProvenance(rootDir, context),
         checkLintLockfile(rootDir),
         checkSbomScript(rootDir),
         checkEnvPlaintext(rootDir),
         checkNpxHardening(),
-        checkNpm2fa(),
+        checkNpm2fa(context),
         checkDevContainer(rootDir),
         checkNodeModulesGitignored(rootDir)
     ];
 }
+function checkPackageManagerField(rootDir, facts) {
+    const pkgPath = path.join(rootDir, "package.json");
+    if (!existsSync(pkgPath)) {
+        return skip("config.package-manager.no-pkg", "config", "No package.json", "Cannot verify packageManager field without package.json.", "Ensure package.json exists.");
+    }
+    const pkg = readJsonSafe(pkgPath, {});
+    const field = pkg.packageManager?.trim();
+    if (!field) {
+        return fail("config.package-manager.missing", "config", "medium", "Missing packageManager field in package.json", "Without packageManager, installs can drift across npm/pnpm/yarn/bun versions between machines and CI.", "Add packageManager to package.json (for example: `pnpm@11.2.2` or `npm@10.x`).");
+    }
+    const declared = field.split("@")[0];
+    if (!["npm", "pnpm", "yarn", "bun"].includes(declared)) {
+        return fail("config.package-manager.invalid", "config", "medium", `Invalid packageManager value: ${field}`, "packageManager must declare npm, pnpm, yarn, or bun with a version.", "Set packageManager to a valid value, like `pnpm@11.2.2`.");
+    }
+    if (facts.packageManager !== "unknown" && declared !== facts.packageManager) {
+        return fail("config.package-manager.mismatch", "config", "high", `packageManager mismatch: declared ${declared}, detected ${facts.packageManager}`, "Declared package manager does not match lockfile-detected package manager.", "Use one package manager strategy: align packageManager with lockfile, and remove conflicting lockfiles.");
+    }
+    return pass("config.package-manager.present", "config", `packageManager pinned: ${field}`);
+}
+function checkMixedLockfiles(rootDir, facts) {
+    const lockfiles = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"].filter((name) => existsSync(path.join(rootDir, name)));
+    if (lockfiles.length <= 1) {
+        return pass("dependencies.lockfile.single", "dependencies", "Single lockfile strategy detected");
+    }
+    return fail("dependencies.lockfile.mixed", "dependencies", "high", `Multiple lockfiles detected: ${lockfiles.join(", ")}`, `Mixed lockfiles cause non-deterministic installs and tool mismatch (detected manager: ${facts.packageManager}).`, "Keep exactly one lockfile for the chosen package manager and delete the others.");
+}
+function readProjectContext(rootDir) {
+    const configPath = path.join(rootDir, "depsentinel.json");
+    const parsed = readJsonSafe(configPath, {
+        context: { publishesToNpm: true, publishFromCi: true, usesOidcTrustedPublisher: false }
+    });
+    return {
+        publishesToNpm: parsed.context?.publishesToNpm ?? true,
+        publishFromCi: parsed.context?.publishFromCi ?? true,
+        usesOidcTrustedPublisher: parsed.context?.usesOidcTrustedPublisher ?? false
+    };
+}
 function checkNpmRc(rootDir) {
     const npmrc = path.join(rootDir, ".npmrc");
     if (!existsSync(npmrc))
@@ -61,18 +101,21 @@ function checkNpmRc(rootDir) {
         return pass("config.npmrc.secure", "config", ".npmrc has secure baseline");
     return fail("config.npmrc.incomplete", "config", "medium", `.npmrc missing: ${missing.join(", ")}`, "Your .npmrc lacks key security settings.", "Run `depsentinel init` to regenerate .npmrc.");
 }
-function checkNpmIgnore(rootDir) {
+function checkNpmIgnore(rootDir, context) {
+    if (!context.publishesToNpm) {
+        return skip("config.npmignore.non-publish", "config", "Package is not published to npm", ".npmignore publish safeguards are not required for non-published apps.", "Set `context.publishesToNpm=true` in depsentinel.json if this changes.");
+    }
     if (existsSync(path.join(rootDir, ".npmignore")))
         return pass("config.npmignore.present", "config", ".npmignore present");
     return fail("config.npmignore.missing", "config", "medium", "Missing .npmignore", "Without .npmignore, sensitive files may leak into published packages.", "Add a .npmignore file listing patterns to exclude from npm publish.");
 }
-function checkPackageJsonFiles(rootDir) {
+function checkPackageJsonFiles(rootDir, context) {
     const pkg = path.join(rootDir, "package.json");
     if (!existsSync(pkg))
         return skip("config.package-json.missing", "config", "No package.json found", "Cannot evaluate package.json settings.", "Ensure package.json exists.");
     const parsed = readJsonSafe(pkg, { files: undefined, private: undefined });
-    if (parsed.private)
-        return pass("config.package-json.files-private", "config", "Private package (no publish risk)");
+    if (parsed.private || !context.publishesToNpm)
+        return pass("config.package-json.files-private", "config", "Private/non-published package (no publish risk)");
     if (parsed.files && parsed.files.length > 0)
         return pass("config.package-json.files-present", "config", "package.json has `files` allowlist");
     return fail("config.package-json.files-missing", "config", "medium", "Missing `files` field in package.json", "Without `files`, npm publishes everything not excluded by .npmignore/.gitignore.", "Add a `files` array to package.json with only the dist/ entry point you want published.");
@@ -129,7 +172,10 @@ function checkLockfileCommitted(rootDir) {
         return skip("ci.lockfile-committed.no-lockfile", "ci", "No lockfile to check", "No lockfile found to verify commit status.", "Generate a lockfile with `npm install` and commit it.");
     return skip("ci.lockfile-committed.manual", "ci", "Verify lockfile committed", "Use `git ls-files package-lock.json` to confirm your lockfile is committed.", "Run `git add package-lock.json && git commit -m \"chore: add lockfile\"`.");
 }
-function checkCiProvenance(rootDir) {
+function checkCiProvenance(rootDir, context) {
+    if (!context.publishesToNpm || !context.publishFromCi) {
+        return skip("ci.provenance.not-applicable", "ci", "Publish provenance not required", "Project context says npm publishing from CI is disabled.", "Set `context.publishesToNpm=true` and `context.publishFromCi=true` if you start publishing from CI.");
+    }
     const workflowsDir = path.join(rootDir, ".github", "workflows");
     if (!existsSync(workflowsDir))
         return fail("ci.provenance.no-workflows", "ci", "medium", "No GitHub Actions workflows found", "Cannot verify provenance/id-token configuration without CI workflows.", "Add `permissions: id-token: write` to your publish workflow for npm provenance.");
@@ -186,7 +232,10 @@ function checkEnvPlaintext(rootDir) {
 function checkNpxHardening() {
     return skip("maintainer.npx-hardening.manual", "maintainer", "Verify npx hardening", "npx can silently pull fresh malicious packages without lockfile verification.", "Create a dedicated workspace with pre-installed npx packages, and use `npx --offline --workspace <path>` to block network fetches. See docs/security-best-practices.md for step-by-step instructions.");
 }
-function checkNpm2fa() {
+function checkNpm2fa(context) {
+    if (!context.publishesToNpm) {
+        return skip("maintainer.2fa.not-applicable", "maintainer", "npm account 2FA not required", "Project context says package is not published to npm.", "Enable this check by setting `context.publishesToNpm=true` in depsentinel.json.");
+    }
     return skip("maintainer.2fa.manual", "maintainer", "Verify npm account 2FA", "Accounts without 2FA are vulnerable to credential theft and package takeover.", "Run `npm profile enable-2fa auth-and-writes` to enable 2FA for your npm account.");
 }
 function checkDevContainer(rootDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depsentinel",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "JS/TS supply-chain hardening CLI — scan, secure, and enforce dependency policies",
   "license": "MIT",
   "author": "depsentinel contributors",