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.
Medium because undocumented permissions slow review and increase rejection risk when reviewers cannot verify each permission is necessary.
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.
ID: extension-store-readiness.review-prep.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)