verdaccio-security-filter 1.4.0 → 1.4.2

package/README.md

@@ -150,47 +150,44 @@ npm link
 
 ## 🔧 How It Works
 
-This plugin implements **two layers of protection** to block malicious packages:
+The plugin works in two layers. Configure both: the same settings go under `filters` and under `middlewares`.
 
 ### Layer 1: Metadata Filtering (`filter_metadata`)
-When a client requests package information (e.g., `npm info lodash`), the plugin:
-1. Checks if the package is allowed (whitelist mode)
-2. Validates against blocked patterns, scopes, and age requirements
-3. **Throws HTTP 404 error** for completely blocked packages (patterns, scopes, whitelist violations)
-4. Filters out specific blocked versions from the versions list for partial blocks
+Runs inside Verdaccio when package metadata is read, so it sees every version:
+1. Removes versions blocked by `blockedVersions`, `versionRangeRules` and `whitelist.versions`
+2. Removes versions rejected by the CVE, license, age and author checks
+3. Blocks the package as a whole when no version is left, or when the package itself is not allowed
 
-**Result**: Blocked packages return "404 Not Found" - as if they don't exist in the registry.
+npm then resolves ranges against the versions that are left.
 
-### Layer 2: Middleware Interception (`register_middlewares`)
-When a client tries to download a tarball file (e.g., during `npm install`), the plugin:
-1. Intercepts **all HTTP requests** early in the middleware chain
-2. Extracts package name and version from the request URL
-3. Applies all security checks (whitelist, patterns, scopes, blocked versions, range rules)
-4. Returns **403 Forbidden** for blocked packages with detailed error message
+### Layer 2: Middleware (`register_middlewares`)
+Runs first on every `GET` request:
+1. Blocks packages by name: whitelist, patterns, scopes
+2. Blocks tarball downloads of blocked versions, even if a client has stale metadata or a lockfile
+3. Turns a whole-package block from layer 1 into an HTTP error that carries the reason
 
-**Result**: Even if metadata is cached, tarball downloads are blocked at the HTTP level.
+### What a client sees
 
-### Why Both Layers?
+A removed version is simply missing from the metadata. A blocked package or tarball is answered with **403 Forbidden**, and the reason is in the `error` field, which npm prints:
 
-- **Metadata filtering (404)** - Makes blocked packages invisible to npm/yarn
-- **Middleware interception (403)** - Blocks tarball downloads even with cached metadata
-- Together, they provide **complete protection** against blocked packages being installed in any way
-
-Example flow when a blocked package is requested:
 ```
 npm install hawk
-→ GET /hawk (metadata request)
-→ [Security Filter] Blocked hawk@* - Package is not in whitelist
-→ HTTP 404 Not Found: Package blocked by security filter: Not in whitelist
-→ npm ERR! 404 Not Found - GET http://localhost:4873/hawk
-
-npm install (with hawk as dependency)
-→ GET /hawk/-/hawk-9.0.1.tgz (tarball request)
-→ [Middleware] Tarball request: hawk/hawk-9.0.1.tgz
-→ [Security Filter] Blocked hawk@9.0.1 - Package is not in whitelist
-→ HTTP 403 Forbidden: {"error": "Package blocked by security filter", "reason": "Package is not in whitelist"}
+npm error code E403
+npm error 403 403 Forbidden - GET http://localhost:4873/hawk - Package blocked by security filter: Package is not in whitelist
 ```
 
+```json
+{
+  "error": "Package blocked by security filter: License 'GPL-3.0' is not in allowed list",
+  "package": "some-package",
+  "reason": "License 'GPL-3.0' is not in allowed list",
+  "security": { "blocked": true, "reason": "...", "plugin": { "name": "verdaccio-security-filter", "version": "..." } },
+  "timestamp": "2026-01-15T10:30:00.000Z"
+}
+```
+
+The 403 for packages blocked in layer 1 (CVE, license, age, author, fail-closed errors) needs the middleware. With only `filters` configured, such a package is returned with an empty version list and npm reports "No versions available" without a reason.
+
 ## ⚙️ Configuration
 
 ### Quick Start (Middleware Only)
