eslint-plugin-chrome-extensions 1.0.0

package/docs/LICENSE.md

@@ -0,0 +1,9 @@
+# 🏛️ MIT License
+
+**Copyright © 2026 [Adam Lui](https://codeberg.org/adamlui).**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

package/docs/SECURITY.md

@@ -0,0 +1,3 @@
+# Security Policy
+
+If you find a vulnerability, please e-mail <security@kudoai.org>.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "eslint-plugin-chrome-extensions",
+  "version": "1.0.0",
+  "description": "ESLint rules for Chrome extensions",
+  "type": "module",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "author": {
+    "name": "Adam Lui",
+    "email": "adam@kudoai.org",
+    "url": "https://codeberg.org/adamlui"
+  },
+  "homepage": "https://codeberg.org/adamlui/eslint-plugin-chrome-extensions/#readme",
+  "bugs": {
+    "url": "https://codeberg.org/adamlui/eslint-plugin-chrome-extensions/issues",
+    "email": "support@adamlui.com"
+  },
+  "license": "MIT",
+  "funding": [
+    {
+      "type": "ko-fi",
+      "url": "https://ko-fi.com/adamlui"
+    },
+    {
+      "type": "paypal",
+      "url": "https://paypal.me/adamlui"
+    }
+  ],
+  "main": "src/index.js",
+  "files": [
+    "docs/",
+    "src/"
+  ],
+  "types": "src/index.d.ts",
+  "scripts": {
+    "prepare": "husky",
+    "lint": "eslint . --cache && yamllint .",
+    "lint:all": "eslint . && yamllint .",
+    "lint:fix": "eslint . --fix --cache && yamllint .",
+    "lint:fix-all": "eslint . --fix && yamllint .",
+    "test": "node tests/run.js",
+    "demo": "node demo/run.js",
+    "bump:patch": "bash utils/bump.sh patch",
+    "bump:minor": "bash utils/bump.sh minor",
+    "bump:feat": "npm run bump:minor",
+    "bump:major": "bash utils/bump.sh major"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/adamlui/eslint-plugin-chrome-extensions.git"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "eslintplugin",
+    "chrome-extensions",
+    "chromium"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@e18e/eslint-plugin": "^0.8.1",
+    "@eslint/js": "^10.0.1",
+    "@eslint/json": "^2.1.0",
+    "@eslint/markdown": "^8.0.3",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^10.11.0",
+    "eslint-plugin-constructors": "^1.4.0",
+    "eslint-plugin-eslint-plugin": "^7.6.2",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-n": "^18.4.0",
+    "eslint-plugin-no-secrets": "^2.3.3",
+    "eslint-plugin-no-unsanitized": "^4.1.5",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-regexp": "^3.3.1",
+    "eslint-plugin-security": "^4.2.0",
+    "husky": "^9.1.7",
+    "yamllint-js": "^0.2.4"
+  },
+  "dependencies": {
+    "globals": "^17.13.0"
+  }
+}

package/src/data/apis.js

