Permission usage explanation provided in Notes to Reviewer
Why it matters
Chrome Web Store reviewers scrutinize permissions that appear broader than the extension's stated purpose. Without documented justification for each permission, reviewers must guess whether a permission is necessary — and they default to rejection when they can't. The chrome-cws-permission-justification best practice exists precisely because extensions are regularly removed for having permissions that look suspicious but are actually legitimate. Documenting every permission also surfaces over-permissioning during development, before it becomes a rejection.
Severity rationale
Medium because undocumented permissions slow review and increase rejection risk when reviewers cannot verify each permission is necessary.
Remediation
Create a PERMISSIONS.md or add a Permissions section to your README listing every manifest permission with a one-sentence justification.
## Permissions
| Permission | Why it's needed |
|---|---|
| `tabs` | Reads open tab titles and URLs to display them in the management UI |
| `storage` | Persists tab groups and user preferences locally |
| `activeTab` | Injects the tab-action UI into the currently focused tab on user click |
| `scripting` | Executes the tab group overlay script in response to user interaction |
Verify this table matches your manifest exactly — add every permission in permissions and host_permissions. During store submission, paste a condensed version of this table into the Notes to Reviewer field.
Detection
-
ID:
permission-justification -
Severity:
medium -
What to look for: Check for documentation (README, "Notes to Reviewer" section, or a PERMISSIONS.md file) that explains each permission requested in the manifest. For each permission, there should be a brief explanation of why it's needed and how it's used.
-
Pass criteria: Count every permission in the manifest. A section exists documenting each one with its usage justification. 100% of declared permissions have a corresponding explanation. The explanations are clear and match the actual functionality. Report even on pass: "N permissions declared, N documented."
-
Fail criteria: No permission documentation found, or the documentation covers fewer than 100% of declared permissions, or the documentation is vague or doesn't match the permissions in the manifest.
-
Skip (N/A) when: Never — permission justification is part of Chrome Web Store submission best practices.
-
Detail on fail:
"No permission documentation found. Manifest has 8 permissions but no explanation of why each is needed". -
Remediation: Create a PERMISSIONS.md or add to your README:
## Permissions This extension requests the following permissions: - **tabs**: Required to read and manage your open browser tabs - **storage**: Used to store your tab groups and preferences locally - **activeTab**: Needed to inject functionality into the currently active tab - **scripting**: Allows the extension to execute scripts in web pages (for tab management UI)
External references
- external · chrome-cws-permission-justification — Chrome Web Store — Permission Justification in Developer Notes
Taxons
History
- 2026-04-18·v1.0.0·Initial import from extension-store-readiness·automated