eslint-plugin-chrome-extensions 1.0.0

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

@@ -0,0 +1,141 @@
+import { remoteCodePatterns } from '../data/manifest.js'
+import { getMemberPath } from '../utils.js'
+
+const re = { url: /^https?:\/\// }
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow remote or dynamically-evaluated code, per the MV3 CSP',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        defaultOptions: [{
+            patterns: ['eval', 'new-function', 'string-timer',
+                'dynamic-import', 'remote-script-src', 'execute-script-url'],
+            checkExecuteScriptClosures: true
+        }],
+        schema: [{
+            type: 'object',
+            properties: {
+                patterns: {
+                    type: 'array',
+                    items: { enum: remoteCodePatterns },
+                    description: 'Detection paths to enable'
+                },
+                checkExecuteScriptClosures: {
+                    type: 'boolean',
+                    description: 'Flag chrome.scripting.executeScript calls whose func captures outer scope'
+                }
+            },
+            additionalProperties: false
+        }],
+        messages: {
+            eval: '`eval()` is forbidden by the MV3 CSP.',
+            newFunction: '`new Function()` is forbidden by the MV3 CSP.',
+            stringTimer: 'String-argument `{{fn}}` is forbidden by the MV3 CSP - pass a function reference.',
+            dynamicImport: 'Remote dynamic `import()` is forbidden by the MV3 CSP.',
+            remoteScriptSrc: 'Injecting remote `<script src>` is forbidden by the MV3 CSP - use `chrome.runtime.getURL()`.',
+            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`.'
+        }
+    },
+
+    create(context) {
+        const opts = context.options[0] || {},
+              patterns = new Set(opts.patterns || remoteCodePatterns),
+              checkClosures = opts.checkExecuteScriptClosures !== false,
+              scriptElems = new Set()
+        function isLiteralUrl(node) {
+            return node?.type == 'Literal'
+                && typeof node.value == 'string'
+                && re.url.test(node.value)
+        }
+        function isCreateScript(node) {
+            return node?.type == 'CallExpression'
+                && node.callee?.property?.name == 'createElement'
+                && node.arguments[0]?.value == 'script'
+        }
+        function isObjectAssign(node) {
+            return node?.type == 'CallExpression'
+                && node.callee?.type == 'MemberExpression'
+                && node.callee.object?.name == 'Object'
+                && node.callee.property?.name == 'assign'
+        }
+        function isScriptSrcAssignment(left, right) {
+            if (left.type != 'MemberExpression') return false
+            if (left.property?.name != 'src') return false
+            if (!isLiteralUrl(right)) return false
+            if (isCreateScript(left.object)) return true
+            if (left.object.type == 'Identifier' && scriptElems.has(left.object.name)) return true
+            return false
+        }
+        function isScriptSrcProperty(node) {
+            const obj = node.parent
+            if (obj?.type != 'ObjectExpression') return false
+            const parent = obj.parent
+            if (isCreateScript(parent)) return true
+            if (isObjectAssign(parent) && isCreateScript(parent.arguments[0])) return true
+            return false
+        }
+        return {
+            VariableDeclarator(node) {
+                if (isCreateScript(node.init) && node.id.type == 'Identifier')
+                    scriptElems.add(node.id.name)
+            },
+            ImportExpression(node) {
+                if (!patterns.has('dynamic-import')) return
+                if (isLiteralUrl(node.source))
+                    context.report({ node, messageId: 'dynamicImport' })
+            },
+            CallExpression(node) {
+                if (patterns.has('eval')
+                    && node.callee.type == 'Identifier'
+                    && node.callee.name == 'eval'
+                ) context.report({ node, messageId: 'eval' })
+                if (patterns.has('string-timer')
+                    && node.callee.type == 'Identifier'
+                    && ['setTimeout', 'setInterval'].includes(node.callee.name)
+                    && node.arguments[0]?.type == 'Literal'
+                    && typeof node.arguments[0].value == 'string'
+                ) context.report({ node, messageId: 'stringTimer', data: { fn: node.callee.name }})
+                if (patterns.has('dynamic-import')
+                    && node.callee.type == 'Import'
+                    && isLiteralUrl(node.arguments[0])
+                ) context.report({ node, messageId: 'dynamicImport' })
+                if (node.callee.type == 'MemberExpression') {
+                    const path = getMemberPath(node.callee)
+                    if (path == 'chrome.scripting.executeScript') {
+                        const optsNode = node.arguments[0]
+                        if (optsNode?.type != 'ObjectExpression') return
+                        const urlProp = optsNode.properties.find(prop => prop.key?.name == 'url'),
+                              funcProp = optsNode.properties.find(prop => prop.key?.name == 'func'),
+                              argsProp = optsNode.properties.find(prop => prop.key?.name == 'args')
+                        if (patterns.has('execute-script-url') && urlProp)
+                            context.report({ node: urlProp, messageId: 'executeScriptURL' })
+                        if (checkClosures && funcProp && !argsProp)
+                            context.report({ node: funcProp, messageId: 'executeScriptClosure' })
+                    }
+                }
+            },
+            NewExpression(node) {
+                if (patterns.has('new-function') && node.callee.name == 'Function')
+                    context.report({ node, messageId: 'newFunction' })
+            },
+            AssignmentExpression(node) {
+                if (!patterns.has('remote-script-src')) return
+                if (isScriptSrcAssignment(node.left, node.right))
+                    context.report({ node: node.right, messageId: 'remoteScriptSrc' })
+            },
+            Property(node) {
+                if (!patterns.has('remote-script-src')
+                    || node.key?.name != 'src'
+                    || !isLiteralUrl(node.value)
+                    || !isScriptSrcProperty(node)
+                ) return
+                context.report({ node: node.value, messageId: 'remoteScriptSrc' })
+            }
+        }
+    }
+}

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

@@ -0,0 +1,39 @@
+import { apiPermissionMap } from '../data/apis.js'
+import { readManifest, getChromeAPIcalls } from '../utils.js'
+
+const mappedPermissions = new Set(apiPermissionMap.values())
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Flag manifest permissions whose APIs are never used in this file',
+            category: 'Best Practices',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            unusedPermission: 'Permission "{{permission}}" is declared but its APIs are never used.'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest) return {}
+        return {
+            'Program:exit'() {
+                const declared = manifest.permissions || [] ; if (!declared.length) return
+                const calls = getChromeAPIcalls(context.sourceCode)
+                const used = new Set()
+                for (const api of calls)
+                    for (const [prefix, permission] of apiPermissionMap)
+                        if (api == prefix || api.startsWith(`${prefix}.`)) { used.add(permission) ; break }
+                for (const permission of declared) {
+                    if (!mappedPermissions.has(permission)) continue
+                    if (used.has(permission)) continue
+                    context.report({ loc: { line: 1, column: 0 },
+                        messageId: 'unusedPermission', data: { permission }})
+                }
+            }
+        }
+    }
+}

package/src/rules/require-mv3.js

@@ -0,0 +1,21 @@
+import { readManifest } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require manifest_version 3',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            notMV3: 'manifest.json must declare `"manifest_version": 3` (MV2 rejected by the Chrome Web Store).'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest || manifest.manifest_version == 3) return {}
+        return { Program(node) { context.report({ node, messageId: 'notMV3' }) }}
+    }
+}

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

@@ -0,0 +1,44 @@
+import { mv2OnlyKeys, forbiddenCSPDirectives } from '../data/manifest.js'
+import { readManifest } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Validate manifest against the MV3 schema',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            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.'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest || manifest.manifest_version != 3) return {}
+        return {
+            Program(node) {
+                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' }})
+                if (manifest.background?.persistent != null)
+                    context.report({ node, messageId: 'mv2Key',
+                        data: { key: 'background.persistent', reason: 'MV3 service workers are never persistent' }})
+                const csp = manifest.content_security_policy
+                if (csp != null && typeof csp == 'string')
+                    context.report({ node, messageId: 'wrongCSPType' })
+                const cspPages = csp?.extension_pages
+                if (typeof cspPages == 'string')
+                    for (const directive of forbiddenCSPDirectives)
+                        if (cspPages.includes(directive))
+                            context.report({ node, messageId: 'unsafeCSP', data: { directive }})
+            }
+        }
+    }
+}

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

@@ -0,0 +1,43 @@
+import { domGlobals, serviceWorkerKeepaliveMinMS } from '../data/manifest.js'
+import { readManifest, isServiceWorkerFile, isInsideNestedFunction } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce valid service worker lifecycle and isolation',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        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.',
+            domInSW: '`{{global}}` is not available in a service worker.'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest || !isServiceWorkerFile(context, manifest)) return {}
+        return {
+            CallExpression(node) {
+                if (node.callee.type == 'MemberExpression'
+                    && node.callee.property.name == 'addListener'
+                    && isInsideNestedFunction(node)
+                ) context.report({ node, messageId: 'listenerNotTopLevel' })
+                if (node.callee.type == 'Identifier'
+                    && ['setTimeout', 'setInterval'].includes(node.callee.name)
+                    && node.arguments[1]?.type == 'Literal'
+                    && typeof node.arguments[1].value == 'number'
+                    && node.arguments[1].value < serviceWorkerKeepaliveMinMS
+                ) 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 }})
+            }
+        }
+    }
+}

package/src/utils.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const re = { chromeAPI: /\bchrome(?:\.\w+)+/g }, // eslint-disable-line security/detect-unsafe-regex
+      manifestCache = new Map()
+
+export function findExtensionRoot(context) {
+    let dir = path.dirname(getFilename(context))
+    const root = path.parse(dir).root
+    while (dir != root) {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        if (fs.existsSync(path.join(dir, 'manifest.json'))) return dir
+        dir = path.dirname(dir)
+    }
+    return null
+}
+
+export function getChromeAPIcalls(sourceCode) {
+    const calls = new Set()
+    for (const match of sourceCode.getText().matchAll(re.chromeAPI))
+        calls.add(match[0])
+    return calls
+}
+
+export function getFilename(context) { return context.filename || context.getFilename() }
+
+export function getMemberPath(node) {
+    const parts = []
+    let cur = node
+    while (cur?.type == 'MemberExpression') {
+        if (cur.computed || cur.property.type != 'Identifier') return null
+        parts.unshift(cur.property.name)
+        cur = cur.object
+    }
+    if (cur?.type != 'Identifier') return null
+    parts.unshift(cur.name)
+    return parts.join('.')
+}
+
+export function isContentScriptFile(context, manifest) {
+    const scripts = (manifest?.content_scripts || []).flatMap(cs => cs.js || [])
+    if (!scripts.length) return false
+    const root = findExtensionRoot(context)
+    if (!root) return false
+    const filename = path.resolve(getFilename(context))
+    return scripts.some(s => filename == path.resolve(root, s))
+}
+
+export function isInsideNestedFunction(node) {
+    let cur = node.parent
+    while (cur) {
+        if (['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(cur.type))
+            return true
+        cur = cur.parent
+    }
+    return false
+}
+
+export function isServiceWorkerFile(context, manifest) {
+    const sw = manifest?.background?.service_worker
+    if (!sw) return false
+    const root = findExtensionRoot(context)
+    if (!root) return false
+    return path.resolve(getFilename(context)) == path.resolve(root, sw)
+}
+
+export function readManifest(context) {
+    const root = findExtensionRoot(context)
+    if (!root) return null
+    if (manifestCache.has(root)) return manifestCache.get(root)
+    let parsed
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        parsed = JSON.parse(fs.readFileSync(path.join(root, 'manifest.json'), 'utf8'))
+    } catch { parsed = null }
+    manifestCache.set(root, parsed)
+    return parsed
+}