eslint-plugin-chrome-extensions 2.0.0 → 2.2.0

package/src/rules/no-missing-web-accessible-resources.js

@@ -0,0 +1,51 @@
+import { getMemberPath, isContentScriptFile, readManifest } from '../utils.js'
+
+const re = { leadingSlash: /^\//, regexSpecial: /[.+?^${}()|[\]\\]/g }
+
+function collectWarPatterns(manifest) {
+    const war = manifest.web_accessible_resources
+    if (!Array.isArray(war)) return []
+    const patterns = []
+    for (const entry of war) {
+        if (typeof entry == 'string') patterns.push(entry)  // MV2 flat
+        else if (Array.isArray(entry?.resources))
+            for (const res of entry.resources) patterns.push(res)  // MV3 object
+    }
+    return patterns
+}
+
+function patternToRegex(pattern) {
+    const escaped = pattern.replace(re.regexSpecial, '\\$&').replace(/\*/g, '.*')
+    return new RegExp(`^${escaped}$`) // eslint-disable-line security/detect-non-literal-regexp
+}
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require content-script getURL() paths to be listed in `web_accessible_resources`',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            missingWar: '`{{path}}` is not in `web_accessible_resources`.'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest) return {}
+        if (!isContentScriptFile(context, manifest)) return {}
+        const regexes = collectWarPatterns(manifest).map(patternToRegex)
+        return {
+            CallExpression(node) {
+                if (node.callee.type != 'MemberExpression') return
+                if (getMemberPath(node.callee) != 'chrome.runtime.getURL') return
+                const arg = node.arguments[0] ; if (arg?.type != 'Literal' || typeof arg.value != 'string') return
+                const resourcePath = arg.value.replace(re.leadingSlash, '')
+                for (const regex of regexes) if (regex.test(resourcePath)) return
+                context.report({ node: arg, messageId: 'missingWar', data: { path: arg.value }})
+            }
+        }
+    }
+}

package/src/rules/no-remote-code.js

@@ -1,4 +1,5 @@
 import { remoteCodePatterns } from '../data/manifest.js'
