# Chrome MV3 permissions, honestly: activeTab, optional permissions, and the update that disables your extension


# Chrome MV3 permissions, honestly: activeTab, optional permissions, and the update that disables your extension

*Not legal advice. Mechanics come from developer.chrome.com (Declare permissions, Permission warning guidelines, activeTab, permissions API) and the Chrome Web Store "Use of Permissions" policy, archived 2026-10-15 (Asia/Shanghai). Chrome changes; re-read the pages before you ship. This article links none of our products.*

A privacy policy and the Privacy practices tab describe what you do with data. The manifest decides what you **can** reach. If the two disagree, users find out at install time, and reviewers find out sooner. This piece is about getting the manifest right and describing it truthfully.

## 1) Lead answer

1. **Ask for the narrowest permission that works.** The policy says that if more than one permission could implement a feature, you must request the one with the least access, and you must not "future proof" by requesting permissions for features you haven't built.
2. **`activeTab` shows no install warning.** It grants temporary access to the current tab only after a user gesture (action click, context-menu item, keyboard command, omnibox suggestion). Access lasts while the user stays on that origin and ends when they navigate away or close the tab. It never covers `chrome://` pages.
3. **Optional permissions are granted at runtime**, via `permissions.request()` called **inside a user gesture**. That lets you explain why at the moment the user turns the feature on.
4. **Adding a required permission that has a warning disables your extension for existing users** until they accept it. Adding an *optional* permission does not.
5. **Some permissions cannot be optional:** `debugger`, `declarativeNetRequest`, `devtools`, `geolocation`, `mdns`, `proxy`, `tts`, `ttsEngine`, `wallpaper` (ChromeOS). If you need one, it has to be in `permissions` from day one, or added later at the cost of an update prompt.

## 2) The five manifest keys

| Key | Granted | Warning? |
|---|---|---|
| `permissions` | At install | Changes may trigger a warning |
| `optional_permissions` | At runtime, by the user | Prompt when requested |
| `host_permissions` | At install | Changes may trigger a warning |
| `optional_host_permissions` | At runtime | Prompt when requested |
| `content_scripts.matches` | At install | Changes may trigger a warning |

Host permissions cover more than injection: `fetch()` from the service worker, reading tab `url`/`title`/`favIconUrl`, `webRequest`, `cookies`, and `declarativeNetRequest` header changes. Make sure your listing does not say "we only touch the page you click" when `host_permissions` says `https://*/*`.

Warnings can hide each other. The `tabs` warning does not show if you also request `<all_urls>`. A short warning list is not evidence of narrow access, so don't write listing copy based on what the dialog happened to show.

## 3) Pick the mechanism per feature

| Feature runs… | Use | What you can honestly say |
|---|---|---|
| Only when the user clicks / uses a shortcut on the current page | `activeTab` (+ `scripting` if injecting) | "Reads the current page only when you click the button." |
| On specific sites the user opts into later | `optional_host_permissions` + `permissions.request()` | "Asks for access to a site when you enable it for that site." |
| Hosts discovered at runtime | `"https://*/*"` in `optional_host_permissions`, request specific origins | Same as above. Don't claim "all sites" if you only request on demand |
| Always, on fixed sites, in the background | `host_permissions` with exact patterns | List those domains by name |
| One of the non-optional APIs | `permissions` | Say it plainly and explain why |

Docs-confirmed trade-off: required permissions mean fewer prompts and guaranteed presence; optional permissions mean less standing access, a just-in-time explanation, and upgrades that don't disable the extension.

## 4) The update trap

The Permission warning guidelines say this directly: when an update adds a permission that triggers a warning, Chrome **disables the extension until the user accepts** the new permission. For a paid or licensed extension, that means active users may suddenly find the tool off, and every one of them has to say yes again.

Before shipping an update that touches permissions:

- [ ] Diff `permissions`, `host_permissions`, and `content_scripts.matches` against the live version. All three can trigger the warning.
- [ ] Ask whether the new capability can be **optional** instead. An upgrade that only adds optional permissions does not disable the extension.
- [ ] Test the upgrade path with Google's Extension Update Testing Tool, or pack it manually with the **same .pem** and update over the old install. You'll see the exact prompt users will see.
- [ ] Write the changelog line *before* release: what new access, and why.
- [ ] Remove permissions you no longer use (`permissions.remove()`). Note: re-requesting a removed permission "usually" re-adds it **without** a prompt, so don't tell users that removal forces a fresh consent.

How long a disabled extension stays disabled, and whether Chrome re-prompts users who ignore the banner: **Not verified**.

## 5) Listing and onboarding language

Say:
- "Works on the tab you're viewing, only when you click the icon" (true for `activeTab`).
- "Optional: grant access to example.com to enable auto-fill there" (true for optional host permissions).
- "Needs `proxy` permission at install because it routes traffic. Chrome won't let this be optional."

Don't say:
- "No permissions required" when the install dialog shows any warning.
- "Only reads the current page" alongside `<all_urls>` in `host_permissions`.
- "We'll never ask for more access" (you can't promise future manifests).
- "Works in incognito / on local files" without telling users to turn it on themselves on the extension's details page. Both need a user toggle, and you can check them with `extension.isAllowedIncognitoAccess()` / `isAllowedFileSchemeAccess()`.

## 6) Self-check before you submit

- [ ] Every entry in `permissions`/`host_permissions` maps to a shipped feature (no future-proofing).
- [ ] Every click-triggered page feature tried `activeTab` first.
- [ ] Every non-core feature uses optional permissions, requested inside a click handler.
- [ ] Non-optional APIs are listed and justified in plain words.
- [ ] Listing copy matches the broadest access in the manifest, not the shortest warning list.
- [ ] The upgrade prompt was tested with the same signing key.
- [ ] The exact current warning text for each permission was checked against the Permissions reference. **Not verified** here.

## Not verified

- Exact current warning strings per permission in Chrome stable.
- Whether adding only optional permissions changes Chrome Web Store review time.
- Whether users who ignore the "new permissions" prompt are re-prompted automatically.