@@ -451,9 +448,9 @@ Recommended before turning on `cveCheck.autoBlock`, a license policy or the auth
 |--------|------|---------|-------------|
 | `licenses.allowed` | `string[]` | `[]` | Allowed license list |
 | `licenses.blocked` | `string[]` | `[]` | Blocked license list |
-| `licenses.requireLicense` | `boolean` | `true` | Reject versions without a license field |
+| `licenses.requireLicense` | `boolean` | `true` with `allowed`, otherwise `false` | Reject versions without a license field |
 
-The license check runs when `licenses.allowed` is not empty. Every version is checked: versions with a rejected license are removed from the metadata, and the package is blocked as a whole only when no version is left.
+The license check runs when `licenses.allowed` or `licenses.blocked` is not empty, or `licenses.requireLicense` is `true`. Every version is checked: versions with a rejected license are removed from the metadata, and the package is blocked as a whole only when no version is left.
 
 ### Whitelist Options
 

package/build/index.js

@@ -56,7 +56,12 @@ const cve_checker_1 = require("./lib/cve-checker");
 const license_checker_1 = require("./lib/license-checker");
 const package_age_checker_1 = require("./lib/package-age-checker");
 const author_checker_1 = require("./lib/author-checker");
+const lru_cache_1 = require("./lib/lru-cache");
 const PLUGIN_VERSION = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf8')).version;