@@ -0,0 +1,65 @@
+export const deprecatedAPIs = new Map([
+    ['chrome.pageAction.show',             'chrome.action.enable'],
+    ['chrome.pageAction.hide',             'chrome.action.disable'],
+    ['chrome.pageAction.setIcon',          'chrome.action.setIcon'],
+    ['chrome.pageAction.setTitle',         'chrome.action.setTitle'],
+    ['chrome.pageAction.setPopup',         'chrome.action.setPopup'],
+    ['chrome.pageAction.getTitle',         'chrome.action.getTitle'],
+    ['chrome.pageAction.getPopup',         'chrome.action.getPopup'],
+    ['chrome.browserAction',               'chrome.action'],
+    ['chrome.pageAction',                  'chrome.action'],
+    ['chrome.extension.getBackgroundPage', 'chrome.runtime.getContexts'],
+    ['chrome.extension.getURL',            'chrome.runtime.getURL'],
+    ['chrome.extension.sendRequest',       'chrome.runtime.sendMessage'],
+    ['chrome.extension.onRequest',         'chrome.runtime.onMessage'],
+    ['chrome.extension.onRequestExternal', 'chrome.runtime.onMessageExternal'],
+    ['chrome.extension.connect',           'chrome.runtime.connect'],
+    ['chrome.extension.onConnect',         'chrome.runtime.onConnect'],
+    ['chrome.extension.onConnectExternal', 'chrome.runtime.onConnectExternal'],
+    ['chrome.tabs.executeScript',          'chrome.scripting.executeScript'],
+    ['chrome.tabs.insertCSS',              'chrome.scripting.insertCSS'],
+    ['chrome.tabs.removeCSS',              'chrome.scripting.removeCSS']
+])
+
+export const apiPermissionMap = new Map([
+    ['chrome.alarms',                'alarms'],
+    ['chrome.bookmarks',             'bookmarks'],
+    ['chrome.browsingData',          'browsingData'],
+    ['chrome.contextMenus',          'contextMenus'],
+    ['chrome.cookies',               'cookies'],
+    ['chrome.debugger',              'debugger'],
+    ['chrome.declarativeNetRequest', 'declarativeNetRequest'],
+    ['chrome.downloads',             'downloads'],
+    ['chrome.history',               'history'],
+    ['chrome.idle',                  'idle'],
+    ['chrome.management',            'management'],
+    ['chrome.notifications',         'notifications'],
+    ['chrome.pageCapture',           'pageCapture'],
+    ['chrome.privacy',               'privacy'],
+    ['chrome.proxy',                 'proxy'],
+    ['chrome.scripting',             'scripting'],
+    ['chrome.sessions',              'sessions'],
+    ['chrome.storage',               'storage'],
+    ['chrome.tabCapture',            'tabCapture'],
+    ['chrome.topSites',              'topSites'],
+    ['chrome.webRequest',            'webRequest']
+])
+
+export const externalMessagingListeners =
+    new Set(['chrome.runtime.onMessageExternal', 'chrome.runtime.onConnectExternal'])
+
+export function findDeprecated(api) {
+    for (const [deprecated, replacement] of deprecatedAPIs)
+        if (api == deprecated || api.startsWith(`${deprecated}.`))
+            return { deprecated, replacement }
+    return null
+}
+
+export function findPermission(api) {
+    for (const [prefix, permission] of apiPermissionMap)
+        if (api == prefix || api.startsWith(`${prefix}.`))
+            return permission
+    return null
+}
+
+export function isExternalMessagingListener(api) { return externalMessagingListeners.has(api) }

package/src/data/manifest.js

@@ -0,0 +1,13 @@
+import globals from 'globals'
+
+export const mv2OnlyKeys = new Set(['browser_action', 'page_action'])
+export const forbiddenCSPDirectives = [
+    `'unsafe-eval'`, `'unsafe-inline'`, `'unsafe-hashes'`, `'wasm-unsafe-eval'`, 'http://', 'https://']
+
+export const serviceWorkerKeepaliveMinMS = 30000
+
+const serviceWorkerGlobals = new Set(Object.keys(globals.serviceworker || {}))
+export const domGlobals = new Set(Object.keys(globals.browser).filter(name => !serviceWorkerGlobals.has(name)))
+
+export const remoteCodePatterns = [
+    'eval', 'new-function', 'string-timer', 'dynamic-import', 'remote-script-src', 'execute-script-url']

package/src/data/permissions.js

