@n8n/scan-community-package 0.17.1 → 0.18.0

package/README.md

@@ -1,5 +1,7 @@
 ## n8n community-package static analysis tool
 
+Checks npm provenance and runs static analysis for n8n community packages.
+
 ### How to use this
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n/scan-community-package",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Static code analyser for n8n community packages",
   "license": "SEE LICENSE IN LICENSE.md",
   "bin": "scanner/cli.mjs",
@@ -13,9 +13,14 @@
     "eslint": "9.29.0",
     "fast-glob": "3.2.12",
     "axios": "1.16.0",
+    "@typescript-eslint/parser": "^8.35.0",
     "semver": "^7.5.4",
     "tmp": "0.2.4",
-    "@n8n/eslint-plugin-community-nodes": "0.15.0"
+    "@n8n/eslint-plugin-community-nodes": "0.16.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.1",
+    "@n8n/vitest-config": "1.10.0"
   },
   "homepage": "https://n8n.io",
   "author": {
@@ -25,5 +30,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/n8n-io/n8n.git"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:dev": "vitest"
   }
 }

package/scanner/provenance.mjs

@@ -0,0 +1,31 @@
+const NPM_PROVENANCE_PREDICATE_TYPE = 'https://slsa.dev/provenance/v1';
+const N8N_COMMUNITY_NODE_PUBLISH_DOCS_URL =
+	'https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/';
+
+export const checkPackageProvenance = (packageMetadata, version) => {
+	const packageVersion = packageMetadata.versions?.[version];
+	const provenance = packageVersion?.dist?.attestations?.provenance;
+
+	if (!packageVersion) {
+		return {
+			passed: false,
+			message: `No package metadata found for version ${version}`,
+		};
+	}
+
+	if (!provenance) {
+		return {
+			passed: false,
+			message: `Package was not published with npm provenance. Learn how to publish community nodes with provenance: ${N8N_COMMUNITY_NODE_PUBLISH_DOCS_URL}`,
+		};
+	}
+
+	if (provenance.predicateType !== NPM_PROVENANCE_PREDICATE_TYPE) {
+		return {
+			passed: false,
+			message: `Unsupported npm provenance predicate type: ${provenance.predicateType ?? 'unknown'}`,
+		};
+	}
+
+	return { passed: true };
+};

package/scanner/scanner.mjs

@@ -11,6 +11,8 @@ import glob from 'fast-glob';
 import { fileURLToPath } from 'url';
 import { defineConfig } from 'eslint/config';
 
+import { checkPackageProvenance } from './provenance.mjs';
+
 const { stdout } = process;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMP_DIR = tmp.dirSync({ unsafeCleanup: true }).name;
@@ -115,29 +117,47 @@ const downloadAndExtractPackage = async (packageName, version) => {
 	}
 };
 
