storecheck
v0.1.0
Published
Chrome Web Store compliance linter for browser extensions. Catch what gets your submission rejected, before you submit.
Maintainers
Readme
storecheck
A Chrome Web Store compliance linter for browser extensions. Point it at an unpacked extension directory or the .zip you are about to upload, and it tells you what will get the submission rejected, before you submit.
storecheck ./distWhy this exists
mozilla/addons-linter is excellent, and it validates against AMO policy. It happily passes extensions that Google rejects, because Google enforces a different and largely unwritten set of rules: excessive permissions, remotely hosted code, obfuscation, listing metadata quality, privacy disclosure.
There is no open-source Chrome-side equivalent. storecheck is that, plus a corpus of the real rejection codes Google sends and what actually fixes them.
Every rule cites the Chrome Web Store program policy or developer documentation it enforces. Where a rule is a heuristic rather than a documented hard limit, it is a warning and the metadata says so.
Install
npm install --save-dev storecheck
npx storecheck ./distOr globally:
npm install -g storecheckRequires Node 20.11 or newer.
Usage
storecheck <path-to-extension-or-zip> [options]
--json Emit machine-readable JSON instead of a terminal report.
--severity=<level> Minimum severity to report: error | warning | info.
--rule=<id> Run only this rule. Repeatable.
--list-rules Print every registered rule and exit.
--quiet Suppress the report; rely on the exit code only.
-h, --help Show this help.
-v, --version Print the version.
Exit codes
0 no findings at or above "error"
1 at least one error-severity finding, or a rule failed to run
2 bad usage, or the package could not be readIt accepts an unpacked directory or a .zip. If your zip wraps everything in a single folder, storecheck finds the real root and lints that.
Real output
This repository ships a deliberately non-compliant extension at examples/needs-work. Clone the repo, run npm install && npm run build, and you get exactly this:
$ storecheck examples/needs-work
storecheck examples/needs-work (directory, 3 files, 24 rules)
ERROR (5)
* content_security_policy.extension_pages allows "script-src https://cdn.example.com", a source outside the package. Manifest V3 requires script to be bundled with the extension; the only sources accepted on extension pages are 'self' and 'none'.
csp/remote-script-source | manifest.json | Blue Argon
https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements
* content_security_policy.extension_pages relaxes "script-src" with 'unsafe-eval'. Manifest V3 does not permit it on extension pages, so the item is rejected at upload. Remove the string-to-code paths that need it, or move that work into a sandboxed page.
csp/unsafe-eval | manifest.json | Blue Argon
https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements
* "icons.128" points at "icon128.png", which is not in the package. The feature it backs will be dead on arrival during review.
manifest/missing-referenced-files | manifest.json | Yellow Magnesium
https://developer.chrome.com/docs/webstore/troubleshooting
* eval( - eval() executes a string as code. Manifest V3 requires that the full functionality of an extension be discernible from the submitted code, so remotely sourced logic is not allowed.
privacy/remote-code-execution | background.js:6 | Blue Argon
https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements
* <script src="https://cdn.example.com/analytics.js"> loads code that is not in the package. Manifest V3 forbids remotely hosted code; vendor the file into the extension and reference it with a relative path.
privacy/remote-script-tag | popup.html:4 | Blue Argon
https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements
WARNING (8)
* "description" repeats "screenshot" 6 times. Repeating the same keyword more than 5 times reads as keyword stuffing and is grounds for rejection. Write the field for a human.
listing/keyword-stuffing | manifest.json | Yellow Argon
https://developer.chrome.com/docs/webstore/program-policies/listing-requirements
* "name" is a 65-character list of 7 comma- or pipe-separated terms. Listing search terms in the title is keyword stuffing; use a real product name.
listing/keyword-stuffing | manifest.json | Yellow Argon
https://developer.chrome.com/docs/webstore/program-policies/listing-requirements
* host_permissions[0]: "<all_urls>" grants access to every site the user visits. Reviewers require the narrowest permissions that make the extension work. Either list the specific hosts you need, or move to "activeTab" plus optional host permissions requested at the moment of use.
permissions/broad-host-permissions | manifest.json | Purple Potassium
https://developer.chrome.com/docs/webstore/program-policies/permissions
* "debugger" attaches to the DevTools protocol and can read and modify anything on any page. This is a permission reviewers scrutinise by hand. Make sure your store description and single purpose statement explain why the extension cannot work without it.
permissions/high-risk-permissions | manifest.json | Purple Potassium
https://developer.chrome.com/docs/webstore/program-policies/permissions
* "bookmarks" is declared but "chrome.bookmarks" is never referenced in the packaged code. Remove permissions you do not use; every unused one widens the install warning and invites an excessive-permissions review.
permissions/unused-declared-permissions | manifest.json | Purple Potassium
https://developer.chrome.com/docs/webstore/program-policies/permissions
* "debugger" is declared but "chrome.debugger" is never referenced in the packaged code. Remove permissions you do not use; every unused one widens the install warning and invites an excessive-permissions review.
permissions/unused-declared-permissions | manifest.json | Purple Potassium
https://developer.chrome.com/docs/webstore/program-policies/permissions
* Google Analytics telemetry endpoint referenced. The package contains no privacy or data-usage document. Collecting analytics without a prominent disclosure and a matching privacy policy is a user data policy violation.
privacy/analytics-without-disclosure | background.js:8 | Purple Nickel, Purple Lithium
https://developer.chrome.com/docs/webstore/program-policies/disclosure-requirements
* This extension handles user data ("bookmarks" reads the bookmark tree) but the package contains no privacy policy or link to one. Any item that handles user data must post an accurate privacy policy and enter its URL in the Developer Dashboard. storecheck cannot read your dashboard, so confirm the URL is filled in even if you dismiss this finding.
privacy/missing-privacy-policy | manifest.json | Purple Lithium
https://developer.chrome.com/docs/webstore/program-policies/privacy
Summary 5 errors, 8 warnings
$ echo $?
1A clean package says so and exits 0:
$ storecheck rules/manifest/manifest-v2/fixtures/pass/base
storecheck rules/manifest/manifest-v2/fixtures/pass/base (directory, 3 files, 24 rules)
No findings. Nothing here will get you an automatic rejection.
A clean run is not an approval. Reviewers also judge your listing copy, screenshots and privacy disclosures.JSON output
$ storecheck ./dist --json --severity=error{
"version": 1,
"source": { "origin": "./dist", "kind": "directory", "fileCount": 24, "manifestVersion": 3 },
"rulesRun": 24,
"summary": { "total": 1, "errors": 1, "warnings": 0, "info": 0 },
"findings": [
{
"message": "manifest.json declares no \"icons\". An item missing an icon is rejected on submission; ship at least a 128x128 PNG.",
"file": "manifest.json",
"ruleId": "manifest/missing-icons",
"category": "manifest",
"title": "Item must ship a 128x128 icon for the store listing",
"severity": "error",
"policyRef": "https://developer.chrome.com/docs/webstore/program-policies/listing-requirements",
"rejectionCodes": ["Yellow Zinc"]
}
],
"ruleErrors": []
}In CI
- run: npx storecheck ./dist --severity=errorThat fails the build on anything that would be rejected outright, while leaving warnings for a human to weigh.
Rules
24 rules across 6 categories. This table is generated by npm run docs.
| Rule | Severity | Rejection codes |
| --- | --- | --- |
| code/minified-without-source | warning | Red Titanium |
| code/obfuscated-code | error | Red Titanium |
| csp/remote-script-source | error | Blue Argon |
| csp/unsafe-eval | error | Blue Argon |
| csp/unsafe-inline | warning | Blue Argon, Yellow Magnesium |
| listing/icon-dimensions | error | Yellow Zinc |
| listing/keyword-stuffing | warning | Yellow Argon |
| listing/store-asset-dimensions | warning | Yellow Zinc |
| manifest/description-length | error | Yellow Zinc |
| manifest/manifest-v2 | error | - |
| manifest/missing-description | error | Yellow Zinc |
| manifest/missing-icons | error | Yellow Zinc |
| manifest/missing-referenced-files | error | Yellow Magnesium |
| manifest/name-length | error | Yellow Zinc |
| manifest/short-description-quality | warning | Yellow Zinc |
| manifest/version-format | error | - |
| permissions/broad-host-permissions | warning | Purple Potassium |
| permissions/high-risk-permissions | warning | Purple Potassium |
| permissions/unused-declared-permissions | warning | Purple Potassium |
| permissions/wildcard-content-script-matches | warning | Purple Potassium |
| privacy/analytics-without-disclosure | warning | Purple Nickel, Purple Lithium |
| privacy/missing-privacy-policy | warning | Purple Lithium |
| privacy/remote-code-execution | error | Blue Argon |
| privacy/remote-script-tag | error | Blue Argon |
Full rationale and policy citation for each rule: docs/RULES.md.
Adding a rule
Adding a rule means adding one directory. No core file is edited, and no registry is updated: the loader discovers rules/<category>/<rule-id>/ from disk, and a single contract test picks it up automatically.
npm run new-rule -- permissions/no-clipboard-readThat scaffolds the directory, including a valid sample extension to use as your pass fixture. Then write the check:
// rules/permissions/no-clipboard-read/rule.ts
import type { Rule } from '../../../src/types.js';
export const rule: Rule = {
check(ctx) {
if (ctx.manifest.permissions?.includes('clipboardRead')) {
ctx.report({
message: '"clipboardRead" exposes everything the user has ever copied, including passwords.',
file: 'manifest.json',
});
}
},
};Edit fixtures/fail/violation/manifest.json so it actually violates the rule, fill in meta.yaml with a real policy URL, and run npm test. That is the whole contribution.
See CONTRIBUTING.md for the 15-minute walkthrough.
Why the architecture looks like this
The contract test does three things for every rule it discovers:
- Validates
meta.yamlagainst a schema, including that anyerror-severity rule cites a policy URL. - Asserts the rule flags every
fail/fixture and stays silent on everypass/fixture. - Asserts the rule stays silent on the shared corpus of every other rule's
pass/fixtures.
Point 3 is the important one. It is the false-positive guard, and it is what makes reviewing a contributed rule cheap: if somebody's regex is too greedy, it lights up against another rule's valid extension and CI fails with the exact fixture that broke.
The rejection corpus
rejections/ documents the violation codes Google actually sends, one file per code: what it means, what triggers it, how to fix it, and which storecheck rules relate to it.
The seed content comes only from Google's published documentation, and every file cites its sources. No rejection emails or user stories in this repository are invented.
The genuinely valuable material can only come from developers who have been through a rejection. Every file has a template section inviting a redacted, real case. If you have one, please file a rejection report.
What storecheck cannot do
Being honest about the boundary matters more than an impressive rule count:
- It cannot see your Developer Dashboard. Your privacy policy URL, data-use declarations, screenshots and store description live there, not in the package. Rules that depend on them can only look for signals in the package and remind you to check.
- It cannot judge intent. Single purpose, deceptive behaviour and most of the
GreyandRedcodes are human judgements about what your extension is for. - It does not execute your extension. Everything here is static analysis of the shipped files.
- A clean run is not an approval. It means nothing in the package trips a known, mechanically detectable rejection trigger.
Where a rule is a heuristic, it is a warning, never an error, and the schema enforces that an error rule must cite a policy URL.
Contributing
Rules, rejection reports, and corrections to the policy citations are all welcome. Start with docs/GOOD-FIRST-ISSUES.md, which lists concrete rules that are ready to be implemented.
See CONTRIBUTING.md and CODE_OF_CONDUCT.md.
Development
npm install
npm test # contract tests across every rule
npm run build # tsc + copy rule metadata into dist
npm run lint
npm run docs # regenerate docs/RULES.md and the table aboveLicense
MIT. See LICENSE.
Built and maintained by Duskel. We build production Chrome extensions, and we wrote this because we got tired of finding out about policy problems from a rejection email a week after submitting.
If you would rather not fight the review process yourself, talk to us.