@@ -0,0 +1,31 @@
+const re = { url: /^https?:\/\// }
+
+export const sensitivePermissions = new Set([
+    'accessibilityFeatures.modify', 'accessibilityFeatures.read', 'bookmarks', 'browsingData', 'clipboardRead',
+    'contentSettings', 'cookies', 'debugger', 'declarativeNetRequest', 'downloads', 'downloads.open', 'downloads.ui',
+    'geolocation', 'history', 'management', 'nativeMessaging', 'pageCapture', 'privacy', 'proxy', 'readingList',
+    'sessions', 'system.storage', 'tabCapture', 'tabGroups', 'tabs', 'topSites', 'ttsEngine',
+    'webAuthenticationProxy', 'webNavigation', 'webRequest', 'webRequestBlocking'
+])
+
+export const validPermissions = new Set([
+    'accessibilityFeatures.modify', 'accessibilityFeatures.read', 'activeTab', 'alarms', 'audio', 'background',
+    'bookmarks', 'browsingData', 'certificateProvider', 'clipboardRead', 'clipboardWrite', 'contentSettings',
+    'contextMenus', 'cookies', 'debugger', 'declarativeContent', 'declarativeNetRequest',
+    'declarativeNetRequestFeedback', 'declarativeNetRequestWithHostAccess', 'desktopCapture', 'dns', 'documentScan',
+    'downloads', 'downloads.open', 'downloads.ui', 'enterprise.deviceAttributes', 'enterprise.hardwarePlatform',
+    'enterprise.networkingAttributes', 'enterprise.platformKeys', 'favicon', 'fileBrowserHandler',
+    'fileSystemProvider', 'fontSettings', 'gcm', 'geolocation', 'history', 'identity', 'identity.email', 'idle',
+    'loginState', 'management', 'nativeMessaging', 'notifications', 'offscreen', 'pageCapture', 'platformKeys',
+    'power', 'printerProvider', 'printing', 'printingMetrics', 'privacy', 'processes', 'proxy', 'publicSuffix',
+    'readingList', 'runtime', 'scripting', 'search', 'sessions', 'sidePanel', 'storage', 'system.cpu',
+    'system.display', 'system.memory', 'system.storage', 'tabCapture', 'tabGroups', 'tabs', 'topSites', 'tts',
+    'ttsEngine', 'unlimitedStorage', 'userScripts', 'vpnProvider', 'wallpaper', 'webAuthenticationProxy',
+    'webNavigation', 'webRequest', 'webRequestBlocking'
+])
+
+export function isValidPermission(name, target = 'mv3') {
+    if (validPermissions.has(name)) return true
+    if (target == 'mv3') return false
+    return re.url.test(name) || name.startsWith('<') || name == '*://*/*'
+}

package/src/index.js

@@ -0,0 +1,58 @@
+import noContentStyleLeak from './rules/no-content-style-leak.js'
+import noDeprecatedAPIs from './rules/no-deprecated-apis.js'
+import noInsecureMessaging from './rules/no-insecure-messaging.js'
+import noInvalidPermissions from './rules/no-invalid-permissions.js'
+import noMissingPermissions from './rules/no-missing-permissions.js'
+import noRemoteCode from './rules/no-remote-code.js'
+import noUnusedPermissions from './rules/no-unused-permissions.js'
+import requireMV3 from './rules/require-mv3.js'
+import validMV3schema from './rules/valid-mv3-schema.js'
+import validServiceWorker from './rules/valid-service-worker.js'
+
+const plugin = {
+    rules: {
+        'require-mv3': requireMV3,
+        'valid-mv3-schema': validMV3schema,
+        'no-deprecated-apis': noDeprecatedAPIs,
+        'no-remote-code': noRemoteCode,
+        'valid-service-worker': validServiceWorker,
+        'no-content-style-leak': noContentStyleLeak,
+        'no-invalid-permissions': noInvalidPermissions,
+        'no-missing-permissions': noMissingPermissions,
+        'no-unused-permissions': noUnusedPermissions,
+        'no-insecure-messaging': noInsecureMessaging
+    }
+}
+
+for (const [ruleId, rule] of Object.entries(plugin.rules))
+    rule.meta.docs.url = `https://codeberg.org/adamlui/eslint-plugin-chrome-extensions/#${ruleId}`
+
+plugin.configs = {
+    recommended: {
+        plugins: { 'chrome-extensions': plugin },
+        rules: {
+            'chrome-extensions/require-mv3': 'error',
+            'chrome-extensions/valid-mv3-schema': 'error',
+            'chrome-extensions/no-deprecated-apis': 'error',
+            'chrome-extensions/no-remote-code': 'error',
+            'chrome-extensions/valid-service-worker': 'error',
+            'chrome-extensions/no-invalid-permissions': 'error',
+            'chrome-extensions/no-missing-permissions': 'error',
+            'chrome-extensions/no-unused-permissions': 'error',
+            'chrome-extensions/no-insecure-messaging': 'error'
+        }
+    },
+    strict: {
+        plugins: { 'chrome-extensions': plugin },
+        rules: Object.fromEntries(Object.keys(plugin.rules)
+            .map(ruleId => [`chrome-extensions/${ruleId}`, 'error']))
+    },
+    problem: {
+        plugins: { 'chrome-extensions': plugin },
+        rules: Object.fromEntries(Object.entries(plugin.rules)
+            .filter(([, rule]) => rule.meta.type == 'problem')
+            .map(([ruleId]) => [`chrome-extensions/${ruleId}`, 'error']))
+    }
+}
+
+export { plugin as default, plugin as chromeExtensions }

package/src/rules/no-content-style-leak.js

@@ -0,0 +1,65 @@
+import { readManifest, isContentScriptFile } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow injecting <style> into the host document from a content script',
+            category: 'Best Practices',
+            recommended: false
+        },
+        schema: [],
+        messages: {
+            styleLeak: 'Inject styles via `chrome.scripting.insertCSS()` or `content_scripts.css` instead of appending to the host document.'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest || !isContentScriptFile(context, manifest)) return {}
+        const styleElems = new Set(), docAliases = new Set()
+        function isCreateStyle(node) {
+            return node?.type == 'CallExpression'
+                && node.callee?.property?.name == 'createElement'
+                && node.arguments[0]?.value == 'style'
+        }
+        function isObjectAssign(node) {
+            return node?.type == 'CallExpression'
+                && node.callee?.type == 'MemberExpression'
+                && node.callee.object?.name == 'Object'
+                && node.callee.property?.name == 'assign'
+        }
+        function isDocumentRef(node) {
+            return node?.type == 'Identifier'
+                && (node.name == 'document' || docAliases.has(node.name))
+        }
+        function isDocumentMember(node) {
+            return node?.type == 'MemberExpression' && isDocumentRef(node.object)
+        }
+        function isStyleTarget(node) {
+            if (isCreateStyle(node)) return true
+            if (node?.type == 'Identifier' && styleElems.has(node.name)) return true
+            if (isObjectAssign(node) && isCreateStyle(node.arguments[0])) return true
+            if (isObjectAssign(node)
+                && node.arguments[0]?.type == 'Identifier'
+                && styleElems.has(node.arguments[0].name)) return true
+            return false
+        }
+        return {
+            VariableDeclarator(node) {
+                if (node.id.type != 'Identifier') return
+                if (isCreateStyle(node.init)) styleElems.add(node.id.name)
+                if (node.init?.type == 'Identifier' && isDocumentRef(node.init))
+                    docAliases.add(node.id.name)
+            },
+            CallExpression(node) {
+                if (node.callee.type != 'MemberExpression') return
+                const method = node.callee.property.name
+                if (method != 'append' && method != 'appendChild') return
+                if (!isDocumentMember(node.callee.object)) return
+                for (const arg of node.arguments)
+                    if (isStyleTarget(arg))
+                        context.report({ node: arg, messageId: 'styleLeak' })
+            }
+        }
+    }
+}