-const analyzePackage = async (packageDir) => {
+export const analyzePackage = async (packageDir) => {
 	const { n8nCommunityNodesPlugin } = await import('@n8n/eslint-plugin-community-nodes');
+	const tsParser = await import('@typescript-eslint/parser');
+
 	const eslint = new ESLint({
 		cwd: packageDir,
 		allowInlineConfig: false,
 		overrideConfigFile: true,
-		overrideConfig: defineConfig(n8nCommunityNodesPlugin.configs.recommended, {
-			rules: { 'no-console': 'error' },
-		}),
+		overrideConfig: defineConfig(
+			n8nCommunityNodesPlugin.configs.recommended,
+			{
+				rules: { 'no-console': 'error' },
+			},
+			// JSON files (notably `package.json`) are not parseable by ESLint's
+			// default JS parser, so register the TypeScript parser for them. The
+			// community-nodes rules that gate on `package.json` walk a TSESTree
+			// `ObjectExpression` AST, which `@typescript-eslint/parser` produces
+			// when given a top-level JSON object literal.
+			{
+				files: ['**/*.json'],
+				languageOptions: { parser: tsParser.default ?? tsParser },
+			},
+		),
 	});
 
 	try {
-		const jsFiles = glob.sync('**/*.js', {
+		// Lint both JS and JSON files. JSON inclusion is required because rules
+		// such as `no-overrides-field`, `valid-peer-dependencies`, and
+		// `package-name-convention` only run against `package.json`. Without
+		// it the scanner silently skips every package.json-based rule.
+		const filesToLint = glob.sync(['**/*.js', '**/*.json'], {
 			cwd: packageDir,
 			absolute: true,
-			ignore: ['node_modules/**'],
+			ignore: ['node_modules/**', '**/package-lock.json'],
 		});
 
-		if (jsFiles.length === 0) {
-			return { passed: true, message: 'No JavaScript files found to analyze' };
+		if (filesToLint.length === 0) {
+			return { passed: true, message: 'No files found to analyze' };
 		}
 
-		const results = await eslint.lintFiles(jsFiles);
+		const results = await eslint.lintFiles(filesToLint);
 		const violations = results.filter((result) => result.errorCount > 0);
 
 		if (violations.length > 0) {
@@ -164,10 +184,12 @@ const analyzePackage = async (packageDir) => {
 export const analyzePackageByName = async (packageName, version) => {
 	try {
 		let exactVersion = version;
+		let packageMetadata;
 
 		// If version is a range, get the latest matching version
 		if (version && semver.validRange(version) && !semver.valid(version)) {
 			const { data } = await axios.get(`${registry}/${packageName}`);
+			packageMetadata = data;
 			const versions = Object.keys(data.versions);
 			exactVersion = semver.maxSatisfying(versions, version);
 
@@ -179,11 +201,33 @@ export const analyzePackageByName = async (packageName, version) => {
 		// If no version specified, get the latest
 		if (!exactVersion) {
 			const { data } = await axios.get(`${registry}/${packageName}`);
+			packageMetadata = data;
 			exactVersion = data['dist-tags'].latest;
 		}
 
+		packageMetadata ??= (await axios.get(`${registry}/${packageName}`)).data;
+		exactVersion = packageMetadata['dist-tags']?.[exactVersion] ?? exactVersion;
 		const label = `${packageName}@${exactVersion}`;
 
+		stdout.write(`Checking provenance for ${label}...`);
+		const provenanceResult = checkPackageProvenance(packageMetadata, exactVersion);
+		if (stdout.TTY) {
+			stdout.clearLine(0);
+			stdout.cursorTo(0);
+		}
+
+		if (!provenanceResult.passed) {
+			stdout.write(`❌ Provenance check failed for ${label} \n`);
+
+			return {
+				packageName,
+				version: exactVersion,
+				...provenanceResult,
+			};
+		}
+
+		stdout.write(`✅ Provenance check passed for ${label} \n`);
+
 		stdout.write(`Downloading ${label}...`);
 		const packageDir = await downloadAndExtractPackage(packageName, exactVersion);
 		if (stdout.TTY) {

package/scanner/scanner.test.mjs

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { analyzePackage } from './scanner.mjs';
+
+/**
+ * Build a temporary package directory on disk so we can hand it to
+ * `analyzePackage` exactly the way the scanner would after extracting a
+ * tarball from npm.
+ */
+function makeFixturePackage(files) {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scan-fixture-'));
+	for (const [relativePath, contents] of Object.entries(files)) {
+		const fullPath = path.join(dir, relativePath);
+		fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+		fs.writeFileSync(
+			fullPath,
+			typeof contents === 'string' ? contents : JSON.stringify(contents, null, 2),
+		);
+	}
+	return dir;
+}
+
+describe('analyzePackage', () => {
+	let fixtureDir;
+
+	afterEach(() => {
+		if (fixtureDir) {
+			fs.rmSync(fixtureDir, { recursive: true, force: true });
+			fixtureDir = undefined;
+		}
+	});
+
+	it('lints package.json and flags forbidden `overrides` field (regression for CE-1023)', async () => {
+		fixtureDir = makeFixturePackage({
+			'package.json': {
+				name: 'n8n-nodes-fixture',
+				version: '1.0.0',
+				keywords: ['n8n-community-node-package'],
+				peerDependencies: { 'n8n-workflow': '*' },
+				overrides: { 'change-case': '4.1.2' },
+			},
+			'index.js': "module.exports = {};\n",
+		});
+
+		const result = await analyzePackage(fixtureDir);
+
+		expect(result.passed).toBe(false);
+		expect(result.details).toContain('no-overrides-field');
+	});
+
+	it('passes a clean package that does not violate any error-level rules', async () => {
+		fixtureDir = makeFixturePackage({
+			'package.json': {
+				name: 'n8n-nodes-fixture',
+				version: '1.0.0',
+				keywords: ['n8n-community-node-package'],
+				peerDependencies: { 'n8n-workflow': '*' },
+			},
+			'index.js': "module.exports = {};\n",
+		});
+
+		const result = await analyzePackage(fixtureDir);
+
+		expect(result.passed).toBe(true);
+	});
+
+	it('flags forbidden lifecycle scripts in package.json', async () => {
+		fixtureDir = makeFixturePackage({
+			'package.json': {
+				name: 'n8n-nodes-fixture',
+				version: '1.0.0',
+				keywords: ['n8n-community-node-package'],
+				peerDependencies: { 'n8n-workflow': '*' },
+				scripts: { postinstall: 'node ./malicious.js' },
+			},
+			'index.js': "module.exports = {};\n",
+		});
+
+		const result = await analyzePackage(fixtureDir);
+
+		expect(result.passed).toBe(false);
+		expect(result.details).toContain('no-forbidden-lifecycle-scripts');
+	});
+
+	it('returns passed when the package contains no lintable files', async () => {
+		fixtureDir = makeFixturePackage({
+			'README.md': '# empty package\n',
+		});
+
+		const result = await analyzePackage(fixtureDir);
+
+		expect(result.passed).toBe(true);
+		expect(result.message).toBe('No files found to analyze');
+	});
+});