Permissions API - update to docs needed

[hamishwillee]

• Permissions API
• Using the Permissions API

The Permission API is associated with UI features that require explicit permission from the user to access (or some equivalent proxy for permission). For example, geolocation potentially exposes very sensitive user information and hence requires explicit user permission to use. It is used by developers to determine whether permission has been granted to use the associated API.

There are a number of things to fix in the current MDN docs. The main one is that it is too easy to confuse with the Permissions API (related to user granted permissions) with the Permission Policy which provides server granted permissions to use similar features. Both APIs are similarly named and use similar/same strings to define the features.

• We need to explicitly capture the main differences, as outlined in https://w3c.github.io/permissions/#relationship-to-permissions-policy . For example, UI vs server, the fact that if permission policy is not allowed, the permission API will always be denied.
• Make sure that the difference is also captured in the Permission policy doc - ie. not just assume the existence of an overlap
• Explain what the permission API permissions are - ie refer to a list.

The permissions API permissions are now defined in each spec, but registered in a powerful feature registry: https://w3c.github.io/powerful-features-registry/ we should explain that.

Other things:

• The "Using" doc refers to quite old builds. General update would be good.

@marcoscaceres Love your work in w3c/permissions#263 . Would appreciate it if you are able to keep an eye on the MDN fixes. Not sure who will do them. Possibly me, once I finish my queue :-)

[marcoscaceres]

@hamishwillee, happy to review things! Just ping 🛎.

[chrisdavidmills]

Fixed via #22439; this should be closed.

[marcoscaceres]

Oh, sorry I totally missed this 😢 . I’ll still have a look.

[chrisdavidmills]

@marcoscaceres hiya mate; hope you like it ;-)

[Josh-Cena]

@chrisdavidmills AFAIU, this issue is talking about the permissions web API, which I don't see #22439 touching; do you think it is still adequately addressed since I can't tell?

[hamishwillee]

@Josh-Cena No, this has not been updated. The fact that @chrisdavidmills confused permissions API and permissions policy is precisely the point :-). I'd love to tackle this, just that it's a significant amount of work.

[chrisdavidmills]

I didn't exactly confuse it, and I did add the following section to try to straighten this out a bit: https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#relationship_with_the_permissions_api

But looking at this again, the Permissions API docs need work too, so this should stay open after all.

[hamishwillee]

THanks @chrisdavidmills - ah, knew I'd seen that. Handy, we can include/cross link that info in the permission API too.

[hamishwillee]

@marcoscaceres Just doing a little prep work for this. I was wondering if I could get some confirmations (no urgency, I'm about to go on holiday for a couple of weeks):

1. The Permissions API browser compatibility table lists request(), requestAll() and revoke() methods. These are not in the spec. The two request methods are marked as experimental. Revoke is marked as "deprecated".

   • Are these all now "non standard" (i.e. not in spec or planned for spec?) and deprecated (not supposted to be used)? Essentially "on the way out, rather than on the way in"?
   • If so, the only api is query, which tells me that via this generic API all a developer can do is find out the current state of the permission
     • they can't grant it programmatically
     • they can't explicitly request a permission - if they want it then they have to call a method that requires the permission right?
     • Essentially this is mostly good for hiding UI that has been denied, and perhaps for showing buttons to attempt to enable API where the state is "prompt". Right?

2. Reading some of the other specs, like the one for accelerometer, it indicates you can revoke a permission " The user can revoke permission,". But there is no method to do this in the spec - just an "Abstract operation".

   • Is the intent that if it makes sense to programmatically revoke a permission that be specified on a per-API basis?

3. The Permissions API browser compatibility table lists a whole bunch of permissions. The permission registry lists a very small subset. Is it just that the registry is still being evolved?

4. Some permissions are also accessible through their own APIs, such as Notification.permission. Is the intent that the they will co-exist, or is it expected that eventually things like Notification.permission would go away?

[hamishwillee]

The #23680 makes use of a pattern we can use for documenting and linking the permission api permissions. Essentially it is a security section that exists in the api overview and the api page where access is requested. This will include all permission info.

[marcoscaceres]

Hi @hamishwillee! Welcome back! I'm also just coming back from vacation.

Are these all now "non standard" (i.e. not in spec or planned for spec?) and deprecated (not supposted to be used)? Essentially "on the way out, rather than on the way in"?

Correct. They are deprecated, non-standard, and there is no plan to bring those back.

Essentially this is mostly good for hiding UI that has been denied, and perhaps for showing buttons to attempt to enable API where the state is "prompt". Right?

Correct. But, it's also extremely useful to know if the API will "prompt" (and if so, to possibly show UI). So good for both showing and hiding.

Reading some of the other specs, like the one for accelerometer, it indicates you can revoke a permission " The user can revoke permission,". But there is no method to do this in the spec - just an "Abstract operation".

Correct. The user does revokes permission through the browser's UI (or maybe even through the OS, as is the case in macOs or iOS). There is no API to revoke permissions.

The Permissions API browser compatibility table lists a whole bunch of permissions. The permission registry lists a very small subset. Is it just that the registry is still being evolved?

Correct. We've been a bit slow in updating the registry. Sorry about that! Nevertheless, the compat table does seem to accurately reflect the state of some permissions still being experimental, which is great.

Some permissions are also accessible through their own APIs, such as Notification.permission. Is the intent that the they will co-exist, or is it expected that eventually things like Notification.permission would go away?

The short answer is: no. things like things like Notification.requestPermission() would not go away (note the "request" bit).

The long version: As you described above, the sole purpose of the Permission API allows you to query() the permission state of various APIs. However, the Permission API does not provide any means to request a permission. This is by design.

So, every APIs must provide their own permission request mechanism. For example:

// Check state of geolocation 
const status = await navigator.permissions.query({name: "geolocation"})
if (status.state === "prompt") {
   try { 
     // getCurrentPosition() and watchPosition() will prompt for permission 
      const pos = await new Promise((res, res) => navigator.geolocation.getCurrentPosition(res, rej);
   } catch (positionError){
      // check if user denied permission...
   }
}
// and so on...

[Josh-Cena]

Should be fixed by #27817, #22439