+
 import { getMemberPath } from '../utils.js'
 
 const re = { url: /^https?:\/\// }
@@ -7,9 +8,10 @@ export default {
     meta: {
         type: 'problem',
         docs: {
-            description: 'Disallow remote or dynamically-evaluated code, per the MV3 CSP',
+            description: 'Disallow remote or dynamically-evaluated code, per MV3\'s CSP',
             category: 'Possible Errors',
-            recommended: true
+            recommended: true,
+            security: true
         },
         defaultOptions: [{
             patterns: ['eval', 'new-function', 'string-timer',
@@ -26,19 +28,19 @@ export default {
                 },
                 checkExecuteScriptClosures: {
                     type: 'boolean',
-                    description: 'Flag chrome.scripting.executeScript calls whose func captures outer scope'
+                    description: 'Flag `chrome.scripting.executeScript` calls whose func captures outer scope'
                 }
             },
             additionalProperties: false
         }],
         messages: {
-            eval: '`eval()` is forbidden under MV3\'s CSP - refactor to use static code.',
-            newFunction: '`new Function()` is forbidden under MV3\'s CSP - refactor to use a real function.',
-            stringTimer: 'String-argument `{{fn}}` is forbidden under MV3\'s CSP - pass a function reference instead.',
-            dynamicImport: 'Remote dynamic `import()` is forbidden under MV3\'s CSP - import local modules w/ a relative path.',
-            remoteScriptSrc: 'Injecting remote `<script src>` is forbidden under MV3\'s CSP - use `chrome.runtime.getURL()` for bundled scripts.',
+            eval: '`eval()` is forbidden under MV3\'s CSP. Use static code instead.',
+            newFunction: '`new Function()` is forbidden under MV3\'s CSP. Use a real function instead.',
+            stringTimer: 'String-argument `{{fn}}` is forbidden under MV3\'s CSP. Pass a function reference instead.',
+            dynamicImport: 'Remote dynamic `import()` is forbidden under MV3\'s CSP. Use a relative path instead.',
+            remoteScriptSrc: 'Injecting remote `<script src>` is forbidden under MV3\'s CSP. Use `chrome.runtime.getURL()` for bundled scripts instead.',
             executeScriptURL: '`chrome.scripting.executeScript` must use local `files`, not a remote URL.',
-            executeScriptClosure: '`chrome.scripting.executeScript({ func })` captures outer-scope variables that fail after serialization - pass them via `args`.'
+            executeScriptClosure: '`chrome.scripting.executeScript({ func })` captures outer-scope variables that fail after serialization. Pass them via `args` instead.'
         }
     },
 

package/src/rules/no-unrestricted-host-permissions.js

@@ -0,0 +1,54 @@
+import { getFilename } from '../utils.js'
+
+const re = { broadHost: /^(?:<all_urls>|\*:\/\/\*\/\*|\w+:\/\/\*\/\*)$/, manifestFilename: /manifest\.json$/ },
+      hostKeys = new Set(['host_permissions', 'optional_host_permissions', 'optional_permissions', 'permissions'])
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow broad host permissions that grant access to every site',
+            category: 'Possible Errors',
+            recommended: false,
+            manifest: true
+        },
+        defaultOptions: [{ allowedPatterns: [] }],
+        schema: [{
+            type: 'object',
+            properties: {
+                allowedPatterns: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Host patterns to explicitly allow despite being broad'
+                }
+            },
+            additionalProperties: false
+        }],
+        messages: {
+            unrestrictedHost: 'Host permission "{{pattern}}" grants access to every site. Narrow to specific origins or allow explicitly instead.'
+        }
+    },
+
+    create(context) {
+        if (!re.manifestFilename.test(getFilename(context))) return {}
+        const allowed = new Set(context.options[0]?.allowedPatterns || [])
+        return {
+            '*'(node) {
+                const keyNode = node.name || node.key ; if (!keyNode) return
+                const keyName = keyNode.value ?? keyNode.name
+                if (!hostKeys.has(keyName)) return
+                const arrNode = node.value ; if (arrNode?.type != 'Array') return
+                const elements = arrNode.elements || arrNode.items || []
+                for (const el of elements) {
+                    const valueNode = el.value || el,
+                          pattern = valueNode?.value
+                    if (typeof pattern != 'string'
+                        || allowed.has(pattern)
+                        || !re.broadHost.test(pattern)
+                    ) continue
+                    context.report({ node: valueNode, messageId: 'unrestrictedHost', data: { pattern }})
+                }
+            }
+        }
+    }
+}

package/src/rules/no-unused-permissions.js

