@dependably/npm-check 1.8.0 → 1.10.0

package/src/audit.js

@@ -4,8 +4,8 @@ import path from 'path';
 import { forEachPackageEntry, detectLockfileFlavor } from './format-library.js';
 import { validatePackageLock } from './validator.js';
 import { validatePackageJson } from './package-json-validator.js';
-import { validateNpmrc, NPMRC_SECURITY_CODES } from './npmrc-validator.js';
-import { validatePnpmWorkspace } from './pnpm-workspace-validator.js';
+import { validateNpmrc, parseNpmrc, NPMRC_SECURITY_CODES } from './npmrc-validator.js';
+import { validatePnpmWorkspace, parsePnpmWorkspace } from './pnpm-workspace-validator.js';
 import { isPlaceholder } from './integrity.js';
 import { classifyRange } from './pinner.js';
 import { walkOverrides } from './overrides.js';
@@ -666,6 +666,187 @@ const validPnpmFieldRule = {
   }
 };
 
+/**
+ * Lockfile portability: every `resolved` URL must point at a host this project
+ * pins to.
+ *
+ * This is deliberately NOT the same question as `secure-resolved` /
+ * `no-remote-deps`, which both consult `allowedRegistryHosts` to ask "is this
+ * host a legitimate, trusted registry?". Trust and portability are orthogonal:
+ * an org's own private mirror is entirely trusted, yet a lockfile resolving
+ * from it cannot be installed by anyone outside that network (a public CI
+ * runner, an external contributor, a GitHub build). A shared
+ * `allowedRegistryHosts` also unions across config levels, so it can only ever
+ * grow more permissive — correct for a trust allowlist, but useless as a pin,
+ * which must be able to narrow.
+ *
+ * Opt-in: with no `hosts` configured the rule is a no-op, so projects that
+ * genuinely install from a private registry are unaffected.
+ */
+// Trim/lowercase the configured pin list, dropping non-string and blank entries.
+// An empty result means the rule is unconfigured, i.e. off.
+function normalizePinnedHosts(hosts) {
+  if (!Array.isArray(hosts)) return [];
+  return hosts.filter((h) => typeof h === 'string' && h.trim()).map((h) => h.trim().toLowerCase());
+}
+
+// Git/file/link/workspace entries resolve outside the registry by definition —
+// no-git-deps / secure-resolved own those.
+function resolvesOutsideRegistry({ isRoot, isWorkspaceSource, isLink, isGitDep, isFileDep }) {
+  return Boolean(isRoot || isWorkspaceSource || isLink || isGitDep || isFileDep);
+}
+
+// Hostname of an entry's http(s) `resolved` URL, or null when it has none or the
+// URL is unparseable (secure-resolved flags that; not this rule's job).
+function resolvedHostname(entry) {
+  const resolved = entry && entry.resolved;
+  if (!resolved || !/^https?:/i.test(resolved)) return null;
+  try {
+    return new URL(resolved).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+const resolvedRegistryPinRule = {
+  id: 'resolved-registry-pin',
+  description: 'Resolved URLs must point only at the registry hosts this project pins to',
+  defaultSeverity: 'error',
+  // pnpm lockfiles carry no `resolved` URLs (the registry is implied by config),
+  // so there is nothing to pin.
+  flavors: ['npm'],
+  check({ lockfile, options }) {
+    const findings = [];
+    // Unconfigured == off. Pinning is a per-project decision, not a default.
+    const pinned = normalizePinnedHosts(options.hosts);
+    if (pinned.length === 0 || !lockfile.packages) return findings;
+
+    forEachPackageEntry(lockfile, (packageEntry) => {
+      if (resolvesOutsideRegistry(packageEntry)) return;
+      const hostname = resolvedHostname(packageEntry.entry);
+      if (hostname === null || pinned.includes(hostname)) return;
+      const { key, name } = packageEntry;
+      findings.push({
+        packagePath: key,
+        message: `${name || key} resolves from "${hostname}", which is not a pinned registry host (${pinned.join(', ')}) — the lockfile will not install where that host is unreachable`
+      });
+    });
+    return findings;
+  }
+};
+
+// Supply-chain "cooldown": refuse to install versions published less than N ago.
+// A compromised maintainer account's malicious release is typically detected and
+// unpublished within hours, so a cooldown means you simply never resolve it.
+//
+// The two package managers disagree on BOTH key name and unit, which is the whole
+// reason this normalizes to days before comparing:
+//   npm  >= 11.10 : `.npmrc`              min-release-age    (DAYS)
+//   pnpm >= 10.16 : `pnpm-workspace.yaml` minimumReleaseAge  (MINUTES)
+// pnpm reads only auth/registry settings from .npmrc, so its cooldown is never
+// there; npm has no equivalent yaml, so its cooldown is never in the workspace file.
+const MINUTES_PER_DAY = 1440;
+
+// Configured cooldown in DAYS for an npm project, or null when unset/unparseable.
+function npmCooldownDays(npmrcPath) {
+  let content;
+  try {
+    content = fs.readFileSync(npmrcPath, 'utf8');
+  } catch {
+    return null; // no committed .npmrc → no committed policy
+  }
+  // parseNpmrc yields an entry list, keys lowercased; last assignment wins (ini).
+  const entry = parseNpmrc(content).filter((e) => e.key === 'min-release-age').pop();
+  if (!entry) return null;
+  const days = Number(entry.value);
+  return Number.isFinite(days) ? days : null;
+}
+
+// Configured cooldown in DAYS for a pnpm project, or null when unset/unparseable.
+function pnpmCooldownDays(workspacePath) {
+  let content;
+  try {
+    content = fs.readFileSync(workspacePath, 'utf8');
+  } catch {
+    return null;
+  }
+  let doc;
+  try {
+    doc = parsePnpmWorkspace(content);
+  } catch {
+    return null; // malformed YAML — valid-pnpm-workspace owns that finding
+  }
+  const raw = doc && doc.minimumReleaseAge;
+  if (raw === undefined) return null;
+  const minutes = Number(raw);
+  return Number.isFinite(minutes) ? minutes / MINUTES_PER_DAY : null;
+}
+
+// A blanket exclusion silently voids the policy, so it is worth its own finding.
+function blanketExclusions(workspacePath) {
+  let doc;
+  try {
+    doc = parsePnpmWorkspace(fs.readFileSync(workspacePath, 'utf8'));
+  } catch {
+    return [];
+  }
+  const list = doc && doc.minimumReleaseAgeExclude;
+  if (!Array.isArray(list)) return [];
+  return list.filter((p) => typeof p === 'string' && (p === '*' || p === '**'));
+}
+
+const minReleaseAgeRule = {
+  id: 'min-release-age',
+  description: 'A minimum release-age cooldown must be configured, so a freshly published (possibly compromised) version is never installed',
+  defaultSeverity: 'warn',
+  flavors: ['npm', 'pnpm'],
+  check({ filePath, options, flavor }) {
+    const { minDays = 3 } = options;
+    const dir = path.dirname(path.resolve(filePath));
+    const isPnpm = flavor === 'pnpm';
+    const configFile = isPnpm ? 'pnpm-workspace.yaml' : '.npmrc';
+    // `npmrcPath` lets a caller point at a .npmrc outside the lockfile's dir
+    // (same option valid-npmrc takes); it is meaningless on the pnpm path.
+    const npmrcPath = options.npmrcPath ? path.resolve(options.npmrcPath) : path.join(dir, '.npmrc');
+    const configPath = isPnpm ? path.join(dir, 'pnpm-workspace.yaml') : npmrcPath;
+
+    const configured = isPnpm ? pnpmCooldownDays(configPath) : npmCooldownDays(configPath);
+    const setting = isPnpm ? 'minimumReleaseAge' : 'min-release-age';
+    const findings = [];
+
+    if (configured === null) {
+      const unit = isPnpm ? `${minDays * MINUTES_PER_DAY} (minutes)` : `${minDays} (days)`;
+      findings.push({
+        packagePath: configFile,
+        message: `no release-age cooldown configured — set "${setting}" to at least ${unit} in ${configFile} so a version published moments ago is never installed`
+      });
+    } else if (configured < minDays) {
+      findings.push({
+        packagePath: configFile,
+        message: `release-age cooldown is ${formatDays(configured)}, below the required minimum of ${formatDays(minDays)} ("${setting}" in ${configFile})`
+      });
+    }
+
+    if (isPnpm) {
+      for (const pattern of blanketExclusions(configPath)) {
+        findings.push({
+          packagePath: configFile,
+          message: `"minimumReleaseAgeExclude" contains the blanket pattern "${pattern}", which exempts every package and voids the cooldown`
+        });
+      }
+    }
+    return findings;
+  }
+};
+
+// Render a day count the way a reader configures it: whole days, or minutes when
+// the value is under a day (which is how a pnpm `minimumReleaseAge` will land here).
+function formatDays(days) {
+  if (days >= 1) return `${Number.isInteger(days) ? days : days.toFixed(2)} day${days === 1 ? '' : 's'}`;
+  const minutes = Math.round(days * MINUTES_PER_DAY);
+  return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
+
 export const rules = [
   lockfileVersionRule,
   validStructureRule,
@@ -675,6 +856,7 @@ export const rules = [
   installScriptsRule,
   noGitDepsRule,
   noRemoteDepsRule,
+  resolvedRegistryPinRule,
   pinnedVersionsRule,
   lockfileSyncRule,
   noOrphanPackagesRule,
@@ -682,7 +864,8 @@ export const rules = [
   noFundRule,
   validNpmrcRule,
   validPnpmWorkspaceRule,
-  validPnpmFieldRule
+  validPnpmFieldRule,
+  minReleaseAgeRule
 ];
 
 /**
@@ -810,30 +993,45 @@ export function runAudit(target, config = {}) {
  * @param {object} options - { format: 'stylish' | 'json' }
  * @returns {string}
  */
-export function formatAuditReport(report, options = {}) {
-  const { format = 'stylish', showSuppressed = false } = options;
-  const suppressed = report.suppressed || [];
+// Machine-readable half of formatAuditReport.
+function formatAuditJson(report, suppressed) {
+  const meta = report.exceptionsMeta || {};
+  return JSON.stringify({
+    filePath: report.filePath,
+    pass: report.pass,
+    summary: report.summary,
+    findings: report.findings,
+    suppressed,
+    exceptionsMeta: {
+      unused: (meta.unused || []).map((e) => e._raw),
+      expired: (meta.expired || []).map((e) => e._raw)
+    }
+  }, null, 2);
+}
 
-  if (format === 'json') {
-    return JSON.stringify({
-      filePath: report.filePath,
-      pass: report.pass,
-      summary: report.summary,
-      findings: report.findings,
-      suppressed,
-      exceptionsMeta: {
-        unused: (report.exceptionsMeta && report.exceptionsMeta.unused || []).map((e) => e._raw),
-        expired: (report.exceptionsMeta && report.exceptionsMeta.expired || []).map((e) => e._raw)
-      }
-    }, null, 2);
-  }
+// One aligned `severity  rule  path  message` line per finding.
+function findingLines(findings) {
+  const ruleWidth = Math.max(...findings.map((f) => f.ruleId.length));
+  return findings.map((finding) => {
+    const sev = finding.severity === 'error' ? 'error' : 'warn ';
+    const loc = finding.packagePath ? `${finding.packagePath}   ` : '';
+    return `  ${sev}  ${finding.ruleId.padEnd(ruleWidth)}  ${loc}${finding.message}`;
+  });
+}
 
-  if (format !== 'stylish') {
-    throw new AuditError(`Unknown report format: ${format}`, 'UNKNOWN_FORMAT');
-  }
+// The closing `N problems (E errors, W warnings)` tally.
+function totalsLine(summary, suppressedCount) {
+  const { errors, warnings, total } = summary;
+  const problemWord = total === 1 ? 'problem' : 'problems';
+  const errorWord = errors === 1 ? 'error' : 'errors';
+  const warningWord = warnings === 1 ? 'warning' : 'warnings';
+  const suffix = suppressedCount > 0 ? ` — ${suppressedCount} suppressed by .dependably` : '';
+  return `${total} ${problemWord} (${errors} ${errorWord}, ${warnings} ${warningWord})${suffix}`;
+}
 
-  const lines = [];
-  lines.push(report.filePath);
+// Human-readable (ESLint-like) half of formatAuditReport.
+function formatAuditStylish(report, suppressed, showSuppressed) {
+  const lines = [report.filePath];
 
   if (report.findings.length === 0) {
     lines.push(suppressed.length > 0 ? `  no problems found (${suppressed.length} suppressed by .dependably)` : '  no problems found');
@@ -841,22 +1039,24 @@ export function formatAuditReport(report, options = {}) {
     return lines.join('\n');
   }
 
-  const ruleWidth = Math.max(...report.findings.map((f) => f.ruleId.length));
-  for (const finding of report.findings) {
-    const sev = finding.severity === 'error' ? 'error' : 'warn ';
-    const loc = finding.packagePath ? `${finding.packagePath}   ` : '';
-    lines.push(`  ${sev}  ${finding.ruleId.padEnd(ruleWidth)}  ${loc}${finding.message}`);
-  }
-
-  const { errors, warnings, total } = report.summary;
-  const problemWord = total === 1 ? 'problem' : 'problems';
-  const suffix = suppressed.length > 0 ? ` — ${suppressed.length} suppressed by .dependably` : '';
+  lines.push(...findingLines(report.findings));
   lines.push('');
-  lines.push(`${total} ${problemWord} (${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'})${suffix}`);
+  lines.push(totalsLine(report.summary, suppressed.length));
   appendSuppressed(lines, suppressed, showSuppressed);
   return lines.join('\n');
 }
 
+export function formatAuditReport(report, options = {}) {
+  const { format = 'stylish', showSuppressed = false } = options;
+  const suppressed = report.suppressed || [];
+
+  if (format === 'json') return formatAuditJson(report, suppressed);
+  if (format !== 'stylish') {
+    throw new AuditError(`Unknown report format: ${format}`, 'UNKNOWN_FORMAT');
+  }
+  return formatAuditStylish(report, suppressed, showSuppressed);
+}
+
 // Optionally list the suppressed findings (with their exception reason) below the
 // summary, so `--show-suppressed` keeps the audit trail visible.
 function appendSuppressed(lines, suppressed, showSuppressed) {

package/src/exceptions.js

@@ -1,9 +1,10 @@
 // src/exceptions.js
 //
-// Reference implementation of the `.dependably` exception grammar
-// (docs/dependably-config-spec.md §6). This is the module the C# and Python
-// ports mirror; keep it behavior-compatible with the conformance fixtures under
-// conformance/dependably/.
+// Reference implementation of the `.dependably` exception grammar, specified in
+// §6 of the config spec at
+// https://gitlab.northwardlabs.ca/moonlitlabs/dependably-spec. This is the module
+// the C# and Python ports mirror; keep it behavior-compatible with the vendored
+// conformance fixtures under conformance/dependably/.
 //
 // An exception suppresses SPECIFIC findings so a run does not fail on them,
 // without excluding whole files (`exclude`) or disabling a rule globally
@@ -109,89 +110,106 @@ function splitPackageSelector(pkg) {
  * @param {string} [opts.configPath]
  * @returns {Array<{rule, reason, expires, source, selectors, _raw}>}
  */
-export function parseExceptions(raw, opts = {}) {
-  const { source = 'own', applicableSelectors = SELECTORS, knownRules = null, configPath = null } = opts;
-  const entries = ensureArray(raw, { configPath });
-  const out = [];
+// An exception entry must be an object carrying non-empty `rule` and `reason`.
+function validateExceptionShape(entry, index, at) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new ExceptionConfigError(`exception #${index} must be an object`, 'INVALID_EXCEPTIONS', at);
+  }
+  if (typeof entry.rule !== 'string' || entry.rule.trim() === '') {
+    throw new ExceptionConfigError(`exception #${index} is missing "rule"`, 'EXCEPTION_MISSING_RULE', at);
+  }
+  if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+    throw new ExceptionConfigError(
+      `exception for rule "${entry.rule}" is missing a non-empty "reason"`,
+      'EXCEPTION_MISSING_REASON',
+      at
+    );
+  }
+}
 
-  entries.forEach((entry, index) => {
-    const at = { configPath, source, index };
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-      throw new ExceptionConfigError(`exception #${index} must be an object`, 'INVALID_EXCEPTIONS', at);
-    }
-    if (typeof entry.rule !== 'string' || entry.rule.trim() === '') {
-      throw new ExceptionConfigError(`exception #${index} is missing "rule"`, 'EXCEPTION_MISSING_RULE', at);
-    }
-    if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+// At least one selector, each a non-empty string. A selector this tool's findings
+// never carry is an error in the tool's OWN section but is tolerated in `common`
+// (it simply never matches).
+function validateExceptionSelectors(entry, source, applicableSelectors, at) {
+  const present = SELECTORS.filter((s) => entry[s] !== undefined);
+  if (present.length === 0) {
+    throw new ExceptionConfigError(
+      `exception for rule "${entry.rule}" needs at least one selector (${SELECTORS.join(', ')})`,
+      'EXCEPTION_NO_SELECTOR',
+      at
+    );
+  }
+  for (const sel of present) {
+    if (typeof entry[sel] !== 'string' || entry[sel].trim() === '') {
       throw new ExceptionConfigError(
-        `exception for rule "${entry.rule}" is missing a non-empty "reason"`,
-        'EXCEPTION_MISSING_REASON',
+        `exception selector "${sel}" for rule "${entry.rule}" must be a non-empty string`,
+        'EXCEPTION_BAD_SELECTOR',
         at
       );
     }
-
-    const present = SELECTORS.filter((s) => entry[s] !== undefined);
-    if (present.length === 0) {
+    if (source === 'own' && !applicableSelectors.includes(sel)) {
       throw new ExceptionConfigError(
-        `exception for rule "${entry.rule}" needs at least one selector (${SELECTORS.join(', ')})`,
-        'EXCEPTION_NO_SELECTOR',
+        `exception selector "${sel}" is not applicable to this tool (applicable: ${applicableSelectors.join(', ')})`,
+        'EXCEPTION_BAD_SELECTOR',
         at
       );
     }
-    for (const sel of present) {
-      if (typeof entry[sel] !== 'string' || entry[sel].trim() === '') {
-        throw new ExceptionConfigError(
-          `exception selector "${sel}" for rule "${entry.rule}" must be a non-empty string`,
-          'EXCEPTION_BAD_SELECTOR',
-          at
-        );
-      }
-      // A selector this tool's findings never carry is an error in the tool's
-      // OWN section but is tolerated in `common` (it simply never matches).
-      if (source === 'own' && !applicableSelectors.includes(sel)) {
-        throw new ExceptionConfigError(
-          `exception selector "${sel}" is not applicable to this tool (applicable: ${applicableSelectors.join(', ')})`,
-          'EXCEPTION_BAD_SELECTOR',
-          at
-        );
-      }
-    }
+  }
+}
 
-    if (entry.expires !== undefined) {
-      if (typeof entry.expires !== 'string' || !EXPIRES_RE.test(entry.expires) || Number.isNaN(Date.parse(entry.expires))) {
-        throw new ExceptionConfigError(
-          `exception "expires" for rule "${entry.rule}" must be a valid YYYY-MM-DD date`,
-          'EXCEPTION_BAD_EXPIRES',
-          at
-        );
-      }
-    }
+// `expires`, when present, must be a valid YYYY-MM-DD date.
+function validateExceptionExpires(entry, at) {
+  if (entry.expires === undefined) return;
+  if (typeof entry.expires !== 'string' || !EXPIRES_RE.test(entry.expires) || Number.isNaN(Date.parse(entry.expires))) {
+    throw new ExceptionConfigError(
+      `exception "expires" for rule "${entry.rule}" must be a valid YYYY-MM-DD date`,
+      'EXCEPTION_BAD_EXPIRES',
+      at
+    );
+  }
+}
 
-    if (source === 'own' && knownRules && !knownRules.includes(entry.rule)) {
-      throw new ExceptionConfigError(
-        `Unknown rule "${entry.rule}" in exception (known rules: ${knownRules.join(', ')})`,
-        'UNKNOWN_RULE',
-        at
-      );
-    }
+// An unknown rule id is an error in the tool's own section (spec §8); in `common`
+// it belongs to a sibling tool and is tolerated.
+function validateExceptionRule(entry, source, knownRules, at) {
+  if (source === 'own' && knownRules && !knownRules.includes(entry.rule)) {
+    throw new ExceptionConfigError(
+      `Unknown rule "${entry.rule}" in exception (known rules: ${knownRules.join(', ')})`,
+      'UNKNOWN_RULE',
+      at
+    );
+  }
+}
+
+function buildExceptionSelectors(entry) {
+  const selectors = { rule: entry.rule };
+  if (entry.package !== undefined) selectors.package = splitPackageSelector(entry.package);
+  if (entry.path !== undefined) selectors.path = entry.path;
+  if (entry.symbol !== undefined) selectors.symbol = entry.symbol;
+  if (entry.id !== undefined) selectors.id = entry.id;
+  return selectors;
+}
+
+export function parseExceptions(raw, opts = {}) {
+  const { source = 'own', applicableSelectors = SELECTORS, knownRules = null, configPath = null } = opts;
+  const entries = ensureArray(raw, { configPath });
 
-    const selectors = { rule: entry.rule };
-    if (entry.package !== undefined) selectors.package = splitPackageSelector(entry.package);
-    if (entry.path !== undefined) selectors.path = entry.path;
-    if (entry.symbol !== undefined) selectors.symbol = entry.symbol;
-    if (entry.id !== undefined) selectors.id = entry.id;
+  return entries.map((entry, index) => {
+    const at = { configPath, source, index };
+    validateExceptionShape(entry, index, at);
+    validateExceptionSelectors(entry, source, applicableSelectors, at);
+    validateExceptionExpires(entry, at);
+    validateExceptionRule(entry, source, knownRules, at);
 
-    out.push({
+    return {
       rule: entry.rule,
       reason: entry.reason,
       expires: entry.expires || null,
       source,
-      selectors,
+      selectors: buildExceptionSelectors(entry),
       _raw: entry
-    });
+    };
   });
-
-  return out;
 }
 
 // --- matching ---
@@ -235,8 +253,7 @@ export function matchException(exception, finding) {
   if (s.package !== undefined && !matchPackage(s.package, finding)) return false;
   if (s.path !== undefined && !matchGlob(s.path, finding.path)) return false;
   if (s.symbol !== undefined && !matchSymbol(s.symbol, finding.symbol)) return false;
-  if (s.id !== undefined && s.id !== finding.id) return false;
-  return true;
+  return !(s.id !== undefined && s.id !== finding.id);
 }
 
 /**