package/src/rules/no-deprecated-apis.js

@@ -0,0 +1,60 @@
+import { findDeprecated } from '../data/apis.js'
+import { getMemberPath } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow deprecated chrome.* extension API calls',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        defaultOptions: [{ target: 'mv3', allowedAPIs: [] }],
+        schema: [{
+            type: 'object',
+            properties: {
+                target: {
+                    enum: ['mv3', 'mv2'],
+                    description: 'Chrome extension platform version whose deprecations to validate against'
+                },
+                allowedAPIs: {
+                    oneOf: [
+                        { type: 'string', description: 'Single deprecated API namespace to allow' },
+                        {
+                            type: 'array',
+                            items: { type: 'string', description: 'Deprecated API namespace to allow' },
+                            description: 'List of deprecated API namespaces to allow'
+                        }
+                    ],
+                    description: 'Additional deprecated API namespaces to allow'
+                }
+            },
+            additionalProperties: false
+        }],
+        messages: {
+            deprecatedAPI: '`{{api}}` is deprecated in {{target}}. Use `{{replacement}}` instead.'
+        }
+    },
+
+    create(context) {
+        const opts = context.options[0] || {},
+              target = opts.target || 'mv3',
+              allowedAPIs = Array.isArray(opts.allowedAPIs) ? opts.allowedAPIs
+                          : opts.allowedAPIs ? [opts.allowedAPIs] : []
+        if (target != 'mv3') return {}
+        function isAllowed(api) {
+            for (const allowed of allowedAPIs)
+                if (api == allowed || api.startsWith(`${allowed}.`)) return true
+            return false
+        }
+        return {
+            MemberExpression(node) {
+                if (node.parent.type == 'MemberExpression' && node.parent.object === node) return
+                const api = getMemberPath(node) ; if (!api?.startsWith('chrome.') || isAllowed(api)) return
+                const found = findDeprecated(api) ; if (!found) return
+                context.report({ node, messageId: 'deprecatedAPI',
+                    data: { api: found.deprecated, replacement: found.replacement, target }})
+            }
+        }
+    }
+}

