Skip to content

host_permissions manifest key documentation #15183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 13, 2022

Conversation

rebloor
Copy link
Contributor

@rebloor rebloor commented Apr 21, 2022

Summary

Add documentation for the host_permissions manifest key becomes available with manifest V3. Also include updates to the permissions and optional_permissions manifest keys indicate that they no longer support the definition of host permissions in manifest V3.

Corresponding browser compatibility data provided in mdn/browser-compat-data#15933.

Related issues

TBC

Metadata

This PR…

  • Adds a new document
  • Rewrites (or significantly expands) a document
  • Fixes a typo, bug, or other error

@rebloor rebloor added the Content:WebExt WebExtensions docs label Apr 21, 2022
@rebloor rebloor requested a review from zombie April 21, 2022 02:58
@rebloor rebloor requested a review from a team as a code owner April 21, 2022 02:58
@rebloor rebloor self-assigned this Apr 21, 2022
@github-actions github-actions bot added the Content:Other Any docs not covered by another "Content:" label label Apr 21, 2022
@github-actions
Copy link
Contributor

github-actions bot commented Apr 21, 2022

@rebloor
Copy link
Contributor Author

rebloor commented May 9, 2022

@zombie a reminder this is awaiting your review

@teoli2003
Copy link
Contributor

teoli2003 commented May 9, 2022

Hi, @rebloor. A small tip: to prevent accidental merge, you can mark the PR as draft PR (even after its initial creation) which invalids the merge button.

Copy link
Member

@zombie zombie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks mostly good, with a one or two important changes.

Don't really love that host_permisions page mostly duplicates info from the permissions page, might be better if we could find a way to reference one from the other (and only list differences), but I don't have a good idea how best to do that. It's probably fine like this for the initial push, we can refine later.

@@ -48,6 +51,8 @@ The key can contain two kinds of permissions: host permissions and API permissio

These are the same as the host permissions you can specify in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) key.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe replace with, or add "(or host_permissions(link) when using Manifest V3 or higher)"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the note on the next line covers this

@@ -48,6 +51,8 @@ The key can contain two kinds of permissions: host permissions and API permissio

These are the same as the host permissions you can specify in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) key.

> **Note:** When using Manifest V3 or higher, host permissions must be specified in the [`host_permission`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions) manifest key.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is true in Chrome, but not yet in Firefox (until bug 1766026, which is not currently a priority).

But maybe we're ok to document it like that, since that's where we want to end up eventually? I'm not sure which is better, so whatever think is more appropriate.

Copy link
Contributor Author

@rebloor rebloor May 12, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mixedpuppy we're only including these changes now because they were supposed to be part of the development preview, if this isn't the case should we hold them for the next release? (Also remove reference from the extension workshop migration guide?)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rebloor this (host_permissions) is part of dev preview. What isn't is the restriction noted. During dev preview, hosts can be in either host_permissions or optional_permissions. At some point, bug 1766026 will be fixed, and then hosts can be in either host_permissions or optional_host_permissions.

I think the comment can be made specific to chrome. We can then clarify the comment when that bug is done.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, sorry for not being clear enough. I like what Shane proposed, just mention that this is currently only restricted in Chrome's MV3.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification, updated

@@ -0,0 +1,84 @@
---
title: host_permissions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The preview page has a visible underlined space in the H1 title, I'm not sure if that's an artifact of the preview generation or something else.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately I don't get a proper preview, so couldn't comment but this line looks OK

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was just looking at the previews created by the bot #15183 (comment)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See what you mean, checked and there's no hidden characters there.


The extra privileges include:

- [XMLHttpRequest](/en-US/docs/Web/API/XMLHttpRequest) and [fetch](/en-US/docs/Web/API/Fetch_API) access to those origins without cross-origin restrictions (even for requests made from content scripts)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(even for requests made from content scripts)
This is not true anymore in mv3, but instead of dropping it, we should probably call it out, since it's a change. Maybe something like "Though not for requests from content scripts, as was the case in MV2"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

- the ability to inject scripts programmatically (using {{webextAPIref("tabs/executeScript", "tabs.executeScript()")}}) into pages served from those origins
- the ability to receive events from the {{webextAPIref("webrequest")}} API for these hosts
- the ability to access cookies for that host using the {{webextAPIref("cookies")}} API, as long as the `"cookies"` API permission is also included.
- bypassing tracking protection for extension pages where a host is specified as a full domain or with wildcards. Content scripts, however, can only bypass tracking protection for hosts specified with a full domain.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the content scripts part here might be also incorrect for mv3, but I'll need to check.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep confirmed, this bit about content scripts can be removed as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, removed

rebloor and others added 2 commits May 13, 2022 09:45
…ermissions/index.md

Co-authored-by: Tomislav Jovanovic <zombie@users.noreply.github.com>
@rebloor rebloor requested a review from zombie May 12, 2022 22:20
Copy link
Member

@zombie zombie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, thanks!

@rebloor rebloor merged commit 5b49049 into mdn:main May 13, 2022
@rebloor rebloor deleted the mv3-host-permissions branch May 13, 2022 16:07
hamishwillee pushed a commit to hamishwillee/content that referenced this pull request May 23, 2022
* host_permissions manifest key documentation

* Update files/en-us/mozilla/add-ons/webextensions/manifest.json/host_permissions/index.md

Co-authored-by: Tomislav Jovanovic <zombie@users.noreply.github.com>

* Feedback updates

Co-authored-by: Tomislav Jovanovic <zombie@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:Other Any docs not covered by another "Content:" label Content:WebExt WebExtensions docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants