# Permission usage explanation provided in Notes to Reviewer

- **Pattern:** `ab-001356` (`extension-store-readiness.review-prep.permission-justification`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001356
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001356)

## 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.

```markdown
## 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:

  ```markdown
  ## 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 — https://developer.chrome.com/docs/webstore/program-policies/permissions/

Taxons: regulatory-conformance

HTML version: https://auditbuffet.com/patterns/ab-001356