package/src/rules/no-insecure-messaging.js

@@ -0,0 +1,42 @@
+import { isExternalMessagingListener } from '../data/apis.js'
+import { getMemberPath } from '../utils.js'
+
+const RE_SENDER_VALIDATION = /sender\.(?:id|origin)/
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require sender validation on external messaging + filtered tab broadcasts',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            unvalidatedExternal: '`{{listener}}` handler must validate `sender.<id|origin>` before processing messages.',
+            unfilteredBroadcast: '`chrome.tabs.query({})` with no filter broadcasts to every open tab - add `url` or `currentWindow`.'
+        }
+    },
+
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (node.callee.type != 'MemberExpression') return
+                const path = getMemberPath(node.callee) ; if (!path) return
+                const listenerRoot = path.endsWith('.addListener') ? path.slice(0, -'.addListener'.length) : null
+                if (listenerRoot && isExternalMessagingListener(listenerRoot)) {
+                    const handler = node.arguments[0] ; if (!handler) return
+                    const body = context.sourceCode.getText(handler)
+                    if (!RE_SENDER_VALIDATION.test(body))
+                        context.report({ node, messageId: 'unvalidatedExternal', data: { listener: listenerRoot }})
+                }
+                if (path == 'chrome.tabs.query') {
+                    const filter = node.arguments[0],
+                          isEmpty = !filter || (filter.type == 'ObjectExpression' && !filter.properties.length)
+                    if (isEmpty)
+                        context.report({ node, messageId: 'unfilteredBroadcast' })
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,57 @@
+import { isValidPermission } from '../data/permissions.js'
+import { readManifest } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow invalid or unsupported manifest permission names',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        defaultOptions: [{ target: 'mv3', allowedPermissions: [] }],
+        schema: [{
+            type: 'object',
+            properties: {
+                target: {
+                    enum: ['mv3', 'mv2'],
+                    description: 'Chrome extension platform version whose permissions to validate against'
+                },
+                allowedPermissions: {
+                    oneOf: [
+                        { type: 'string', description: 'Single permission name to allow' },
+                        {
+                            type: 'array',
+                            items: { type: 'string', description: 'Permission name to allow' },
+                            description: 'List of permission names to allow'
+                        }
+                    ],
+                    description: 'Additional permission names to allow beyond the built-in list'
+                }
+            },
+            additionalProperties: false
+        }],
+        messages: {
+            invalidPermission: '`{{permission}}` is not a valid {{target}} permission.'
+        }
+    },
+
+    create(context) {
+        const opts = context.options[0] || {},
+              target = opts.target || 'mv3',
+              allowed = new Set(Array.isArray(opts.allowedPermissions) ? opts.allowedPermissions
+                      : opts.allowedPermissions ? [opts.allowedPermissions] : []),
+              manifest = readManifest(context)
+        if (!manifest) return {}
+        const all = [...(manifest.permissions || []), ...(manifest.optional_permissions || [])]
+        return {
+            'Program:exit'() {
+                for (const permission of all) {
+                    if (allowed.has(permission) || isValidPermission(permission, target)) continue
+                    context.report({ loc: { line: 1, column: 0 },
+                        messageId: 'invalidPermission', data: { permission, target }})
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+import { findPermission } from '../data/apis.js'
+import { readManifest, getMemberPath } from '../utils.js'
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Flag chrome.* API calls used without a matching manifest permission',
+            category: 'Possible Errors',
+            recommended: true
+        },
+        schema: [],
+        messages: {
+            missingPermission: '`{{api}}` requires the "{{permission}}" manifest permission.'
+        }
+    },
+
+    create(context) {
+        const manifest = readManifest(context) ; if (!manifest) return {}
+        const declared = new Set([...(manifest.permissions || []), ...(manifest.optional_permissions || [])])
+        return {
+            CallExpression(node) {
+                if (node.callee.type != 'MemberExpression') return
+                const api = getMemberPath(node.callee) ; if (!api) return
+                const permission = findPermission(api) ; if (!permission || declared.has(permission)) return
+                context.report({ node, messageId: 'missingPermission', data: { api, permission }})
+            }
+        }
+    }
+}