@@ -33,7 +33,7 @@ export default {
         docs: {
             description: 'Flag manifest permissions whose APIs are never used',
             category: 'Possible Errors',
-            recommended: true,
+            recommended: false,
             manifest: true
         },
         schema: [],

package/src/rules/require-mv3.js

@@ -8,12 +8,12 @@ export default {
         docs: {
             description: 'Require manifest_version 3',
             category: 'Possible Errors',
-            recommended: true,
+            recommended: false,
             manifest: true
         },
         schema: [],
         messages: {
-            notMV3: 'manifest.json must declare `"manifest_version": 3` (MV2 rejected by the Chrome Web Store).'
+            notMV3: 'manifest.json must declare `"manifest_version": 3`.'
         }
     },
 

package/src/rules/valid-manifest-icons.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { findExtensionRoot, getFilename } from '../utils.js'
+
+const re = { manifestFilename: /manifest\.json$/, svg: /\.svg$/i },
+      sizes = { recommended: ['16', '32', '48', '128'], required: '128' }
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Validate manifest icons: sizes, existing files, no SVG',
+            category: 'Possible Errors',
+            recommended: false,
+            manifest: true
+        },
+        defaultOptions: [{
+            requireRecommendedSizes: true,
+            checkIconExists: true,
+            noSVG: true
+        }],
+        schema: [{
+            type: 'object',
+            properties: {
+                requireRecommendedSizes: {
+                    type: 'boolean',
+                    description: 'Require all recommended sizes (16, 32, 48, 128)'
+                },
+                checkIconExists: {
+                    type: 'boolean',
+                    description: 'Flag icon paths that do not resolve to a file'
+                },
+                noSVG: {
+                    type: 'boolean',
+                    description: 'Flag SVG icon paths (unsupported by Chrome)'
+                }
+            },
+            additionalProperties: false
+        }],
+        messages: {
+            missingSize: 'Recommended icon size "{{size}}" is missing (16, 32, 48, 128).',
+            missingRequiredSize: 'Icons must include a 128x128 icon.',
+            missingFile: 'Icon file "{{file}}" does not exist in the extension root.',
+            svgNotSupported: 'SVG icons are not supported by Chrome. Use PNG instead.'
+        }
+    },
+
+    create(context) {
+        if (!re.manifestFilename.test(getFilename(context))) return {}
+        const opts = context.options[0] || {},
+              requireRecommended = opts.requireRecommendedSizes !== false,
+              checkFiles = opts.checkIconExists !== false,
+              checkSVG = opts.noSVG !== false
+        const root = checkFiles ? findExtensionRoot(context) : null
+        return {
+            '*'(node) {
+                const keyNode = node.name || node.key ; if (!keyNode) return
+                const keyName = keyNode.value ?? keyNode.name ; if (keyName != 'icons') return
+                const iconsObj = node.value ; if (iconsObj?.type != 'Object') return
+                const members = iconsObj.members || iconsObj.properties || []
+                const declaredSizes = new Set()
+                for (const member of members) {
+                    const sizeNode = member.name || member.key,
+                          size = sizeNode?.value ?? sizeNode?.name,
+                          fileNode = member.value,
+                          file = fileNode?.value
+                    if (typeof size == 'string') declaredSizes.add(size)
+                    if (typeof file != 'string') continue
+                    if (checkSVG && re.svg.test(file))
+                        context.report({ node: fileNode, messageId: 'svgNotSupported' })
+                    else if (checkFiles && root // eslint-disable-next-line security/detect-non-literal-fs-filename
+                        && !fs.existsSync(path.resolve(root, file))
+                    ) context.report({ node: fileNode, messageId: 'missingFile', data: { file }})
+                }
+                if (requireRecommended) {
+                    for (const size of sizes.recommended)
+                        if (!declaredSizes.has(size))
+                            context.report({ node: iconsObj, messageId: 'missingSize', data: { size }})
+                } else if (!declaredSizes.has(sizes.required))
+                    context.report({ node: iconsObj, messageId: 'missingRequiredSize' })
+            }
+        }
+    }
+}

package/src/rules/valid-mv3-schema.js

@@ -1,5 +1,6 @@
-import { mv2OnlyKeys, forbiddenCSPdirectives } from '../data/manifest.js'
 import { getFilename, readManifest } from '../utils.js'
+import { mv2OnlyKeys, forbiddenCSPdirectives, ffMV3bgKeys, ffDataCollectionRequired, ffDataCollectionOptional }
+    from '../data/manifest.js'
 
 const re = { manifestFilename: /manifest\.json$/ }
 
