Proposal: initial_permissions and initial_host_permissions

[carlosjeurissen]

initial_permissions and initial_host_permissions will allow extension authors to declare the permissions browsers may prompt extension users at initial installation time. This resolves #227 and could help with #700.

Permissions in initial_permissions will be prompted to the user on installation similar to the current browser behaviour for permissions. With the difference being during an update. If an extension updates with additional permissions in initial_permissions, new permissions will not be prompted to existing users. Only to new users. This covers the initial use case of this proposal. This resolves issue #711.

In addition, if initial_permissions is present and understood by the browser. The prompting behaviour of the permissions key and match patterns in content_scripts will be suppressed. This would allow for maximum backwards compatibility while opening up for the new behaviour for new browser versions. This resolves #116.

[fregante]

Can you also specify whether the browser should prompt the user to add the suppressed hosts?

{
  "manifest_version": 3,
  "initial_host_permissions": ["*://*/*"],
  "content_scripts": [{
    "scripts": ["main.js"],
    "matches": ["*://*/*"]
  }]
}

I don't want Safari to again start prompting the user to grant each website individually in this case.

1. Extension is installed without host permissions
2. Extension decides when to ask for more host permissions

[carlosjeurissen]

@fregante the proposal document specifies you can use initial_host_permissions with an empty array. In your example, if you don't want the browser to prompt these permissions but let the extension handle it, you would use:

{
  "manifest_version": 3,
  "initial_host_permissions": [],
  "content_scripts": [{
    "scripts": ["main.js"],
    "matches": ["*://*/*"]
  }]
}

Explicitly declaring initial_host_permissions in the manifest would ideally reduce the need for browsers to guess extension authors intentions. Which indeed has caused the annoying Safari permission prompts in the past.

[fregante]

I don't see any mentions of this specific behavior after the installation. It's clear that it won't request them on install, but not that the browser will stay put later.

Just to clarify what's currently happening in Safari since 18.4 I think:

1. Extension is installed without host permissions, but with *://*/* in the optional host permissions
2. Safari will at random times prompt the user modally that "the extension is requesting access to [whatever tab or even iframe it encounters]"

More details here:

• Extension asks to access other websites in Safari 18.4 refined-github/refined-github#8319
• Safari 18.4+ SponsorBlock asks for permission causing Invidious support to be removed ajayyy/SponsorBlock#2227

[carlosjeurissen]

@fregante Thanks for clarifying! In general, if declared in optional_host_permissions, I do not see a reason why a browser is expected to prompt for access. @xeenon or @kiaraarose is this behavior intentional?

If not, initial_host_permissions could potentially also be used to suppress this behavior.

[oleksiilevzhynskyi]

@carlosjeurissen, thank you for the proposal!

initial_permissions will take over the permission prompt on initial
installation of the existing permissions field. In supported browsers,
permissions in permissions should be treated as optional_permissions
unless they are specified in initial_permissions.

Does the author need to specify permissions twice to benefit from the proposed behavior?

---

Here is an example to illustrate my question. Let's assume the author would like to add a new "nativeMessaging" permission that triggers a warning right now.

a) According to the proposal, the new permissions should be added to initial_permissions and permissions, right?

{
  "initial_permissions": ["nativeMessaging"],
  "permissions": ["nativeMessaging"]
}

This means:

• for new install - permissions will be requested as part of the regular installation flow
• for update - nothing happens, extension must explicitly request it later on.

b) And in case the manifest will contain only "permissions", they will be optional, right?

{
  "permissions": ["nativeMessaging"]
}

This means:

• for new install - nothing happens, extension must explicitly request it later on.
• for update - nothing happens, extension must explicitly request it later on.

Does it make sense?

[carlosjeurissen]

@oleksiilevzhynskyi Thanks for checking the proposal! No, you would not have to add it to both. Specifying it both in permissions and initial_permissions would only be required for browsers not having implemented initial_permissions.

Updated the proposal to clarify new permissions added in an update will be treated as optional_permissions for existing users.

For backwards compatibility (IE, handle browsers without initital_permissions support. You have two options.

Given the following setup:

{
  "initial_permissions": ["nativeMessaging"],
  "optional_permissions": ["bookmarks"]
}

1. If initial_permissions is unsupported, prefer "nativeMessaging" to be prompted on installation for existing browsers for all users both on update and installation. This would be similar to the behaviour of new users of browsers with initial_permissions support.

{
  "initial_permissions": ["nativeMessaging"],
  "permissions": ["nativeMessaging"],
  "optional_permissions": ["bookmarks"]
}

2. If initial_permissions is unsupported, prefer "nativeMessaging" to NOT be prompted for all users. This would align with the behaviour of existing users of browsers with initial_permissions support.

{
  "initial_permissions": ["nativeMessaging"],
  "permissions": ["nativeMessaging"],
  "optional_permissions": ["bookmarks"]
}

The benefit of this is you can choose this on a per-permission level. Which would be more flexible than a for-all global permission flag.

[carlosjeurissen]

@Rob--W for "data_collection_permissions", a top level "initial" key could be used.

[oleksiilevzhynskyi]

@carlosjeurissen, I have a clarification question. In case I would like to introduce a new permission that will be mandatory for new installs, but optional for existing users. Should I use a combination of "initial_permissions" and "optional_permissions"?

Example 1:

{
  "initial_permissions": ["nativeMessaging"],
  "optional_permissions": ["nativeMessaging"]
}

My understanding is that with this config, it should

• a) non-supporting browsers (old version) will treat "nativeMessaging" permission as options and ignore "initial_permissions" completely.
• b) for browsers that support the permission, the "nativeMessaging" will be prompted on install, but will remain optional in case of extension update.

Am I getting it right?

[oleksiilevzhynskyi]

And just to double-check. If permission is only mentioned "initial_permissions", but not in "permissions" or "optional_permissions", it will be treated as "optional_permission" during extension update, right?

Example 2:

{
  "initial_permissions": ["nativeMessaging"],
  "permission": []
  "optional_permissions": []
}

In this case

• a) Non-supporting browsers will ignore "nativeMessaging" altogether, as they ignore the "initial_permissions" key.
• b) For browsers that support the "initial_permissions" key, the "nativeMessaging" will be prompted on install, and treated as "optional" during extension update.

Does it make sense?

[carlosjeurissen]

And just to double-check. If permission is only mentioned "initial_permissions", but not in "permissions" or "optional_permissions", it will be treated as "optional_permission" during extension update, right?

Example 2:

{
  "initial_permissions": ["nativeMessaging"],
  "permission": []
  "optional_permissions": []
}

In this case
a) Non-supporting browsers will ignore "nativeMessaging" altogether, as they ignore the "initial_permissions" key.
b) For browsers that support the "initial_permissions" key, the "nativeMessaging" will be prompted on install, and treated as "optional" during extension update.

Does it make sense?

Yes, both A and B are true.