--- name: browser-extension-requirements description: >- User permissions model, store policies (Chrome Web Store, AMO), accessibility requirements, and performance budgets for browser extensions topics: - browser-extension - requirements - permissions - store-policies - accessibility - performance volatility: evolving last-reviewed: 2026-06-05 version-pin: Manifest V3 sources: - url: https://developer.chrome.com/docs/webstore/program-policies hash: sha256:b920f88cdb7ee59c5e91d45357680c06a781db04bdfc72aa242e3dde71862838 retrieved: 2026-06-05 - url: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/AMO/Policy hash: sha256:9791bbdf9ed9ecd0f0b6b8478bda286ab4fce4c7544a0100186b5fa28988daa1 retrieved: 2026-06-05 --- Browser extension requirements differ fundamentally from web app requirements because the extension operates inside a user's browser with elevated trust and broad access to browsing data. Every permission requested must be justified, every store policy must be understood before writing code, and performance budgets must be set early because extensions run on every page a user visits — regressions directly degrade the entire browsing experience. ## Summary Browser extension requirements center on four domains: permissions (request only what the feature requires, justify each in the store listing), store policies (Chrome Web Store and AMO have distinct review timelines and policy sets that affect architecture decisions), accessibility (popup UIs must meet WCAG 2.1 AA, keyboard-only operation is mandatory), and performance budgets (content scripts add parse time to every page load, service workers must stay under memory limits). Lock these down before implementation to avoid costly store rejections or permission refactors. ## Deep Guidance ### User Permissions Model The permissions model is the most consequential requirement decision. Every permission granted to an extension represents a promise to the user and a liability in the store review process. **Permission categories in Manifest V3:** - `permissions` — Declared API access that is always active (e.g., `storage`, `tabs`, `alarms`, `contextMenus`). Granted at install time with no per-use prompt. - `host_permissions` — Access to specific origins or all origins (``). Triggers a prominent install-time warning. In MV3, these can be made optional via `optional_host_permissions`. - `optional_permissions` — APIs requested at runtime via `chrome.permissions.request()`. Prefer optional for features that not all users need. **Principle of least privilege — apply strictly:** - Never request `` if you only need `https://api.example.com/*`. Broad host permissions trigger stricter review and user concern. - Request `tabs` only if you need tab URL, title, or favicon. If you only need the active tab's content, use `activeTab` instead — it requires no persistent permission and is granted only on explicit user gesture. - Audit permissions on every sprint. Remove any permission no longer used by shipping features. **Sensitive permissions that trigger enhanced review:** - `webRequest` / `declarativeNetRequest` — Modifying network requests is the highest-scrutiny permission. Justify it explicitly in your store listing. - `history` — Access to browsing history requires strong justification. - `cookies` — Access to cookies including session tokens requires explicit user-facing documentation of what data is accessed and why. - `nativeMessaging` — Communicates with native applications; triggers manual review on CWS. **Communicating permissions to users:** - Write a clear Privacy Policy linked in the store listing before submission. Extensions that access user data without a privacy policy are rejected. - The store listing description must explain every permission in plain language. "This extension requires access to all websites to block ads" is better than silence. ### Chrome Web Store Policies The Chrome Web Store (CWS) review process is automated for most submissions but involves manual review for sensitive permissions or policy violations. **Key policies affecting architecture:** - **Single purpose policy**: An extension must have a single, clearly described purpose. A "productivity suite" that does 10 unrelated things will be rejected. Define the purpose before writing code. - **No remote code execution**: Extensions cannot load and execute remote JavaScript. All logic must be bundled at submission time. This directly prohibits `eval()`, `new Function()`, and dynamic `