@@ -9,12 +10,13 @@ export default {
         docs: {
             description: 'Validate manifest against the MV3 schema',
             category: 'Possible Errors',
-            recommended: true,
+            recommended: false,
             manifest: true
         },
         schema: [],
         messages: {
-            mv2Key: '`{{key}}` is not allowed in MV3 - {{reason}}.',
+            invalidDataCollectionValue: '`{{value}}` is not a valid data collection permission value for {{kind}}.',
+            mv2Key: '`{{key}}` is not allowed in MV3. {{reason}}.',
             unsafeCSP: 'MV3 CSP must not include `{{directive}}`.',
             wrongCSPType: '`content_security_policy` must be an object in MV3, not a string.'
         }
@@ -22,11 +24,11 @@ export default {
 
     create(context) {
         if (re.manifestFilename.test(getFilename(context))) { // lint it directly
-            const ancestors = [], pendingReports = []
-            let isMV3 = false
-            const keyOf = n => {
-                const k = n?.name || n?.key
-                return k?.value ?? k?.name
+            const ancestors = [], pendingReports = [], deferredMV2 = []
+            let isMV3 = false, isFF = false
+            function keyOf(node) {
+                const keyNode = node?.name || node?.key
+                return keyNode?.value ?? keyNode?.name
             }
             return {
                 '*'(node) {
@@ -35,18 +37,23 @@ export default {
                         const isTopLevel = ancestors.length == 2
                             && ancestors[0].type == 'Document'
                             && ancestors[1].type == 'Object'
-                        const inBackground = ancestors.some(a => keyOf(a) == 'background')
-                        const inCSP = ancestors.some(a => keyOf(a) == 'content_security_policy')
+                        const inBackground = ancestors.some(ancestor => keyOf(ancestor) == 'background')
+                        const inCSP = ancestors.some(ancestor => keyOf(ancestor) == 'content_security_policy')
+                        const inDataCollection = ancestors.some(ancestor =>
+                            keyOf(ancestor) == 'data_collection_permissions')
                         if (keyName == 'manifest_version' && node.value?.value == 3) isMV3 = true
+                        if (isTopLevel && keyName == 'browser_specific_settings') isFF = true
                         if (isTopLevel && mv2OnlyKeys.has(keyName))
                             pendingReports.push({ node, messageId: 'mv2Key',
                                 data: { key: keyName, reason: 'MV2-only key' }})
-                        if (inBackground && keyName == 'scripts')
-                            pendingReports.push({ node, messageId: 'mv2Key',
-                                data: { key: 'background.scripts', reason: 'use background.service_worker' }})
+                        if (inBackground && ffMV3bgKeys.has(keyName))
+                            deferredMV2.push({ node, messageId: 'mv2Key',
+                                data: { key: `background.${keyName}`,
+                                        reason: 'Use background.service_worker instead' }})
                         if (inBackground && keyName == 'persistent')
                             pendingReports.push({ node, messageId: 'mv2Key',
-                                data: { key: 'background.persistent', reason: 'MV3 service workers are never persistent' }})
+                                data: { key: 'background.persistent',
+                                        reason: 'MV3 service workers are never persistent' }})
                         if (isTopLevel && keyName == 'content_security_policy' && node.value?.type == 'String')
                             pendingReports.push({ node: node.value, messageId: 'wrongCSPType' })
                         if (inCSP && keyName == 'extension_pages' && typeof node.value?.value == 'string')
@@ -54,6 +61,17 @@ export default {
                                 if (node.value.value.includes(directive))
                                     pendingReports.push({ node: node.value, messageId: 'unsafeCSP',
                                         data: { directive }})
+                        if (inDataCollection && (keyName == 'required' || keyName == 'optional')
+                            && Array.isArray(node.value?.elements)
+                        ) for (const el of node.value.elements) {
+                            const value = typeof el.value == 'string' ? el.value : el.value?.value
+                            if (typeof value == 'string') {
+                                const set = keyName == 'required' ? ffDataCollectionRequired : ffDataCollectionOptional
+                                if (!set.has(value))
+                                    pendingReports.push({ node: el, messageId: 'invalidDataCollectionValue',
+                                        data: { value, kind: keyName }})
+                            }
+                        }
                     }
                     ancestors.push(node)
                 },
@@ -61,20 +79,23 @@ export default {
                     ancestors.pop()
                     if (node.type == 'Document') {
                         if (!isMV3) return
-                        for (const r of pendingReports) context.report(r)
+                        if (!isFF) pendingReports.push(...deferredMV2)
+                        for (const report of pendingReports) context.report(report)
                     }
                 }
             }
         }
         const manifest = readManifest(context) ; if (!manifest || manifest.manifest_version != 3) return {}
+        const isFF = manifest.browser_specific_settings != null
         return {
-            Program(node) {
+            Program(node) { /* eslint-disable security/detect-object-injection */
                 for (const key of Object.keys(manifest))
                     if (mv2OnlyKeys.has(key))
                         context.report({ node, messageId: 'mv2Key', data: { key, reason: 'MV2-only key' }})
-                if (manifest.background?.scripts)
-                    context.report({ node, messageId: 'mv2Key',
-                        data: { key: 'background.scripts', reason: 'use background.service_worker' }})
+                for (const key of ffMV3bgKeys)
+                    if (manifest.background?.[key] && !isFF)
+                        context.report({ node, messageId: 'mv2Key',
+                            data: { key: `background.${key}`, reason: 'Use background.service_worker instead' }})
                 if (manifest.background?.persistent != null)
                     context.report({ node, messageId: 'mv2Key',
                         data: { key: 'background.persistent', reason: 'MV3 service workers are never persistent' }})
@@ -86,7 +107,16 @@ export default {
                     for (const directive of forbiddenCSPdirectives)
                         if (cspPages.includes(directive))
                             context.report({ node, messageId: 'unsafeCSP', data: { directive }})
-            }
+                if (isFF) { // validate data collection permissions
+                    const dcp = manifest.browser_specific_settings?.gecko?.data_collection_permissions
+                    for (const [kind, set] of [['required', ffDataCollectionRequired], ['optional', ffDataCollectionOptional]])
+                        if (Array.isArray(dcp?.[kind]))
+                            for (const value of dcp[kind])
+                                if (!set.has(value))
+                                    context.report({ node, messageId: 'invalidDataCollectionValue',
+                                        data: { value, kind }})
+                }
+            } /* eslint-enable security/detect-object-injection */
         }
     }
 }

package/src/rules/valid-service-worker.js

@@ -12,7 +12,7 @@ export default {
         schema: [],
         messages: {
             listenerNotTopLevel: '`chrome.*.addListener()` must be registered at module top level so it attaches on service worker wake-up.',
-            keepaliveTimer: 'Sub-30s `{{fn}}` will not keep the MV3 service worker alive - use `chrome.alarms` instead.',
+            keepaliveTimer: 'Sub-30s `{{fn}}` will not keep the MV3 service worker alive. Use `chrome.alarms` instead.',
             domInSW: '`{{global}}` is not available in a service worker.'
         }
     },
@@ -30,13 +30,18 @@ export default {
                     && node.arguments[1]?.type == 'Literal'
                     && typeof node.arguments[1].value == 'number'
                     && node.arguments[1].value < serviceWorkerKeepaliveMinMS
+                    && !isInsideNestedFunction(node)
                 ) context.report({ node, messageId: 'keepaliveTimer', data: { fn: node.callee.name }})
             },
             Identifier(node) {
                 if (node.parent?.type == 'MemberExpression' && node.parent.property === node) return
                 if (node.parent?.type == 'Property' && node.parent.key === node && !node.parent.computed) return
-                if (domGlobals.has(node.name))
-                    context.report({ node, messageId: 'domInSW', data: { global: node.name }})
+                if (!domGlobals.has(node.name)) return
+                for (let scope = context.sourceCode.getScope(node) ;
+                    scope && scope.type != 'global' ;
+                    scope = scope.upper
+                ) if (scope.set.has(node.name)) return // shadowed by a local binding
+                context.report({ node, messageId: 'domInSW', data: { global: node.name }})
             }
         }
     }