+const filterBlocks = new lru_cache_1.LRUCache(1000);
+function forbiddenBody(packageName, reason, extra = {}) {
+    return Object.assign(Object.assign({ error: `Package blocked by security filter: ${reason}`, package: packageName, reason }, extra), { timestamp: new Date().toISOString() });
+}
 class SecurityFilterPlugin {
     constructor(config, options) {
         this.config = config || {};
@@ -141,7 +146,7 @@ class SecurityFilterPlugin {
         }
     }
     _getEnabledFeatures() {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d;
         const features = [];
         if (this.config.dryRun)
             features.push('dry-run');
@@ -151,11 +156,11 @@ class SecurityFilterPlugin {
             features.push('metrics');
         if ((_b = this.config.cveCheck) === null || _b === void 0 ? void 0 : _b.enabled)
             features.push('cve-checking');
-        if (((_c = this.config.licenses) === null || _c === void 0 ? void 0 : _c.allowed) && this.config.licenses.allowed.length > 0)
+        if (this.licenseChecker.enabled)
             features.push('license-filtering');
-        if ((_d = this.config.packageAge) === null || _d === void 0 ? void 0 : _d.enabled)
+        if ((_c = this.config.packageAge) === null || _c === void 0 ? void 0 : _c.enabled)
             features.push('package-age-verification');
-        if ((_e = this.config.authorFilter) === null || _e === void 0 ? void 0 : _e.enabled)
+        if ((_d = this.config.authorFilter) === null || _d === void 0 ? void 0 : _d.enabled)
             features.push('author-filtering');
         if (this.securityRules.versionRangeRules.length > 0)
             features.push('version-range-rules');
@@ -233,13 +238,7 @@ class SecurityFilterPlugin {
                         if (this.config.dryRun) {
                             return next();
                         }
-                        res.status(403).json({
-                            error: 'Package blocked by security filter',
-                            package: packageName,
-                            version: version || 'all versions',
-                            reason: blockResult.reason,
-                            timestamp: new Date().toISOString()
-                        });
+                        res.status(403).json(forbiddenBody(packageName, blockResult.reason, { version: version || 'all versions' }));
                         return;
                     }
                     this.logger.debug(`[Middleware] [OK] ALLOWED TARBALL: ${packageName}@${version || 'unknown'}`);
@@ -252,10 +251,7 @@ class SecurityFilterPlugin {
                         if (this.config.dryRun) {
                             return next();
                         }
-                        const blockedResponse = {
-                            name: packageName,
-                            versions: {},
-                            'dist-tags': {},
+                        res.status(403).json(forbiddenBody(packageName, blockResult.reason, {
                             security: {
                                 blocked: true,
                                 reason: blockResult.reason,
@@ -266,21 +262,24 @@ class SecurityFilterPlugin {
                                 },
                                 blockedAt: new Date().toISOString(),
                                 rules: this._getAppliedRules(packageName),
-                                message: `This package has been blocked by security filter: ${blockResult.reason}`,
                                 contact: 'Please contact your registry administrator for more information',
                             },
-                            _security: {
-                                blocked: true,
-                                reason: blockResult.reason,
-                                blockedBy: 'verdaccio-security-filter',
-                                blockedAt: new Date().toISOString(),
-                            }
-                        };
-                        res.status(200).json(blockedResponse);
+                        }));
                         return;
                     }
-                    else {
-                        this.logger.debug(`[Middleware] [OK] ALLOWED METADATA: ${packageName}`);
+                    this.logger.debug(`[Middleware] [OK] ALLOWED METADATA: ${packageName}`);
+                    if (!this.config.dryRun) {
+                        const startedAt = Date.now();
+                        const send = res.send.bind(res);
+                        res.send = (body) => {
+                            const block = filterBlocks.get(packageName);
+                            if (block && block.at >= startedAt && res.statusCode < 300) {
+                                res.removeHeader('ETag');
+                                res.status(403);
+                                return send(JSON.stringify(forbiddenBody(packageName, block.security.reason, { security: block.security })));
+                            }
+                            return send(body);
+                        };
                     }
                 }
                 next();
@@ -334,7 +333,14 @@ class SecurityFilterPlugin {
     filter_metadata(packageInfo) {
         return __awaiter(this, void 0, void 0, function* () {
             const filtered = yield this._filterMetadata(packageInfo);
-            if (!this.config.dryRun || filtered === packageInfo) {
+            if (!this.config.dryRun) {
+                const security = filtered.security;
+                if (security === null || security === void 0 ? void 0 : security.blocked) {
+                    filterBlocks.set(packageInfo.name, { security, at: Date.now() });
+                }
+                return filtered;
+            }
+            if (filtered === packageInfo) {
                 return filtered;
             }
             const total = Object.keys(packageInfo.versions || {}).length;
@@ -397,7 +403,7 @@ class SecurityFilterPlugin {
                         pkg = this._removeVersions(pkg, vulnerableVersions);
                     }
                 }
-                if (this.config.licenses && this.config.licenses.allowed && this.config.licenses.allowed.length > 0) {
+                if (this.licenseChecker.enabled) {
                     const rejected = this._rejectedVersions(pkg, data => this.licenseChecker.checkLicense(data));
                     if (rejected.all) {
                         const reason = rejected.first.reason || 'License not allowed';

package/build/lib/license-checker.d.ts

@@ -3,6 +3,7 @@ import { Version } from '@verdaccio/types';
 export declare class LicenseChecker {
     private config;
     constructor(config?: LicenseConfig);
+    get enabled(): boolean;
     checkLicense(versionData: Version): {
         allowed: boolean;
         reason?: string;

package/build/lib/license-checker.js

@@ -3,12 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LicenseChecker = void 0;
 class LicenseChecker {
     constructor(config) {
+        var _a;
         this.config = {
             allowed: (config === null || config === void 0 ? void 0 : config.allowed) || [],
             blocked: (config === null || config === void 0 ? void 0 : config.blocked) || [],
-            requireLicense: (config === null || config === void 0 ? void 0 : config.requireLicense) !== false,
+            requireLicense: (_a = config === null || config === void 0 ? void 0 : config.requireLicense) !== null && _a !== void 0 ? _a : ((config === null || config === void 0 ? void 0 : config.allowed) || []).length > 0,
         };
     }
+    get enabled() {
+        return this.config.allowed.length > 0 || this.config.blocked.length > 0 || this.config.requireLicense;
+    }
     checkLicense(versionData) {
         const license = this.extractLicense(versionData);
         if (!license || license === 'UNLICENSED' || license === '') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verdaccio-security-filter",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Advanced security filter plugin for Verdaccio with version range blocking and fallback strategies",
   "main": "build/index.js",
   "types": "build/index.d.ts",