package/src/rules/valid-version-field.js

@@ -13,7 +13,7 @@ export default {
         docs: {
             description: 'Validate the manifest version field format',
             category: 'Possible Errors',
-            recommended: true,
+            recommended: false,
             manifest: true
         },
         schema: [{
@@ -37,8 +37,8 @@ export default {
         }],
         defaultOptions: [{}],
         messages: {
-            invalidVersion: 'Invalid manifest `version`: must be a valid {{versionType}} version (expected format: {{example}})',
-            futureVersion: 'Invalid manifest `version`: date cannot be in the future'
+            invalidVersion: 'Invalid manifest `version`: must be a valid {{versionType}} version (expected format: {{example}}).',
+            futureVersion: 'Invalid manifest `version`: date cannot be in the future.'
         }
     },
 

package/src/utils.js

@@ -10,6 +10,17 @@ export function bundleRules(rules, predicate, pluginName) {
         .map(([ruleId]) => [`${pluginName}/${ruleId}`, 'error']))
 }
 
+export function initBundleDeprecation(plugin, [ruleId, bundleNames], pluginName) {
+    for (const bundleName of bundleNames) {
+        /* eslint-disable security/detect-object-injection */
+        if (plugin.configs[bundleName])
+            plugin.configs[bundleName].rules[`${pluginName}/${ruleId}`] = 'error'
+        /* eslint-enable security/detect-object-injection */
+        if (process.env.DEBUG_MODE)
+            console.warn(`[${pluginName}] '${ruleId}' will be removed from '${bundleName}' in a future major release`)
+    }
+}
+
 export function findExtensionRoot(context) {
     let dir = path.dirname(getFilename(context))
     while (dir) {